From e8a35b67c33386357efacbf442bb59b87102b5e8 Mon Sep 17 00:00:00 2001 From: Nicky Chu Date: Wed, 18 Nov 2026 01:09:16 +0800 Subject: [PATCH 1/3] feat: publish HTML uploads with customer share links --- CHANGELOG.md | 13 + README.md | 10 + README.zh-CN.md | 8 + contracts/command-catalog.json | 277 +++++++++++++++++- contracts/task-index.yaml | 8 +- docs/agent-discoverability.md | 6 +- docs/domain-command-framework.md | 6 +- docs/guide.md | 10 +- museoncli/domains/_discovery.py | 2 +- museoncli/domains/html_documents.py | 133 ++++++++- .../references/task-index.md | 2 +- tests/test_html_documents.py | 114 ++++++- 12 files changed, 558 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ab683db..897e110 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ Museon CLI follows semantic versioning for its package and command contract. +## Unreleased + +- HTML uploads now enable customer link sharing by default and return `data.share_url`. + Anyone with that link can view the document without signing in. Add `--private` + (or `"private": true` in structured input) to preserve organization-only access. + Existing documents and built-in guides remain private until explicitly shared. +- New `html-documents +share --id ` and `+unshare --id ` + enable and stop link access without uploading a duplicate document. An active + link is reused; after stopping sharing, enabling it again returns a new link. +- Migration: scripts uploading internal HTML must add `--private` before upgrading. + Deploy the corresponding HTML-sharing API before releasing this CLI change. + This visibility-default change requires a major version release. + ## 2.3.1 Fixes from production QA of 2.3.0 `html-documents` errors. diff --git a/README.md b/README.md index 5de7df8..c139161 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,7 @@ at the last published release until a separate release is approved. | Analyze video content | `content-analysis` | | Upload files, import image URLs and read media records | `media` | | Validate, host and share durable reports | `artifacts` | +| Upload HTML pages and share them with customers without a login | `html-documents` | | Connect and inspect accounts, use bound phones, read performance and edit profiles | `social-account` | | Schedule Agent work and retain run memory | `routines` | | Discover organization methodology | `skills` | @@ -86,6 +87,15 @@ The CLI executes atomic operations; the Agent composes workflows. Museon checks organization role and Campaign scope for every request. Verify writes with readback from the owning domain, not with a request receipt alone. +HTML uploads now enable link sharing by default. Use +`museoncli html-documents +upload --file ./proposal.html --title "Customer proposal"` +and give the customer the returned `data.share_url`. Anyone with that link can open it. +For internal material, add `--private`; existing documents remain private until explicitly +shared with `html-documents +share --id `. `+unshare --id ` +stops new visits through the current link; sharing again creates a new link. +Use `+list` to recover document IDs and share URLs after an uncertain upload result; +uploading again creates another document. This change requires the HTML-sharing API release. + Which command does a job? `museoncli guide` lists every task by chapter (UGC Campaign operations in the order the work happens, tracking, analytics, accounts and publishing, AI image posts, research, the organization); `museoncli guide ` gives its diff --git a/README.zh-CN.md b/README.zh-CN.md index a8ae706..e89f85a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -67,6 +67,14 @@ https://www.museon.ai/cli/install.md `ai-slideshow` 保留素材、独立生成与旧 slideshow 发布。五个集成 skill 分别承载基础原子能力、研究、HireAICreator、slideshow 与 Campaign(campaigns)流程。Agent 使用这些原子命令编排工作流。 写入后必须回读所属业务状态,不能把请求成功当成任务完成。 +HTML 上传现在默认开启链接分享。执行 +`museoncli html-documents +upload --file ./proposal.html --title "客户方案"`, +把返回的 `data.share_url` 发给客户,对方无需登录即可打开,任何持有链接的人均可查看。 +内部资料请加 `--private`;已有文档仍保持私密,直到用 `html-documents +share --id <文档ID>` +主动开启分享。`+unshare --id <文档ID>` 停止通过当前链接访问;重新分享会生成新链接。 +上传结果不确定时先用 `+list` 找回文档和分享链接,重复上传会新建文档。 +此改动依赖支持 HTML 分享的服务端版本。 + 某件事该用哪个命令?`museoncli guide` 按章节列出所有任务(UGC Campaign 运营按实际工作顺序排列, 另有内容追踪、数据分析、账号与发布、AI 图文、调研、组织);`museoncli guide ` 给出该任务按顺序的命令、 必填参数、风险和注意事项;`museoncli guide --search <词>` 用用户自己的话(中英文都可)查任务和命令。 diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index d366a51..2d8868b 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -11872,7 +11872,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "Upload one local HTML file into this organization's document library with --title. 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.", + "summary": "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. 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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11903,6 +11903,60 @@ "supports_dry_run": false, "transport": "agent_cli_api" }, + { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "organization_member" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "server_evaluated_organization_and_resource_access" + }, + "capability_key": "html-documents.share", + "cli": "museoncli html-documents +share", + "domain": "html-documents", + "execution": "direct", + "name": "html-documents.share", + "requires_confirmation": false, + "resource": null, + "risk_level": "write", + "shortcut": "+share", + "stability": "stable", + "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. An active link is reused; after +unshare this creates a new link and the old one stays invalid. Needs asset edit on the organization; the server decides.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, + { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "organization_member" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "server_evaluated_organization_and_resource_access" + }, + "capability_key": "html-documents.unshare", + "cli": "museoncli html-documents +unshare", + "domain": "html-documents", + "execution": "direct", + "name": "html-documents.unshare", + "requires_confirmation": false, + "resource": null, + "risk_level": "write", + "shortcut": "+unshare", + "stability": "stable", + "summary": "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 it again creates a new link. Needs asset edit on the organization; the server decides.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, { "authorization": { "authentication_required": true, @@ -64702,7 +64756,7 @@ }, "name": "html-documents.list", "output_schema": { - "description": "data: folders (id, name, document_count), root_count, and documents (id, title, filename, folder_id, slug, updated_at).", + "description": "data: folders (id, name, document_count), root_count, and documents (id, title, filename, folder_id, slug, updated_at, share_url). share_url is null when sharing is off.", "properties": { "command": { "type": "string" @@ -64765,6 +64819,212 @@ "supports_dry_run": false, "transport": "agent_cli_api" }, + "html-documents.share": { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "organization_member" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "server_evaluated_organization_and_resource_access" + }, + "capability_key": "html-documents.share", + "cli": "museoncli html-documents +share", + "domain": "html-documents", + "examples": [ + "museoncli html-documents +share --id 11111111-1111-4111-8111-111111111111" + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": { + "dry_run": { + "description": "Read and preview only; write nothing.", + "type": "boolean" + }, + "id": { + "description": "Document to share or stop sharing (html-documents +list). Canonical UUID copied from a previous command response; never a placeholder.", + "format": "uuid", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "name": "html-documents.share", + "output_schema": { + "description": "data: the document with share_url. Give this URL to the customer exactly as returned.", + "properties": { + "command": { + "type": "string" + }, + "data": { + "type": [ + "object", + "array", + "string", + "number", + "boolean", + "null" + ] + }, + "next_steps": { + "items": { + "type": "string" + }, + "type": "array" + }, + "ok": { + "type": "boolean" + }, + "organization": { + "description": "The organization this command addressed (id, name).", + "type": [ + "object", + "null" + ] + }, + "run": { + "type": [ + "object", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "ok", + "command", + "data", + "run", + "warnings", + "next_steps" + ], + "type": "object" + }, + "requires_confirmation": false, + "resource": null, + "risk_level": "write", + "shortcut": "+share", + "stability": "stable", + "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. An active link is reused; after +unshare this creates a new link and the old one stays invalid. Needs asset edit on the organization; the server decides.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, + "html-documents.unshare": { + "authorization": { + "authentication_required": true, + "enforcement": "museon_server", + "organization_bound": true, + "required_roles": [ + "organization_member" + ], + "required_scopes": [ + "agent_cli.access" + ], + "resource_policy": "server_evaluated_organization_and_resource_access" + }, + "capability_key": "html-documents.unshare", + "cli": "museoncli html-documents +unshare", + "domain": "html-documents", + "examples": [ + "museoncli html-documents +unshare --id 11111111-1111-4111-8111-111111111111" + ], + "execution": "direct", + "input_schema": { + "additionalProperties": false, + "properties": { + "dry_run": { + "description": "Read and preview only; write nothing.", + "type": "boolean" + }, + "id": { + "description": "Document to share or stop sharing (html-documents +list). Canonical UUID copied from a previous command response; never a placeholder.", + "format": "uuid", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "name": "html-documents.unshare", + "output_schema": { + "description": "data: the document with share_url set to null.", + "properties": { + "command": { + "type": "string" + }, + "data": { + "type": [ + "object", + "array", + "string", + "number", + "boolean", + "null" + ] + }, + "next_steps": { + "items": { + "type": "string" + }, + "type": "array" + }, + "ok": { + "type": "boolean" + }, + "organization": { + "description": "The organization this command addressed (id, name).", + "type": [ + "object", + "null" + ] + }, + "run": { + "type": [ + "object", + "null" + ] + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "ok", + "command", + "data", + "run", + "warnings", + "next_steps" + ], + "type": "object" + }, + "requires_confirmation": false, + "resource": null, + "risk_level": "write", + "shortcut": "+unshare", + "stability": "stable", + "summary": "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 it again creates a new link. Needs asset edit on the organization; the server decides.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, "html-documents.upload": { "authorization": { "authentication_required": true, @@ -64782,8 +65042,8 @@ "cli": "museoncli html-documents +upload", "domain": "html-documents", "examples": [ - "museoncli html-documents +upload --file ./guide.html --title \"Architecture notes\"", - "museoncli html-documents +upload --file ./guide.html --title \"Architecture notes\" --filename guide.html --folder-id 72defd40-39ad-40d3-8105-8f23a9a016da" + "museoncli html-documents +upload --file ./proposal.html --title \"Customer proposal\"", + "museoncli html-documents +upload --file ./guide.html --title \"Architecture notes\" --private --filename guide.html --folder-id 72defd40-39ad-40d3-8105-8f23a9a016da" ], "execution": "direct", "input_schema": { @@ -64810,6 +65070,11 @@ "format": "uuid", "type": "string" }, + "private": { + "default": false, + "description": "Keep the upload inside the organization. By default it is shared: anyone with the returned share_url can open it without signing in.", + "type": "boolean" + }, "title": { "description": "Document title.", "maxLength": 200, @@ -64825,7 +65090,7 @@ }, "name": "html-documents.upload", "output_schema": { - "description": "data: id, title, filename, folder_id, slug, updated_at, html.", + "description": "data: id, title, filename, folder_id, slug, updated_at, html, share_url. Give the customer share_url exactly as returned; it is null for private uploads.", "properties": { "command": { "type": "string" @@ -64884,7 +65149,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "Upload one local HTML file into this organization's document library with --title. 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.", + "summary": "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. 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.", "supports_dry_run": true, "transport": "agent_cli_api" }, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index 4a24b70..31b3843 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -869,12 +869,14 @@ chapters: - organization.member-list: "Role and Campaign scope per member (owner, admin, operator)." - organization.billing-get: "Plan, AI credits and usage (owner, admin)." - id: html-documents - title: Upload HTML documents into the organization library - when: ["html document", "html library", "upload html", "html folder", "HTML 文档", "文档库"] + 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.folder-create: "One level only. The body is the name. No idempotency key: after an unknown outcome, list first." - - html-documents.upload: "Title is required. The filename is the file's basename when that is one .html or .htm name; otherwise the server names it from the title." + - html-documents.upload: "Public by default: give the customer the returned share_url. Anyone with the link can open it without signing in. Use --private for organization-only documents. A second upload creates a second document; after an unknown result, list before retrying." + - html-documents.share: "Enable sharing for an existing document; reuses its active link. Share only content intended for anyone with the link." + - html-documents.unshare: "Stop new visits through the current link. The document stays in the library; sharing again creates a new link." - html-documents.install-defaults: "Copies the three built-in guides into this organization. A second call does not duplicate them." - id: business-skills title: Use or write the organization's Business Skills diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index e00fe61..d4fa6f6 100644 --- a/docs/agent-discoverability.md +++ b/docs/agent-discoverability.md @@ -22,7 +22,7 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. -499 commands across 18 domains (source of truth: `museoncli schema`). +501 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -608,8 +608,10 @@ 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 into this organization's document library with --title. 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 +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. 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. An active link is reused; after +unshare this creates a new link and the old one stays invalid. 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 it again creates a new 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. | diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index 22cc803..d6ee0c4 100644 --- a/docs/domain-command-framework.md +++ b/docs/domain-command-framework.md @@ -56,7 +56,7 @@ The tables below are generated — edit code, then run -499 commands across 18 domains (source of truth: `museoncli schema`). +501 commands across 18 domains (source of truth: `museoncli schema`). ### research @@ -642,8 +642,10 @@ 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 into this organization's document library with --title. 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 +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. 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. An active link is reused; after +unshare this creates a new link and the old one stays invalid. 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 it again creates a new 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. | diff --git a/docs/guide.md b/docs/guide.md index 79ac4dc..a575531 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -796,14 +796,16 @@ See: `organizations` 1. `museoncli organization member +list` (read): Role and Campaign scope per member (owner, admin, operator). 2. `museoncli organization billing +get` (read): Plan, AI credits and usage (owner, admin). -### Upload HTML documents into the organization library +### Upload and share HTML pages with customers -`museoncli guide html-documents` · when: html document; html library; upload html; html folder; HTML 文档; 文档库 +`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. 2. `museoncli html-documents folder +create --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 --title ` (write): Title is required. The filename is the file's basename when that is one .html or .htm name; otherwise the server names it from the title. -4. `museoncli html-documents +install-defaults` (write): Copies the three built-in guides into this organization. A second call does not duplicate them. +3. `museoncli html-documents +upload --file <file> --title <title>` (write): Public by default: give the customer the returned share_url. Anyone with the link can open it without signing in. Use --private for organization-only documents. 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; reuses its active link. Share only content intended for anyone with the link. +5. `museoncli html-documents +unshare --id <html-documents-id>` (write): Stop new visits through the current link. The document stays in the library; sharing again creates a new link. +6. `museoncli html-documents +install-defaults` (write): Copies the three built-in guides into this organization. A second call does not duplicate them. ### Use or write the organization's Business Skills diff --git a/museoncli/domains/_discovery.py b/museoncli/domains/_discovery.py index 611e56a..cf31026 100644 --- a/museoncli/domains/_discovery.py +++ b/museoncli/domains/_discovery.py @@ -215,7 +215,7 @@ def command_examples(spec: CommandSpec) -> list[str]: "staff-ops": "MuseOn staff diagnostics.", "analytics": "Multi-Campaign analytics boards.", "organization": "Organization members and billing.", - "html-documents": "The organization's HTML documents: list, upload, folders, built-in guides.", + "html-documents": "HTML pages: upload and share with customers, stop sharing, folders and built-in guides.", "routines": "Recurring Agent work on a schedule, with memory.", } diff --git a/museoncli/domains/html_documents.py b/museoncli/domains/html_documents.py index 4d54da6..f610f40 100644 --- a/museoncli/domains/html_documents.py +++ b/museoncli/domains/html_documents.py @@ -31,6 +31,7 @@ MAX_HTML_BYTES = 1_500_000 _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." _UPLOAD = { @@ -43,6 +44,14 @@ max_length=_MAX_FILENAME, ), "folder_id": uuid_property("Folder to store the document in (html-documents +list)."), + "private": { + "type": "boolean", + "default": False, + "description": ( + "Keep the upload inside the organization. By default it is shared: anyone with " + "the returned share_url can open it without signing in." + ), + }, "dry_run": DRY_RUN_PROPERTY, } _LIST = { @@ -61,6 +70,10 @@ "dry_run": DRY_RUN_PROPERTY, } _INSTALL = {"dry_run": DRY_RUN_PROPERTY} +_SHARE = { + "id": uuid_property("Document to share or stop sharing (html-documents +list)."), + "dry_run": DRY_RUN_PROPERTY, +} def _basename(value: str) -> str: @@ -160,7 +173,11 @@ async def _execute_upload(ctx: CommandContext) -> Any: arguments = ctx.arguments raw_path = str(arguments["file"]) html = _read_html(Path(raw_path).expanduser()) - body: dict[str, Any] = {"title": arguments["title"], "html": html} + body: dict[str, Any] = { + "title": arguments["title"], + "html": html, + "is_shared": not arguments.get("private", False), + } filename = filename_to_send(raw_path, arguments.get("filename")) if filename is not None: body["filename"] = filename @@ -172,7 +189,38 @@ async def _execute_upload(ctx: CommandContext) -> Any: _library(require_organization(ctx)), json_body=body, ) - return data, [], ["museoncli html-documents +list"] + return _sharing_result(data, shared=not arguments.get("private", False)) + + +def _sharing_result(data: Any, *, shared: bool) -> tuple[Any, list[str], list[str]]: + share_url = data.get("share_url") if isinstance(data, dict) else None + warnings = [] + if shared and not share_url: + warnings.append( + "No share URL was returned. Check html-documents +list before retrying; " + "this response does not confirm public sharing." + ) + next_steps = ["museoncli html-documents +list"] + if share_url: + next_steps.insert(0, f"Share this link with your customer: {share_url}") + return data, warnings, next_steps + + +async def _execute_share(ctx: CommandContext) -> Any: + data = await ctx.api_data( + ctx.cfg, + "POST", + f"{_library(require_organization(ctx))}/{ctx.arguments['id']}/share", + ) + return _sharing_result(data, shared=True) + + +async def _execute_unshare(ctx: CommandContext) -> Any: + return await ctx.api_data( + ctx.cfg, + "DELETE", + f"{_library(require_organization(ctx))}/{ctx.arguments['id']}/share", + ) async def _execute_list(ctx: CommandContext) -> Any: @@ -224,13 +272,21 @@ def _add_upload_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--title") parser.add_argument("--filename") parser.add_argument("--folder-id", dest="folder_id") + parser.add_argument( + "--private", + action="store_true", + help="Keep this upload private. By default anyone with its share link can view it.", + ) parser.add_argument("--dry-run", action="store_true") def _build_upload_arguments(args: argparse.Namespace) -> dict[str, Any]: - payload = merged_input(args, ("file", "title", "filename", "folder_id")) + payload = merged_input(args, ("file", "title", "filename", "folder_id", "private")) reject_unknown(payload, _UPLOAD) require(payload, "file", "title") + private = payload.setdefault("private", False) + if not isinstance(private, bool): + raise ValueError("private must be a boolean (true or false).") title = str(payload["title"]).strip() if not 1 <= len(title) <= 200: raise ValueError("--title must be 1-200 characters.") @@ -309,6 +365,21 @@ def _build_install_arguments(args: argparse.Namespace) -> dict[str, Any]: return payload +def _add_share_arguments(parser: argparse.ArgumentParser) -> None: + add_structured_arguments(parser) + parser.add_argument("--id") + parser.add_argument("--dry-run", action="store_true") + + +def _build_share_arguments(args: argparse.Namespace) -> dict[str, Any]: + payload = merged_input(args, ("id",)) + reject_unknown(payload, _SHARE) + require(payload, "id") + payload["id"] = uuid_arg(str(payload["id"]), flag="--id", lookup=_id_lookup_hint()) + _dry_run(args, payload) + return payload + + def specs() -> list[CommandSpec]: domain = Domain.HTML_DOCUMENTS return [ @@ -316,8 +387,10 @@ def specs() -> list[CommandSpec]: domain=domain, shortcut="+upload", summary=( - "Upload one local HTML file into this organization's document library with " - "--title. The stored filename is --filename, or the file's basename when it is " + "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. 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." + _EDIT @@ -327,13 +400,14 @@ def specs() -> list[CommandSpec]: adapter_tool_name="html_documents_upload", input_schema=schema(_UPLOAD, ["file", "title"]), output_schema=output_schema( - "data: id, title, filename, folder_id, slug, updated_at, html." + "data: id, title, filename, folder_id, slug, updated_at, html, share_url. " + "Give the customer share_url exactly as returned; it is null for private uploads." ), examples=[ - 'museoncli html-documents +upload --file ./guide.html --title "Architecture notes"', + 'museoncli html-documents +upload --file ./proposal.html --title "Customer proposal"', ( "museoncli html-documents +upload --file ./guide.html " - f'--title "Architecture notes" --filename guide.html --folder-id {_FOLDER}' + f'--title "Architecture notes" --private --filename guide.html --folder-id {_FOLDER}' ), ], add_arguments=_add_upload_arguments, @@ -354,12 +428,51 @@ def specs() -> list[CommandSpec]: input_schema=schema(_LIST), output_schema=output_schema( "data: folders (id, name, document_count), root_count, and documents " - "(id, title, filename, folder_id, slug, updated_at)." + "(id, title, filename, folder_id, slug, updated_at, share_url). " + "share_url is null when sharing is off." ), examples=["museoncli html-documents +list --q architecture --folder root"], add_arguments=_add_list_arguments, build_arguments=_build_list_arguments, ), + CommandSpec( + domain=domain, + shortcut="+share", + summary=( + "Enable customer sharing for one existing HTML document. Anyone with the " + "returned share_url can view it without signing in. An active link is reused; " + "after +unshare this creates a new link and the old one stays invalid." + _EDIT + ), + risk_level="write", + execution="direct", + adapter_tool_name="html_documents_share", + input_schema=schema(_SHARE, ["id"]), + output_schema=output_schema( + "data: the document with share_url. Give this URL to the customer exactly as returned." + ), + examples=[f"museoncli html-documents +share --id {_DOCUMENT}"], + add_arguments=_add_share_arguments, + build_arguments=_build_share_arguments, + supports_dry_run=True, + ), + CommandSpec( + domain=domain, + shortcut="+unshare", + summary=( + "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 it again creates a new link." + _EDIT + ), + risk_level="write", + execution="direct", + adapter_tool_name="html_documents_unshare", + input_schema=schema(_SHARE, ["id"]), + output_schema=output_schema("data: the document with share_url set to null."), + examples=[f"museoncli html-documents +unshare --id {_DOCUMENT}"], + add_arguments=_add_share_arguments, + build_arguments=_build_share_arguments, + supports_dry_run=True, + ), CommandSpec( domain=domain, resource="folder", @@ -404,6 +517,8 @@ def specs() -> list[CommandSpec]: EXECUTORS = { "html-documents.upload": with_notes(_execute_upload), "html-documents.list": direct_enveloped(_execute_list), + "html-documents.share": with_notes(_execute_share), + "html-documents.unshare": direct_enveloped(_execute_unshare), "html-documents.folder-create": with_notes(_execute_folder_create), "html-documents.install-defaults": direct_enveloped(_execute_install_defaults), } diff --git a/skills/museon-content-workflow-base/references/task-index.md b/skills/museon-content-workflow-base/references/task-index.md index d26d6bf..6b6ace5 100644 --- a/skills/museon-content-workflow-base/references/task-index.md +++ b/skills/museon-content-workflow-base/references/task-index.md @@ -107,7 +107,7 @@ Public evidence from the web, social platforms, communities and ad libraries; Ho Who is in the organization and its billing; the organization's HTML document library; its Business Skills (methodology the Agent loads before strategic work); routines that run work on a schedule. - **Read members, roles and billing** (`org-members`): `museoncli organization member +list` → `museoncli organization billing +get` -- **Upload HTML documents into the organization library** (`html-documents`): `museoncli html-documents +list` → `museoncli html-documents folder +create` → `museoncli html-documents +upload` → `museoncli html-documents +install-defaults` +- **Upload and share HTML pages with customers** (`html-documents`): `museoncli html-documents +list` → `museoncli html-documents folder +create` → `museoncli html-documents +upload` → `museoncli html-documents +share` → `museoncli html-documents +unshare` → `museoncli html-documents +install-defaults` - **Use or write the organization's Business Skills** (`business-skills`): `museoncli skills +list` → `museoncli skills +get` → `museoncli skills +create` → `museoncli skills +update` - **Schedule recurring work (routines)** (`routines`): `museoncli routines +list` → `museoncli routines +get` → `museoncli routines +create-draft` → `museoncli routines +accept-draft` → `museoncli routines +create-ad-hoc` → `museoncli routines +rebuild-ad-hoc` → `museoncli routines +pause` → `museoncli routines +resume` → `museoncli routines +cancel` → `museoncli routines +get-memory` → `museoncli routines +record` diff --git a/tests/test_html_documents.py b/tests/test_html_documents.py index 78e1a96..8184c82 100644 --- a/tests/test_html_documents.py +++ b/tests/test_html_documents.py @@ -18,6 +18,7 @@ FOLDER = "72defd40-39ad-40d3-8105-8f23a9a016da" OTHER = "70000000-0000-4000-8000-000000000002" DOC = "11111111-1111-4111-8111-111111111111" +SHARE_URL = "https://museon.ai/share/html/test-random-token" LIBRARY = f"/api/v1/organizations/{ORG}/html-documents" @@ -35,6 +36,7 @@ def _document(html: str) -> dict: "slug": None, "updated_at": "2026-11-17T12:00:00Z", "html": html, + "share_url": SHARE_URL, } ) @@ -68,10 +70,14 @@ def test_upload_posts_title_html_basename_and_folder(monkeypatch, tmp_path: Path "filename": "guide.html", "folder_id": FOLDER, "html": html, + "is_shared": True, } assert "parent_id" not in body(sent) assert result["data"]["id"] == DOC - assert result["next_steps"] == ["museoncli html-documents +list"] + assert result["next_steps"] == [ + f"Share this link with your customer: {SHARE_URL}", + "museoncli html-documents +list", + ] def test_upload_omits_filename_when_the_basename_is_not_one_html_name( @@ -93,8 +99,8 @@ def test_upload_omits_filename_when_the_basename_is_not_one_html_name( ) assert [body(request) for request in server.requests] == [ - {"title": "Notes", "html": "<p>Notes</p>"}, - {"title": "Dotted", "html": "<p>Dotted</p>"}, + {"title": "Notes", "html": "<p>Notes</p>", "is_shared": True}, + {"title": "Dotted", "html": "<p>Dotted</p>", "is_shared": True}, ] @@ -189,6 +195,108 @@ def test_upload_dry_run_reads_the_file_and_sends_nothing(monkeypatch, tmp_path: assert arguments["dry_run"] is True assert "html" not in arguments assert "parent_id" not in arguments + assert arguments["private"] is False + + +@pytest.mark.parametrize("privacy_args", [["--private"], ["--args-json", '{"private":true}']]) +def test_private_upload_never_enables_sharing(monkeypatch, tmp_path: Path, privacy_args) -> None: + path = tmp_path / "private.html" + path.write_text("<p>Internal notes</p>", encoding="utf-8") + + def answer(request: httpx.Request) -> dict: + assert body(request)["is_shared"] is False + return _library({"id": DOC, "share_url": None}) + + server = Server({("POST", LIBRARY): answer}) + result = run( + monkeypatch, + server, + ["html-documents", "+upload", "--file", str(path), "--title", "Notes", *privacy_args], + ) + assert result["data"]["share_url"] is None + assert result["warnings"] == [] + assert result["next_steps"] == ["museoncli html-documents +list"] + + +@pytest.mark.parametrize("private", ["false", "true", None, 0, 1]) +def test_upload_rejects_ambiguous_privacy_values(monkeypatch, tmp_path: Path, private) -> None: + path = tmp_path / "private.html" + path.write_text("<p>Internal notes</p>", encoding="utf-8") + server = Server({}) + with pytest.raises(ValueError, match="private must be a boolean"): + run( + monkeypatch, + server, + [ + "html-documents", + "+upload", + "--file", + str(path), + "--title", + "Notes", + "--args-json", + json.dumps({"private": private}), + ], + ) + assert server.requests == [] + + +def test_upload_without_returned_share_link_does_not_claim_publication( + monkeypatch, tmp_path: Path +) -> None: + path = tmp_path / "guide.html" + path.write_text("<p>Notes</p>", encoding="utf-8") + server = Server({("POST", LIBRARY): _library({"id": DOC})}) + result = run( + monkeypatch, + server, + ["html-documents", "+upload", "--file", str(path), "--title", "Notes"], + ) + assert len(server.writes()) == 1 + assert result["warnings"] and "No share URL" in result["warnings"][0] + assert result["next_steps"] == ["museoncli html-documents +list"] + + +@pytest.mark.parametrize( + ("command", "method", "share_url"), + [("+share", "POST", SHARE_URL), ("+unshare", "DELETE", None)], +) +def test_sharing_targets_explicit_organization_without_rebuilding_links( + monkeypatch, command: str, method: str, share_url: str | None +) -> None: + path = f"/api/v1/organizations/{OTHER}/html-documents/{DOC}/share" + server = Server({(method, path): _library({"id": DOC, "share_url": share_url})}) + result = run( + monkeypatch, + server, + ["html-documents", command, "--id", DOC, "--organization-id", OTHER], + ) + assert len(server.requests) == 1 + request = server.requests[0] + assert request.headers["X-Organization-Id"] == OTHER + assert not request.content + assert result["data"]["share_url"] == share_url + assert result["organization"] == {"id": OTHER, "name": None} + if share_url: + assert share_url in result["next_steps"][0] + else: + assert result["next_steps"] == [] + + +@pytest.mark.parametrize("command", ["+share", "+unshare"]) +def test_sharing_dry_run_does_not_change_visibility(monkeypatch, command: str) -> None: + server = Server({}) + result = run(monkeypatch, server, ["html-documents", command, "--id", DOC, "--dry-run"]) + assert result["data"]["dry_run"] is True + assert server.requests == [] + + +@pytest.mark.parametrize("command", ["+share", "+unshare"]) +def test_sharing_refuses_noncanonical_document_ids(monkeypatch, command: str) -> None: + server = Server({}) + with pytest.raises(ValueError, match=r"--id.*canonical UUID"): + run(monkeypatch, server, ["html-documents", command, "--id", "customer-doc"]) + assert server.requests == [] @pytest.mark.parametrize( From 70ed0de7be3e3b2ded7c56f02dd8fe48d2ae3c60 Mon Sep 17 00:00:00 2001 From: Nicky Chu <nickychu@MacBook-Air-2.local> Date: Wed, 18 Nov 2026 01:20:14 +0800 Subject: [PATCH 2/3] feat: choose custom HTML share link names --- CHANGELOG.md | 8 +- README.md | 6 +- README.zh-CN.md | 5 +- contracts/command-catalog.json | 48 ++++++-- contracts/task-index.yaml | 6 +- docs/agent-discoverability.md | 6 +- docs/domain-command-framework.md | 6 +- docs/guide.md | 6 +- museoncli/domains/html_documents.py | 115 ++++++++++++++++--- museoncli/main.py | 3 + tests/test_html_documents.py | 166 ++++++++++++++++++++++++++++ 11 files changed, 335 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 897e110..d393088 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,13 @@ Museon CLI follows semantic versioning for its package and command contract. Existing documents and built-in guides remain private until explicitly shared. - New `html-documents +share --id <document-id>` and `+unshare --id <document-id>` enable and stop link access without uploading a duplicate document. An active - link is reused; after stopping sharing, enabling it again returns a new link. + link is reused. After stopping sharing, enabling it restores a reserved custom + name or creates a new random link. +- `+upload` and `+share` accept `--share-slug manus-proposal` for a customer URL + such as `museon.ai/share/manus-proposal`. `+share --random-link` clears the custom + name; omitted options preserve it. Private uploads can reserve a name without + making the document public. Renamed names stop resolving and stay reserved to + the same document, so another document cannot take over an old customer link. - Migration: scripts uploading internal HTML must add `--private` before upgrading. Deploy the corresponding HTML-sharing API before releasing this CLI change. This visibility-default change requires a major version release. diff --git a/README.md b/README.md index c139161..2771f86 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,11 @@ HTML uploads now enable link sharing by default. Use and give the customer the returned `data.share_url`. Anyone with that link can open it. For internal material, add `--private`; existing documents remain private until explicitly shared with `html-documents +share --id <document-id>`. `+unshare --id <document-id>` -stops new visits through the current link; sharing again creates a new link. +stops new visits through the current link; sharing again restores a custom name +or creates a new random link. Add `--share-slug manus-proposal` when uploading or +sharing to choose `museon.ai/share/manus-proposal`. A private upload can reserve +that name without making the document public. To return to a random link, use +`html-documents +share --id <document-id> --random-link`. Use `+list` to recover document IDs and share URLs after an uncertain upload result; uploading again creates another document. This change requires the HTML-sharing API release. diff --git a/README.zh-CN.md b/README.zh-CN.md index e89f85a..47f84ea 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -71,7 +71,10 @@ HTML 上传现在默认开启链接分享。执行 `museoncli html-documents +upload --file ./proposal.html --title "客户方案"`, 把返回的 `data.share_url` 发给客户,对方无需登录即可打开,任何持有链接的人均可查看。 内部资料请加 `--private`;已有文档仍保持私密,直到用 `html-documents +share --id <文档ID>` -主动开启分享。`+unshare --id <文档ID>` 停止通过当前链接访问;重新分享会生成新链接。 +主动开启分享。`+unshare --id <文档ID>` 停止通过当前链接访问;重新分享恢复预留的自定义名, +没有自定义名时生成新的随机链接。上传或分享时加 `--share-slug manus-proposal`,即可选择 +`museon.ai/share/manus-proposal`;私有上传也能预留名字,文档仍不会公开。 +用 `html-documents +share --id <文档ID> --random-link` 可清空自定义名、切回随机链接。 上传结果不确定时先用 `+list` 找回文档和分享链接,重复上传会新建文档。 此改动依赖支持 HTML 分享的服务端版本。 diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index 2d8868b..dd0697e 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -11872,7 +11872,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "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. 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.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11926,7 +11926,7 @@ "risk_level": "write", "shortcut": "+share", "stability": "stable", - "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. An active link is reused; after +unshare this creates a new link and the old one stays invalid. Needs asset edit on the organization; the server decides.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11953,7 +11953,7 @@ "risk_level": "write", "shortcut": "+unshare", "stability": "stable", - "summary": "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 it again creates a new link. Needs asset edit on the organization; the server decides.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -64756,7 +64756,7 @@ }, "name": "html-documents.list", "output_schema": { - "description": "data: folders (id, name, document_count), root_count, and documents (id, title, filename, folder_id, slug, updated_at, share_url). share_url is null when sharing is off.", + "description": "data: folders (id, name, document_count), root_count, and documents (id, title, filename, folder_id, slug, updated_at, share_slug, share_url). share_url is null when sharing is off.", "properties": { "command": { "type": "string" @@ -64836,7 +64836,9 @@ "cli": "museoncli html-documents +share", "domain": "html-documents", "examples": [ - "museoncli html-documents +share --id 11111111-1111-4111-8111-111111111111" + "museoncli html-documents +share --id 11111111-1111-4111-8111-111111111111", + "museoncli html-documents +share --id 11111111-1111-4111-8111-111111111111 --share-slug manus-proposal", + "museoncli html-documents +share --id 11111111-1111-4111-8111-111111111111 --random-link" ], "execution": "direct", "input_schema": { @@ -64850,6 +64852,21 @@ "description": "Document to share or stop sharing (html-documents +list). Canonical UUID copied from a previous command response; never a placeholder.", "format": "uuid", "type": "string" + }, + "random_link": { + "default": false, + "description": "Clear the custom link name and switch to a random link. Cannot be combined with share_slug.", + "type": "boolean" + }, + "share_slug": { + "description": "Custom customer link name, e.g. manus-proposal for museon.ai/share/manus-proposal. 3-80 letters/digits separated by single hyphens; normalized to lowercase. The server checks reserved and taken names. Private uploads may reserve a name without enabling sharing. Null uses a random link.", + "maxLength": 80, + "minLength": 3, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", + "type": [ + "string", + "null" + ] } }, "required": [ @@ -64859,7 +64876,7 @@ }, "name": "html-documents.share", "output_schema": { - "description": "data: the document with share_url. Give this URL to the customer exactly as returned.", + "description": "data: the document with share_slug and share_url. Give this URL to the customer exactly as returned.", "properties": { "command": { "type": "string" @@ -64918,7 +64935,7 @@ "risk_level": "write", "shortcut": "+share", "stability": "stable", - "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. An active link is reused; after +unshare this creates a new link and the old one stays invalid. Needs asset edit on the organization; the server decides.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -65021,7 +65038,7 @@ "risk_level": "write", "shortcut": "+unshare", "stability": "stable", - "summary": "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 it again creates a new link. Needs asset edit on the organization; the server decides.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -65043,6 +65060,7 @@ "domain": "html-documents", "examples": [ "museoncli html-documents +upload --file ./proposal.html --title \"Customer proposal\"", + "museoncli html-documents +upload --file ./proposal.html --title \"Manus proposal\" --share-slug manus-proposal", "museoncli html-documents +upload --file ./guide.html --title \"Architecture notes\" --private --filename guide.html --folder-id 72defd40-39ad-40d3-8105-8f23a9a016da" ], "execution": "direct", @@ -65075,6 +65093,16 @@ "description": "Keep the upload inside the organization. By default it is shared: anyone with the returned share_url can open it without signing in.", "type": "boolean" }, + "share_slug": { + "description": "Custom customer link name, e.g. manus-proposal for museon.ai/share/manus-proposal. 3-80 letters/digits separated by single hyphens; normalized to lowercase. The server checks reserved and taken names. Private uploads may reserve a name without enabling sharing. Null uses a random link.", + "maxLength": 80, + "minLength": 3, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", + "type": [ + "string", + "null" + ] + }, "title": { "description": "Document title.", "maxLength": 200, @@ -65090,7 +65118,7 @@ }, "name": "html-documents.upload", "output_schema": { - "description": "data: id, title, filename, folder_id, slug, updated_at, html, share_url. Give the customer share_url exactly as returned; it is null for private uploads.", + "description": "data: id, title, filename, folder_id, slug, updated_at, html, share_slug, share_url. Give the customer share_url exactly as returned; it is null for private uploads.", "properties": { "command": { "type": "string" @@ -65149,7 +65177,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "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. 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.", + "summary": "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.", "supports_dry_run": true, "transport": "agent_cli_api" }, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index 31b3843..4be993b 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -874,9 +874,9 @@ chapters: steps: - html-documents.list: "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 the returned share_url. Anyone with the link can open it without signing in. Use --private for organization-only documents. A second upload creates a second document; after an unknown result, list before retrying." - - html-documents.share: "Enable sharing for an existing document; reuses its active link. Share only content intended for anyone with the link." - - html-documents.unshare: "Stop new visits through the current link. The document stays in the library; sharing again creates a new link." + - 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." + - html-documents.unshare: "Stop new visits through the current link. Sharing again restores the reserved custom name, or creates a new random link." - html-documents.install-defaults: "Copies the three built-in guides into this organization. A second call does not duplicate them." - id: business-skills title: Use or write the organization's Business Skills diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index d4fa6f6..71ebad8 100644 --- a/docs/agent-discoverability.md +++ b/docs/agent-discoverability.md @@ -608,10 +608,10 @@ 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. 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 +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. An active link is reused; after +unshare this creates a new link and the old one stays invalid. 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 it again creates a new link. Needs asset edit on the organization; 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. | diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index d6ee0c4..3ce843c 100644 --- a/docs/domain-command-framework.md +++ b/docs/domain-command-framework.md @@ -642,10 +642,10 @@ 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. 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 +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. An active link is reused; after +unshare this creates a new link and the old one stays invalid. 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 it again creates a new link. Needs asset edit on the organization; 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. | diff --git a/docs/guide.md b/docs/guide.md index a575531..f2fbf94 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -802,9 +802,9 @@ See: `organizations` 1. `museoncli html-documents +list` (read): 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 the returned share_url. Anyone with the link can open it without signing in. Use --private for organization-only documents. 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; reuses its active link. Share only content intended for anyone with the link. -5. `museoncli html-documents +unshare --id <html-documents-id>` (write): Stop new visits through the current link. The document stays in the library; sharing again creates a new link. +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. +5. `museoncli html-documents +unshare --id <html-documents-id>` (write): Stop new visits through the current link. Sharing again restores the reserved custom name, or creates a new random link. 6. `museoncli html-documents +install-defaults` (write): Copies the three built-in guides into this organization. A second call does not duplicate them. ### Use or write the organization's Business Skills diff --git a/museoncli/domains/html_documents.py b/museoncli/domains/html_documents.py index f610f40..225dc3d 100644 --- a/museoncli/domains/html_documents.py +++ b/museoncli/domains/html_documents.py @@ -8,6 +8,7 @@ from __future__ import annotations import argparse +import re from pathlib import Path from typing import Any @@ -33,6 +34,18 @@ _FOLDER = "72defd40-39ad-40d3-8105-8f23a9a016da" _DOCUMENT = "11111111-1111-4111-8111-111111111111" _EDIT = " Needs asset edit on the organization; the server decides." +_SHARE_SLUG = { + "type": ["string", "null"], + "minLength": 3, + "maxLength": 80, + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", + "description": ( + "Custom customer link name, e.g. manus-proposal for museon.ai/share/manus-proposal. " + "3-80 letters/digits separated by single hyphens; normalized to lowercase. " + "The server checks reserved and taken names. Private uploads may reserve a name " + "without enabling sharing. Null uses a random link." + ), +} _UPLOAD = { "file": string_property("Local HTML file to upload.", max_length=4096), @@ -44,6 +57,7 @@ max_length=_MAX_FILENAME, ), "folder_id": uuid_property("Folder to store the document in (html-documents +list)."), + "share_slug": _SHARE_SLUG, "private": { "type": "boolean", "default": False, @@ -70,10 +84,22 @@ "dry_run": DRY_RUN_PROPERTY, } _INSTALL = {"dry_run": DRY_RUN_PROPERTY} -_SHARE = { +_DOCUMENT_ACTION = { "id": uuid_property("Document to share or stop sharing (html-documents +list)."), "dry_run": DRY_RUN_PROPERTY, } +_SHARE = { + **_DOCUMENT_ACTION, + "share_slug": _SHARE_SLUG, + "random_link": { + "type": "boolean", + "default": False, + "description": ( + "Clear the custom link name and switch to a random link. " + "Cannot be combined with share_slug." + ), + }, +} def _basename(value: str) -> str: @@ -183,6 +209,8 @@ async def _execute_upload(ctx: CommandContext) -> Any: body["filename"] = filename if arguments.get("folder_id"): body["folder_id"] = arguments["folder_id"] + if "share_slug" in arguments: + body["share_slug"] = arguments["share_slug"] data = await ctx.api_data( ctx.cfg, "POST", @@ -207,10 +235,16 @@ def _sharing_result(data: Any, *, shared: bool) -> tuple[Any, list[str], list[st async def _execute_share(ctx: CommandContext) -> Any: + body: dict[str, Any] = {} + if ctx.arguments.get("random_link"): + body["share_slug"] = None + elif "share_slug" in ctx.arguments: + body["share_slug"] = ctx.arguments["share_slug"] data = await ctx.api_data( ctx.cfg, "POST", f"{_library(require_organization(ctx))}/{ctx.arguments['id']}/share", + json_body=body or None, ) return _sharing_result(data, shared=True) @@ -272,6 +306,7 @@ def _add_upload_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--title") parser.add_argument("--filename") parser.add_argument("--folder-id", dest="folder_id") + parser.add_argument("--share-slug", dest="share_slug") parser.add_argument( "--private", action="store_true", @@ -281,12 +316,15 @@ def _add_upload_arguments(parser: argparse.ArgumentParser) -> None: def _build_upload_arguments(args: argparse.Namespace) -> dict[str, Any]: - payload = merged_input(args, ("file", "title", "filename", "folder_id", "private")) + payload = merged_input( + args, ("file", "title", "filename", "folder_id", "private", "share_slug") + ) reject_unknown(payload, _UPLOAD) require(payload, "file", "title") private = payload.setdefault("private", False) if not isinstance(private, bool): raise ValueError("private must be a boolean (true or false).") + _normalize_share_slug(payload) title = str(payload["title"]).strip() if not 1 <= len(title) <= 200: raise ValueError("--title must be 1-200 characters.") @@ -365,17 +403,51 @@ def _build_install_arguments(args: argparse.Namespace) -> dict[str, Any]: return payload -def _add_share_arguments(parser: argparse.ArgumentParser) -> None: +def _normalize_share_slug(payload: dict[str, Any]) -> None: + value = payload.get("share_slug") + if value is None: + return + if not isinstance(value, str): + raise ValueError("--share-slug must be text or null.") + value = value.strip().lower() + if not 3 <= len(value) <= 80 or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", value): + raise ValueError("--share-slug must be 3-80 letters/digits separated by single hyphens.") + payload["share_slug"] = value + + +def _add_document_arguments(parser: argparse.ArgumentParser) -> None: add_structured_arguments(parser) parser.add_argument("--id") parser.add_argument("--dry-run", action="store_true") -def _build_share_arguments(args: argparse.Namespace) -> dict[str, Any]: +def _add_share_arguments(parser: argparse.ArgumentParser) -> None: + _add_document_arguments(parser) + choice = parser.add_mutually_exclusive_group() + choice.add_argument("--share-slug", dest="share_slug") + choice.add_argument("--random-link", action="store_true") + + +def _build_document_arguments(args: argparse.Namespace) -> dict[str, Any]: payload = merged_input(args, ("id",)) + reject_unknown(payload, _DOCUMENT_ACTION) + require(payload, "id") + payload["id"] = uuid_arg(str(payload["id"]), flag="--id", lookup=_id_lookup_hint()) + _dry_run(args, payload) + return payload + + +def _build_share_arguments(args: argparse.Namespace) -> dict[str, Any]: + payload = merged_input(args, ("id", "share_slug", "random_link")) reject_unknown(payload, _SHARE) require(payload, "id") payload["id"] = uuid_arg(str(payload["id"]), flag="--id", lookup=_id_lookup_hint()) + random_link = payload.get("random_link", False) + if not isinstance(random_link, bool): + raise ValueError("random_link must be a boolean (true or false).") + if random_link and "share_slug" in payload: + raise ValueError("Use only one of --share-slug and --random-link.") + _normalize_share_slug(payload) _dry_run(args, payload) return payload @@ -389,7 +461,8 @@ def specs() -> list[CommandSpec]: summary=( "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. The stored filename is " + "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: " @@ -400,11 +473,15 @@ def specs() -> list[CommandSpec]: adapter_tool_name="html_documents_upload", input_schema=schema(_UPLOAD, ["file", "title"]), output_schema=output_schema( - "data: id, title, filename, folder_id, slug, updated_at, html, share_url. " + "data: id, title, filename, folder_id, slug, updated_at, html, share_slug, share_url. " "Give the customer share_url exactly as returned; it is null for private uploads." ), examples=[ 'museoncli html-documents +upload --file ./proposal.html --title "Customer proposal"', + ( + "museoncli html-documents +upload --file ./proposal.html " + '--title "Manus proposal" --share-slug manus-proposal' + ), ( "museoncli html-documents +upload --file ./guide.html " f'--title "Architecture notes" --private --filename guide.html --folder-id {_FOLDER}' @@ -428,7 +505,7 @@ def specs() -> list[CommandSpec]: input_schema=schema(_LIST), output_schema=output_schema( "data: folders (id, name, document_count), root_count, and documents " - "(id, title, filename, folder_id, slug, updated_at, share_url). " + "(id, title, filename, folder_id, slug, updated_at, share_slug, share_url). " "share_url is null when sharing is off." ), examples=["museoncli html-documents +list --q architecture --folder root"], @@ -440,17 +517,24 @@ def specs() -> list[CommandSpec]: shortcut="+share", summary=( "Enable customer sharing for one existing HTML document. Anyone with the " - "returned share_url can view it without signing in. An active link is reused; " - "after +unshare this creates a new link and the old one stays invalid." + _EDIT + "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." + _EDIT ), risk_level="write", execution="direct", adapter_tool_name="html_documents_share", input_schema=schema(_SHARE, ["id"]), output_schema=output_schema( - "data: the document with share_url. Give this URL to the customer exactly as returned." + "data: the document with share_slug and share_url. " + "Give this URL to the customer exactly as returned." ), - examples=[f"museoncli html-documents +share --id {_DOCUMENT}"], + examples=[ + f"museoncli html-documents +share --id {_DOCUMENT}", + f"museoncli html-documents +share --id {_DOCUMENT} --share-slug manus-proposal", + f"museoncli html-documents +share --id {_DOCUMENT} --random-link", + ], add_arguments=_add_share_arguments, build_arguments=_build_share_arguments, supports_dry_run=True, @@ -461,16 +545,17 @@ def specs() -> list[CommandSpec]: summary=( "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 it again creates a new link." + _EDIT + "stays in the organization library. Sharing again restores its custom name " + "when one is reserved, or creates a new random link." + _EDIT ), risk_level="write", execution="direct", adapter_tool_name="html_documents_unshare", - input_schema=schema(_SHARE, ["id"]), + input_schema=schema(_DOCUMENT_ACTION, ["id"]), output_schema=output_schema("data: the document with share_url set to null."), examples=[f"museoncli html-documents +unshare --id {_DOCUMENT}"], - add_arguments=_add_share_arguments, - build_arguments=_build_share_arguments, + add_arguments=_add_document_arguments, + build_arguments=_build_document_arguments, supports_dry_run=True, ), CommandSpec( diff --git a/museoncli/main.py b/museoncli/main.py index f22aedd..e80c86d 100644 --- a/museoncli/main.py +++ b/museoncli/main.py @@ -137,6 +137,9 @@ def cli_outdated_error(response: httpx.Response) -> CliOutdatedError: "invalid_folder_name": "Enter a folder name.", "invalid_slug": "Slug is not valid.", "slug_taken": "A document with this slug already exists.", + "invalid_share_slug": "Use a share link name of 3-80 letters/digits separated by single hyphens.", + "share_slug_reserved": "This share link name is reserved. Choose another name.", + "share_slug_taken": "This share link name belongs to another document. Choose another name.", "invalid_document": "Document could not be saved.", } diff --git a/tests/test_html_documents.py b/tests/test_html_documents.py index 8184c82..0829d9e 100644 --- a/tests/test_html_documents.py +++ b/tests/test_html_documents.py @@ -299,6 +299,172 @@ def test_sharing_refuses_noncanonical_document_ids(monkeypatch, command: str) -> assert server.requests == [] +@pytest.mark.parametrize("private", [False, True]) +def test_upload_custom_name_does_not_override_privacy(monkeypatch, tmp_path: Path, private) -> None: + path = tmp_path / "proposal.html" + path.write_text("<p>Proposal</p>", encoding="utf-8") + share_url = None if private else "https://museon.ai/share/manus-proposal" + server = Server( + { + ("POST", LIBRARY): _library( + { + "id": DOC, + "share_slug": "manus-proposal", + "share_url": share_url, + } + ) + } + ) + result = run( + monkeypatch, + server, + [ + "html-documents", + "+upload", + "--file", + str(path), + "--title", + "Proposal", + "--share-slug", + " Manus-Proposal ", + *(["--private"] if private else []), + ], + ) + sent = body(server.requests[0]) + assert sent["share_slug"] == "manus-proposal" + assert sent["is_shared"] is not private + assert result["data"]["share_url"] == share_url + + +@pytest.mark.parametrize( + ("options", "expected"), + [ + ([], None), + (["--share-slug", " Manus-Proposal "], {"share_slug": "manus-proposal"}), + (["--args-json", '{"share_slug":"manus-proposal"}'], {"share_slug": "manus-proposal"}), + (["--random-link"], {"share_slug": None}), + (["--args-json", '{"share_slug":null}'], {"share_slug": None}), + (["--args-json", '{"random_link":true}'], {"share_slug": None}), + (["--args-json", '{"random_link":false}'], None), + ], +) +def test_share_distinguishes_keep_name_rename_and_clear(monkeypatch, options, expected) -> None: + server = Server( + {("POST", f"{LIBRARY}/{DOC}/share"): _library({"id": DOC, "share_url": SHARE_URL})} + ) + run(monkeypatch, server, ["html-documents", "+share", "--id", DOC, *options]) + assert len(server.requests) == 1 + assert body(server.requests[0]) == expected + + +@pytest.mark.parametrize( + "slug", ["", "ab", "a" * 81, "has space", "../page", "a--b", "-abc", "abc-", 4] +) +def test_share_rejects_invalid_custom_name_without_a_write(monkeypatch, slug) -> None: + server = Server({}) + with pytest.raises(ValueError, match="--share-slug"): + run( + monkeypatch, + server, + [ + "html-documents", + "+share", + "--id", + DOC, + "--args-json", + json.dumps({"share_slug": slug}), + ], + ) + assert server.requests == [] + + +@pytest.mark.parametrize( + "payload", + [ + {"share_slug": "manus-proposal", "random_link": True}, + {"share_slug": None, "random_link": True}, + {"random_link": "false"}, + ], +) +def test_share_rejects_ambiguous_link_choices(monkeypatch, payload) -> None: + server = Server({}) + with pytest.raises(ValueError): + run( + monkeypatch, + server, + [ + "html-documents", + "+share", + "--id", + DOC, + "--args-json", + json.dumps(payload), + ], + ) + assert server.requests == [] + + +def test_custom_name_dry_run_does_not_reserve_name(monkeypatch) -> None: + server = Server({}) + result = run( + monkeypatch, + server, + [ + "html-documents", + "+share", + "--id", + DOC, + "--share-slug", + "manus-proposal", + "--dry-run", + ], + ) + assert result["data"]["arguments"]["share_slug"] == "manus-proposal" + assert server.requests == [] + + +@pytest.mark.parametrize( + ("code", "status", "message"), + [ + ( + "share_slug_taken", + 409, + "This share link name belongs to another document. Choose another name.", + ), + ("share_slug_reserved", 422, "This share link name is reserved. Choose another name."), + ( + "invalid_share_slug", + 422, + "Use a share link name of 3-80 letters/digits separated by single hyphens.", + ), + ], +) +def test_custom_name_refusals_preserve_server_code_without_retry( + monkeypatch, code, status, message +) -> None: + requests = [] + + def answer(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response(status, json={"detail": {"code": code}}) + + payload = _refused( + monkeypatch, + answer, + [ + "html-documents", + "+share", + "--id", + DOC, + "--share-slug", + "manus-proposal", + ], + ) + assert payload["error"]["server_code"] == code + assert payload["error"]["message"] == message + assert len(requests) == 1 + + @pytest.mark.parametrize( "prepare", [ From 7481c73f6b6e5a0212e2f4e60091a1972d428c96 Mon Sep 17 00:00:00 2001 From: Nicky Chu <nickychu@MacBook-Air-2.local> Date: Wed, 18 Nov 2026 01:31:17 +0800 Subject: [PATCH 3/3] chore: prepare v3.0.0 HTML sharing release --- CHANGELOG.md | 4 ++-- README.md | 2 +- README.zh-CN.md | 2 +- contracts/command-catalog.json | 2 +- docs/guide.md | 2 +- docs/install.md | 12 ++++++------ docs/llms.txt | 2 +- pyproject.toml | 2 +- skills/museon-content-workflow-base/SKILL.md | 2 +- .../references/task-index.md | 2 +- uv.lock | 2 +- 11 files changed, 17 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d393088..f648f73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ Museon CLI follows semantic versioning for its package and command contract. -## Unreleased +## 3.0.0 - HTML uploads now enable customer link sharing by default and return `data.share_url`. Anyone with that link can view the document without signing in. Add `--private` @@ -19,7 +19,7 @@ Museon CLI follows semantic versioning for its package and command contract. the same document, so another document cannot take over an old customer link. - Migration: scripts uploading internal HTML must add `--private` before upgrading. Deploy the corresponding HTML-sharing API before releasing this CLI change. - This visibility-default change requires a major version release. + This major release changes the upload visibility default. ## 2.3.1 diff --git a/README.md b/README.md index 2771f86..781342e 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ If you prefer to install the CLI yourself, use Python 3.11+, `uv`, and the exact wheel from the official GitHub release: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.3.1/museoncli-2.3.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.0.0/museoncli-3.0.0-py3-none-any.whl" ``` Then continue with Skill setup and browser authorization: diff --git a/README.zh-CN.md b/README.zh-CN.md index 47f84ea..8340236 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -122,7 +122,7 @@ MuseOn 只有组织:访问权限由组织角色加 Campaign 范围决定。每 固定版本的 wheel: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.3.1/museoncli-2.3.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.0.0/museoncli-3.0.0-py3-none-any.whl" ``` 安装成功后继续配置 Skills 和浏览器授权: diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index dd0697e..ca1388d 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -18529,7 +18529,7 @@ "html-documents" ] }, - "contract_revision": "2.3.1", + "contract_revision": "3.0.0", "package": "museoncli", "schema_version": 3, "schemas": { diff --git a/docs/guide.md b/docs/guide.md index f2fbf94..e598b14 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,6 +1,6 @@ <!-- Generated by scripts/gen_task_index.py from contracts/task-index.yaml. Do not edit by hand. --> -# Museon CLI task guide (2.3.1) +# Museon CLI task guide (3.0.0) Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (set up, recruit, approve, contract, daily tasks, content review, counting, client reports), content tracking Campaigns, analytics boards, social accounts and publishing, AI image posts, research and the organization. Find the task below, then run its commands in order. Every command prints one JSON envelope; reads change nothing; a write that reaches someone outside the organization or cannot be undone needs --yes, which only the user may give. diff --git a/docs/install.md b/docs/install.md index c04ae72..0ff9915 100644 --- a/docs/install.md +++ b/docs/install.md @@ -70,7 +70,7 @@ If the command is unavailable: reviewed wheel from the official GitHub release: ```bash - uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.3.1/museoncli-2.3.1-py3-none-any.whl" + uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.0.0/museoncli-3.0.0-py3-none-any.whl" ``` Do not clone the repository, install from a mutable branch, or substitute a @@ -103,11 +103,11 @@ or `current` and includes their destination paths. For another Agent that supports Skills, use that Agent's native Skill installer to install the workflow Skill folders and Hook Analysis Skill: -https://github.com/Museon-AI/museon-cli/tree/v2.3.1/skills/museon-content-workflow-base -https://github.com/Museon-AI/museon-cli/tree/v2.3.1/skills/museon-research -https://github.com/Museon-AI/museon-cli/tree/v2.3.1/skills/museon-content-workflow-hireaicreator -https://github.com/Museon-AI/museon-cli/tree/v2.3.1/skills/museon-content-workflow-ai-slideshow -https://github.com/Museon-AI/museon-cli/tree/v2.3.1/skills/museon-content-workflow-campaigns +https://github.com/Museon-AI/museon-cli/tree/v3.0.0/skills/museon-content-workflow-base +https://github.com/Museon-AI/museon-cli/tree/v3.0.0/skills/museon-research +https://github.com/Museon-AI/museon-cli/tree/v3.0.0/skills/museon-content-workflow-hireaicreator +https://github.com/Museon-AI/museon-cli/tree/v3.0.0/skills/museon-content-workflow-ai-slideshow +https://github.com/Museon-AI/museon-cli/tree/v3.0.0/skills/museon-content-workflow-campaigns Do not invent a Skill directory for an unsupported host. If the Agent has no native Skill installation mechanism, finish the CLI authorization steps and diff --git a/docs/llms.txt b/docs/llms.txt index 920a217..7dd3b76 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -7,7 +7,7 @@ Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (s ## Start - [Install guide](https://www.museon.ai/cli/install.md): install the CLI and its Agent Skills, sign in, choose an organization. -- [Task guide](https://www.museon.ai/cli/guide.md): every task as ordered commands with their required flags, risk and gotchas (Museon CLI 2.3.1). +- [Task guide](https://www.museon.ai/cli/guide.md): every task as ordered commands with their required flags, risk and gotchas (Museon CLI 3.0.0). - Offline, the CLI answers the same: `museoncli guide`, `museoncli guide <task-id>`, `museoncli guide --search <words>`, `museoncli schema <command>`. ## Tasks diff --git a/pyproject.toml b/pyproject.toml index cc1c740..ab5b2c4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "museoncli" -version = "2.3.1" +version = "3.0.0" description = "Agent-ready CLI for Museon's social media operating platform" readme = "README.md" license = "Apache-2.0" diff --git a/skills/museon-content-workflow-base/SKILL.md b/skills/museon-content-workflow-base/SKILL.md index 8bfd20a..873c474 100644 --- a/skills/museon-content-workflow-base/SKILL.md +++ b/skills/museon-content-workflow-base/SKILL.md @@ -49,7 +49,7 @@ verify `museoncli version`, then resume the original task: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.3.1/museoncli-2.3.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v3.0.0/museoncli-3.0.0-py3-none-any.whl" ``` Read [operating-model.md](references/operating-model.md) for risk, async work, authentication, diff --git a/skills/museon-content-workflow-base/references/task-index.md b/skills/museon-content-workflow-base/references/task-index.md index 6b6ace5..bd48a2e 100644 --- a/skills/museon-content-workflow-base/references/task-index.md +++ b/skills/museon-content-workflow-base/references/task-index.md @@ -1,6 +1,6 @@ <!-- Generated by scripts/gen_task_index.py from contracts/task-index.yaml. Do not edit by hand. --> -# Task index (Museon CLI 2.3.1) +# Task index (Museon CLI 3.0.0) Museon CLI runs MuseOn's social-media operations from an Agent: UGC Campaigns (set up, recruit, approve, contract, daily tasks, content review, counting, client reports), content tracking Campaigns, analytics boards, social accounts and publishing, AI image posts, research and the organization. Find the task below, then run its commands in order. Every command prints one JSON envelope; reads change nothing; a write that reaches someone outside the organization or cannot be undone needs --yes, which only the user may give. diff --git a/uv.lock b/uv.lock index 15562da..1c3fdec 100644 --- a/uv.lock +++ b/uv.lock @@ -330,7 +330,7 @@ wheels = [ [[package]] name = "museoncli" -version = "2.3.1" +version = "3.0.0" source = { editable = "." } dependencies = [ { name = "anyio" },