Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 36 additions & 36 deletions contracts/command-catalog.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion contracts/task-index.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -872,7 +872,7 @@ chapters:
title: Upload and share HTML pages with customers
when: ["html document", "html library", "upload html", "html folder", "share html", "HTML 文档", "文档库", "客户分享", "网页分享"]
steps:
- html-documents.list: "folder is omitted, root, or a folder id; q searches titles."
- html-documents.list: "Museon staff only, plus asset read; the server decides. folder is omitted, root, or a folder id; q searches titles."
- html-documents.folder-create: "One level only. The body is the name. No idempotency key: after an unknown outcome, list first."
- html-documents.upload: "Public by default: give the customer share_url. --share-slug chooses a custom link name; --private keeps the document internal, even when a name is reserved. A second upload creates a second document; after an unknown result, list before retrying."
- html-documents.share: "Enable sharing for an existing document. Omit link options to keep the custom name, --share-slug to rename, or --random-link to clear it. Old names stay reserved to this document."
Expand Down
16 changes: 9 additions & 7 deletions docs/agent-discoverability.md
Original file line number Diff line number Diff line change
Expand Up @@ -608,12 +608,12 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift.

| command | risk | dry-run | confirm | execution | summary |
|---|---|---|---|---|---|
| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. |
| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides. |
| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides. |
| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides. |
| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. |
| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides. |
| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |

<!-- END GENERATED COMMANDS -->

Expand All @@ -633,7 +633,9 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift.
- Requests act in the organization chosen with `museoncli org select`
(`X-Organization-Id`); pass `--organization-id <uuid>` on a domain command to address
another organization for one call. Catalog entries mark this with `organization_bound`
and roles `organization_member` / `organization_admin_or_staff`. Since 1.0 no command
and roles `organization_member` / `organization_admin_or_staff`. `html-documents`
stays organization-bound and also requires `staff`
(`staff_with_organization_asset_access`); the server enforces both. Since 1.0 no command
takes a workspace; only `agentic-campaign` and `hireaicreator` keep their 0.25
`--workspace-id` and `workspace_bound` mirror until they move to organizations.
- Envelopes carry an `organization` key (`{id, name}` or `null`) and no `workspace` key
Expand Down
15 changes: 9 additions & 6 deletions docs/domain-command-framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ any more: organizations are the only unit of access.
(`organization_member`, `organization_admin_or_staff`) and
`resource_policy: server_evaluated_organization_and_resource_access`: the server
evaluates organization role, Campaign scope and target-resource access on every request.
`html-documents` keeps `organization_bound` and adds `required_roles: staff` with
`resource_policy: staff_with_organization_asset_access` (staff, and still the
organization's asset permission). The CLI records that and does not enforce it.
- 1.0 removed `museoncli workspace list|current|select`, every `--workspace-id` and
every `workspace_id` input. `agentic-campaign` and `hireaicreator` are the exception
and keep their 0.25 behaviour until they move to organizations; all of it lives in
Expand Down Expand Up @@ -642,12 +645,12 @@ The tables below are generated — edit code, then run

| command | risk | dry-run | confirm | execution | summary |
|---|---|---|---|---|---|
| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. |
| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides. |
| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides. |
| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides. |
| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. |
| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides. |
| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |
| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. |

<!-- END GENERATED COMMANDS -->

Expand Down
2 changes: 1 addition & 1 deletion docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -800,7 +800,7 @@ See: `organizations`

`museoncli guide html-documents` · when: html document; html library; upload html; html folder; share html; HTML 文档; 文档库; 客户分享; 网页分享

1. `museoncli html-documents +list` (read): folder is omitted, root, or a folder id; q searches titles.
1. `museoncli html-documents +list` (read): Museon staff only, plus asset read; the server decides. folder is omitted, root, or a folder id; q searches titles.
2. `museoncli html-documents folder +create --name <name>` (write): One level only. The body is the name. No idempotency key: after an unknown outcome, list first.
3. `museoncli html-documents +upload --file <file> --title <title>` (write): Public by default: give the customer share_url. --share-slug chooses a custom link name; --private keeps the document internal, even when a name is reserved. A second upload creates a second document; after an unknown result, list before retrying.
4. `museoncli html-documents +share --id <html-documents-id>` (write): Enable sharing for an existing document. Omit link options to keep the custom name, --share-slug to rename, or --random-link to clear it. Old names stay reserved to this document.
Expand Down
30 changes: 27 additions & 3 deletions museoncli/domains/html_documents.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@

Documents and one-level folders belong to the organization in the path. The CLI
sends that organization as ``X-Organization-Id`` and never a workspace or a
``parent_id``. Reads need asset read and writes need asset edit; the server decides.
``parent_id``. Private management is Museon staff plus the organization's asset
permission (read to list, edit to write). That is catalog metadata only: the CLI
does not enforce it, and the server decides. A customer share link is anonymous
and is not one of these commands.
"""

from __future__ import annotations
Expand Down Expand Up @@ -33,7 +36,16 @@
_MAX_FILENAME = 180
_FOLDER = "72defd40-39ad-40d3-8105-8f23a9a016da"
_DOCUMENT = "11111111-1111-4111-8111-111111111111"
_EDIT = " Needs asset edit on the organization; the server decides."
_STAFF_ROLES = ("staff",)
_STAFF_POLICY = "staff_with_organization_asset_access"
_STAFF_KEY = (
"A staff API key does not gain staff support outside its organization role, and "
"stays inside the organization it was issued in. The server decides."
)
_EDIT = (
" Museon staff only, and needs asset edit on the organization. " + _STAFF_KEY
)
_READ = "Museon staff only, and needs asset read on the organization. " + _STAFF_KEY
_SHARE_SLUG = {
"type": ["string", "null"],
"minLength": 3,
Expand Down Expand Up @@ -490,14 +502,16 @@ def specs() -> list[CommandSpec]:
add_arguments=_add_upload_arguments,
build_arguments=_build_upload_arguments,
supports_dry_run=True,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
CommandSpec(
domain=domain,
shortcut="+list",
summary=(
"List this organization's HTML documents and its one-level folders. --q searches "
"titles. --folder is omitted (every document), root (no folder), or a folder id. "
"Anyone who can read the organization's assets can list; the server decides."
+ _READ
),
risk_level="read",
execution="direct",
Expand All @@ -511,6 +525,8 @@ def specs() -> list[CommandSpec]:
examples=["museoncli html-documents +list --q architecture --folder root"],
add_arguments=_add_list_arguments,
build_arguments=_build_list_arguments,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
CommandSpec(
domain=domain,
Expand Down Expand Up @@ -538,6 +554,8 @@ def specs() -> list[CommandSpec]:
add_arguments=_add_share_arguments,
build_arguments=_build_share_arguments,
supports_dry_run=True,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
CommandSpec(
domain=domain,
Expand All @@ -557,6 +575,8 @@ def specs() -> list[CommandSpec]:
add_arguments=_add_document_arguments,
build_arguments=_build_document_arguments,
supports_dry_run=True,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
CommandSpec(
domain=domain,
Expand All @@ -576,6 +596,8 @@ def specs() -> list[CommandSpec]:
add_arguments=_add_folder_arguments,
build_arguments=_build_folder_arguments,
supports_dry_run=True,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
CommandSpec(
domain=domain,
Expand All @@ -595,6 +617,8 @@ def specs() -> list[CommandSpec]:
add_arguments=_add_install_arguments,
build_arguments=_build_install_arguments,
supports_dry_run=True,
required_roles=_STAFF_ROLES,
resource_policy=_STAFF_POLICY,
),
]

Expand Down
Loading
Loading