diff --git a/CHANGELOG.md b/CHANGELOG.md index e073a19..012dfc0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ Museon CLI follows semantic versioning for its package and command contract. +## 2.1.0 + +Agentic Creative Campaign publish time and one-off Plan posts. + +- `agentic-campaign +campaign-create` / `+campaign-update --publish-timezone `: the Campaign publish time is `--preferred-publish-windows-json` read in this timezone for every member account (default `Asia/Shanghai`). Both may change while the Campaign is active; future slots that have not started generating move to the new time. The help no longer says config is setup-only. +- New `agentic-campaign plan +extra-post`: one more post for one Plan member outside the daily cadence (for example a missed day), from the Plan's current reference pairs, generated and published by Museon, idempotent per `--idempotency-key`. +- `ai-slideshow publish +create-schedule`, `+preview-schedule-plan` and `+submit-schedule-plan` explain Agentic Campaign accounts: a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is publishing; pairs outside the Plan are rejected with `AGENTIC_PLAN_PAIR_NOT_IN_PLAN`; `plan +extra-post` adds a post on top. The managed-publishing skill and task guide say the same and ask to agree the publish time before admitting accounts. + ## 2.0.1 Fixes from a production sweep of 2.0.0. diff --git a/README.md b/README.md index 81a4b22..c8c9d9c 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,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.0.1/museoncli-2.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.1.0/museoncli-2.1.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 927778d..85139f6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -111,7 +111,7 @@ MuseOn 只有组织:访问权限由组织角色加 Campaign 范围决定。每 固定版本的 wheel: ```bash -uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.0.1/museoncli-2.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.1.0/museoncli-2.1.0-py3-none-any.whl" ``` 安装成功后继续配置 Skills 和浏览器授权: diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index d3da298..0f8d92f 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -81,6 +81,34 @@ "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", + "workspace_bound": true + }, + "capability_key": "agentic-campaign.plan-extra-post", + "cli": "museoncli agentic-campaign plan +extra-post", + "domain": "agentic-campaign", + "execution": "direct", + "name": "agentic-campaign.plan-extra-post", + "requires_confirmation": false, + "resource": "plan", + "risk_level": "write", + "shortcut": "+extra-post", + "stability": "stable", + "summary": "Schedule one more post for one member account of a Plan, outside its daily cadence (for example to make up a missed day). The post uses one of the Plan's current reference pairs (--element-id, or the Plan's rotation when omitted), is generated and published by Museon like the daily posts, and neither replaces nor occupies that day's daily post. The account must be a member with automatic execution enabled, and --scheduled-at (ISO-8601 with offset) at least 30 minutes ahead. Use this instead of `ai-slideshow publish` schedules for Agentic Campaign accounts.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, { "authorization": { "authentication_required": true, @@ -397,7 +425,7 @@ "risk_level": "write", "shortcut": "+campaign-update", "stability": "stable", - "summary": "Patch only supplied campaign fields. Budget and config fields are setup-only; name must be changed by itself. Field-level hashtag, mention, and publish-window options merge into existing config, while --config-json replaces the full config.", + "summary": "Patch only supplied campaign fields; name must be changed by itself. Field-level hashtag, mention, publish-window and publish-timezone options merge into existing config, while --config-json replaces the full config. The publish time is --preferred-publish-windows-json read in --publish-timezone (IANA, default Asia/Shanghai) for every member account; both can change while the campaign is active, and future not-yet-generated slots move to the new time.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -1791,7 +1819,7 @@ "risk_level": "read", "shortcut": "+preview-schedule-plan", "stability": "stable", - "summary": "Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission.", + "summary": "Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`.", "supports_dry_run": false, "transport": "agent_cli_api" }, @@ -1824,7 +1852,7 @@ "risk_level": "destructive", "shortcut": "+submit-schedule-plan", "stability": "stable", - "summary": "Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them.", + "summary": "On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -2253,7 +2281,7 @@ "risk_level": "write", "shortcut": "+create-schedule", "stability": "stable", - "summary": "Create one manual account publish schedule item.", + "summary": "Create one manual account publish schedule item. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -18308,7 +18336,7 @@ "organization" ] }, - "contract_revision": "2.0.1", + "contract_revision": "2.1.0", "package": "museoncli", "schema_version": 3, "schemas": { @@ -18592,6 +18620,11 @@ }, "type": "array" }, + "publish_timezone": { + "description": "IANA timezone every member account reads the publish windows in, for example Europe/London. Defaults to Asia/Shanghai.", + "maxLength": 64, + "type": "string" + }, "required_hashtags": { "default": [], "items": { @@ -18993,7 +19026,8 @@ "domain": "agentic-campaign", "examples": [ "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --total-account-budget 107 --yes", - "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --bind-notification-conversation --yes" + "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --bind-notification-conversation --yes", + "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --preferred-publish-windows-json '[{\"start\":\"20:00\",\"end\":\"20:01\"}]' --publish-timezone Europe/London --yes" ], "execution": "direct", "input_schema": { @@ -19034,6 +19068,11 @@ }, "type": "array" }, + "publish_timezone": { + "description": "IANA timezone every member account reads the publish windows in, for example Europe/London. Defaults to Asia/Shanghai.", + "maxLength": 64, + "type": "string" + }, "required_hashtags": { "default": [], "items": { @@ -19103,6 +19142,11 @@ "format": "uuid", "type": "string" }, + "publish_timezone": { + "description": "IANA timezone every member account reads the publish windows in, for example Europe/London. Defaults to Asia/Shanghai.", + "maxLength": 64, + "type": "string" + }, "required_hashtags": { "default": [], "items": { @@ -19198,7 +19242,7 @@ "risk_level": "write", "shortcut": "+campaign-update", "stability": "stable", - "summary": "Patch only supplied campaign fields. Budget and config fields are setup-only; name must be changed by itself. Field-level hashtag, mention, and publish-window options merge into existing config, while --config-json replaces the full config.", + "summary": "Patch only supplied campaign fields; name must be changed by itself. Field-level hashtag, mention, publish-window and publish-timezone options merge into existing config, while --config-json replaces the full config. The publish time is --preferred-publish-windows-json read in --publish-timezone (IANA, default Asia/Shanghai) for every member account; both can change while the campaign is active, and future not-yet-generated slots move to the new time.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -19981,6 +20025,157 @@ "supports_dry_run": true, "transport": "agent_cli_api" }, + "agentic-campaign.plan-extra-post": { + "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", + "workspace_bound": true + }, + "capability_key": "agentic-campaign.plan-extra-post", + "cli": "museoncli agentic-campaign plan +extra-post", + "domain": "agentic-campaign", + "examples": [ + "museoncli agentic-campaign plan +extra-post --campaign-id 11111111-1111-4111-8111-111111111111 --plan-id 33333333-3333-4333-8333-333333333333 --account-id 44444444-4444-4444-8444-444444444444 --scheduled-at 2026-11-17T15:00:00+00:00 --idempotency-key makeup-20261114" + ], + "execution": "direct", + "input_schema": { + "properties": { + "account_id": { + "description": "Member account", + "examples": [ + "33333333-3333-4333-8333-333333333333" + ], + "format": "uuid", + "type": "string" + }, + "campaign_id": { + "description": "Owning Museon campaign id", + "examples": [ + "33333333-3333-4333-8333-333333333333" + ], + "format": "uuid", + "type": "string" + }, + "dry_run": { + "type": "boolean" + }, + "element_id": { + "description": "Plan reference pair (element) to publish", + "examples": [ + "33333333-3333-4333-8333-333333333333" + ], + "format": "uuid", + "type": "string" + }, + "idempotency_key": { + "maxLength": 120, + "minLength": 1, + "pattern": "^[A-Za-z0-9._:-]+$", + "type": "string" + }, + "plan_id": { + "description": "Agentic Persona Plan id", + "examples": [ + "33333333-3333-4333-8333-333333333333" + ], + "format": "uuid", + "type": "string" + }, + "scheduled_at": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "campaign_id", + "plan_id", + "account_id", + "scheduled_at", + "idempotency_key" + ], + "type": "object" + }, + "name": "agentic-campaign.plan-extra-post", + "output_schema": { + "description": "Created schedule item id and its Plan occurrence key.", + "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" + }, + "workspace": { + "deprecated": true, + "description": "Deprecated: the --workspace-id this command was given, if any.", + "type": [ + "object", + "null" + ] + } + }, + "required": [ + "ok", + "command", + "data", + "run", + "warnings", + "next_steps" + ], + "type": "object" + }, + "requires_confirmation": false, + "resource": "plan", + "risk_level": "write", + "shortcut": "+extra-post", + "stability": "stable", + "summary": "Schedule one more post for one member account of a Plan, outside its daily cadence (for example to make up a missed day). The post uses one of the Plan's current reference pairs (--element-id, or the Plan's rotation when omitted), is generated and published by Museon like the daily posts, and neither replaces nor occupies that day's daily post. The account must be a member with automatic execution enabled, and --scheduled-at (ISO-8601 with offset) at least 30 minutes ahead. Use this instead of `ai-slideshow publish` schedules for Agentic Campaign accounts.", + "supports_dry_run": true, + "transport": "agent_cli_api" + }, "agentic-campaign.plan-get": { "authorization": { "authentication_required": true, @@ -26589,7 +26784,7 @@ "risk_level": "write", "shortcut": "+create-schedule", "stability": "stable", - "summary": "Create one manual account publish schedule item.", + "summary": "Create one manual account publish schedule item. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -28157,7 +28352,7 @@ "risk_level": "read", "shortcut": "+preview-schedule-plan", "stability": "stable", - "summary": "Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission.", + "summary": "Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`.", "supports_dry_run": false, "transport": "agent_cli_api" }, @@ -28720,7 +28915,7 @@ "risk_level": "destructive", "shortcut": "+submit-schedule-plan", "stability": "stable", - "summary": "Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them.", + "summary": "On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them.", "supports_dry_run": true, "transport": "agent_cli_api" }, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index fd62c49..6d34356 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -749,7 +749,7 @@ chapters: before: MuseOn publishes on its own after the rollout; do not run a local loop. Plans keep reviewed {format, topic} pairs, never a cross product. steps: - agentic-campaign.list - - agentic-campaign.campaign-create: "Confirm name, budget and persona count with the user first." + - agentic-campaign.campaign-create: "Confirm name, budget, persona count and publish time (--preferred-publish-windows-json read in --publish-timezone, an IANA zone) with the user first." - agentic-campaign.campaign-review-only: "Manual review for the whole Campaign; tell the user it affects every Plan." - agentic-campaign.plan-create: "Only in setup; --persona-id." - agentic-campaign.plan-supply-update: "The complete paired supply with the latest Plan version; opens a proposal, does not publish." @@ -771,8 +771,9 @@ chapters: - agentic-campaign.plan-get - agentic-campaign.plan-tags - agentic-campaign.plan-attribution - - agentic-campaign.campaign-update: "Budget and config are setup-only; change the name by itself." + - agentic-campaign.campaign-update: "Change the name by itself. Publish window and --publish-timezone may change while active; future not-yet-generated slots move to the new time." - agentic-campaign.plan-update + - agentic-campaign.plan-extra-post: "One more post on top of the daily one (e.g. a missed day). A manual ai-slideshow publish schedule on these accounts instead replaces that day's automatic post." - agentic-campaign.campaign-pause - agentic-campaign.campaign-activate - agentic-campaign.campaign-archive: "Stops every member account of every Plan." diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index 0e93de7..920cfe6 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. -493 commands across 17 domains (source of truth: `museoncli schema`). +494 commands across 17 domains (source of truth: `museoncli schema`). ### research @@ -309,8 +309,8 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. | `ai-slideshow publish +bulk-set-asset-pools` | destructive | yes | `--yes` | async_run | Submit one durable Cloud Task job to change publish asset pools for MULTIPLE accounts. Use this instead of issuing one write per account or writing Python/shell scripts; keep the single command for small, precise one-account edits. This batch command is preferred when atomically configuring all five pools for one account. Requires the opaque token and identical normalized patches from a fresh live preview, plus a stable idempotency key and --yes. After submission, poll only +get-asset-pool-job and inspect every failed/skipped account. If preview marks any fully-managed account requires_managed_operation_approved=true, relay its impact and add --managed-operation-approved only after explicit approval; without it those accounts fail per-account. | | `ai-slideshow publish +get-asset-pool-job` | read | — | — | direct | Read durable asset-pool batch progress and per-account results. This is the only state source after +bulk-set-asset-pools; do not rescan accounts or loop +bulk-get-asset-pools for verification. | | `ai-slideshow publish +cancel-asset-pool-job` | write | yes | — | direct | Request cancellation of a durable asset-pool batch job. Stops account work not yet started but does not roll back accounts already completed. | -| `ai-slideshow publish +preview-schedule-plan` | read | — | — | direct | Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. | -| `ai-slideshow publish +submit-schedule-plan` | destructive | yes | `--yes` | async_run | Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them. | +| `ai-slideshow publish +preview-schedule-plan` | read | — | — | direct | Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. | +| `ai-slideshow publish +submit-schedule-plan` | destructive | yes | `--yes` | async_run | On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them. | | `ai-slideshow publish +get-schedule-plan-job` | read | — | — | direct | Read durable schedule-plan operation progress and per-account results. This is the only state source after submission. cancel-only results include cancelled and protected counts by prior status. For plan with --bgm-policy required and status succeeded, bgm_bound_count/summary.bgm_bound is the server-owned proof that every created occurrence has concrete BGM; never call schedule-list, bgm-asset-list, or routines for post-write verification, rescan accounts, or rely on /tmp state. | | `ai-slideshow publish +cancel-schedule-plan-job` | write | yes | — | direct | Abort unfinished work in a durable schedule-plan job. This is job control only: it never deletes schedule items already created. Use +preview-schedule-plan/+submit-schedule-plan --operation cancel-only when the operator wants schedule items removed. | | `ai-slideshow publish +get-config` | read | — | — | direct | Read account publish configuration, including the account-wide output language used for overlays, captions, and hashtags. | @@ -323,7 +323,7 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. | `ai-slideshow publish +list-schedules` | read | — | — | direct | List account publish schedule items. | | `ai-slideshow publish +get-schedule` | read | — | — | direct | Read one account publish schedule item. | | `ai-slideshow publish +generate-schedule` | write | yes | — | async_run | Start content generation for one account publish schedule item. | -| `ai-slideshow publish +create-schedule` | write | yes | — | direct | Create one manual account publish schedule item. | +| `ai-slideshow publish +create-schedule` | write | yes | — | direct | Create one manual account publish schedule item. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. | | `ai-slideshow publish +update-schedule` | write | yes | — | direct | Update one account publish schedule item. | | `ai-slideshow publish +delete-schedule` | write | yes | — | direct | Cancel one account publish schedule item. | | `ai-slideshow cta-target +list` | read | — | — | direct | List a product's CTA targets (what its posts point viewers to): title, Markdown body, images and status. Staff only (the server refuses other callers). | @@ -396,6 +396,7 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. |---|---|---|---|---|---| | `agentic-campaign plan +supply-update` | write | yes | — | direct | Set reviewed reference pairs for a Museon persona Plan. This opens a proposal; it does not start publishing. Keep existing pairs when appending. Never creates a Format × Topic cross product. | | `agentic-campaign plan +account-control` | destructive | yes | `--yes` | direct | Control one explicitly selected Museon managed member. Enable after reviewed rollout; pause/resume preserve membership; stop retires and releases it. Already-submitted posts keep reconciling. | +| `agentic-campaign plan +extra-post` | write | yes | — | direct | Schedule one more post for one member account of a Plan, outside its daily cadence (for example to make up a missed day). The post uses one of the Plan's current reference pairs (--element-id, or the Plan's rotation when omitted), is generated and published by Museon like the daily posts, and neither replaces nor occupies that day's daily post. The account must be a member with automatic execution enabled, and --scheduled-at (ISO-8601 with offset) at least 30 minutes ahead. Use this instead of `ai-slideshow publish` schedules for Agentic Campaign accounts. | | `agentic-campaign plan +posts` | read | — | — | direct | Read this Plan's posts and metrics by account or reference. Missing metrics are not zero results; platform acceptance is not public-post confirmation. | | `agentic-campaign +campaign-review-only` | write | yes | — | direct | Require manual review for future reference/persona/strategy changes in this Museon Campaign, and disable automatic recruitment. Existing confirmed publishing continues. New CLI campaigns use this policy by default. | | `agentic-campaign plan +members-reconcile` | write | yes | — | direct | Atomically reconcile a Plan's managed accounts and matching Plan budget. The CLI reads current versions, raises Campaign total budget only when required, and submits the member/budget change as one compare-and-swap operation. | @@ -406,7 +407,7 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. | `agentic-campaign proposal +list` | read | — | — | direct | List Proposals for exactly one Plan or all Plans in one Campaign. Campaign scope returns each Proposal's Plan and Persona summary. | | `agentic-campaign proposal +get` | read | — | — | direct | Read an adjustment proposal, its latest revision guidance, and the full round-by-round annotation history (annotations). | | `agentic-campaign +campaign-create` | write | yes | — | direct | Create an Agentic Creative Campaign in the selected organization. Confirm the intent (name, total budget, planned persona count) with the operator before creating, and report the campaign link back afterward. | -| `agentic-campaign +campaign-update` | write | yes | `--yes` | direct | Patch only supplied campaign fields. Budget and config fields are setup-only; name must be changed by itself. Field-level hashtag, mention, and publish-window options merge into existing config, while --config-json replaces the full config. | +| `agentic-campaign +campaign-update` | write | yes | `--yes` | direct | Patch only supplied campaign fields; name must be changed by itself. Field-level hashtag, mention, publish-window and publish-timezone options merge into existing config, while --config-json replaces the full config. The publish time is --preferred-publish-windows-json read in --publish-timezone (IANA, default Asia/Shanghai) for every member account; both can change while the campaign is active, and future not-yet-generated slots move to the new time. | | `agentic-campaign +plan-update` | write | yes | — | direct | Update plan tokens for the next generation while a campaign is active or paused, or update name/budget only during setup. | | `agentic-campaign +plan-create` | write | yes | — | direct | Create a Persona Plan under a campaign. Only allowed while the campaign is in setup (setting_up or setup_ready); the server rejects the request otherwise and the error is passed through unchanged. | | `agentic-campaign +campaign-activate` | write | yes | — | direct | Activate an Agentic Creative Campaign, resuming member account operations. | diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index 8248f33..b89023e 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 -493 commands across 17 domains (source of truth: `museoncli schema`). +494 commands across 17 domains (source of truth: `museoncli schema`). ### research @@ -343,8 +343,8 @@ The tables below are generated — edit code, then run | `ai-slideshow publish +bulk-set-asset-pools` | destructive | yes | `--yes` | async_run | Submit one durable Cloud Task job to change publish asset pools for MULTIPLE accounts. Use this instead of issuing one write per account or writing Python/shell scripts; keep the single command for small, precise one-account edits. This batch command is preferred when atomically configuring all five pools for one account. Requires the opaque token and identical normalized patches from a fresh live preview, plus a stable idempotency key and --yes. After submission, poll only +get-asset-pool-job and inspect every failed/skipped account. If preview marks any fully-managed account requires_managed_operation_approved=true, relay its impact and add --managed-operation-approved only after explicit approval; without it those accounts fail per-account. | | `ai-slideshow publish +get-asset-pool-job` | read | — | — | direct | Read durable asset-pool batch progress and per-account results. This is the only state source after +bulk-set-asset-pools; do not rescan accounts or loop +bulk-get-asset-pools for verification. | | `ai-slideshow publish +cancel-asset-pool-job` | write | yes | — | direct | Request cancellation of a durable asset-pool batch job. Stops account work not yet started but does not roll back accounts already completed. | -| `ai-slideshow publish +preview-schedule-plan` | read | — | — | direct | Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. | -| `ai-slideshow publish +submit-schedule-plan` | destructive | yes | `--yes` | async_run | Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them. | +| `ai-slideshow publish +preview-schedule-plan` | read | — | — | direct | Live-preview a durable schedule-plan operation without writing. --operation cancel-only is the primary way to inspect deletion of current eligible schedule items: it returns cancellable/protected counts by status and an opaque token for the matching batch. For --operation plan, use this before replace-non-published; unlike generic --dry-run, it asks the server to inspect current conflicts, account assets, product bindings, and BGM availability. After resolving account IDs in one bulk social-account +list call, invoke this preview directly; do not preflight with per-account asset, BGM, schedule, or publish-version calls. The response preview_token must be passed unchanged to the matching replace submission. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. | +| `ai-slideshow publish +submit-schedule-plan` | destructive | yes | `--yes` | async_run | On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. Submit one durable asynchronous schedule-plan operation. --operation cancel-only is the primary batch deletion path for current eligible schedule items; it requires the matching preview token and reports cancelled, already cancelled, and protected results by prior status. For --operation plan, create MULTIPLE accounts or MULTIPLE occurrences. MUST use this command instead of looping social-account +list-schedules/+create-schedule/+delete-schedule or Python/shell scripts. One plan accepts up to 200 accounts and 5,000 total occurrences. BGM mode required makes an account fail when its pool has no valid BGM; it never silently creates a no-BGM occurrence. After submission, the only state source is +get-schedule-plan-job. When --bgm-policy required finishes with status succeeded, the server guarantees every created occurrence has a concrete BGM; use bgm_bound_count/summary.bgm_bound and never call schedule-list, bgm-asset-list, or routines to verify it. Inspect every failed/skipped account. replace-non-published requires the opaque preview token from a matching live preview and fails closed when the preview has drifted. --idempotency-key is required: reuse it only for retries of the same submission, and use a new key for an intentional new job. Copy full canonical account UUIDs and the preview token verbatim from the successful preview; never reconstruct them. | | `ai-slideshow publish +get-schedule-plan-job` | read | — | — | direct | Read durable schedule-plan operation progress and per-account results. This is the only state source after submission. cancel-only results include cancelled and protected counts by prior status. For plan with --bgm-policy required and status succeeded, bgm_bound_count/summary.bgm_bound is the server-owned proof that every created occurrence has concrete BGM; never call schedule-list, bgm-asset-list, or routines for post-write verification, rescan accounts, or rely on /tmp state. | | `ai-slideshow publish +cancel-schedule-plan-job` | write | yes | — | direct | Abort unfinished work in a durable schedule-plan job. This is job control only: it never deletes schedule items already created. Use +preview-schedule-plan/+submit-schedule-plan --operation cancel-only when the operator wants schedule items removed. | | `ai-slideshow publish +get-config` | read | — | — | direct | Read account publish configuration, including the account-wide output language used for overlays, captions, and hashtags. | @@ -357,7 +357,7 @@ The tables below are generated — edit code, then run | `ai-slideshow publish +list-schedules` | read | — | — | direct | List account publish schedule items. | | `ai-slideshow publish +get-schedule` | read | — | — | direct | Read one account publish schedule item. | | `ai-slideshow publish +generate-schedule` | write | yes | — | async_run | Start content generation for one account publish schedule item. | -| `ai-slideshow publish +create-schedule` | write | yes | — | direct | Create one manual account publish schedule item. | +| `ai-slideshow publish +create-schedule` | write | yes | — | direct | Create one manual account publish schedule item. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. | | `ai-slideshow publish +update-schedule` | write | yes | — | direct | Update one account publish schedule item. | | `ai-slideshow publish +delete-schedule` | write | yes | — | direct | Cancel one account publish schedule item. | | `ai-slideshow cta-target +list` | read | — | — | direct | List a product's CTA targets (what its posts point viewers to): title, Markdown body, images and status. Staff only (the server refuses other callers). | @@ -430,6 +430,7 @@ The tables below are generated — edit code, then run |---|---|---|---|---|---| | `agentic-campaign plan +supply-update` | write | yes | — | direct | Set reviewed reference pairs for a Museon persona Plan. This opens a proposal; it does not start publishing. Keep existing pairs when appending. Never creates a Format × Topic cross product. | | `agentic-campaign plan +account-control` | destructive | yes | `--yes` | direct | Control one explicitly selected Museon managed member. Enable after reviewed rollout; pause/resume preserve membership; stop retires and releases it. Already-submitted posts keep reconciling. | +| `agentic-campaign plan +extra-post` | write | yes | — | direct | Schedule one more post for one member account of a Plan, outside its daily cadence (for example to make up a missed day). The post uses one of the Plan's current reference pairs (--element-id, or the Plan's rotation when omitted), is generated and published by Museon like the daily posts, and neither replaces nor occupies that day's daily post. The account must be a member with automatic execution enabled, and --scheduled-at (ISO-8601 with offset) at least 30 minutes ahead. Use this instead of `ai-slideshow publish` schedules for Agentic Campaign accounts. | | `agentic-campaign plan +posts` | read | — | — | direct | Read this Plan's posts and metrics by account or reference. Missing metrics are not zero results; platform acceptance is not public-post confirmation. | | `agentic-campaign +campaign-review-only` | write | yes | — | direct | Require manual review for future reference/persona/strategy changes in this Museon Campaign, and disable automatic recruitment. Existing confirmed publishing continues. New CLI campaigns use this policy by default. | | `agentic-campaign plan +members-reconcile` | write | yes | — | direct | Atomically reconcile a Plan's managed accounts and matching Plan budget. The CLI reads current versions, raises Campaign total budget only when required, and submits the member/budget change as one compare-and-swap operation. | @@ -440,7 +441,7 @@ The tables below are generated — edit code, then run | `agentic-campaign proposal +list` | read | — | — | direct | List Proposals for exactly one Plan or all Plans in one Campaign. Campaign scope returns each Proposal's Plan and Persona summary. | | `agentic-campaign proposal +get` | read | — | — | direct | Read an adjustment proposal, its latest revision guidance, and the full round-by-round annotation history (annotations). | | `agentic-campaign +campaign-create` | write | yes | — | direct | Create an Agentic Creative Campaign in the selected organization. Confirm the intent (name, total budget, planned persona count) with the operator before creating, and report the campaign link back afterward. | -| `agentic-campaign +campaign-update` | write | yes | `--yes` | direct | Patch only supplied campaign fields. Budget and config fields are setup-only; name must be changed by itself. Field-level hashtag, mention, and publish-window options merge into existing config, while --config-json replaces the full config. | +| `agentic-campaign +campaign-update` | write | yes | `--yes` | direct | Patch only supplied campaign fields; name must be changed by itself. Field-level hashtag, mention, publish-window and publish-timezone options merge into existing config, while --config-json replaces the full config. The publish time is --preferred-publish-windows-json read in --publish-timezone (IANA, default Asia/Shanghai) for every member account; both can change while the campaign is active, and future not-yet-generated slots move to the new time. | | `agentic-campaign +plan-update` | write | yes | — | direct | Update plan tokens for the next generation while a campaign is active or paused, or update name/budget only during setup. | | `agentic-campaign +plan-create` | write | yes | — | direct | Create a Persona Plan under a campaign. Only allowed while the campaign is in setup (setting_up or setup_ready); the server rejects the request otherwise and the error is passed through unchanged. | | `agentic-campaign +campaign-activate` | write | yes | — | direct | Activate an Agentic Creative Campaign, resuming member account operations. | diff --git a/docs/guide.md b/docs/guide.md index 09a2209..a4c43e7 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,6 +1,6 @@ -# Museon CLI task guide (2.0.1) +# Museon CLI task guide (2.1.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. @@ -675,7 +675,7 @@ Preview, then submit with the preview token and a stable idempotency key; the jo MuseOn publishes on its own after the rollout; do not run a local loop. Plans keep reviewed {format, topic} pairs, never a cross product. 1. `museoncli agentic-campaign +list` (read) -2. `museoncli agentic-campaign +campaign-create --name ` (write): Confirm name, budget and persona count with the user first. +2. `museoncli agentic-campaign +campaign-create --name ` (write): Confirm name, budget, persona count and publish time (--preferred-publish-windows-json read in --publish-timezone, an IANA zone) with the user first. 3. `museoncli agentic-campaign +campaign-review-only --campaign-id ` (write): Manual review for the whole Campaign; tell the user it affects every Plan. 4. `museoncli agentic-campaign +plan-create --campaign-id --name --account-budget 1` (write): Only in setup; --persona-id. 5. `museoncli agentic-campaign plan +supply-update --campaign-id --plan-id --persona-id --expected-version 1 --pairs-json ` (write): The complete paired supply with the latest Plan version; opens a proposal, does not publish. @@ -698,11 +698,12 @@ MuseOn publishes on its own after the rollout; do not run a local loop. Plans ke 3. `museoncli agentic-campaign +plan-get --campaign-id --plan-id ` (read) 4. `museoncli agentic-campaign +plan-tags --campaign-id --plan-id ` (read) 5. `museoncli agentic-campaign +plan-attribution --campaign-id --plan-id ` (read) -6. `museoncli agentic-campaign +campaign-update --campaign-id ` (write, needs --yes): Budget and config are setup-only; change the name by itself. +6. `museoncli agentic-campaign +campaign-update --campaign-id ` (write, needs --yes): Change the name by itself. Publish window and --publish-timezone may change while active; future not-yet-generated slots move to the new time. 7. `museoncli agentic-campaign +plan-update --campaign-id --plan-id ` (write) -8. `museoncli agentic-campaign +campaign-pause --campaign-id ` (write) -9. `museoncli agentic-campaign +campaign-activate --campaign-id ` (write) -10. `museoncli agentic-campaign +campaign-archive --campaign-id ` (destructive, needs --yes): Stops every member account of every Plan. +8. `museoncli agentic-campaign plan +extra-post --campaign-id --plan-id --account-id --scheduled-at 2026-10-01T09:00:00+08:00 --idempotency-key ` (write): One more post on top of the daily one (e.g. a missed day). A manual ai-slideshow publish schedule on these accounts instead replaces that day's automatic post. +9. `museoncli agentic-campaign +campaign-pause --campaign-id ` (write) +10. `museoncli agentic-campaign +campaign-activate --campaign-id ` (write) +11. `museoncli agentic-campaign +campaign-archive --campaign-id ` (destructive, needs --yes): Stops every member account of every Plan. ## 6. Research, analyze content and handle media diff --git a/docs/install.md b/docs/install.md index c9b6849..8bf6278 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.0.1/museoncli-2.0.1-py3-none-any.whl" + uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.1.0/museoncli-2.1.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.0.1/skills/museon-content-workflow-base -https://github.com/Museon-AI/museon-cli/tree/v2.0.1/skills/museon-research -https://github.com/Museon-AI/museon-cli/tree/v2.0.1/skills/museon-content-workflow-hireaicreator -https://github.com/Museon-AI/museon-cli/tree/v2.0.1/skills/museon-content-workflow-ai-slideshow -https://github.com/Museon-AI/museon-cli/tree/v2.0.1/skills/museon-content-workflow-campaigns +https://github.com/Museon-AI/museon-cli/tree/v2.1.0/skills/museon-content-workflow-base +https://github.com/Museon-AI/museon-cli/tree/v2.1.0/skills/museon-research +https://github.com/Museon-AI/museon-cli/tree/v2.1.0/skills/museon-content-workflow-hireaicreator +https://github.com/Museon-AI/museon-cli/tree/v2.1.0/skills/museon-content-workflow-ai-slideshow +https://github.com/Museon-AI/museon-cli/tree/v2.1.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 cf26fe7..d7c20b1 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.0.1). +- [Task guide](https://www.museon.ai/cli/guide.md): every task as ordered commands with their required flags, risk and gotchas (Museon CLI 2.1.0). - Offline, the CLI answers the same: `museoncli guide`, `museoncli guide `, `museoncli guide --search `, `museoncli schema `. ## Tasks diff --git a/museoncli/cli_commands.py b/museoncli/cli_commands.py index cfc223d..b27e223 100644 --- a/museoncli/cli_commands.py +++ b/museoncli/cli_commands.py @@ -214,8 +214,7 @@ def _envelope(data: dict[str, Any]) -> dict[str, Any]: def cli_command_summary(entry: dict[str, Any]) -> dict[str, Any]: return { - key: entry[key] - for key in ("name", "cli", "summary", "risk_level", "requires_confirmation") + key: entry[key] for key in ("name", "cli", "summary", "risk_level", "requires_confirmation") } diff --git a/museoncli/config.py b/museoncli/config.py index ea0464e..514e1be 100644 --- a/museoncli/config.py +++ b/museoncli/config.py @@ -141,7 +141,8 @@ def safe_dict(self) -> dict[str, Any]: if authenticated else "unauthenticated" ), - "reason": self.auth.resolution_error or ("credential_expired" if auth_expired else None), + "reason": self.auth.resolution_error + or ("credential_expired" if auth_expired else None), "auth_method": self.auth.method or ("api_key" if auth.get("api_key") else "none"), "credential_storage": self.auth.provider or credential_backend(config_path()), "expires_at": auth.get("expires_at"), diff --git a/museoncli/domains/_ai_slideshow_asset.py b/museoncli/domains/_ai_slideshow_asset.py index 0589b7d..2defc3f 100644 --- a/museoncli/domains/_ai_slideshow_asset.py +++ b/museoncli/domains/_ai_slideshow_asset.py @@ -1392,7 +1392,9 @@ async def _execute_list(ctx: CommandContext) -> Any: "topic_direction_id": filters.get("topic_direction_id"), "status": filters.get("status"), # The assets API still names the organization's own library "workspace". - "scope": _ORGANIZATION_SCOPE_ON_WIRE.get(filters.get("scope"), filters.get("scope")), + "scope": _ORGANIZATION_SCOPE_ON_WIRE.get( + filters.get("scope"), filters.get("scope") + ), "media_type": filters.get("media_type"), "source_type": filters.get("source_type"), "page": page_number, diff --git a/museoncli/domains/_ai_slideshow_publish.py b/museoncli/domains/_ai_slideshow_publish.py index 9d9b8e0..a9db3d4 100644 --- a/museoncli/domains/_ai_slideshow_publish.py +++ b/museoncli/domains/_ai_slideshow_publish.py @@ -1039,7 +1039,8 @@ def specs() -> list[CommandSpec]: "preview directly; do not preflight with per-account asset, BGM, schedule, or " "publish-version calls. " "The response preview_token must be passed unchanged to the matching replace " - "submission." + "submission. " + "On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`." ), risk_level="read", execution="direct", @@ -1070,6 +1071,7 @@ def specs() -> list[CommandSpec]: shortcut="+submit-schedule-plan", legacy_shortcuts=("+schedule-plan-batch",), summary=( + "On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`. " "Submit one durable asynchronous schedule-plan operation. --operation " "cancel-only is the primary batch deletion path for current eligible schedule " "items; it requires the matching preview token and reports cancelled, already " @@ -1210,9 +1212,7 @@ async def _execute_asset_pools_batch_cancel(ctx: CommandContext) -> Any: ctx.cfg, "POST", f"/account-publish/asset-pools/jobs/{job_id}:cancel", - json_body=compact_params( - {"reason": ctx.arguments.get("reason")} - ), + json_body=compact_params({"reason": ctx.arguments.get("reason")}), ) @@ -1249,9 +1249,7 @@ async def _execute_schedule_plan_cancel(ctx: CommandContext) -> Any: ctx.cfg, "POST", f"/account-publish/schedule-plans/{job_id}:cancel", - json_body=compact_params( - {"reason": ctx.arguments.get("reason")} - ), + json_body=compact_params({"reason": ctx.arguments.get("reason")}), ) @@ -1262,9 +1260,13 @@ async def _execute_schedule_plan_cancel(ctx: CommandContext) -> Any: ), "ai-slideshow.publish-bulk-set-asset-pools": direct_enveloped(_execute_asset_pools_batch_set), "ai-slideshow.publish-get-asset-pool-job": direct_enveloped(_execute_asset_pools_batch_status), - "ai-slideshow.publish-cancel-asset-pool-job": direct_enveloped(_execute_asset_pools_batch_cancel), + "ai-slideshow.publish-cancel-asset-pool-job": direct_enveloped( + _execute_asset_pools_batch_cancel + ), "ai-slideshow.publish-preview-schedule-plan": direct_enveloped(_execute_schedule_plan_preview), "ai-slideshow.publish-submit-schedule-plan": direct_enveloped(_execute_schedule_plan_batch), "ai-slideshow.publish-get-schedule-plan-job": direct_enveloped(_execute_schedule_plan_status), - "ai-slideshow.publish-cancel-schedule-plan-job": direct_enveloped(_execute_schedule_plan_cancel), + "ai-slideshow.publish-cancel-schedule-plan-job": direct_enveloped( + _execute_schedule_plan_cancel + ), } diff --git a/museoncli/domains/_ai_slideshow_publish_account.py b/museoncli/domains/_ai_slideshow_publish_account.py index 2db1f86..78d64e0 100644 --- a/museoncli/domains/_ai_slideshow_publish_account.py +++ b/museoncli/domains/_ai_slideshow_publish_account.py @@ -1010,7 +1010,7 @@ def _all_specs() -> list[CommandSpec]: domain=Domain.AI_SLIDESHOW, shortcut="+create-schedule", legacy_shortcuts=("+schedule-create",), - summary="Create one manual account publish schedule item.", + summary="Create one manual account publish schedule item. On an account in an Agentic Creative Campaign a manual row becomes that day's Plan post and replaces the automatic post of the day unless it is already publishing (the cadence adds none); its format/topic must be one of the Plan's current reference pairs, otherwise AGENTIC_PLAN_PAIR_NOT_IN_PLAN. To add a post on top of the daily one use `agentic-campaign plan +extra-post`.", risk_level="write", execution="direct", adapter_tool_name="social_account_schedule_create", diff --git a/museoncli/domains/_discovery.py b/museoncli/domains/_discovery.py index d9781a5..4150bd1 100644 --- a/museoncli/domains/_discovery.py +++ b/museoncli/domains/_discovery.py @@ -237,4 +237,3 @@ def one_line(text: str, limit: int = 110) -> str: def resource_help(specs: list[CommandSpec]) -> str: """What a resource offers: its actions.""" return ", ".join(spec.shortcut for spec in specs) - diff --git a/museoncli/domains/_removed.py b/museoncli/domains/_removed.py index 9b6148b..26724ac 100644 --- a/museoncli/domains/_removed.py +++ b/museoncli/domains/_removed.py @@ -154,7 +154,7 @@ def removed_invocation(tokens: list[str]) -> RemovedCommandError | None: if group not in REMOVED_GROUPS: continue if action is not None: - resource = words[1:words.index(action)] + resource = words[1 : words.index(action)] path = " ".join([words[0], *resource, action]) if path in REMOVED_COMMANDS: return RemovedCommandError(path, REMOVED_COMMANDS[path], exact=True) diff --git a/museoncli/domains/_shared.py b/museoncli/domains/_shared.py index cb7b790..7ae86ce 100644 --- a/museoncli/domains/_shared.py +++ b/museoncli/domains/_shared.py @@ -348,9 +348,7 @@ def _spec_summary_payload(spec: CommandSpec) -> dict[str, Any]: "organization_bound": spec.organization_bound, # agentic-campaign and hireaicreator keep their 0.25 contract, mirror included. **( - {"workspace_bound": spec.organization_bound} - if keeps_workspace(spec.domain) - else {} + {"workspace_bound": spec.organization_bound} if keeps_workspace(spec.domain) else {} ), "resource_policy": spec.resource_policy, "enforcement": "museon_server" if spec.authentication_required else "local_process", diff --git a/museoncli/domains/_ugc_writes.py b/museoncli/domains/_ugc_writes.py index 5715be5..4c176bc 100644 --- a/museoncli/domains/_ugc_writes.py +++ b/museoncli/domains/_ugc_writes.py @@ -66,9 +66,7 @@ _PAGE_LIMIT = 100 -CAMPAIGN_ID = _uuid_property( - "UGC Campaign ID (from campaign +list)." -) +CAMPAIGN_ID = _uuid_property("UGC Campaign ID (from campaign +list).") DRY_RUN = { "type": "boolean", "default": False, @@ -99,8 +97,7 @@ "members and Brand viewers cannot." ) ROLE_MESSAGE = ( - " Role: owner, admin, or an operator assigned to the Campaign; members cannot message " - "creators." + " Role: owner, admin, or an operator assigned to the Campaign; members cannot message creators." ) ROLE_REVIEW = ( " Role: owner, admin, an operator assigned to the Campaign, or a Brand editor on a " @@ -246,4 +243,3 @@ def same_key_next_step(key: str) -> str: f"If the outcome is unknown (timeout, network error), retry with --idempotency-key {key} " "and the same text; a new key sends a second message." ) - diff --git a/museoncli/domains/_writes.py b/museoncli/domains/_writes.py index 55473ae..9d62275 100644 --- a/museoncli/domains/_writes.py +++ b/museoncli/domains/_writes.py @@ -88,7 +88,9 @@ def require_organization(ctx: CommandContext) -> str: return ctx.organization_id -def changes(before: dict[str, Any], after: dict[str, Any], fields: list[str]) -> list[dict[str, Any]]: +def changes( + before: dict[str, Any], after: dict[str, Any], fields: list[str] +) -> list[dict[str, Any]]: return [ {"field": field, "before": before.get(field), "after": after.get(field)} for field in fields diff --git a/museoncli/domains/agentic_campaign.py b/museoncli/domains/agentic_campaign.py index 8e482d0..a8236a9 100644 --- a/museoncli/domains/agentic_campaign.py +++ b/museoncli/domains/agentic_campaign.py @@ -225,6 +225,7 @@ def _add_campaign_create_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--required-hashtags", default=None) parser.add_argument("--required-mentions", default=None) parser.add_argument("--preferred-publish-windows-json", default=None) + parser.add_argument("--publish-timezone", default=None) parser.add_argument("--bind-notification-conversation", action="store_true") parser.add_argument("--dry-run", action="store_true") @@ -234,11 +235,12 @@ def _field_config(args: argparse.Namespace) -> dict[str, Any] | None: args.required_hashtags, args.required_mentions, args.preferred_publish_windows_json, + args.publish_timezone, ) if args.config_json is not None and any(value is not None for value in values): raise ValueError( "--config-json is mutually exclusive with --required-hashtags, " - "--required-mentions, and --preferred-publish-windows-json." + "--required-mentions, --preferred-publish-windows-json, and --publish-timezone." ) if args.config_json is not None: return _candidate_json(args.config_json, field="config", expected_type=dict) @@ -253,6 +255,8 @@ def _field_config(args: argparse.Namespace) -> dict[str, Any] | None: field="preferred-publish-windows", expected_type=list, ) + if args.publish_timezone is not None: + config["publish_timezone"] = args.publish_timezone return config or None @@ -286,6 +290,7 @@ def _add_campaign_update_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--required-hashtags") parser.add_argument("--required-mentions") parser.add_argument("--preferred-publish-windows-json") + parser.add_argument("--publish-timezone") parser.add_argument("--bind-notification-conversation", action="store_true") parser.add_argument("--dry-run", action="store_true") parser.add_argument("--yes", action="store_true") @@ -296,11 +301,12 @@ def _build_campaign_update_arguments(args: argparse.Namespace) -> dict[str, Any] args.required_hashtags, args.required_mentions, args.preferred_publish_windows_json, + args.publish_timezone, ) if args.config_json is not None and any(value is not None for value in field_config_values): raise ValueError( "--config-json is mutually exclusive with --required-hashtags, " - "--required-mentions, and --preferred-publish-windows-json." + "--required-mentions, --preferred-publish-windows-json, and --publish-timezone." ) mutable = compact_params( { @@ -329,6 +335,7 @@ def _build_campaign_update_arguments(args: argparse.Namespace) -> dict[str, Any] if args.preferred_publish_windows_json is not None else None ), + "publish_timezone": args.publish_timezone, "bind_notification_conversation": ( True if args.bind_notification_conversation else None ), @@ -494,6 +501,14 @@ def _campaign_config_schema() -> dict[str, Any]: }, "default": [], }, + "publish_timezone": { + "type": "string", + "maxLength": 64, + "description": ( + "IANA timezone every member account reads the publish windows in, " + "for example Europe/London. Defaults to Asia/Shanghai." + ), + }, }, } @@ -503,6 +518,7 @@ def specs() -> list[CommandSpec]: return [ _supply_spec(), _account_control_spec(), + _extra_post_spec(), *_managed_read_specs(), CommandSpec( domain=domain, @@ -749,7 +765,7 @@ def specs() -> list[CommandSpec]: CommandSpec( domain=domain, shortcut="+campaign-update", - summary="Patch only supplied campaign fields. Budget and config fields are setup-only; name must be changed by itself. Field-level hashtag, mention, and publish-window options merge into existing config, while --config-json replaces the full config.", + summary="Patch only supplied campaign fields; name must be changed by itself. Field-level hashtag, mention, publish-window and publish-timezone options merge into existing config, while --config-json replaces the full config. The publish time is --preferred-publish-windows-json read in --publish-timezone (IANA, default Asia/Shanghai) for every member account; both can change while the campaign is active, and future not-yet-generated slots move to the new time.", risk_level="write", requires_confirmation=True, execution="direct", @@ -772,6 +788,7 @@ def specs() -> list[CommandSpec]: "preferred_publish_windows": _campaign_config_schema()["properties"][ "preferred_publish_windows" ], + "publish_timezone": _campaign_config_schema()["properties"]["publish_timezone"], "bind_notification_conversation": {"type": "boolean"}, "dry_run": {"type": "boolean", "default": False}, }, @@ -781,6 +798,7 @@ def specs() -> list[CommandSpec]: examples=[ "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --total-account-budget 107 --yes", "museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --bind-notification-conversation --yes", + 'museoncli agentic-campaign +campaign-update --campaign-id 22222222-2222-4222-8222-222222222222 --preferred-publish-windows-json \'[{"start":"20:00","end":"20:01"}]\' --publish-timezone Europe/London --yes', ], add_arguments=_add_campaign_update_arguments, build_arguments=_build_campaign_update_arguments, @@ -1390,6 +1408,7 @@ async def _execute_campaign_update(ctx: CommandContext) -> Any: "required_hashtags", "required_mentions", "preferred_publish_windows", + "publish_timezone", "bind_notification_conversation", } } @@ -1717,6 +1736,89 @@ async def _execute_account_control(ctx: CommandContext) -> Any: ) +def _add_extra_post_arguments(parser: argparse.ArgumentParser) -> None: + _add_plan_id_arguments(parser) + parser.add_argument("--account-id", required=True) + parser.add_argument("--scheduled-at", required=True) + parser.add_argument("--element-id") + parser.add_argument("--idempotency-key", required=True) + parser.add_argument("--dry-run", action="store_true") + + +def _build_extra_post_arguments(args: argparse.Namespace) -> dict[str, Any]: + return compact_params( + { + **_build_plan_id_arguments(args), + "account_id": args.account_id, + "scheduled_at": args.scheduled_at, + "element_id": args.element_id, + "idempotency_key": args.idempotency_key, + "dry_run": args.dry_run, + } + ) + + +async def _execute_extra_post(ctx: CommandContext) -> Any: + campaign_id, plan, _detail = await _locate_plan(ctx) + return await ctx.api_data_v2( + ctx.cfg, + "POST", + f"/agentic-creative-campaigns/{campaign_id}/persona-plans/{plan['id']}:extra-post", + json_body=compact_params( + { + "pool_account_id": ctx.arguments["account_id"], + "scheduled_at": ctx.arguments["scheduled_at"], + "element_id": ctx.arguments.get("element_id"), + "idempotency_key": ctx.arguments["idempotency_key"], + } + ), + ) + + +def _extra_post_spec() -> CommandSpec: + return CommandSpec( + domain=Domain.AGENTIC_CAMPAIGN, + resource="plan", + shortcut="+extra-post", + summary=( + "Schedule one more post for one member account of a Plan, outside its daily cadence " + "(for example to make up a missed day). The post uses one of the Plan's current " + "reference pairs (--element-id, or the Plan's rotation when omitted), is generated " + "and published by Museon like the daily posts, and neither replaces nor occupies " + "that day's daily post. The account must be a member with automatic execution " + "enabled, and --scheduled-at (ISO-8601 with offset) at least 30 minutes ahead. " + "Use this instead of `ai-slideshow publish` schedules for Agentic Campaign accounts." + ), + risk_level="write", + execution="direct", + adapter_tool_name="agentic_campaign_plan_extra_post", + input_schema=_plan_schema( + { + "account_id": _uuid_property("Member account"), + "scheduled_at": {"type": "string", "format": "date-time"}, + "element_id": _uuid_property("Plan reference pair (element) to publish"), + "idempotency_key": { + "type": "string", + "minLength": 1, + "maxLength": 120, + "pattern": "^[A-Za-z0-9._:-]+$", + }, + "dry_run": {"type": "boolean"}, + }, + required=["account_id", "scheduled_at", "idempotency_key"], + ), + output_schema=_direct_output_schema( + "Created schedule item id and its Plan occurrence key." + ), + examples=[ + "museoncli agentic-campaign plan +extra-post --campaign-id 11111111-1111-4111-8111-111111111111 --plan-id 33333333-3333-4333-8333-333333333333 --account-id 44444444-4444-4444-8444-444444444444 --scheduled-at 2026-11-17T15:00:00+00:00 --idempotency-key makeup-20261114" + ], + supports_dry_run=True, + add_arguments=_add_extra_post_arguments, + build_arguments=_build_extra_post_arguments, + ) + + def _account_control_spec() -> CommandSpec: return CommandSpec( domain=Domain.AGENTIC_CAMPAIGN, @@ -1896,6 +1998,9 @@ async def execute(ctx: CommandContext) -> dict[str, Any]: "agentic-campaign.plan-account-control": _managed_enveloped( _execute_account_control, redact_api_errors=True ), + "agentic-campaign.plan-extra-post": _managed_enveloped( + _execute_extra_post, redact_api_errors=True + ), "agentic-campaign.plan-supply-update": _managed_enveloped( _execute_supply, redact_api_errors=True ), diff --git a/museoncli/domains/ai_slideshow_publish_actions.py b/museoncli/domains/ai_slideshow_publish_actions.py index 66a1cb2..8a534cf 100644 --- a/museoncli/domains/ai_slideshow_publish_actions.py +++ b/museoncli/domains/ai_slideshow_publish_actions.py @@ -150,8 +150,7 @@ def specs() -> list[CommandSpec]: shortcut="+schedule-approve", summary=( "Approve one scheduled item of a pool account's publish plan (an item whose " - "account requires approval before publish), so it can go out at its time." - + _STAFF + "account requires approval before publish), so it can go out at its time." + _STAFF ), risk_level="write", adapter_tool_name="social_account_schedule_approve", diff --git a/museoncli/domains/ai_slideshow_review.py b/museoncli/domains/ai_slideshow_review.py index 196dce8..03c77f9 100644 --- a/museoncli/domains/ai_slideshow_review.py +++ b/museoncli/domains/ai_slideshow_review.py @@ -114,9 +114,7 @@ def _decide(action: str): async def run(ctx: CommandContext) -> Any: generation_id = ctx.arguments["generation_id"] - data = await ctx.api_data_v2( - ctx.cfg, "POST", _path(generation_id, suffix), json_body={} - ) + data = await ctx.api_data_v2(ctx.cfg, "POST", _path(generation_id, suffix), json_body={}) return data, [], [f"museoncli ai-slideshow generation +get --id {generation_id}"] return with_notes(run) @@ -134,7 +132,9 @@ async def _execute_adjust(ctx: CommandContext) -> Any: ) return ( data, - ["The adjustment starts a new generation; data.replacement_generation_id is the post to review next."], + [ + "The adjustment starts a new generation; data.replacement_generation_id is the post to review next." + ], [], ) @@ -193,7 +193,9 @@ def _build_adjust_arguments(args: argparse.Namespace) -> dict[str, Any]: if len(annotations) > MAX_ANNOTATIONS: raise ValueError(f"annotations takes at most {MAX_ANNOTATIONS} marks.") if not payload.get("instruction") and not annotations: - raise ValueError("Adjustment feedback must not be empty: give --instruction or annotations.") + raise ValueError( + "Adjustment feedback must not be empty: give --instruction or annotations." + ) _dry_run(args, payload) return payload diff --git a/museoncli/domains/boards_write.py b/museoncli/domains/boards_write.py index 019f744..bfdb587 100644 --- a/museoncli/domains/boards_write.py +++ b/museoncli/domains/boards_write.py @@ -154,9 +154,7 @@ async def _execute_update(ctx: CommandContext) -> Any: return data, ["Nothing differs from the board as saved; nothing was written."], [] if args.get("dry_run"): return data, [], [ask_first("these changes")] - body = compact_params( - {"name": args.get("name"), "filters": filters if edits else None} - ) + body = compact_params({"name": args.get("name"), "filters": filters if edits else None}) data["board"] = await ctx.api_data(ctx.cfg, "PATCH", _path(args["id"]), json_body=body) return data, [], [] @@ -257,7 +255,8 @@ def _filter_edits(args: argparse.Namespace) -> dict[str, Any]: edits["chart_mode"] = args.chart_mode if args.account_ids is not None: edits["accounts"] = ( - [] if _is_none(args.account_ids) + [] + if _is_none(args.account_ids) else [uuid_arg(value, flag="--account-id") for value in args.account_ids] ) if args.metrics is not None: @@ -368,9 +367,7 @@ def _build_delete_arguments(args: argparse.Namespace) -> dict[str, Any]: "items": {"type": "string", "format": "uuid"}, "minItems": 1, "maxItems": MAX_CAMPAIGNS, - "description": ( - "The Campaigns the board reads (ids from campaign +list), 1 to 10." - ), + "description": ("The Campaigns the board reads (ids from campaign +list), 1 to 10."), } _CAMPAIGN_TYPE = { "type": "string", @@ -392,7 +389,11 @@ def _build_delete_arguments(args: argparse.Namespace) -> dict[str, Any]: "enum": POST_SCOPES, "description": "approved shows confirmed posts only (UGC and mixed boards).", }, - "accounts": {"type": "array", "items": {"type": "string", "format": "uuid"}, "maxItems": 50}, + "accounts": { + "type": "array", + "items": {"type": "string", "format": "uuid"}, + "maxItems": 50, + }, "thresholds": { "type": "object", "description": "METRIC_min / METRIC_max floors and ceilings, e.g. views_min: 1000.", @@ -444,7 +445,9 @@ def specs() -> list[CommandSpec]: }, ["name", "campaign_ids", "campaign_type"], ), - output_schema=_direct_output_schema("The board as saved (id, name, campaigns, filters)."), + output_schema=_direct_output_schema( + "The board as saved (id, name, campaigns, filters)." + ), examples=[ f'museoncli analytics board +create --name "Q4 UGC" --campaign-type ugc ' f"--campaign-id {campaign} --campaign-id {other} --post-scope approved --dry-run" diff --git a/museoncli/domains/campaign_data.py b/museoncli/domains/campaign_data.py index d90ee03..8f106ef 100644 --- a/museoncli/domains/campaign_data.py +++ b/museoncli/domains/campaign_data.py @@ -441,8 +441,6 @@ def _build_campaign_period_performance_arguments( return payload - - def _campaign_id_input_schema() -> dict[str, Any]: return { "type": "object", @@ -1157,8 +1155,6 @@ async def _read_creator_page(ctx: CommandContext) -> Any: ) - - async def _execute_dimensions(ctx: CommandContext) -> Any: cfg = ctx.cfg arguments = ctx.arguments @@ -1198,8 +1194,6 @@ async def _execute_breakdown(ctx: CommandContext) -> Any: ) - - async def _execute_summary(ctx: CommandContext) -> Any: cfg = ctx.cfg arguments = ctx.arguments @@ -1356,8 +1350,18 @@ async def _campaign_kind(ctx: CommandContext) -> str: def _creator_item(row: dict[str, Any], source_kind: str) -> dict[str, Any]: performance = row.get("performance") if isinstance(row.get("performance"), dict) else {} values = { - **{key: performance.get(key) for key in ("views", "avg_views", "likes", "comments", - "shares", "collects", "engagement_rate")}, + **{ + key: performance.get(key) + for key in ( + "views", + "avg_views", + "likes", + "comments", + "shares", + "collects", + "engagement_rate", + ) + }, **{key: value for key, value in row.items() if value is not None}, } values["creator_social_account_id"] = row.get("creator_social_account_id") or row.get("id") @@ -1402,9 +1406,7 @@ def _normalized_page( async def _execute_creator_list(ctx: CommandContext) -> dict[str, Any]: raw, source_kind = await asyncio.gather(_read_creator_page(ctx), _campaign_kind(ctx)) - data = _normalized_page( - raw, list_key="creators", source_kind=source_kind, item=_creator_item - ) + data = _normalized_page(raw, list_key="creators", source_kind=source_kind, item=_creator_item) next_steps: list[str] = [] if source_kind == "ugc": next_steps.append( diff --git a/museoncli/domains/campaign_lifecycle.py b/museoncli/domains/campaign_lifecycle.py index 30cabfd..ab7c50d 100644 --- a/museoncli/domains/campaign_lifecycle.py +++ b/museoncli/domains/campaign_lifecycle.py @@ -85,7 +85,9 @@ async def _list(ctx: CommandContext, arguments: dict[str, Any]) -> Any: archived = True if status == "archived" else None paging = {"cursor": arguments.get("cursor"), "limit": arguments.get("page_size") or 50} if arguments.get("with_progress"): - return await get(ctx, Route(AGENCY + "/campaigns/progress", {"archived": archived, **paging})) + return await get( + ctx, Route(AGENCY + "/campaigns/progress", {"archived": archived, **paging}) + ) page = await get( ctx, Route( @@ -106,7 +108,9 @@ async def _list(ctx: CommandContext, arguments: dict[str, Any]) -> Any: page = { **page, "items": [ - item for item in items if isinstance(item, dict) and item.get("status") == status + item + for item in items + if isinstance(item, dict) and item.get("status") == status ], } return page @@ -203,7 +207,9 @@ async def _execute_transition(ctx: CommandContext, action: str) -> Any: } warnings = [_TRANSITION_NOTES[action]] if action == "launch": - launchability = view.get("launchability") if isinstance(view.get("launchability"), dict) else {} + launchability = ( + view.get("launchability") if isinstance(view.get("launchability"), dict) else {} + ) data["launchability"] = launchability if launchability and not launchability.get("ok", True): warnings.append( @@ -277,7 +283,9 @@ def _build_create_arguments(args: argparse.Namespace) -> dict[str, Any]: def _add_campaign_id(parser: argparse.ArgumentParser) -> None: - parser.add_argument("--campaign-id", required=True, help="ID of the Campaign (from campaign +list).") + parser.add_argument( + "--campaign-id", required=True, help="ID of the Campaign (from campaign +list)." + ) def _add_transition_arguments(*, confirm: bool): @@ -481,7 +489,8 @@ def specs() -> list[CommandSpec]: shortcut="+rename", summary=( "Rename a Campaign in any status; its tracking pages' title follows. --dry-run " - "returns the old and new name without writing." + w.CONFIRM_FIRST + "returns the old and new name without writing." + + w.CONFIRM_FIRST + " Role: owner, admin, or an operator or editor on the Campaign." ), adapter="campaign_rename", @@ -492,7 +501,9 @@ def specs() -> list[CommandSpec]: }, required=["campaign_id", "name"], output_description="dry_run, campaign, before and after name.", - examples=[f"museoncli campaign +rename --campaign-id {campaign} --name 'Spring launch EU' --dry-run"], + examples=[ + f"museoncli campaign +rename --campaign-id {campaign} --name 'Spring launch EU' --dry-run" + ], add_arguments=_add_rename_arguments, build_arguments=_build_rename_arguments, kind=w.WRITE, diff --git a/museoncli/domains/campaign_store.py b/museoncli/domains/campaign_store.py index 913c1de..48104d9 100644 --- a/museoncli/domains/campaign_store.py +++ b/museoncli/domains/campaign_store.py @@ -185,11 +185,13 @@ def _build_social_media_post_resolve_arguments(args: argparse.Namespace) -> dict def _social_media_creator_get_input_schema() -> dict[str, Any]: return { "type": "object", - "properties": {"creator_id": { + "properties": { + "creator_id": { "type": "string", "minLength": 1, "description": "The creator's social account ID (not a campaign ID).", - }}, + } + }, "required": ["creator_id"], } diff --git a/museoncli/domains/client_reports_write.py b/museoncli/domains/client_reports_write.py index 038f770..7fb3fc2 100644 --- a/museoncli/domains/client_reports_write.py +++ b/museoncli/domains/client_reports_write.py @@ -147,7 +147,9 @@ def _blocked(report: dict[str, Any], action: str) -> list[str]: capability = _capability(report, action) if capability.get("enabled", True): return [] - codes = [item.get("code") for item in capability.get("blockers") or [] if isinstance(item, dict)] + codes = [ + item.get("code") for item in capability.get("blockers") or [] if isinstance(item, dict) + ] return [f"The server would refuse {action} now: {', '.join(map(str, codes)) or 'blocked'}."] @@ -248,7 +250,10 @@ async def _execute_regenerate(ctx: CommandContext) -> Any: if args.get("dry_run"): return ( data, - [*warnings, "Regenerating replaces the report's text with a fresh draft from the data."], + [ + *warnings, + "Regenerating replaces the report's text with a fresh draft from the data.", + ], [ask_first("the report that would be rewritten")], ) data["report"] = await _post( @@ -280,8 +285,10 @@ async def _execute_refresh(ctx: CommandContext) -> Any: "dry_run": bool(args.get("dry_run")), "report": _report_line(report), "changes": [ - {**{key: item.get(key) for key in ("id", "label", "before", "after")}, - "apply": str(item.get("id")) not in keep} + { + **{key: item.get(key) for key in ("id", "label", "before", "after")}, + "apply": str(item.get("id")) not in keep, + } for item in found ], } @@ -426,7 +433,9 @@ def _settings_view(write: dict[str, Any]) -> dict[str, Any]: "timezone": write.get("timezone"), "daily_generate_time": write.get("dailyGenerateTime"), "daily_due_time": write.get("dailyOperatorDueTime"), - "weekly_weekday": WEEKDAYS[weekday] if isinstance(weekday, int) and 0 <= weekday <= 6 else None, + "weekly_weekday": WEEKDAYS[weekday] + if isinstance(weekday, int) and 0 <= weekday <= 6 + else None, "weekly_generate_time": schedule.get("generateTime"), "weekly_due_time": schedule.get("submissionDueTime"), "data_scope": write.get("reportDataScope"), @@ -481,7 +490,10 @@ def apply_settings_edits( if edit in edits: after["weeklySchedule"][key] = edits[edit] if "language" in edits: - after["defaultAppearance"] = {**(after.get("defaultAppearance") or {}), "language": edits["language"]} + after["defaultAppearance"] = { + **(after.get("defaultAppearance") or {}), + "language": edits["language"], + } for edit, key in (("owner_user_id", "ownerUserId"), ("reviewer_user_id", "reviewerUserId")): if edit in edits: after[key] = None if edits[edit] == NONE else edits[edit] @@ -498,7 +510,9 @@ async def _execute_config_update(ctx: CommandContext) -> Any: args = ctx.arguments workspace = await _workspace(ctx, args["campaign_id"]) communication = _communication(workspace) - candidates = workspace.get("candidates") if isinstance(workspace.get("candidates"), list) else [] + candidates = ( + workspace.get("candidates") if isinstance(workspace.get("candidates"), list) else [] + ) before = settings_write(communication) after = apply_settings_edits(before, args.get("edits") or {}, candidates) view_before, view_after = _settings_view(before), _settings_view(after) @@ -522,7 +536,10 @@ async def _execute_config_update(ctx: CommandContext) -> Any: "PUT", f"{_base(args['campaign_id'])}/communication", params=_query(ctx), - json_body={"expectedVersion": int(communication.get("version") or 0), "communication": after}, + json_body={ + "expectedVersion": int(communication.get("version") or 0), + "communication": after, + }, ) ) data["settings"] = _settings_view(settings_write(saved if isinstance(saved, dict) else {})) @@ -597,7 +614,12 @@ def _build_update_arguments(args: argparse.Namespace) -> dict[str, Any]: if args.title is not None and not args.title.strip(): raise ValueError("--title cannot be empty.") return compact_params( - {**_report_args(args), "title": args.title, "markdown": markdown, "dry_run": bool(args.dry_run)} + { + **_report_args(args), + "title": args.title, + "markdown": markdown, + "dry_run": bool(args.dry_run), + } ) @@ -697,7 +719,12 @@ def _build_config_arguments(args: argparse.Namespace) -> dict[str, Any]: edits["disable"] = list(args.disable) if args.timezone is not None: edits["timezone"] = args.timezone - for name in ("daily_generate_time", "daily_due_time", "weekly_generate_time", "weekly_due_time"): + for name in ( + "daily_generate_time", + "daily_due_time", + "weekly_generate_time", + "weekly_due_time", + ): value = getattr(args, name) if value is not None: edits[name] = _clock(value, flag="--" + name.replace("_", "-")) @@ -741,7 +768,11 @@ def _build_config_arguments(args: argparse.Namespace) -> dict[str, Any]: "Omitted, the revision read just before the write is used." ), } -_REPORT_INPUT = {"campaign_id": _CAMPAIGN_ID, "id": _REPORT_ID, "expected_revision": _EXPECTED_REVISION} +_REPORT_INPUT = { + "campaign_id": _CAMPAIGN_ID, + "id": _REPORT_ID, + "expected_revision": _EXPECTED_REVISION, +} _REPORT_OUT = _direct_output_schema("report (id, type, status, revision, period) after the write.") @@ -773,7 +804,11 @@ def specs() -> list[CommandSpec]: { "campaign_id": _CAMPAIGN_ID, "type": {"type": "string", "enum": REPORT_TYPES}, - "date": {"type": "string", "format": "date", "description": "A day of the report's period."}, + "date": { + "type": "string", + "format": "date", + "description": "A day of the report's period.", + }, "language": {"type": "string", "enum": LANGUAGES}, "title": {"type": "string", "maxLength": 500}, "markdown": {"type": "string", "maxLength": 500000}, @@ -782,7 +817,9 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "type", "date"], ), - output_schema=_direct_output_schema("The report as generated (id, status, revision, markdown)."), + output_schema=_direct_output_schema( + "The report as generated (id, status, revision, markdown)." + ), examples=[ f"museoncli ugc client-report +create --campaign-id {campaign} --type daily " "--date 2026-11-12 --dry-run" @@ -856,7 +893,9 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "id"], ), - output_schema=_direct_output_schema("report and changes (id, label, before, after, apply)."), + output_schema=_direct_output_schema( + "report and changes (id, label, before, after, apply)." + ), examples=[ f"museoncli ugc client-report +refresh --campaign-id {campaign} --id {report} --dry-run" ], @@ -869,7 +908,8 @@ def specs() -> list[CommandSpec]: shortcut="+request-review", summary=( "Ask the Campaign's reviewer to review a client report: posts it to the internal " - "Feishu group. Without --yes it is refused with a preview of the report and the group." + _ROLE + "Feishu group. Without --yes it is refused with a preview of the report and the group." + + _ROLE ), adapter_tool_name="ugc_client_report_request_review", input_schema=schema({**_REPORT_INPUT, "dry_run": DRY_RUN}, ["campaign_id", "id"]), @@ -949,7 +989,9 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "id"], ), - output_schema=_direct_output_schema("action, destination and the report after sending."), + output_schema=_direct_output_schema( + "action, destination and the report after sending." + ), examples=[ f"museoncli ugc client-report +send --campaign-id {campaign} --id {report}", f"museoncli ugc client-report +send --campaign-id {campaign} --id {report} --yes", @@ -986,7 +1028,9 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "edits"], ), - output_schema=_direct_output_schema("version, settings and changes (field, before, after)."), + output_schema=_direct_output_schema( + "version, settings and changes (field, before, after)." + ), examples=[ f"museoncli ugc client-report-config +update --campaign-id {campaign} --enable daily " "--daily-generate-time 09:00 --daily-due-time 12:00 --dry-run" @@ -1009,7 +1053,9 @@ def specs() -> list[CommandSpec]: "ugc.client-report-approve": with_notes( _action_executor("approve", what="the report revision being approved") ), - "ugc.client-report-skip": with_notes(_action_executor("skip", what="the report and the reason")), + "ugc.client-report-skip": with_notes( + _action_executor("skip", what="the report and the reason") + ), "ugc.client-report-send": with_notes( _action_executor("send", what="the report and where it would go") ), diff --git a/museoncli/domains/cloud_phone.py b/museoncli/domains/cloud_phone.py index 18c785d..e6edf28 100644 --- a/museoncli/domains/cloud_phone.py +++ b/museoncli/domains/cloud_phone.py @@ -109,9 +109,7 @@ def redact(value: Any) -> Any: def _envelope(ctx: CommandContext, raw: Any) -> dict[str, Any]: - return direct_api_envelope( - ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url - ) + return direct_api_envelope(ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url) async def _get(ctx: CommandContext, path: str, **params: Any) -> Any: diff --git a/museoncli/domains/hireaicreator.py b/museoncli/domains/hireaicreator.py index 5632159..2944667 100644 --- a/museoncli/domains/hireaicreator.py +++ b/museoncli/domains/hireaicreator.py @@ -368,11 +368,7 @@ def _load( if key.endswith("_ids") and properties[key].get("items", {}).get("type") == "string": # Flags accept CSV and repetition; structured arrays stay literal. # Split before validation so maxItems still counts individual IDs. - payload[key] = [ - item.strip() - for value in payload[key] - for item in value.split(",") - ] + payload[key] = [item.strip() for value in payload[key] for item in value.split(",")] _validate(payload, obj(properties, required)) return payload diff --git a/museoncli/domains/hireaicreator_local_publish.py b/museoncli/domains/hireaicreator_local_publish.py index c0251f1..3fe30a1 100644 --- a/museoncli/domains/hireaicreator_local_publish.py +++ b/museoncli/domains/hireaicreator_local_publish.py @@ -150,9 +150,7 @@ async def submit(json_body: dict[str, Any]) -> Any: _save(receipt_path, record) if raw is None: raw = await submit({**body, "campaign_id": campaign_id}) - receipt = direct_api_envelope( - ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url - ) + receipt = direct_api_envelope(ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url) receipt["warnings"].append( "Accepted publication tasks, not proof of public posts. Read each video for final delivery state." ) diff --git a/museoncli/domains/hireaicreator_test_groups.py b/museoncli/domains/hireaicreator_test_groups.py index e41eef7..fb7d10a 100644 --- a/museoncli/domains/hireaicreator_test_groups.py +++ b/museoncli/domains/hireaicreator_test_groups.py @@ -65,9 +65,7 @@ def arr(items, minimum=0, maximum=None): "schedule_timezone": nullable(TZ), "publish_times": nullable(arr(S, maximum=100)), } -READBACK = ( - "Read test-group +get and +get-publishing for the same organization and group before dependent writes." -) +READBACK = "Read test-group +get and +get-publishing for the same organization and group before dependent writes." def page(maximum=100, search_length=120): diff --git a/museoncli/domains/publish.py b/museoncli/domains/publish.py index d731547..6f18899 100644 --- a/museoncli/domains/publish.py +++ b/museoncli/domains/publish.py @@ -236,9 +236,7 @@ async def uploaded(path: str, digest: str, media_type: str) -> str: idempotency_key=args["idempotency_key"], unwrap_success=False, ) - receipt = direct_api_envelope( - ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url - ) + receipt = direct_api_envelope(ctx.spec.schema_name, raw, site_url=ctx.cfg.site_url) receipt["warnings"].append( "Accepted publish tasks, not proof of public posts. Read each task for its final state." ) diff --git a/museoncli/domains/research.py b/museoncli/domains/research.py index 5109d35..7429cc3 100644 --- a/museoncli/domains/research.py +++ b/museoncli/domains/research.py @@ -332,13 +332,9 @@ def _build_social_hook_source_arguments(args: argparse.Namespace) -> dict[str, A payload = _load_structured_args(args) if args.candidate_urls: payload["candidate_urls"] = list(args.candidate_urls) - candidate_urls = _optional_url_list( - payload.get("candidate_urls"), field="candidate_urls" - ) + candidate_urls = _optional_url_list(payload.get("candidate_urls"), field="candidate_urls") if not 1 <= len(candidate_urls) <= 40: - raise ValueError( - "research +submit-hook-candidates requires 1 to 40 --url values." - ) + raise ValueError("research +submit-hook-candidates requires 1 to 40 --url values.") if len(candidate_urls) != len(set(candidate_urls)): raise ValueError("--url values must be unique.") payload["candidate_urls"] = candidate_urls @@ -346,9 +342,7 @@ def _build_social_hook_source_arguments(args: argparse.Namespace) -> dict[str, A payload["idempotency_key"] = args.idempotency_key.strip() if not 8 <= len(payload["idempotency_key"]) <= 240: raise ValueError("--idempotency-key must contain 8 to 240 characters.") - _validate_int_range( - payload, key="max_items", flag="--max-items", minimum=1, maximum=30 - ) + _validate_int_range(payload, key="max_items", flag="--max-items", minimum=1, maximum=30) return payload @@ -1780,13 +1774,9 @@ async def _execute_creative_search_ads_results(ctx: CommandContext) -> Any: "research.list-ads-search-results": direct_enveloped(_execute_creative_search_ads_results), "research.create-hook-analysis": direct_enveloped(_execute_social_hook_analyze), "research.submit-hook-candidates": direct_enveloped(_execute_social_hook_source), - "research.check-hooks-analyzed": direct_enveloped( - _execute_social_hook_analyze_seen - ), + "research.check-hooks-analyzed": direct_enveloped(_execute_social_hook_analyze_seen), "research.get-hook-analysis": direct_enveloped(_execute_social_hook_get), "research.bulk-get-hook-analyses": direct_enveloped(_execute_social_hook_poll), "research.list-hook-analysis-results": direct_enveloped(_execute_social_hook_results), - "research.get-hook-analysis-media": direct_enveloped( - _execute_social_hook_media_get - ), + "research.get-hook-analysis-media": direct_enveloped(_execute_social_hook_media_get), } diff --git a/museoncli/domains/routines.py b/museoncli/domains/routines.py index cbcce74..51c10db 100644 --- a/museoncli/domains/routines.py +++ b/museoncli/domains/routines.py @@ -475,8 +475,7 @@ def _routine_command_spec_payloads() -> list[dict[str, Any]]: "domain": ROUTINES_DOMAIN, "shortcut": "accept-draft", "summary": ( - "Accept a draft ad-hoc routine and register its trigger with Museon's " - "scheduler." + "Accept a draft ad-hoc routine and register its trigger with Museon's scheduler." ), "risk_level": "write", "execution": "direct", diff --git a/museoncli/domains/social_account.py b/museoncli/domains/social_account.py index 5d3d5a0..ad0ec06 100644 --- a/museoncli/domains/social_account.py +++ b/museoncli/domains/social_account.py @@ -1212,10 +1212,7 @@ async def _execute_adb_connect(ctx: CommandContext) -> Any: ) if isinstance(resolved_account, dict): result.update( - { - key: resolved_account.get(key) - for key in ("account_id", "username", "platform") - } + {key: resolved_account.get(key) for key in ("account_id", "username", "platform")} ) return result diff --git a/museoncli/domains/social_account_sync.py b/museoncli/domains/social_account_sync.py index 551606c..2044b99 100644 --- a/museoncli/domains/social_account_sync.py +++ b/museoncli/domains/social_account_sync.py @@ -160,8 +160,7 @@ def specs() -> list[CommandSpec]: shortcut="+sync-all", summary=( "Sync every bound profile in the caller's own landing workspace of the " - "selected organization (not every workspace in it). Repeating it is safe." - + _ROLE + "selected organization (not every workspace in it). Repeating it is safe." + _ROLE ), risk_level="write", adapter_tool_name="social_account_sync_all", @@ -182,13 +181,14 @@ def specs() -> list[CommandSpec]: "the id and echoes it: it reads nothing from the server, so confirm which " "account that id is (social-account +list) before asking the user to approve; " "then run with --yes. The account has to be connected again " - "(social-account +create-connect-link) to publish." - + _ROLE + "(social-account +create-connect-link) to publish." + _ROLE ), risk_level="destructive", adapter_tool_name="social_account_unbind", input_schema=schema(_UNBIND, ["account_id"]), - output_schema=output_schema("data.unbound and data.account_id; a dry run echoes the validated input."), + output_schema=output_schema( + "data.unbound and data.account_id; a dry run echoes the validated input." + ), examples=[ f"museoncli social-account +unbind --account-id {_EXAMPLE_ACCOUNT} --dry-run", f"museoncli social-account +unbind --account-id {_EXAMPLE_ACCOUNT} --yes", diff --git a/museoncli/domains/ugc.py b/museoncli/domains/ugc.py index 4280afa..bc90fb1 100644 --- a/museoncli/domains/ugc.py +++ b/museoncli/domains/ugc.py @@ -139,9 +139,7 @@ def _live(row: dict[str, Any]) -> bool: def _envelope( ctx: CommandContext, data: Any, warnings: list[str], next_steps: list[str] ) -> dict[str, Any]: - envelope = direct_api_envelope( - ctx.spec.schema_name, data, site_url=ctx.cfg.site_url - ) + envelope = direct_api_envelope(ctx.spec.schema_name, data, site_url=ctx.cfg.site_url) envelope["warnings"] = [*envelope["warnings"], *warnings] envelope["next_steps"] = [*envelope["next_steps"], *next_steps] return envelope @@ -292,7 +290,9 @@ def brief_progress( "videos_counted": sum(int(row.get("videos_counted") or 0) for row in live), "video_limit_total": sum(int(limit) for limit in limits if limit is not None), "unlimited_assignments": sum(1 for limit in limits if limit is None), - "rows": [{field: row.get(field) for field in _ASSIGNMENT_ROW_FIELDS} for row in live], + "rows": [ + {field: row.get(field) for field in _ASSIGNMENT_ROW_FIELDS} for row in live + ], } ) return output @@ -518,7 +518,11 @@ async def _execute_brief_update(ctx: CommandContext) -> Any: live = sum(1 for row in assignments if row.get("brief_id") == brief_id and _live(row)) data: dict[str, Any] = { "dry_run": dry_run, - "brief": {"id": brief_id, "title": summary.get("title"), "current_version": current_version}, + "brief": { + "id": brief_id, + "title": summary.get("title"), + "current_version": current_version, + }, "changes": changes, "live_assignments": live, } @@ -589,7 +593,11 @@ async def _execute_brief_upload_media(ctx: CommandContext) -> Any: content_type=str(session.get("content_type") or ""), size_bytes=int(args["size_bytes"]), ) - reference: dict[str, Any] = {"type": "stored", "kind": session.get("kind"), "url": session["url"]} + reference: dict[str, Any] = { + "type": "stored", + "kind": session.get("kind"), + "url": session["url"], + } if session.get("kind") == "file": reference["name"] = args["filename"] data = { @@ -598,10 +606,14 @@ async def _execute_brief_upload_media(ctx: CommandContext) -> Any: "url": session["url"], "size_bytes": args["size_bytes"], } - return data, [], [ - "Add data.reference to the brief's current references (document.references of " - "+get) and pass the whole list as --references-json to +update." - ] + return ( + data, + [], + [ + "Add data.reference to the brief's current references (document.references of " + "+get) and pass the whole list as --references-json to +update." + ], + ) async def _file_chunks(path: Path) -> AsyncIterator[bytes]: @@ -642,7 +654,10 @@ async def _execute_assignment_create(ctx: CommandContext) -> Any: { "enrollment_id": enrollment_id, "existing_assignment": ( - {"id": held[enrollment_id].get("id"), "status": held[enrollment_id].get("status")} + { + "id": held[enrollment_id].get("id"), + "status": held[enrollment_id].get("status"), + } if enrollment_id in held else None ), @@ -1029,9 +1044,7 @@ def _uuid_property(description: str) -> dict[str, Any]: return {"type": "string", "format": "uuid", "description": description} -_CAMPAIGN_ID = _uuid_property( - "UGC Campaign ID (from campaign +list)." -) +_CAMPAIGN_ID = _uuid_property("UGC Campaign ID (from campaign +list).") _DRY_RUN = { "type": "boolean", "default": False, @@ -1121,7 +1134,9 @@ def specs() -> list[CommandSpec]: ["campaign_id"], ), output_schema=_direct_output_schema("Roster rows (items) and next_cursor."), - examples=[f"museoncli ugc enrollment +list --campaign-id {campaign} --status participating"], + examples=[ + f"museoncli ugc enrollment +list --campaign-id {campaign} --status participating" + ], add_arguments=_add_enrollment_list_arguments, build_arguments=_build_enrollment_list_arguments, **read, # type: ignore[arg-type] @@ -1276,7 +1291,9 @@ def specs() -> list[CommandSpec]: "which creatives it would link, without writing." + _CONFIRM_FIRST ), adapter_tool_name="ugc_creative_apply_default_briefs", - input_schema=_schema({"campaign_id": _CAMPAIGN_ID, "dry_run": _DRY_RUN}, ["campaign_id"]), + input_schema=_schema( + {"campaign_id": _CAMPAIGN_ID, "dry_run": _DRY_RUN}, ["campaign_id"] + ), output_schema=_direct_output_schema( "linked (creative_id, brief_id, brief_title), ambiguous, without_assignment, dry_run." ), diff --git a/museoncli/domains/ugc_briefs.py b/museoncli/domains/ugc_briefs.py index e0e6436..d70d43d 100644 --- a/museoncli/domains/ugc_briefs.py +++ b/museoncli/domains/ugc_briefs.py @@ -61,7 +61,9 @@ def _shared_warning(view: dict[str, Any]) -> list[str]: if not linked: return [] more = " or more" if view.get("has_more_campaigns") else "" - return [f"{_plural(len(linked), 'Campaign uses', 'Campaigns use')}{more} this Format; the change reaches every one of them."] + return [ + f"{_plural(len(linked), 'Campaign uses', 'Campaigns use')}{more} this Format; the change reaches every one of them." + ] # -- library ------------------------------------------------------------------- @@ -98,10 +100,15 @@ async def _execute_library_get(ctx: CommandContext) -> Any: view = await _library_brief(ctx, args["id"]) summary = view["brief"] wanted = args.get("version") or summary.get("current_version") - versions = [*w._dicts(view.get("versions")), *([view["current"]] if isinstance(view.get("current"), dict) else [])] + versions = [ + *w._dicts(view.get("versions")), + *([view["current"]] if isinstance(view.get("current"), dict) else []), + ] version = next((item for item in versions if item.get("version") == wanted), None) if version is None: - raise RuntimeError(f"not_found: brief_version_not_found: the Format has no version {wanted}") + raise RuntimeError( + f"not_found: brief_version_not_found: the Format has no version {wanted}" + ) return { "brief": summary, "version": version, @@ -117,7 +124,11 @@ async def _execute_library_create(ctx: CommandContext) -> Any: args = ctx.arguments key = w.idempotency_key(args) document = args.get("document") or {} - data: dict[str, Any] = {"dry_run": args["dry_run"], "document": document, "idempotency_key": key} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "document": document, + "idempotency_key": key, + } if args["dry_run"]: return data, [], w.ask("the new Format") view = await w.call( @@ -212,11 +223,16 @@ async def _execute_campaign_create(ctx: CommandContext) -> Any: campaign_id = args["campaign_id"] briefs = await _campaign_briefs(ctx, campaign_id) key = w.idempotency_key(args) - body = {**args["document"], **({"persona_id": args["persona_id"]} if args.get("persona_id") else {})} + body = { + **args["document"], + **({"persona_id": args["persona_id"]} if args.get("persona_id") else {}), + } data: dict[str, Any] = {"dry_run": args["dry_run"], "document": body, "idempotency_key": key} warnings = ( [f"The Campaign already links a Format titled {body['title']!r}."] - if any(item.get("title") == body["title"] and item.get("status") == "active" for item in briefs) + if any( + item.get("title") == body["title"] and item.get("status") == "active" for item in briefs + ) else [] ) if args["dry_run"]: @@ -243,7 +259,9 @@ async def _execute_campaign_link(ctx: CommandContext) -> Any: return data, ["The Campaign already links this Format; nothing was written."], [] warnings = [] if replaces and replaces not in linked: - warnings.append("The Campaign does not link the Format to replace; the workbench refuses it.") + warnings.append( + "The Campaign does not link the Format to replace; the workbench refuses it." + ) if args["dry_run"]: return data, warnings, w.ask("which Format the Campaign would link") await w.call( @@ -260,7 +278,10 @@ async def _execute_campaign_unlink(ctx: CommandContext) -> Any: args = ctx.arguments campaign_id, brief_id = args["campaign_id"], args["id"] linked = {item.get("id"): item for item in await _campaign_briefs(ctx, campaign_id)} - data: dict[str, Any] = {"dry_run": args["dry_run"], "brief": _brief_line(linked.get(brief_id) or {"id": brief_id})} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "brief": _brief_line(linked.get(brief_id) or {"id": brief_id}), + } if brief_id not in linked: return data, ["The Campaign does not link this Format; nothing was written."], [] warnings = ["The Format stays in the library; only this Campaign stops using it."] @@ -294,7 +315,11 @@ async def _execute_campaign_copy(ctx: CommandContext) -> Any: if args["dry_run"]: return data, warnings, w.ask("the Format copy") params = compact_params( - {"version": version, "persona_id": args.get("persona_id"), "keep_source": "true" if keep_source else None} + { + "version": version, + "persona_id": args.get("persona_id"), + "keep_source": "true" if keep_source else None, + } ) written = await w.call( ctx, @@ -331,7 +356,11 @@ def _document(args: argparse.Namespace) -> dict[str, Any]: ) if len(content) > 20000: raise ValueError("The Format's body is at most 20000 characters.") - references = [write_reference(item) for item in _references(args.references_json)] if args.references_json else [] + references = ( + [write_reference(item) for item in _references(args.references_json)] + if args.references_json + else [] + ) if len(references) > 20: raise ValueError("At most 20 references.") caption = (args.required_caption or "").strip() or None @@ -357,7 +386,12 @@ def _build_library_list_arguments(args: argparse.Namespace) -> dict[str, Any]: if not 1 <= args.page_size <= _PAGE_LIMIT: raise ValueError(f"--page-size must be between 1 and {_PAGE_LIMIT}.") return compact_params( - {"status": args.status, "search": args.search, "cursor": args.cursor, "page_size": args.page_size} + { + "status": args.status, + "search": args.search, + "cursor": args.cursor, + "page_size": args.page_size, + } ) @@ -377,7 +411,11 @@ def _add_library_create_arguments(parser: argparse.ArgumentParser) -> None: def _build_library_create_arguments(args: argparse.Namespace) -> dict[str, Any]: - return {"document": _document(args), **w.build_idempotency_key(args), "dry_run": bool(args.dry_run)} + return { + "document": _document(args), + **w.build_idempotency_key(args), + "dry_run": bool(args.dry_run), + } def _add_library_update_arguments(parser: argparse.ArgumentParser) -> None: @@ -389,7 +427,9 @@ def _add_library_update_arguments(parser: argparse.ArgumentParser) -> None: content.add_argument("--content-file") parser.add_argument("--references-json") parser.add_argument("--required-caption") - parser.add_argument("--require-ad-disclosure", action=argparse.BooleanOptionalAction, default=None) + parser.add_argument( + "--require-ad-disclosure", action=argparse.BooleanOptionalAction, default=None + ) w.add_dry_run(parser) @@ -463,7 +503,9 @@ def _build_campaign_create_arguments(args: argparse.Namespace) -> dict[str, Any] return { "campaign_id": w._uuid(args.campaign_id, flag="--campaign-id"), "document": _document(args), - **({"persona_id": w._uuid(args.persona_id, flag="--persona-id")} if args.persona_id else {}), + **( + {"persona_id": w._uuid(args.persona_id, flag="--persona-id")} if args.persona_id else {} + ), **w.build_idempotency_key(args), "dry_run": bool(args.dry_run), } @@ -508,7 +550,9 @@ def _build_campaign_copy_arguments(args: argparse.Namespace) -> dict[str, Any]: "campaign_id": w._uuid(args.campaign_id, flag="--campaign-id"), "id": w._uuid(args.id, flag="--id"), **({"version": args.version} if args.version else {}), - **({"persona_id": w._uuid(args.persona_id, flag="--persona-id")} if args.persona_id else {}), + **( + {"persona_id": w._uuid(args.persona_id, flag="--persona-id")} if args.persona_id else {} + ), "keep_source": bool(args.keep_source), **w.build_idempotency_key(args), "dry_run": bool(args.dry_run), @@ -521,8 +565,15 @@ def _build_campaign_copy_arguments(args: argparse.Namespace) -> dict[str, Any]: _ID = w.uuid_property("Format (brief) ID.") _DOCUMENT = { "title": {"type": "string", "maxLength": 200, "description": "Format title."}, - "content": {"type": "string", "maxLength": 20000, "description": "The Format's body, Markdown."}, - "content_file": {"type": "string", "description": "Path to a UTF-8 file holding the Markdown body."}, + "content": { + "type": "string", + "maxLength": 20000, + "description": "The Format's body, Markdown.", + }, + "content_file": { + "type": "string", + "description": "Path to a UTF-8 file holding the Markdown body.", + }, "references_json": { "type": "string", "description": ( @@ -531,10 +582,21 @@ def _build_campaign_copy_arguments(args: argparse.Namespace) -> dict[str, Any]: "optional note. Upload a file first with ugc brief +upload-media." ), }, - "required_caption": {"type": "string", "maxLength": 2200, "description": "Caption every post must carry."}, - "require_ad_disclosure": {"type": "boolean", "description": "Posts must carry an ad disclosure."}, + "required_caption": { + "type": "string", + "maxLength": 2200, + "description": "Caption every post must carry.", + }, + "require_ad_disclosure": { + "type": "boolean", + "description": "Posts must carry an ad disclosure.", + }, +} +_VERSION = { + "type": "integer", + "minimum": 1, + "description": "Version to use; the current one when left out.", } -_VERSION = {"type": "integer", "minimum": 1, "description": "Version to use; the current one when left out."} _EXPECTED_VERSION = { "type": "integer", "minimum": 0, @@ -555,10 +617,22 @@ def specs() -> list[CommandSpec]: ), adapter="ugc_brief_library_list", properties={ - "status": {"type": "string", "enum": BRIEF_STATUSES, "description": "active (default) or archived."}, + "status": { + "type": "string", + "enum": BRIEF_STATUSES, + "description": "active (default) or archived.", + }, "search": {"type": "string", "maxLength": 200, "description": "Title search."}, - "cursor": {"type": ["string", "null"], "description": "next_cursor from the previous page."}, - "page_size": {"type": "integer", "minimum": 1, "maximum": _PAGE_LIMIT, "default": 50}, + "cursor": { + "type": ["string", "null"], + "description": "next_cursor from the previous page.", + }, + "page_size": { + "type": "integer", + "minimum": 1, + "maximum": _PAGE_LIMIT, + "default": 50, + }, }, required=[], output_description="Format lines (items: id, title, status, persona_id, current_version, ...) and next_cursor.", @@ -589,13 +663,16 @@ def specs() -> list[CommandSpec]: summary=( "Create a Format in the organization's library (not yet used by any Campaign; " "link it with ugc brief +link). --dry-run returns the document without writing." - + w.CONFIRM_FIRST + _ROLE + + w.CONFIRM_FIRST + + _ROLE ), adapter="ugc_brief_library_create", properties={**_DOCUMENT, "idempotency_key": w.IDEMPOTENCY_KEY, "dry_run": w.DRY_RUN}, required=["title"], output_description="dry_run, document, idempotency_key, brief.", - examples=["museoncli ugc brief-library +create --title 'Morning routine' --content-file ./format.md --dry-run"], + examples=[ + "museoncli ugc brief-library +create --title 'Morning routine' --content-file ./format.md --dry-run" + ], add_arguments=_add_library_create_arguments, build_arguments=_build_library_create_arguments, kind=w.WRITE, @@ -617,7 +694,9 @@ def specs() -> list[CommandSpec]: }, required=["id", "expected_version"], output_description="dry_run, brief, changes (field, before, after), linked_campaign_ids.", - examples=[f"museoncli ugc brief-library +update --id {b} --expected-version 2 --title 'Morning hook' --dry-run"], + examples=[ + f"museoncli ugc brief-library +update --id {b} --expected-version 2 --title 'Morning hook' --dry-run" + ], add_arguments=_add_library_update_arguments, build_arguments=_build_library_update_arguments, kind=w.WRITE, @@ -627,13 +706,17 @@ def specs() -> list[CommandSpec]: shortcut="+archive", summary=( "Archive a library Format: it leaves the library list (there is no restore). " - "--dry-run returns it and the Campaigns using it without writing." + w.CONFIRM_YES + _ROLE + "--dry-run returns it and the Campaigns using it without writing." + + w.CONFIRM_YES + + _ROLE ), adapter="ugc_brief_library_archive", properties={"id": _ID, "expected_version": _EXPECTED_VERSION, "dry_run": w.DRY_RUN}, required=["id", "expected_version"], output_description="dry_run, brief, linked_campaign_ids.", - examples=[f"museoncli ugc brief-library +archive --id {b} --expected-version 2 --dry-run"], + examples=[ + f"museoncli ugc brief-library +archive --id {b} --expected-version 2 --dry-run" + ], add_arguments=_add_library_archive_arguments, build_arguments=_build_library_archive_arguments, kind=w.DESTRUCTIVE, @@ -644,10 +727,16 @@ def specs() -> list[CommandSpec]: summary=( "Duplicate a library Format (its current version, or --version N) as a new " "Format in the library. --dry-run returns the source without writing." - + w.CONFIRM_FIRST + _ROLE + + w.CONFIRM_FIRST + + _ROLE ), adapter="ugc_brief_library_copy", - properties={"id": _ID, "version": _VERSION, "idempotency_key": w.IDEMPOTENCY_KEY, "dry_run": w.DRY_RUN}, + properties={ + "id": _ID, + "version": _VERSION, + "idempotency_key": w.IDEMPOTENCY_KEY, + "dry_run": w.DRY_RUN, + }, required=["id"], output_description="dry_run, source, version, idempotency_key, brief (the copy).", examples=[f"museoncli ugc brief-library +copy --id {b} --dry-run"], @@ -673,7 +762,9 @@ def specs() -> list[CommandSpec]: }, required=["campaign_id", "title"], output_description="dry_run, document, idempotency_key, brief.", - examples=[f"museoncli ugc brief +create --campaign-id {c} --title 'Unboxing' --content 'Open the box on camera.' --persona-id {p} --dry-run"], + examples=[ + f"museoncli ugc brief +create --campaign-id {c} --title 'Unboxing' --content 'Open the box on camera.' --persona-id {p} --dry-run" + ], add_arguments=_add_campaign_create_arguments, build_arguments=_build_campaign_create_arguments, kind=w.WRITE, @@ -729,14 +820,22 @@ def specs() -> list[CommandSpec]: "campaign_id": w.CAMPAIGN_ID, "id": _ID, "version": _VERSION, - "persona_id": w.uuid_property("The persona the copy is written for; the source's when left out."), - "keep_source": {"type": "boolean", "default": False, "description": "Link the copy beside the source."}, + "persona_id": w.uuid_property( + "The persona the copy is written for; the source's when left out." + ), + "keep_source": { + "type": "boolean", + "default": False, + "description": "Link the copy beside the source.", + }, "idempotency_key": w.IDEMPOTENCY_KEY, "dry_run": w.DRY_RUN, }, required=["campaign_id", "id"], output_description="dry_run, source, version, persona_id, keep_source, idempotency_key, brief.", - examples=[f"museoncli ugc brief +copy --campaign-id {c} --id {o} --keep-source --persona-id {p} --dry-run"], + examples=[ + f"museoncli ugc brief +copy --campaign-id {c} --id {o} --keep-source --persona-id {p} --dry-run" + ], add_arguments=_add_campaign_copy_arguments, build_arguments=_build_campaign_copy_arguments, kind=w.WRITE, diff --git a/museoncli/domains/ugc_broadcasts.py b/museoncli/domains/ugc_broadcasts.py index b2c0893..375fe59 100644 --- a/museoncli/domains/ugc_broadcasts.py +++ b/museoncli/domains/ugc_broadcasts.py @@ -127,7 +127,9 @@ def count(field: str) -> int: if selection.get("to_all_private_channels") else len(selection.get("private_channel_ids") or []) ), - "direct_messages": count("direct_messages") if selection.get("to_all_direct_messages") else 0, + "direct_messages": count("direct_messages") + if selection.get("to_all_direct_messages") + else 0, "public_channels": [ {"channel_id": cid, "name": channels.get(cid)} for cid in selection.get("guild_channel_ids") or [] @@ -146,10 +148,18 @@ def _reach_warnings(selection: dict[str, Any], audience: dict[str, Any]) -> list f"{numbers['direct_messages']} direct messages exceed the limit of {limit}; " "the server refuses the send (broadcast_too_many_direct_messages)." ) - if not (numbers["private_channels"] or numbers["direct_messages"] or numbers["public_channels"]): + if not ( + numbers["private_channels"] or numbers["direct_messages"] or numbers["public_channels"] + ): warnings.append("It reaches nobody: pick private channels, direct messages or channels.") - known = {str(item.get("channel_id")) for item in audience.get("channels") or [] if isinstance(item, dict)} - unknown = [cid for cid in selection.get("guild_channel_ids") or [] if known and cid not in known] + known = { + str(item.get("channel_id")) + for item in audience.get("channels") or [] + if isinstance(item, dict) + } + unknown = [ + cid for cid in selection.get("guild_channel_ids") or [] if known and cid not in known + ] if unknown: warnings.append(f"Channel {unknown[0]} is not a public channel of the Campaign's server.") if selection.get("purpose") == "recruitment" and audience.get("recruitment_blockers"): @@ -219,7 +229,11 @@ async def _execute_create(ctx: CommandContext) -> Any: return created, [], ["Nothing is sent yet: run +send (now) or +schedule (later)."] audience = await _audience(ctx, args["campaign_id"], selection["purpose"]) data = {"dry_run": True, "draft": selection, "would_reach_now": reach(selection, audience)} - return data, _reach_warnings(selection, audience), [ask_first("the draft and who it would reach")] + return ( + data, + _reach_warnings(selection, audience), + [ask_first("the draft and who it would reach")], + ) async def _execute_update(ctx: CommandContext) -> Any: @@ -247,9 +261,16 @@ async def _execute_update(ctx: CommandContext) -> Any: if args.get("dry_run"): audience = await _audience(ctx, args["campaign_id"], selection.get("purpose") or "notice") data["would_reach_now"] = reach(selection, audience) - return data, [*warnings, *_reach_warnings(selection, audience)], [ask_first("these changes")] + return ( + data, + [*warnings, *_reach_warnings(selection, audience)], + [ask_first("these changes")], + ) data["broadcast"] = await ctx.api_data_v2( - ctx.cfg, "PUT", _path(args), json_body=_write_body(selection, current.get("attachments") or []) + ctx.cfg, + "PUT", + _path(args), + json_body=_write_body(selection, current.get("attachments") or []), ) return data, [], [] @@ -290,7 +311,8 @@ async def run(ctx: CommandContext) -> Any: body = {"scheduled_at": args["scheduled_at"]} if action == "retry": failed = [ - item for item in detail.get("deliveries") or [] + item + for item in detail.get("deliveries") or [] if isinstance(item, dict) and item.get("can_retry") ] data["retryable_deliveries"] = len(failed) @@ -317,7 +339,11 @@ async def _execute_unschedule(ctx: CommandContext) -> Any: current = _broadcast(await _detail(ctx)) data: dict[str, Any] = {"dry_run": bool(args.get("dry_run")), "broadcast": _line(current)} if current.get("status") != "scheduled": - return data, [f"The broadcast is {current.get('status')}, not scheduled; nothing to cancel."], [] + return ( + data, + [f"The broadcast is {current.get('status')}, not scheduled; nothing to cancel."], + [], + ) if args.get("dry_run"): return data, [], [ask_first("the schedule that would be cancelled")] data["broadcast"] = await ctx.api_data_v2(ctx.cfg, "POST", _path(args, "/unschedule")) @@ -409,7 +435,12 @@ def _selection_edits(args: argparse.Namespace) -> dict[str, Any]: if len(body.strip()) > BODY_MAX: raise ValueError(f"--body is {len(body.strip())} characters; at most {BODY_MAX}.") edits["body"] = body - for name in ("purpose", "to_all_private_channels", "to_all_direct_messages", "mention_creators"): + for name in ( + "purpose", + "to_all_private_channels", + "to_all_direct_messages", + "mention_creators", + ): value = getattr(args, name) if value is not None: edits[name] = value @@ -591,8 +622,16 @@ def specs() -> list[CommandSpec]: "campaign_id": _CAMPAIGN_ID, "statuses": {"type": "array", "items": {"type": "string", "enum": STATUSES}}, "purpose": {"type": "string", "enum": PURPOSES}, - "cursor": {"type": ["string", "null"], "description": "next_cursor from the previous page."}, - "page_size": {"type": "integer", "minimum": 1, "maximum": PAGE_LIMIT, "default": 20}, + "cursor": { + "type": ["string", "null"], + "description": "next_cursor from the previous page.", + }, + "page_size": { + "type": "integer", + "minimum": 1, + "maximum": PAGE_LIMIT, + "default": 20, + }, }, ["campaign_id"], ), @@ -610,8 +649,12 @@ def specs() -> list[CommandSpec]: "withdrawn, with a Discord link) and its history." + _ROLE ), adapter_tool_name="ugc_broadcast_get", - input_schema=schema({"campaign_id": _CAMPAIGN_ID, "id": _BROADCAST_ID}, ["campaign_id", "id"]), - output_schema=_direct_output_schema("broadcast, deliveries, history, attachment_previews."), + input_schema=schema( + {"campaign_id": _CAMPAIGN_ID, "id": _BROADCAST_ID}, ["campaign_id", "id"] + ), + output_schema=_direct_output_schema( + "broadcast, deliveries, history, attachment_previews." + ), examples=[f"museoncli ugc broadcast +get --campaign-id {campaign} --id {broadcast}"], add_arguments=_add_get_arguments, build_arguments=_ids, @@ -665,7 +708,8 @@ def specs() -> list[CommandSpec]: shortcut="+send", summary=( "Send a draft or scheduled broadcast now; the recipients are fixed at this moment. " - "Without --yes it is refused with a preview of the message and who it would reach." + _ROLE + "Without --yes it is refused with a preview of the message and who it would reach." + + _ROLE ), adapter_tool_name="ugc_broadcast_send", input_schema=schema(_ID_INPUT, ["campaign_id", "id"]), @@ -734,7 +778,9 @@ def specs() -> list[CommandSpec]: adapter_tool_name="ugc_broadcast_retry", input_schema=schema(_ID_INPUT, ["campaign_id", "id"]), output_schema=_VIEW_OUT, - examples=[f"museoncli ugc broadcast +retry --campaign-id {campaign} --id {broadcast} --yes"], + examples=[ + f"museoncli ugc broadcast +retry --campaign-id {campaign} --id {broadcast} --yes" + ], add_arguments=_add_confirmed_arguments, build_arguments=_build_confirmed_arguments, **confirmed, # type: ignore[arg-type] @@ -787,7 +833,9 @@ def specs() -> list[CommandSpec]: _confirmed("send", what="the message and who it would reach", allowed="send") ), "ugc.broadcast-schedule": with_notes( - _confirmed("schedule", what="the message, when it goes and who it would reach", allowed="schedule") + _confirmed( + "schedule", what="the message, when it goes and who it would reach", allowed="schedule" + ) ), "ugc.broadcast-unschedule": with_notes(_execute_unschedule), "ugc.broadcast-retry": with_notes( diff --git a/museoncli/domains/ugc_campaign_settings_write.py b/museoncli/domains/ugc_campaign_settings_write.py index bbcc4e9..7551c2c 100644 --- a/museoncli/domains/ugc_campaign_settings_write.py +++ b/museoncli/domains/ugc_campaign_settings_write.py @@ -141,10 +141,20 @@ async def _execute_settings_update(ctx: CommandContext) -> Any: _validate_settings(merged, set(edits)) diff = w.changes(current, merged, [*SETTINGS_FIELDS]) if "application_form" in edits: - diff.append({"field": "application_form", "before": stored.get("application_form"), "after": edits["application_form"]}) + diff.append( + { + "field": "application_form", + "before": stored.get("application_form"), + "after": edits["application_form"], + } + ) rules_change = None if rules is not ... and rules != stored.get("platform_pay_rules"): - rules_change = {"field": "platform_pay_rules", "before": stored.get("platform_pay_rules"), "after": rules} + rules_change = { + "field": "platform_pay_rules", + "before": stored.get("platform_pay_rules"), + "after": rules, + } unknown = _platforms_of_rules(rules) - set(merged.get("allowed_platforms") or []) if unknown: raise ValueError( @@ -223,7 +233,10 @@ async def _execute_staff_set(ctx: CommandContext) -> Any: after = {key: args.get(key, before[key]) for key in before} data: dict[str, Any] = { "dry_run": args["dry_run"], - "before": {"managers": _people(stored.get("managers")), "operators": _people(stored.get("operators"))}, + "before": { + "managers": _people(stored.get("managers")), + "operators": _people(stored.get("operators")), + }, "after": after, "expected_updated_at": token, } @@ -241,12 +254,18 @@ async def _execute_staff_set(ctx: CommandContext) -> Any: # -- delivery targets -------------------------------------------------------- TARGET_FIELDS = ("target_views", "target_posts", "target_creators", "start_date", "due_date") -_TARGET_MAX = {"target_views": 9007199254740991, "target_posts": 2147483647, "target_creators": 100000} +_TARGET_MAX = { + "target_views": 9007199254740991, + "target_posts": 2147483647, + "target_creators": 100000, +} def _validate_target(target: dict[str, Any]) -> None: if not any(target.get(field) is not None for field in _TARGET_MAX): - raise ValueError("A target needs at least one of --target-views, --target-posts, --target-creators.") + raise ValueError( + "A target needs at least one of --target-views, --target-posts, --target-creators." + ) for field, maximum in _TARGET_MAX.items(): value = target.get(field) if value is not None and not 0 < value <= maximum: @@ -262,7 +281,9 @@ async def _targets(ctx: CommandContext, campaign_id: str) -> dict[str, Any]: def _find_target(view: dict[str, Any], target_id: str) -> dict[str, Any]: - found = next((item for item in w._dicts(view.get("items")) if item.get("id") == target_id), None) + found = next( + (item for item in w._dicts(view.get("items")) if item.get("id") == target_id), None + ) if found is None: raise RuntimeError("not_found: campaign_target_not_found: no such target in this Campaign") return found @@ -295,13 +316,20 @@ async def _execute_target_update(ctx: CommandContext) -> Any: after = {**before, **args["target"]} _validate_target(after) diff = w.changes(before, after, TARGET_FIELDS) - data: dict[str, Any] = {"dry_run": args["dry_run"], "id": target_id, "changes": diff, "expected_updated_at": token} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "id": target_id, + "changes": diff, + "expected_updated_at": token, + } if not diff: return data, [w.nothing_to_write("the current target")], [] if args["dry_run"]: return data, [], w.ask("the target changes") body = {**after, "expected_updated_at": token} - data["target"] = await w.call(ctx, "PUT", f"/campaigns/{campaign_id}/targets/{target_id}", body=body) + data["target"] = await w.call( + ctx, "PUT", f"/campaigns/{campaign_id}/targets/{target_id}", body=body + ) return data, [], [] @@ -343,7 +371,9 @@ def _validate_terms(terms: list[dict[str, Any]]) -> None: if not label or len(label) > 80: raise ValueError(f"Contract term {name}: label is required, at most 80 characters.") if not str(term.get("default_value") or "") or len(str(term["default_value"])) > 2000: - raise ValueError(f"Contract term {name}: default_value is required, at most 2000 characters.") + raise ValueError( + f"Contract term {name}: default_value is required, at most 2000 characters." + ) async def _execute_contract_set(ctx: CommandContext) -> Any: @@ -365,13 +395,21 @@ async def _execute_contract_set(ctx: CommandContext) -> Any: terms = _terms_of(stored) _validate_terms(terms) body = {"source": "custom", "body": text, "terms": terms} - before = {"source": stored.get("source"), "body": stored.get("body"), "terms": _terms_of(stored)} + before = { + "source": stored.get("source"), + "body": stored.get("body"), + "terms": _terms_of(stored), + } after = {"source": source, "body": body.get("body"), "terms": body.get("terms", [])} - diff = w.changes(before, after, ["source", "body", "terms"] if source == "custom" else ["source"]) + diff = w.changes( + before, after, ["source", "body", "terms"] if source == "custom" else ["source"] + ) data: dict[str, Any] = {"dry_run": args["dry_run"], "changes": diff} if not diff: return data, [w.nothing_to_write("the current contract")], [] - warnings = ["Contracts already sent keep their wording; contracts sent from now on use the new one."] + warnings = [ + "Contracts already sent keep their wording; contracts sent from now on use the new one." + ] if args["dry_run"]: if source == "custom": # The page's preview: the body filled the way sending fills it, for an example creator. @@ -523,7 +561,9 @@ def _validate_dm_rule(rule: dict[str, Any]) -> None: for field in ("utm_medium", "utm_source_platform"): value = str(rule.get(field) or "") if _PLACEHOLDER.search(value) or len(value) > 100: - raise ValueError(f"{field} takes no {{{{...}}}} placeholder and at most 100 characters.") + raise ValueError( + f"{field} takes no {{{{...}}}} placeholder and at most 100 characters." + ) campaign = str(rule.get("utm_campaign") or "").strip() if any(token != _ACCOUNT_TOKEN for token in _PLACEHOLDER.findall(campaign)): raise ValueError(f"utm_campaign takes only the {_ACCOUNT_TOKEN} placeholder.") @@ -553,7 +593,9 @@ async def _dm_rules(ctx: CommandContext, campaign_id: str) -> list[dict[str, Any async def _execute_dm_create(ctx: CommandContext) -> Any: args = ctx.arguments campaign_id = args["campaign_id"] - existing = [item for item in await _dm_rules(ctx, campaign_id) if item.get("status") != "archived"] + existing = [ + item for item in await _dm_rules(ctx, campaign_id) if item.get("status") != "archived" + ] rule = {**_DM_DEFAULTS, "keywords": [], **args["rule"]} _validate_dm_rule(rule) data: dict[str, Any] = {"dry_run": args["dry_run"], "rule": rule} @@ -578,7 +620,9 @@ async def _execute_dm_create(ctx: CommandContext) -> Any: async def _execute_dm_update(ctx: CommandContext) -> Any: args = ctx.arguments campaign_id, rule_id = args["campaign_id"], args["id"] - stored = next((item for item in await _dm_rules(ctx, campaign_id) if item.get("id") == rule_id), None) + stored = next( + (item for item in await _dm_rules(ctx, campaign_id) if item.get("id") == rule_id), None + ) if stored is None: raise RuntimeError("not_found: dm_rule_not_found: no such rule in this Campaign") token = w.check_token("updated_at", stored.get("updated_at"), args.get("expected_updated_at")) @@ -586,7 +630,12 @@ async def _execute_dm_update(ctx: CommandContext) -> Any: after = {**before, **args["rule"]} _validate_dm_rule(after) diff = w.changes(before, after, DM_FIELDS) - data: dict[str, Any] = {"dry_run": args["dry_run"], "id": rule_id, "changes": diff, "expected_updated_at": token} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "id": rule_id, + "changes": diff, + "expected_updated_at": token, + } if not diff: return data, [w.nothing_to_write("the current rule")], [] warnings: list[str] = [] @@ -723,9 +772,11 @@ async def _execute_payscale_create(ctx: CommandContext) -> Any: if args["dry_run"]: return data, warnings, w.ask("the new payscale") data["payscale"] = await w.call(ctx, "POST", f"/campaigns/{campaign_id}/payscales", body=body) - return data, warnings, [ - "Add its pay rates with ugc pay-rate +create --payscale-id ." - ] + return ( + data, + warnings, + ["Add its pay rates with ugc pay-rate +create --payscale-id ."], + ) async def _execute_payscale_update(ctx: CommandContext) -> Any: @@ -734,7 +785,11 @@ async def _execute_payscale_update(ctx: CommandContext) -> Any: edits = args["edits"] before = {field: scale.get(field) for field in edits} diff = w.changes(before, edits, list(edits)) - data: dict[str, Any] = {"dry_run": args["dry_run"], "payscale": _payscale_line(scale), "changes": diff} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "payscale": _payscale_line(scale), + "changes": diff, + } if not diff: return data, [w.nothing_to_write("the current payscale")], [] warnings = [] @@ -788,7 +843,11 @@ async def _execute_rate_create(ctx: CommandContext) -> Any: scale = _find_payscale(await _payscales(ctx, campaign_id), args["payscale_id"]) rate = {**args["rate"], "kind": args["kind"]} check_rate(args["kind"], rate) - data: dict[str, Any] = {"dry_run": args["dry_run"], "payscale": _payscale_line(scale), "rate": rate} + data: dict[str, Any] = { + "dry_run": args["dry_run"], + "payscale": _payscale_line(scale), + "rate": rate, + } if args["dry_run"]: data["preview"] = await _rate_preview(ctx, campaign_id, rate) return data, [], w.ask("the new pay rate and what a video would earn under it") @@ -813,7 +872,9 @@ async def _execute_rate_update(ctx: CommandContext) -> Any: if not diff: return data, [w.nothing_to_write("the current pay rate")], [] if args["dry_run"]: - data["preview"] = await _rate_preview(ctx, campaign_id, {**after, "kind": stored.get("kind")}) + data["preview"] = await _rate_preview( + ctx, campaign_id, {**after, "kind": stored.get("kind")} + ) return data, [], w.ask("the pay rate changes and what a video would earn under it") data["rate"] = await w.call(ctx, "PUT", f"/pay-rates/{args['id']}", body=after) return data, ["Creators on this payscale are paid by the changed rate from now on."], [] @@ -860,8 +921,12 @@ def _add_settings_arguments(parser: argparse.ArgumentParser) -> None: parser.add_argument("--budget-cap-cents") parser.add_argument("--post-grouping", choices=kebab_choices(POST_GROUPINGS)) parser.add_argument("--brief-mode", choices=kebab_choices(BRIEF_MODES)) - parser.add_argument("--allowed-platform", action="append", choices=w.PLATFORMS, dest="allowed_platforms") - parser.add_argument("--required-platform", action="append", choices=w.PLATFORMS, dest="required_platforms") + parser.add_argument( + "--allowed-platform", action="append", choices=w.PLATFORMS, dest="allowed_platforms" + ) + parser.add_argument( + "--required-platform", action="append", choices=w.PLATFORMS, dest="required_platforms" + ) parser.add_argument("--no-required-platforms", action="store_true") parser.add_argument("--files-only", action=argparse.BooleanOptionalAction, default=None) parser.add_argument("--discord-onboarding", action=argparse.BooleanOptionalAction, default=None) @@ -983,7 +1048,9 @@ def _build_target_arguments(args: argparse.Namespace) -> dict[str, Any]: { "target_views": w.optional_int(args.target_views, flag="--target-views", minimum=1), "target_posts": w.optional_int(args.target_posts, flag="--target-posts", minimum=1), - "target_creators": w.optional_int(args.target_creators, flag="--target-creators", minimum=1), + "target_creators": w.optional_int( + args.target_creators, flag="--target-creators", minimum=1 + ), "start_date": _date(args.start_date, flag="--start-date"), "due_date": _date(args.due_date, flag="--due-date"), } @@ -1017,7 +1084,11 @@ def _add_contract_arguments(parser: argparse.ArgumentParser) -> None: def _build_contract_arguments(args: argparse.Namespace) -> dict[str, Any]: out = _common(args) | {"source": args.source} - text = args.body if args.body is not None else (w.read_text(args.body_file) if args.body_file else None) + text = ( + args.body + if args.body is not None + else (w.read_text(args.body_file) if args.body_file else None) + ) terms = w.json_value(args.terms_json, flag="--terms-json") if args.source == "default" and (text is not None or terms is not ...): raise ValueError("--source default takes no --body or --terms-json.") @@ -1027,7 +1098,9 @@ def _build_contract_arguments(args: argparse.Namespace) -> dict[str, Any]: out["body"] = text if terms is not ...: if not isinstance(terms, list) or not all(isinstance(item, dict) for item in terms): - raise ValueError("--terms-json must be a JSON array of {name, label, default_value, states_pay}.") + raise ValueError( + "--terms-json must be a JSON array of {name, label, default_value, states_pay}." + ) out["terms"] = [ { "name": item.get("name"), @@ -1067,7 +1140,10 @@ def _guild(args: argparse.Namespace) -> str: def _build_discord_set_arguments(args: argparse.Namespace) -> dict[str, Any]: layout = w.passed( - {field: _snowflake(getattr(args, field), flag=f"--{field.replace('_', '-')}") for field in GUILD_FIELDS} + { + field: _snowflake(getattr(args, field), flag=f"--{field.replace('_', '-')}") + for field in GUILD_FIELDS + } | {"invite_url": w.optional_text(args.invite_url)} ) invite = layout.get("invite_url") @@ -1111,11 +1187,12 @@ def add(parser: argparse.ArgumentParser) -> None: parser.add_argument("--utm-medium") parser.add_argument("--utm-campaign") parser.add_argument( - "--utm-parameter", action="append", dest="utm_parameters", choices=kebab_choices(UTM_PARAMETERS) - ) - parser.add_argument( - "--status", choices=DM_STATUSES if not create else ["active", "paused"] + "--utm-parameter", + action="append", + dest="utm_parameters", + choices=kebab_choices(UTM_PARAMETERS), ) + parser.add_argument("--status", choices=DM_STATUSES if not create else ["active", "paused"]) parser.add_argument("--utm-source-platform") w.add_dry_run(parser) w.add_yes(parser) @@ -1171,8 +1248,12 @@ def _build_payscale_arguments(args: argparse.Namespace) -> dict[str, Any]: fields = w.passed( { "name": w.optional_text(args.name), - "cap_per_creator_cents": w.optional_int(args.cap_per_creator_cents, flag="--cap-per-creator-cents"), - "cap_reset_days": w.optional_int(args.cap_reset_days, flag="--cap-reset-days", minimum=1), + "cap_per_creator_cents": w.optional_int( + args.cap_per_creator_cents, flag="--cap-per-creator-cents" + ), + "cap_reset_days": w.optional_int( + args.cap_reset_days, flag="--cap-reset-days", minimum=1 + ), } ) if "name" in fields and not fields["name"]: @@ -1222,7 +1303,10 @@ def _build_rate_arguments(args: argparse.Namespace) -> dict[str, Any]: if getattr(args, "payscale_id", None) is not None: if not str(rate.get("name") or "").strip(): raise ValueError('--rate-json needs a "name".') - out |= {"payscale_id": w._uuid(args.payscale_id, flag="--payscale-id"), "kind": dekebab(args.kind)} + out |= { + "payscale_id": w._uuid(args.payscale_id, flag="--payscale-id"), + "kind": dekebab(args.kind), + } elif not rate: raise ValueError("--rate-json must name at least one field to change.") return out @@ -1247,7 +1331,10 @@ def _add_rate_delete_arguments(parser: argparse.ArgumentParser) -> None: def _int_or_none(description: str) -> dict[str, Any]: - return {"type": ["integer", "string", "null"], "description": description + " 'none' clears it."} + return { + "type": ["integer", "string", "null"], + "description": description + " 'none' clears it.", + } def specs() -> list[CommandSpec]: @@ -1265,22 +1352,53 @@ def specs() -> list[CommandSpec]: "mode, budget cap, post grouping, Format mode, platforms, Discord onboarding, and " "via --settings-json languages, countries, stay/warmup/trial rules, content intake " "and the apply form), plus the publishing-platform pay rule. --dry-run returns " - "the changes and the current settings without writing." + w.CONFIRM_FIRST + "the changes and the current settings without writing." + + w.CONFIRM_FIRST + _SETTINGS_ROLE ), adapter="ugc_campaign_settings_update", properties={ "campaign_id": w.CAMPAIGN_ID, - "approval_mode": {"type": "string", "enum": APPROVAL_MODES, "description": "auto approves applicants; manual waits for a reviewer."}, - "join_mode": {"type": "string", "enum": kebab_choices(JOIN_MODES), "description": "open (anyone with the apply link) or invite-only."}, + "approval_mode": { + "type": "string", + "enum": APPROVAL_MODES, + "description": "auto approves applicants; manual waits for a reviewer.", + }, + "join_mode": { + "type": "string", + "enum": kebab_choices(JOIN_MODES), + "description": "open (anyone with the apply link) or invite-only.", + }, "budget_cap_cents": _int_or_none("Campaign budget cap in cents."), - "post_grouping": {"type": "string", "enum": kebab_choices(POST_GROUPINGS), "description": "How a creative's posts on several platforms are counted for pay."}, - "brief_mode": {"type": "string", "enum": kebab_choices(BRIEF_MODES), "description": "Whether creators pick a Format or get one written for them."}, - "allowed_platforms": {"type": "array", "items": {"type": "string", "enum": w.PLATFORMS}, "description": "The platforms creators post on (replaces the list)."}, - "required_platforms": {"type": "array", "items": {"type": "string", "enum": w.PLATFORMS}, "description": "Platforms a creator must connect before starting; a subset of allowed_platforms."}, + "post_grouping": { + "type": "string", + "enum": kebab_choices(POST_GROUPINGS), + "description": "How a creative's posts on several platforms are counted for pay.", + }, + "brief_mode": { + "type": "string", + "enum": kebab_choices(BRIEF_MODES), + "description": "Whether creators pick a Format or get one written for them.", + }, + "allowed_platforms": { + "type": "array", + "items": {"type": "string", "enum": w.PLATFORMS}, + "description": "The platforms creators post on (replaces the list).", + }, + "required_platforms": { + "type": "array", + "items": {"type": "string", "enum": w.PLATFORMS}, + "description": "Platforms a creator must connect before starting; a subset of allowed_platforms.", + }, "no_required_platforms": {"type": "boolean", "description": "Require no platform."}, - "files_only": {"type": "boolean", "description": "Creators deliver files instead of posting."}, - "discord_onboarding": {"type": "boolean", "description": "Onboard creators through the Campaign's Discord server."}, + "files_only": { + "type": "boolean", + "description": "Creators deliver files instead of posting.", + }, + "discord_onboarding": { + "type": "boolean", + "description": "Onboard creators through the Campaign's Discord server.", + }, "settings_json": { "type": "string", "description": ( @@ -1304,7 +1422,7 @@ def specs() -> list[CommandSpec]: output_description="dry_run, campaign, expected_updated_at, changes (field, before, after); settings on a dry run.", examples=[ f"museoncli campaign settings +update --campaign-id {c} --approval-mode manual --budget-cap-cents 500000 --dry-run", - f"museoncli campaign settings +update --campaign-id {c} --settings-json '{{\"stay_rules\": {{\"inactivity_days\": 7}}}}' --dry-run", + f'museoncli campaign settings +update --campaign-id {c} --settings-json \'{{"stay_rules": {{"inactivity_days": 7}}}}\' --dry-run', ], add_arguments=_add_settings_arguments, build_arguments=_build_settings_arguments, @@ -1323,8 +1441,18 @@ def specs() -> list[CommandSpec]: adapter="ugc_campaign_staff_set", properties={ "campaign_id": w.CAMPAIGN_ID, - "manager_user_ids": {"type": "array", "items": {"type": "string", "format": "uuid"}, "maxItems": MAX_STAFF, "description": "User IDs of the PMs (replaces the list)."}, - "operator_user_ids": {"type": "array", "items": {"type": "string", "format": "uuid"}, "maxItems": MAX_STAFF, "description": "User IDs of the OPs (replaces the list)."}, + "manager_user_ids": { + "type": "array", + "items": {"type": "string", "format": "uuid"}, + "maxItems": MAX_STAFF, + "description": "User IDs of the PMs (replaces the list).", + }, + "operator_user_ids": { + "type": "array", + "items": {"type": "string", "format": "uuid"}, + "maxItems": MAX_STAFF, + "description": "User IDs of the OPs (replaces the list).", + }, "no_managers": {"type": "boolean", "description": "Remove every PM."}, "no_operators": {"type": "boolean", "description": "Remove every OP."}, **eua, @@ -1332,7 +1460,9 @@ def specs() -> list[CommandSpec]: }, required=["campaign_id"], output_description="dry_run, before (managers, operators), after (user ids), expected_updated_at.", - examples=[f"museoncli campaign staff +set --campaign-id {c} --manager-user-id {w.USER} --dry-run"], + examples=[ + f"museoncli campaign staff +set --campaign-id {c} --manager-user-id {w.USER} --dry-run" + ], add_arguments=_add_staff_arguments, build_arguments=_build_staff_arguments, kind=w.WRITE, @@ -1352,14 +1482,29 @@ def specs() -> list[CommandSpec]: "campaign_id": w.CAMPAIGN_ID, "target_views": {"type": "integer", "minimum": 1, "description": "Views to reach."}, "target_posts": {"type": "integer", "minimum": 1, "description": "Posts to reach."}, - "target_creators": {"type": "integer", "minimum": 1, "maximum": 100000, "description": "Creators to reach."}, - "start_date": {"type": "string", "format": "date", "description": "First day counted."}, - "due_date": {"type": "string", "format": "date", "description": "Last day counted."}, + "target_creators": { + "type": "integer", + "minimum": 1, + "maximum": 100000, + "description": "Creators to reach.", + }, + "start_date": { + "type": "string", + "format": "date", + "description": "First day counted.", + }, + "due_date": { + "type": "string", + "format": "date", + "description": "Last day counted.", + }, "dry_run": w.DRY_RUN, }, required=["campaign_id"], output_description="dry_run, target, existing_targets.", - examples=[f"museoncli ugc delivery-target +create --campaign-id {c} --target-views 1000000 --due-date 2026-12-31 --dry-run"], + examples=[ + f"museoncli ugc delivery-target +create --campaign-id {c} --target-views 1000000 --due-date 2026-12-31 --dry-run" + ], add_arguments=_add_target_arguments(create=True), build_arguments=_build_target_arguments, kind=w.WRITE, @@ -1371,7 +1516,8 @@ def specs() -> list[CommandSpec]: "Change a Campaign's delivery target; figures and dates not passed keep their " "value, 'none' clears one. The dates are the target's window only; they do not " "move the Campaign's start day. --dry-run returns the changes without writing." - + w.CONFIRM_FIRST + _TEAM_ROLE + + w.CONFIRM_FIRST + + _TEAM_ROLE ), adapter="ugc_delivery_target_update", properties={ @@ -1380,14 +1526,24 @@ def specs() -> list[CommandSpec]: "target_views": _int_or_none("Views to reach."), "target_posts": _int_or_none("Posts to reach."), "target_creators": _int_or_none("Creators to reach."), - "start_date": {"type": "string", "format": "date", "description": "First day counted; 'none' opens it."}, - "due_date": {"type": "string", "format": "date", "description": "Last day counted; 'none' opens it."}, + "start_date": { + "type": "string", + "format": "date", + "description": "First day counted; 'none' opens it.", + }, + "due_date": { + "type": "string", + "format": "date", + "description": "Last day counted; 'none' opens it.", + }, **eua, "dry_run": w.DRY_RUN, }, required=["campaign_id", "id"], output_description="dry_run, id, changes, expected_updated_at, target.", - examples=[f"museoncli ugc delivery-target +update --campaign-id {c} --id {o} --target-posts 300 --dry-run"], + examples=[ + f"museoncli ugc delivery-target +update --campaign-id {c} --id {o} --target-posts 300 --dry-run" + ], add_arguments=_add_target_arguments(create=False), build_arguments=_build_target_arguments, kind=w.WRITE, @@ -1400,10 +1556,17 @@ def specs() -> list[CommandSpec]: "writing." + w.CONFIRM_YES + _TEAM_ROLE ), adapter="ugc_delivery_target_delete", - properties={"campaign_id": w.CAMPAIGN_ID, "id": _ID("Target ID."), **eua, "dry_run": w.DRY_RUN}, + properties={ + "campaign_id": w.CAMPAIGN_ID, + "id": _ID("Target ID."), + **eua, + "dry_run": w.DRY_RUN, + }, required=["campaign_id", "id"], output_description="dry_run, target, deleted.", - examples=[f"museoncli ugc delivery-target +delete --campaign-id {c} --id {o} --dry-run"], + examples=[ + f"museoncli ugc delivery-target +delete --campaign-id {c} --id {o} --dry-run" + ], add_arguments=_add_target_delete_arguments, build_arguments=_build_id_arguments, kind=w.DESTRUCTIVE, @@ -1421,9 +1584,20 @@ def specs() -> list[CommandSpec]: adapter="ugc_contract_template_set", properties={ "campaign_id": w.CAMPAIGN_ID, - "source": {"type": "string", "enum": CONTRACT_SOURCES, "description": "default or custom."}, - "body": {"type": "string", "maxLength": 100000, "description": "The custom contract text, with {{name}} fields."}, - "body_file": {"type": "string", "description": "Path to a UTF-8 file holding the custom contract text."}, + "source": { + "type": "string", + "enum": CONTRACT_SOURCES, + "description": "default or custom.", + }, + "body": { + "type": "string", + "maxLength": 100000, + "description": "The custom contract text, with {{name}} fields.", + }, + "body_file": { + "type": "string", + "description": "Path to a UTF-8 file holding the custom contract text.", + }, "terms_json": { "type": "string", "description": ( @@ -1452,22 +1626,35 @@ def specs() -> list[CommandSpec]: "visitor and ops role ids and the invite link. On the same server, ids not " "passed keep their value; 'none' clears one. The workbench checks them with " "Discord first. --dry-run returns the layout before and after without writing." - + w.CONFIRM_FIRST + _TEAM_ROLE + + w.CONFIRM_FIRST + + _TEAM_ROLE ), adapter="ugc_discord_server_set", properties={ "campaign_id": w.CAMPAIGN_ID, - "guild_id": {"type": "string", "pattern": "^[0-9]{17,20}$", "description": "Discord server id."}, + "guild_id": { + "type": "string", + "pattern": "^[0-9]{17,20}$", + "description": "Discord server id.", + }, **{ - field: {"type": "string", "description": f"Discord {field.removesuffix('_id').replace('_', ' ')} id; 'none' clears it."} + field: { + "type": "string", + "description": f"Discord {field.removesuffix('_id').replace('_', ' ')} id; 'none' clears it.", + } for field in GUILD_FIELDS }, - "invite_url": {"type": "string", "description": "https:// invite link creators join with."}, + "invite_url": { + "type": "string", + "description": "https:// invite link creators join with.", + }, "dry_run": w.DRY_RUN, }, required=["campaign_id", "guild_id"], output_description="dry_run, changes, guild_link.", - examples=[f"museoncli ugc discord-server +set --campaign-id {c} --guild-id 123456789012345678 --welcome-channel-id 223456789012345678 --dry-run"], + examples=[ + f"museoncli ugc discord-server +set --campaign-id {c} --guild-id 123456789012345678 --welcome-channel-id 223456789012345678 --dry-run" + ], add_arguments=_add_discord_set_arguments, build_arguments=_build_discord_set_arguments, kind=w.WRITE, @@ -1483,12 +1670,18 @@ def specs() -> list[CommandSpec]: adapter="ugc_discord_server_initialize", properties={ "campaign_id": w.CAMPAIGN_ID, - "guild_id": {"type": "string", "pattern": "^[0-9]{17,20}$", "description": "Discord server id."}, + "guild_id": { + "type": "string", + "pattern": "^[0-9]{17,20}$", + "description": "Discord server id.", + }, "dry_run": w.DRY_RUN, }, required=["campaign_id", "guild_id"], output_description="dry_run, guild_id, current, guild_link.", - examples=[f"museoncli ugc discord-server +initialize --campaign-id {c} --guild-id 123456789012345678 --dry-run"], + examples=[ + f"museoncli ugc discord-server +initialize --campaign-id {c} --guild-id 123456789012345678 --dry-run" + ], add_arguments=_add_discord_initialize_arguments, build_arguments=_build_discord_initialize_arguments, kind=w.CONFIRMED_WRITE, @@ -1498,7 +1691,8 @@ def specs() -> list[CommandSpec]: shortcut="+remove", summary=( "Stop using the Campaign's Discord server; its channels and roles stay in " - "Discord. --dry-run returns the current server without writing." + w.CONFIRM_YES + "Discord. --dry-run returns the current server without writing." + + w.CONFIRM_YES + _TEAM_ROLE ), adapter="ugc_discord_server_remove", @@ -1543,7 +1737,9 @@ def specs() -> list[CommandSpec]: properties=_dm_properties(create=False), required=["campaign_id", "id"], output_description="dry_run, id, changes, expected_updated_at, rule.", - examples=[f"museoncli ugc dm-rule +update --campaign-id {c} --id {o} --status paused --dry-run"], + examples=[ + f"museoncli ugc dm-rule +update --campaign-id {c} --id {o} --status paused --dry-run" + ], add_arguments=_add_dm_arguments(create=False), build_arguments=_build_dm_arguments, kind=w.CONFIRMED_WRITE, @@ -1555,19 +1751,30 @@ def specs() -> list[CommandSpec]: "Add a custom payscale to a Campaign, with an optional per-creator cap " "(--cap-per-creator-cents over --cap-reset-days). Add its rates with ugc pay-rate " "+create. --dry-run returns it and the existing payscales without writing." - + w.CONFIRM_FIRST + _TEAM_ROLE + + w.CONFIRM_FIRST + + _TEAM_ROLE ), adapter="ugc_payscale_create", properties={ "campaign_id": w.CAMPAIGN_ID, "name": {"type": "string", "description": "Payscale name."}, - "cap_per_creator_cents": {"type": "integer", "minimum": 0, "description": "Most a creator earns per window, in cents."}, - "cap_reset_days": {"type": "integer", "minimum": 1, "description": "The cap's window in days."}, + "cap_per_creator_cents": { + "type": "integer", + "minimum": 0, + "description": "Most a creator earns per window, in cents.", + }, + "cap_reset_days": { + "type": "integer", + "minimum": 1, + "description": "The cap's window in days.", + }, "dry_run": w.DRY_RUN, }, required=["campaign_id", "name"], output_description="dry_run, payscale, existing.", - examples=[f"museoncli ugc payscale +create --campaign-id {c} --name 'Top creators' --dry-run"], + examples=[ + f"museoncli ugc payscale +create --campaign-id {c} --name 'Top creators' --dry-run" + ], add_arguments=_add_payscale_arguments(create=True), build_arguments=_build_payscale_arguments, kind=w.WRITE, @@ -1591,7 +1798,9 @@ def specs() -> list[CommandSpec]: }, required=["campaign_id", "id"], output_description="dry_run, payscale, changes.", - examples=[f"museoncli ugc payscale +update --campaign-id {c} --id {o} --cap-per-creator-cents 50000 --dry-run"], + examples=[ + f"museoncli ugc payscale +update --campaign-id {c} --id {o} --cap-per-creator-cents 50000 --dry-run" + ], add_arguments=_add_payscale_arguments(create=False), build_arguments=_build_payscale_arguments, kind=w.WRITE, @@ -1601,10 +1810,15 @@ def specs() -> list[CommandSpec]: shortcut="+delete", summary=( "Delete a custom payscale nobody is on. --dry-run returns it without writing." - + w.CONFIRM_YES + _TEAM_ROLE + + w.CONFIRM_YES + + _TEAM_ROLE ), adapter="ugc_payscale_delete", - properties={"campaign_id": w.CAMPAIGN_ID, "id": _ID("Payscale ID."), "dry_run": w.DRY_RUN}, + properties={ + "campaign_id": w.CAMPAIGN_ID, + "id": _ID("Payscale ID."), + "dry_run": w.DRY_RUN, + }, required=["campaign_id", "id"], output_description="dry_run, payscale, deleted.", examples=[f"museoncli ugc payscale +delete --campaign-id {c} --id {o} --dry-run"], @@ -1627,7 +1841,7 @@ def specs() -> list[CommandSpec]: required=["campaign_id", "payscale_id", "kind", "rate_json"], output_description="dry_run, payscale, rate, preview (dry run).", examples=[ - f"museoncli ugc pay-rate +create --campaign-id {c} --payscale-id {o} --kind anything-else --rate-json '{{\"name\": \"Per video\", \"base_rate_mode\": \"per_video\", \"base_fee_cents\": 5000}}' --dry-run" + f'museoncli ugc pay-rate +create --campaign-id {c} --payscale-id {o} --kind anything-else --rate-json \'{{"name": "Per video", "base_rate_mode": "per_video", "base_fee_cents": 5000}}\' --dry-run' ], add_arguments=_add_rate_arguments(create=True), build_arguments=_build_rate_arguments, @@ -1639,13 +1853,17 @@ def specs() -> list[CommandSpec]: summary=( "Change a pay rate: the fields in --rate-json change, the rest keep their value, " "and the rate is written whole (its kind never changes). --dry-run returns the " - "changes and what a video would earn, without writing." + w.CONFIRM_FIRST + _TEAM_ROLE + "changes and what a video would earn, without writing." + + w.CONFIRM_FIRST + + _TEAM_ROLE ), adapter="ugc_pay_rate_update", properties=_rate_properties(create=False), required=["campaign_id", "id", "rate_json"], output_description="dry_run, payscale, id, changes, preview (dry run), rate.", - examples=[f"museoncli ugc pay-rate +update --campaign-id {c} --id {o} --rate-json '{{\"base_fee_cents\": 6000}}' --dry-run"], + examples=[ + f"museoncli ugc pay-rate +update --campaign-id {c} --id {o} --rate-json '{{\"base_fee_cents\": 6000}}' --dry-run" + ], add_arguments=_add_rate_arguments(create=False), build_arguments=_build_rate_arguments, kind=w.WRITE, @@ -1655,10 +1873,15 @@ def specs() -> list[CommandSpec]: shortcut="+delete", summary=( "Delete a pay rate from its payscale. --dry-run returns it without writing." - + w.CONFIRM_YES + _TEAM_ROLE + + w.CONFIRM_YES + + _TEAM_ROLE ), adapter="ugc_pay_rate_delete", - properties={"campaign_id": w.CAMPAIGN_ID, "id": _ID("Pay rate ID."), "dry_run": w.DRY_RUN}, + properties={ + "campaign_id": w.CAMPAIGN_ID, + "id": _ID("Pay rate ID."), + "dry_run": w.DRY_RUN, + }, required=["campaign_id", "id"], output_description="dry_run, payscale, rate, deleted.", examples=[f"museoncli ugc pay-rate +delete --campaign-id {c} --id {o} --dry-run"], @@ -1675,20 +1898,61 @@ def _dm_properties(*, create: bool) -> dict[str, Any]: properties["id"] = _ID("Rule ID.") properties["expected_updated_at"] = w.EXPECTED_UPDATED_AT properties |= { - "keywords": {"type": "array", "items": {"type": "string", "maxLength": 50}, "maxItems": 20, "description": "Words a comment must carry (replaces the list)."}, + "keywords": { + "type": "array", + "items": {"type": "string", "maxLength": 50}, + "maxItems": 20, + "description": "Words a comment must carry (replaces the list).", + }, "any_comment": {"type": "boolean", "description": "Any comment triggers the DM."}, "match_mode": {"type": "string", "enum": MATCH_MODES, "description": "How keywords match."}, - "dm_message": {"type": "string", "maxLength": 607, "description": "The DM; {{name}} is the commenter."}, - "dm_message_file": {"type": "string", "description": "Path to a UTF-8 file holding the DM."}, - "comment_replies": {"type": "array", "items": {"type": "string", "maxLength": 300}, "maxItems": 6, "description": "Public replies to the comment, used in turn."}, + "dm_message": { + "type": "string", + "maxLength": 607, + "description": "The DM; {{name}} is the commenter.", + }, + "dm_message_file": { + "type": "string", + "description": "Path to a UTF-8 file holding the DM.", + }, + "comment_replies": { + "type": "array", + "items": {"type": "string", "maxLength": 300}, + "maxItems": 6, + "description": "Public replies to the comment, used in turn.", + }, "no_comment_replies": {"type": "boolean", "description": "Reply to no comment publicly."}, - "button_title": {"type": "string", "maxLength": 20, "description": "The DM's button label."}, + "button_title": { + "type": "string", + "maxLength": 20, + "description": "The DM's button label.", + }, "destination_url": {"type": "string", "description": "https:// page the button opens."}, - "utm_medium": {"type": "string", "maxLength": 100, "description": "The link's UTM medium (default dm)."}, - "utm_campaign": {"type": "string", "maxLength": 100, "description": "The link's UTM campaign; {{account}} is the posting account."}, - "utm_parameters": {"type": "array", "items": {"type": "string", "enum": kebab_choices(UTM_PARAMETERS)}, "description": "UTM parameters the link carries (replaces the list)."}, - "utm_source_platform": {"type": "string", "maxLength": 100, "description": "The link's UTM source platform (default museon)."}, - "status": {"type": "string", "enum": DM_STATUSES if not create else ["active", "paused"], "description": "active DMs, paused stops; archived ends the rule."}, + "utm_medium": { + "type": "string", + "maxLength": 100, + "description": "The link's UTM medium (default dm).", + }, + "utm_campaign": { + "type": "string", + "maxLength": 100, + "description": "The link's UTM campaign; {{account}} is the posting account.", + }, + "utm_parameters": { + "type": "array", + "items": {"type": "string", "enum": kebab_choices(UTM_PARAMETERS)}, + "description": "UTM parameters the link carries (replaces the list).", + }, + "utm_source_platform": { + "type": "string", + "maxLength": 100, + "description": "The link's UTM source platform (default museon).", + }, + "status": { + "type": "string", + "enum": DM_STATUSES if not create else ["active", "paused"], + "description": "active DMs, paused stops; archived ends the rule.", + }, "dry_run": w.DRY_RUN, } return properties @@ -1698,7 +1962,11 @@ def _rate_properties(*, create: bool) -> dict[str, Any]: properties: dict[str, Any] = {"campaign_id": w.CAMPAIGN_ID} if create: properties["payscale_id"] = _ID("Payscale ID.") - properties["kind"] = {"type": "string", "enum": kebab_choices(RATE_KINDS), "description": "What the block is; fixed once created."} + properties["kind"] = { + "type": "string", + "enum": kebab_choices(RATE_KINDS), + "description": "What the block is; fixed once created.", + } else: properties["id"] = _ID("Pay rate ID.") properties["rate_json"] = { diff --git a/museoncli/domains/ugc_enrollment_actions.py b/museoncli/domains/ugc_enrollment_actions.py index 0fe1d30..8f2747e 100644 --- a/museoncli/domains/ugc_enrollment_actions.py +++ b/museoncli/domains/ugc_enrollment_actions.py @@ -178,9 +178,7 @@ async def _execute_pause(ctx: CommandContext) -> Any: route="pause", allowed="active", done="paused", - warnings=[ - "A paused creator's posts are not collected or settled until they are resumed." - ], + warnings=["A paused creator's posts are not collected or settled until they are resumed."], ask="whom this pauses", ) @@ -241,9 +239,7 @@ async def _execute_set_persona(ctx: CommandContext) -> Any: data: dict[str, Any] = {"dry_run": args["dry_run"], "persona_id": persona} if args["dry_run"]: rows = await _rows(ctx, ids) - data["enrollments"] = [ - {**_row(rows[key]), "after": persona} for key in ids - ] + data["enrollments"] = [{**_row(rows[key]), "after": persona} for key in ids] changing = sum(1 for key in ids if rows[key].get("persona_id") != persona) warnings = [] if changing else ["Every enrollment already has this persona."] return data, warnings, [_ask_next_step("the persona before and after")] @@ -296,10 +292,14 @@ async def _execute_graduate_trial(ctx: CommandContext) -> Any: "trial": pick(trial, "on_trial", "outcome", "measure_by", "views_observed", "target_views"), } if args["dry_run"]: - return data, [ - "Graduating moves the creator off the trial payment structure onto the Campaign's " - "regular one." - ], [_ask_next_step("who graduates")] + return ( + data, + [ + "Graduating moves the creator off the trial payment structure onto the Campaign's " + "regular one." + ], + [_ask_next_step("who graduates")], + ) written = await call(ctx, "POST", f"/enrollments/{args['id']}/graduate-trial", body) data["enrollment"] = _row(written) if isinstance(written, dict) else written return data, [], [] diff --git a/museoncli/domains/ugc_messaging.py b/museoncli/domains/ugc_messaging.py index a505d8a..fbc1cb4 100644 --- a/museoncli/domains/ugc_messaging.py +++ b/museoncli/domains/ugc_messaging.py @@ -116,7 +116,12 @@ async def _execute_send(ctx: CommandContext) -> Any: data: dict[str, Any] = { "dry_run": args["dry_run"], "conversation": pick( - conversation, "enrollment_id", "campaign_name", "enrollment_status", "can_send", "blockers" + conversation, + "enrollment_id", + "campaign_name", + "enrollment_status", + "can_send", + "blockers", ), "body": args["body"], "idempotency_key": key, @@ -178,7 +183,9 @@ async def _execute_resend_card(ctx: CommandContext) -> Any: data: dict[str, Any] = { "dry_run": args["dry_run"], "kind": kebab(card), - "earlier_deliveries": [pick(row, "intent_id", "kind", "status", "error_code") for row in deliveries], + "earlier_deliveries": [ + pick(row, "intent_id", "kind", "status", "error_code") for row in deliveries + ], } warnings = ["The creator gets the card again; the delivery ledger picks the channel."] if args["dry_run"]: @@ -203,9 +210,11 @@ async def _execute_retry(ctx: CommandContext) -> Any: "delivery": pick(delivery, "intent_id", "kind", "status", "error_code"), } if args["dry_run"]: - return data, ["Retrying delivers the message to the creator again."], [ - _ask_next_step("which message would be delivered again") - ] + return ( + data, + ["Retrying delivers the message to the creator again."], + [_ask_next_step("which message would be delivered again")], + ) data["result"] = await call( ctx, "POST", f"/enrollments/{args['enrollment_id']}/messages/{args['id']}/retry" ) @@ -261,7 +270,9 @@ def _send_args(args: argparse.Namespace) -> dict[str, Any]: if about_creative and args.campaign_id is None: raise ValueError("--creative-id needs --campaign-id (the video's UGC campaign).") if not about_creative and args.campaign_id is not None: - raise ValueError("--campaign-id goes with --creative-id; a project message needs only --enrollment-id.") + raise ValueError( + "--campaign-id goes with --creative-id; a project message needs only --enrollment-id." + ) return { **( { @@ -384,7 +395,8 @@ def specs() -> list[CommandSpec]: "(read on their MuseOn project page); --campaign-id with --creative-id writes " "about one video and pushes it to their Discord. An idempotency key makes a " "retry safe; the CLI makes one when left out and returns it." - + OUTBOUND_NOTE + ROLE_MESSAGE + + OUTBOUND_NOTE + + ROLE_MESSAGE ), adapter_tool_name="ugc_message_send", input_schema=_schema( diff --git a/museoncli/domains/ugc_personas.py b/museoncli/domains/ugc_personas.py index d4772a4..7ce339d 100644 --- a/museoncli/domains/ugc_personas.py +++ b/museoncli/domains/ugc_personas.py @@ -200,13 +200,22 @@ def specs() -> list[CommandSpec]: ), adapter="ugc_persona_create", properties={ - "title": {"type": "string", "description": "Persona title, unique in the organization."}, - "description": {"type": "string", "maxLength": 2000, "description": "Who this creator is."}, + "title": { + "type": "string", + "description": "Persona title, unique in the organization.", + }, + "description": { + "type": "string", + "maxLength": 2000, + "description": "Who this creator is.", + }, "dry_run": w.DRY_RUN, }, required=["title"], output_description="dry_run and persona.", - examples=["museoncli ugc persona +create --title 'Busy mom' --description 'Parents of toddlers' --dry-run"], + examples=[ + "museoncli ugc persona +create --title 'Busy mom' --description 'Parents of toddlers' --dry-run" + ], add_arguments=_add_create_arguments, build_arguments=_build_create_arguments, kind=w.WRITE, @@ -222,7 +231,11 @@ def specs() -> list[CommandSpec]: properties={ "id": _ID, "title": {"type": "string", "description": "New title."}, - "description": {"type": "string", "maxLength": 2000, "description": "New description."}, + "description": { + "type": "string", + "maxLength": 2000, + "description": "New description.", + }, "dry_run": w.DRY_RUN, }, required=["id"], diff --git a/museoncli/domains/ugc_recruiting.py b/museoncli/domains/ugc_recruiting.py index 6ea2d33..e0712d8 100644 --- a/museoncli/domains/ugc_recruiting.py +++ b/museoncli/domains/ugc_recruiting.py @@ -216,10 +216,14 @@ async def _execute_invitation_create(ctx: CommandContext) -> Any: if not cursor: break same = [ - row for row in open_rows if str(row.get("address") or "").lower() == args["email"].lower() + row + for row in open_rows + if str(row.get("address") or "").lower() == args["email"].lower() ] if same: - data["open_invitations_to_this_address"] = [pick(row, *_INVITATION_FIELDS) for row in same] + data["open_invitations_to_this_address"] = [ + pick(row, *_INVITATION_FIELDS) for row in same + ] warnings.append( "An open invitation to this address exists; resend it with ugc invitation " "+resend instead of sending another." @@ -291,7 +295,11 @@ def _add_list(parser: argparse.ArgumentParser) -> None: def _list_args(args: argparse.Namespace) -> dict[str, Any]: - return {**_campaign(args), "page_size": _page_size(args), **compact_params({"cursor": args.cursor})} + return { + **_campaign(args), + "page_size": _page_size(args), + **compact_params({"cursor": args.cursor}), + } def _add_link_fields(parser: argparse.ArgumentParser) -> None: @@ -511,7 +519,8 @@ def specs() -> list[CommandSpec]: resource="recruit-link", shortcut="+revoke", summary=( - "Revoke a recruitment link: it stops working at once." + OUTBOUND_NOTE + "Revoke a recruitment link: it stops working at once." + + OUTBOUND_NOTE + ROLE_ENROLLMENT ), adapter_tool_name="ugc_recruit_link_revoke", @@ -557,7 +566,8 @@ def specs() -> list[CommandSpec]: shortcut="+create", summary=( "Invite a creator to a UGC campaign by email; MuseOn sends the invitation. The " - "preview flags an open invitation already sent to the address." + OUTBOUND_NOTE + "preview flags an open invitation already sent to the address." + + OUTBOUND_NOTE + ROLE_ENROLLMENT ), adapter_tool_name="ugc_invitation_create", @@ -602,7 +612,8 @@ def specs() -> list[CommandSpec]: resource="invitation", shortcut="+revoke", summary=( - "Revoke an open invitation: its link stops working." + OUTBOUND_NOTE + "Revoke an open invitation: its link stops working." + + OUTBOUND_NOTE + ROLE_ENROLLMENT ), adapter_tool_name="ugc_invitation_revoke", diff --git a/museoncli/domains/ugc_reminders.py b/museoncli/domains/ugc_reminders.py index 530455d..f3221ea 100644 --- a/museoncli/domains/ugc_reminders.py +++ b/museoncli/domains/ugc_reminders.py @@ -152,7 +152,11 @@ async def _execute_update(ctx: CommandContext) -> Any: "changes": diff, } if not diff: - return data, ["Nothing differs from the project's saved reminders; nothing was written."], [] + return ( + data, + ["Nothing differs from the project's saved reminders; nothing was written."], + [], + ) warnings = [] if settings.get("covered") is False: warnings.append( @@ -176,9 +180,11 @@ async def _execute_test(ctx: CommandContext) -> Any: settings = await _settings(ctx, args["campaign_id"]) data: dict[str, Any] = {"dry_run": bool(args.get("dry_run")), **_settings_line(settings)} if args.get("dry_run"): - return data, [], [ - ask_then_yes("that a test of the group's reminders goes to their own chat with Mel") - ] + return ( + data, + [], + [ask_then_yes("that a test of the group's reminders goes to their own chat with Mel")], + ) result = await ctx.api_data_v2( ctx.cfg, "POST", f"{_base(args['campaign_id'])}/reminder-settings/test" ) @@ -214,9 +220,7 @@ async def _execute_subscribe(ctx: CommandContext) -> Any: async def _execute_delegation_create(ctx: CommandContext) -> Any: args = ctx.arguments - body = { - key: args[key] for key in ("user_id", "delegate_user_id", "starts_at", "ends_at") - } + body = {key: args[key] for key in ("user_id", "delegate_user_id", "starts_at", "ends_at")} if args.get("dry_run"): settings = await _settings(ctx, args["campaign_id"]) overlapping = [ @@ -288,9 +292,11 @@ async def _execute_auto_nudge_update(ctx: CommandContext) -> Any: warnings.append("Days with no check are refused: pass --check for who gets nudged.") if args.get("dry_run"): turning = "off" if not after.get("days") else "on" - return data, warnings, [ - ask_then_yes(f"the change (it turns automatic creator nudges {turning})") - ] + return ( + data, + warnings, + [ask_then_yes(f"the change (it turns automatic creator nudges {turning})")], + ) body = { "checks": after.get("checks") or [], "days": after.get("days") or [], @@ -343,7 +349,9 @@ def _switch(value: str) -> bool | None: return None if value == INHERIT else value == "on" -def _list_edit(values: list[str], *, flag: str, allowed: list[str] | None = None) -> list[str] | None: +def _list_edit( + values: list[str], *, flag: str, allowed: list[str] | None = None +) -> list[str] | None: """inherit -> null (fall back), none -> [] (nothing), otherwise the values.""" if _inherit_list(values): return None @@ -556,7 +564,9 @@ def specs() -> list[CommandSpec]: {"campaign_id": _CAMPAIGN_ID, "edits": _POLICY_EDITS, "dry_run": DRY_RUN}, ["campaign_id", "edits"], ), - output_schema=_direct_output_schema("campaign_layer, effective and changes (field, before, after)."), + output_schema=_direct_output_schema( + "campaign_layer, effective and changes (field, before, after)." + ), examples=[ f"museoncli ugc reminder +update --campaign-id {campaign} --feishu on " "--digest-time 09:30 --digest-time 17:30 --task-kind review-creative " @@ -577,7 +587,9 @@ def specs() -> list[CommandSpec]: ), adapter_tool_name="ugc_reminder_test", input_schema=schema({"campaign_id": _CAMPAIGN_ID, "dry_run": DRY_RUN}, ["campaign_id"]), - output_schema=_direct_output_schema("test.outcome: sent, already_sent, no_direct_chat or unavailable."), + output_schema=_direct_output_schema( + "test.outcome: sent, already_sent, no_direct_chat or unavailable." + ), examples=[f"museoncli ugc reminder +test --campaign-id {campaign} --yes"], add_arguments=_add_test_arguments, build_arguments=_build_test_arguments, @@ -593,7 +605,11 @@ def specs() -> list[CommandSpec]: ), adapter_tool_name="ugc_reminder_subscribe", input_schema=schema( - {"campaign_id": _CAMPAIGN_ID, "subscribed": {"type": "boolean"}, "dry_run": DRY_RUN}, + { + "campaign_id": _CAMPAIGN_ID, + "subscribed": {"type": "boolean"}, + "dry_run": DRY_RUN, + }, ["campaign_id", "subscribed"], ), output_schema=_direct_output_schema("subscribed before and after."), @@ -668,7 +684,9 @@ def specs() -> list[CommandSpec]: ), adapter_tool_name="ugc_auto_nudge_get", input_schema=campaign_only, - output_schema=_direct_output_schema("checks, days, send_at, timezone, next_send_at, recent."), + output_schema=_direct_output_schema( + "checks, days, send_at, timezone, next_send_at, recent." + ), examples=[f"museoncli ugc auto-nudge +get --campaign-id {campaign}"], add_arguments=_add_campaign_only, build_arguments=_campaign, diff --git a/museoncli/domains/ugc_review_actions.py b/museoncli/domains/ugc_review_actions.py index c5fc26c..00cbb42 100644 --- a/museoncli/domains/ugc_review_actions.py +++ b/museoncli/domains/ugc_review_actions.py @@ -147,7 +147,9 @@ async def _execute_merge(ctx: CommandContext) -> Any: "into": pick(target, *_CREATIVE_FIELDS), "merged": [pick(rows[key], *_CREATIVE_FIELDS) for key in merged], } - others = [key for key in merged if rows[key].get("ugc_creator_id") != target.get("ugc_creator_id")] + others = [ + key for key in merged if rows[key].get("ugc_creator_id") != target.get("ugc_creator_id") + ] if others: raise RuntimeError( "conflict: video_merge_unavailable: only videos of the same creator merge; " @@ -183,7 +185,9 @@ async def _execute_stop_counting(ctx: CommandContext) -> Any: # No per-post read: the workbench decides each post when it is sent. return data, warnings, [_ask_next_step("which posts would stop counting")] if len(ids) == 1: - data["result"] = await call(ctx, "POST", f"/campaigns/{campaign}/posts/{ids[0]}/not-counted") + data["result"] = await call( + ctx, "POST", f"/campaigns/{campaign}/posts/{ids[0]}/not-counted" + ) else: data["result"] = await call( ctx, "POST", f"/campaigns/{campaign}/posts/not-counted", {"content_ids": ids} @@ -313,7 +317,9 @@ def _review_args(args: argparse.Namespace) -> dict[str, Any]: **compact_params( { "note": text(args.note, flag="--note", limit=5000), - "review_classification": "strategist_original" if args.strategist_original else None, + "review_classification": "strategist_original" + if args.strategist_original + else None, "expected_status": dekebab(args.expected_status), } ), @@ -606,7 +612,8 @@ def specs() -> list[CommandSpec]: shortcut="+create", summary=( "Start a feedback thread on a creative (optionally at --time-ms into the " - "video); the creator reads it and it is pushed to their Discord." + OUTBOUND_NOTE + "video); the creator reads it and it is pushed to their Discord." + + OUTBOUND_NOTE + ROLE_REVIEW ), adapter_tool_name="ugc_feedback_thread_create", @@ -625,7 +632,9 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "creative_id", "body"], ), - output_schema=_direct_output_schema("dry_run, creative, body, idempotency_key, thread."), + output_schema=_direct_output_schema( + "dry_run, creative, body, idempotency_key, thread." + ), examples=[ f"museoncli ugc feedback-thread +create --campaign-id {campaign} " f"--creative-id {creative} --body 'Cut the intro' --time-ms 2500 --dry-run" @@ -639,7 +648,8 @@ def specs() -> list[CommandSpec]: resource="feedback-thread", shortcut="+reply", summary=( - "Reply in a creative's feedback thread; the creator reads it." + OUTBOUND_NOTE + "Reply in a creative's feedback thread; the creator reads it." + + OUTBOUND_NOTE + ROLE_REVIEW ), adapter_tool_name="ugc_feedback_thread_reply", @@ -654,9 +664,7 @@ def specs() -> list[CommandSpec]: }, ["campaign_id", "creative_id", "id", "body"], ), - output_schema=_direct_output_schema( - "dry_run, thread, reply and idempotency_key." - ), + output_schema=_direct_output_schema("dry_run, thread, reply and idempotency_key."), examples=[ f"museoncli ugc feedback-thread +reply --campaign-id {campaign} " f"--creative-id {creative} --id {thread} --body 'Looks good now' --dry-run" diff --git a/museoncli/domains/ugc_task_actions.py b/museoncli/domains/ugc_task_actions.py index d357c3f..1921092 100644 --- a/museoncli/domains/ugc_task_actions.py +++ b/museoncli/domains/ugc_task_actions.py @@ -323,9 +323,7 @@ def _add_set_assignees(parser: argparse.ArgumentParser) -> None: def _build_set_assignees(args: argparse.Namespace) -> dict[str, Any]: assignees = ( - [] - if args.unassign - else uuids(args.assignee_user_ids, flag="--assignee-user-id", limit=20) + [] if args.unassign else uuids(args.assignee_user_ids, flag="--assignee-user-id", limit=20) ) return { **_id_args(args), @@ -372,7 +370,9 @@ def _add_run_action(parser: argparse.ArgumentParser) -> None: def _build_run_action(args: argparse.Namespace) -> dict[str, Any]: action = args.action.strip().lower() if not _ACTION.match(action): - raise ValueError("--action must be one of the task's actions, e.g. approve or attach-unpaid.") + raise ValueError( + "--action must be one of the task's actions, e.g. approve or attach-unpaid." + ) fields: dict[str, Any] = {} if args.fields_json is not None: try: diff --git a/museoncli/envelopes.py b/museoncli/envelopes.py index d9e4c08..93a20f9 100644 --- a/museoncli/envelopes.py +++ b/museoncli/envelopes.py @@ -40,7 +40,9 @@ def domain_command_envelope( response = adapter_response if isinstance(adapter_response, dict) else {} job = response.get("job") data = response.get("result") - if command_name.startswith("ai-slideshow.generation-") or _is_async_generation_command(command_name): + if command_name.startswith("ai-slideshow.generation-") or _is_async_generation_command( + command_name + ): data = add_generation_refs(data, site_url=site_url) run = None if isinstance(job, dict): @@ -66,7 +68,9 @@ def direct_api_envelope( *, site_url: str = DEFAULT_SITE_URL, ) -> dict[str, Any]: - if command_name.startswith("ai-slideshow.generation-") or _is_async_generation_command(command_name): + if command_name.startswith("ai-slideshow.generation-") or _is_async_generation_command( + command_name + ): data = add_generation_refs(data, site_url=site_url) if _is_async_generation_command(command_name): run = _generation_run_from_data(data) diff --git a/museoncli/guide.py b/museoncli/guide.py index afb2e64..d320afa 100644 --- a/museoncli/guide.py +++ b/museoncli/guide.py @@ -236,7 +236,9 @@ def validate() -> list[str]: seen: set[str] = set() def claim(kind: str, identifier: Any) -> None: - if not isinstance(identifier, str) or not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", identifier): + if not isinstance(identifier, str) or not re.fullmatch( + r"[a-z0-9]+(-[a-z0-9]+)*", identifier + ): problems.append(f"{kind} id must be kebab-case: {identifier!r}") return if identifier in seen: @@ -341,9 +343,7 @@ def overview() -> dict[str, Any]: } for chapter in chapters() ], - "unlisted": [ - {"match": entry["match"], "reason": entry["reason"]} for entry in unlisted() - ], + "unlisted": [{"match": entry["match"], "reason": entry["reason"]} for entry in unlisted()], } @@ -496,7 +496,10 @@ def search(words: list[str], *, task_limit: int = 8, command_limit: int = 10) -> [ *(spec.legacy_cli_path(name) for name in spec.legacy_shortcuts), # 1.x names it replaced: an Agent with an old Skill still finds it. - *(alias["cli"] for alias in removed_aliases(spec.cli_path.removeprefix("museoncli "))), + *( + alias["cli"] + for alias in removed_aliases(spec.cli_path.removeprefix("museoncli ")) + ), ] ) weighted = [ @@ -741,9 +744,7 @@ def render_llms_txt() -> str: ) lines += ["", "## Optional", ""] lines.append( - f"- [Topics]({GUIDE_URL}#topics): " - + "; ".join(topic["title"] for topic in topics()) - + "." + f"- [Topics]({GUIDE_URL}#topics): " + "; ".join(topic["title"] for topic in topics()) + "." ) lines.append( "- [Source and command contract](https://github.com/Museon-AI/museon-cli): " diff --git a/museoncli/large_json.py b/museoncli/large_json.py index 2d3d73c..f8165b7 100644 --- a/museoncli/large_json.py +++ b/museoncli/large_json.py @@ -545,8 +545,7 @@ def _powershell_query_manifest(path: str) -> dict[str, Any]: ], "templates": { "keys_and_types": ( - load - + "$result.PSObject.Properties.Name | ConvertTo-Json -Compress" + load + "$result.PSObject.Properties.Name | ConvertTo-Json -Compress" ), "count_and_fields": ( load diff --git a/museoncli/main.py b/museoncli/main.py index 8227cdc..6e8470b 100644 --- a/museoncli/main.py +++ b/museoncli/main.py @@ -266,9 +266,7 @@ def with_notice( return {**payload, "_notice": notice} if notice else payload -def skills_notice( - args: argparse.Namespace, update: dict[str, Any] | None -) -> dict[str, Any] | None: +def skills_notice(args: argparse.Namespace, update: dict[str, Any] | None) -> dict[str, Any] | None: """Keep the Agent's installed Skills on this CLI's version. Skills that `setup` installed are synced automatically, like the CLI itself; the @@ -359,9 +357,14 @@ def build_parser() -> argparse.ArgumentParser: "works too). --search: tasks and commands matching the words (English or 中文)." ), ) - guide_parser.add_argument("task", nargs="?", help="Task, chapter or topic id from `museoncli guide`.") guide_parser.add_argument( - "--search", nargs="+", metavar="WORD", help="Words describing the job, e.g. approve creator." + "task", nargs="?", help="Task, chapter or topic id from `museoncli guide`." + ) + guide_parser.add_argument( + "--search", + nargs="+", + metavar="WORD", + help="Words describing the job, e.g. approve creator.", ) sub.add_parser("whoami", help="The signed-in user and the organizations this login can act in.") sub.add_parser("health", help="Check that the Museon API answers.") @@ -572,9 +575,7 @@ def organization_view(cfg: Config) -> dict[str, Any] | None: def organizations_from_whoami(data: dict[str, Any]) -> tuple[list[dict[str, Any]], str | None]: """Organizations a login can act in, and its default one.""" rows = [ - row - for row in data.get("organizations") or [] - if isinstance(row, dict) and row.get("id") + row for row in data.get("organizations") or [] if isinstance(row, dict) and row.get("id") ] default_id = data.get("default_organization_id") or next( (row["id"] for row in rows if row.get("is_default")), None @@ -689,12 +690,15 @@ async def download_api_file( raise cli_outdated_error(response) raise ApiRequestError(response.status_code, response_error_payload(response)) content_type = response.headers.get("content-type", "").split(";", 1)[0].lower() - if content_type not in (allowed_content_types or { - "video/mp4", - "video/quicktime", - "video/webm", - "video/x-msvideo", - }): + if content_type not in ( + allowed_content_types + or { + "video/mp4", + "video/quicktime", + "video/webm", + "video/x-msvideo", + } + ): raise RuntimeError("unsupported_media_type") declared_length = response.headers.get("content-length") if declared_length: @@ -704,7 +708,9 @@ async def download_api_file( except ValueError as exc: raise RuntimeError("invalid_content_length") from exc written = 0 - with os.fdopen(os.open(destination, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "wb") as output: + with os.fdopen( + os.open(destination, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "wb" + ) as output: async for chunk in response.aiter_bytes(): written += len(chunk) if written > max_bytes: @@ -730,7 +736,11 @@ async def _api_request( if not auth_headers(cfg): raise RuntimeError("missing_auth") response = await _api_send( - cfg, method, url, json_body=json_body, params=params, + cfg, + method, + url, + json_body=json_body, + params=params, **({"idempotency_key": idempotency_key} if idempotency_key is not None else {}), ) if response.status_code == 401: @@ -767,7 +777,14 @@ async def _api_send( return await client.request( method, url, - headers={**_request_headers(cfg), **({"Idempotency-Key": idempotency_key} if idempotency_key is not None else {})}, + headers={ + **_request_headers(cfg), + **( + {"Idempotency-Key": idempotency_key} + if idempotency_key is not None + else {} + ), + }, json=json_body, params=params, ) @@ -829,9 +846,7 @@ def organization_id_arg(args: argparse.Namespace, arguments: dict[str, Any]) -> return str(value) -def envelope_organization( - cfg: Config, organization_id: str | None -) -> dict[str, Any] | None: +def envelope_organization(cfg: Config, organization_id: str | None) -> dict[str, Any] | None: """The organization a command addressed, for the envelope's ``organization`` key.""" if organization_id and organization_id != cfg.organization.id: return {"id": organization_id, "name": None} @@ -992,8 +1007,7 @@ async def upload_media_file( UUID(str(media_id)) except (ValueError, TypeError, AttributeError): raise RuntimeError( - "media_upload_unverified: receipt has no valid media_id; " - "do not retry the write blindly" + "media_upload_unverified: receipt has no valid media_id; do not retry the write blindly" ) from None return receipt @@ -1029,9 +1043,7 @@ async def upload_artifact_file( ): value = arguments.get(argument_key) if isinstance(value, dict): - form_data[form_key] = json.dumps( - value, ensure_ascii=False, separators=(",", ":") - ) + form_data[form_key] = json.dumps(value, ensure_ascii=False, separators=(",", ":")) if private_media_file and arguments.get("title") is not None: form_data["title"] = str(arguments["title"]) if not auth_headers(cfg): @@ -1239,7 +1251,9 @@ def deprecation_notices(args: argparse.Namespace) -> list[str]: f"`{old_flag}` is deprecated here and will be removed; use `{new_flag}` (same value)." ) if command: - notice = workspace_flag_notice(get_command_spec(command), getattr(args, "workspace_id", None)) + notice = workspace_flag_notice( + get_command_spec(command), getattr(args, "workspace_id", None) + ) if notice: notices.append(notice) return notices diff --git a/museoncli/secret_provider.py b/museoncli/secret_provider.py index 49509f4..bbba839 100644 --- a/museoncli/secret_provider.py +++ b/museoncli/secret_provider.py @@ -71,7 +71,9 @@ def resolve(self) -> CredentialLease: persistable=False, ) if lease.is_expired(): - return CredentialLease(**{**lease.__dict__, "value": None, "error": "credential_expired"}) + return CredentialLease( + **{**lease.__dict__, "value": None, "error": "credential_expired"} + ) return lease def _failure(self, error: str) -> CredentialLease: diff --git a/museoncli/setup_agent.py b/museoncli/setup_agent.py index 7125688..ee9fbec 100644 --- a/museoncli/setup_agent.py +++ b/museoncli/setup_agent.py @@ -164,9 +164,7 @@ def _skill_sources() -> dict[str, Any]: return sources -def _install_one( - source, agent: str, *, skill_name: str, force: bool -) -> dict[str, str]: +def _install_one(source, agent: str, *, skill_name: str, force: bool) -> dict[str, str]: destination = _agent_home(agent) / "skills" / skill_name source_digest = _tree_digest(source) if destination.is_dir() and _tree_digest(destination) == source_digest: diff --git a/museoncli/updates.py b/museoncli/updates.py index da6e337..1f2023f 100644 --- a/museoncli/updates.py +++ b/museoncli/updates.py @@ -663,6 +663,5 @@ def upgrade_result(update: dict[str, Any] | None) -> dict[str, Any]: "cannot upgrade itself." ) raise RuntimeError( - "network_error: could not reach GitHub to find the latest Museon CLI release; " - "retry later." + "network_error: could not reach GitHub to find the latest Museon CLI release; retry later." ) diff --git a/pyproject.toml b/pyproject.toml index 1df9105..0bfda98 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "museoncli" -version = "2.0.1" +version = "2.1.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-ai-slideshow/SKILL.md b/skills/museon-content-workflow-ai-slideshow/SKILL.md index 94eefa2..4fd53f6 100644 --- a/skills/museon-content-workflow-ai-slideshow/SKILL.md +++ b/skills/museon-content-workflow-ai-slideshow/SKILL.md @@ -33,7 +33,12 @@ Do not schedule a local Codex loop or use the manual generation path for this in 3. Keep each reference as an explicit `{format_id, topic_id}` pair. Twenty references mean twenty reviewed pairs, never a Cartesian product. Read back resource IDs before retrying imports; do not blindly recreate successful assets. -4. Create a Campaign only when the selected scope needs one. New CLI campaigns +4. Agree the publish time with the operator before any account is admitted: a + window in `--preferred-publish-windows-json` read in `--publish-timezone` + (IANA, e.g. `Europe/London`; default `Asia/Shanghai`), set on + `+campaign-create` or `+campaign-update`. One Campaign has one publish time + for all member accounts. Never convert the time into Asia/Shanghai by hand. + Create a Campaign only when the selected scope needs one. New CLI campaigns require manual strategy review and disable automatic recruitment. Existing campaigns must have that policy before `plan +supply-update`; changing it with `+campaign-review-only` affects the whole Campaign, so do not silently change @@ -50,13 +55,17 @@ Do not schedule a local Codex loop or use the manual generation path for this in reference version is confirmed. This applies their finalized supply and tops up the existing seven-day window. Inspect the calendar and `+plan-get` before `plan +account-control --action enable` for each selected account, using its - returned version. Current cadence is one post per account per local day, - starting with the next local day; do not promise arbitrary daily frequency. + returned version. Current cadence is one post per account per day at the + Campaign publish time, starting with the next day; do not promise arbitrary + daily frequency. Changing the publish time later moves future slots that + have not started generating; today's slot keeps its time. 8. Return the Plan ID, `web_url`, exact accounts, reference count, schedule, timezone and execution state. Use `plan +posts` and the account/calendar views for readback. Generation done, channel acceptance, public post and metrics availability are different facts. Missing metrics are not zero results. +To make up a missed day or add a post for one member, use `plan +extra-post` +with a stable idempotency key; it does not change the daily cadence. Maintenance uses the same Plan and resource IDs. Retire references through a reviewed supply update; do not erase their history. Reconcile the full desired account list to add/remove members. Pause/resume/stop selected accounts through @@ -80,6 +89,7 @@ stop on a handover conflict. Never overwrite the old Plan's persona identity. ## DON'T - **DON'T** bind generation to an account or schedule. +- **DON'T** expect a manual publish schedule on an Agentic Creative Campaign account to add a post: `publish +create-schedule` / `+submit-schedule-plan` on such an account makes that row the day's Plan post and replaces the automatic post of the day (even if already generated) unless it is publishing. Use it when the operator prepared that day's post by hand. To add a post on top of the daily one use `agentic-campaign plan +extra-post`; to post a new format/topic add the pair with `plan +supply-update` (other pairs are rejected with `AGENTIC_PLAN_PAIR_NOT_IN_PLAN`). - **DON'T** treat generation creation or a batch job receipt as terminal success. - **DON'T** add evaluator or CTA inputs, or bind generation itself to an account or schedule. - **DON'T** confuse a product's CTA targets (`cta-target`, what its posts point viewers to) with generation inputs. Listing, creating and editing them is staff only; `+retire` takes owner, admin or operator and `--yes` after the user agrees. `+create` has no idempotency key: list before retrying an unknown outcome. diff --git a/skills/museon-content-workflow-base/SKILL.md b/skills/museon-content-workflow-base/SKILL.md index 2eb151d..f216399 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.0.1/museoncli-2.0.1-py3-none-any.whl" +uv tool install "https://github.com/Museon-AI/museon-cli/releases/download/v2.1.0/museoncli-2.1.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 e72ed54..c944658 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 @@ -# Task index (Museon CLI 2.0.1) +# Task index (Museon CLI 2.1.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. @@ -88,7 +88,7 @@ AI image posts (生图/图文) are built from reusable format, topic and persona - **Change many accounts' pools or schedule plans at once** (`slideshow-bulk`): `museoncli ai-slideshow publish +bulk-get-asset-pools` → `museoncli ai-slideshow publish +bulk-preview-asset-pools` → `museoncli ai-slideshow publish +bulk-set-asset-pools` → `museoncli ai-slideshow publish +get-asset-pool-job` → `museoncli ai-slideshow publish +cancel-asset-pool-job` → `museoncli ai-slideshow publish +preview-schedule-plan` → `museoncli ai-slideshow publish +submit-schedule-plan` → `museoncli ai-slideshow publish +get-schedule-plan-job` → `museoncli ai-slideshow publish +cancel-schedule-plan-job` - **Manage a product's CTA targets** (`slideshow-cta`): `museoncli ai-slideshow cta-target +list` → `museoncli ai-slideshow cta-target +create` → `museoncli ai-slideshow cta-target +update` → `museoncli ai-slideshow cta-target +retire` - **Keep image posts publishing daily (Agentic Creative Campaign)** (`managed-publishing`): `museoncli agentic-campaign +list` → `museoncli agentic-campaign +campaign-create` → `museoncli agentic-campaign +campaign-review-only` → `museoncli agentic-campaign +plan-create` → `museoncli agentic-campaign plan +supply-update` → `museoncli agentic-campaign proposal +list` → `museoncli agentic-campaign proposal +get` → `museoncli agentic-campaign +schedule-rollout-preflight` → `museoncli agentic-campaign +confirm-schedule-rollout` → `museoncli agentic-campaign +schedule-rollout-get` → `museoncli agentic-campaign plan +members-reconcile` → `museoncli agentic-campaign plan +account-control` → `museoncli agentic-campaign plan +posts` → `museoncli agentic-campaign proposal +withdraw` -- **Read and maintain Agentic Creative Campaigns** (`managed-publishing-maintain`): `museoncli agentic-campaign +get` → `museoncli agentic-campaign +plan-list` → `museoncli agentic-campaign +plan-get` → `museoncli agentic-campaign +plan-tags` → `museoncli agentic-campaign +plan-attribution` → `museoncli agentic-campaign +campaign-update` → `museoncli agentic-campaign +plan-update` → `museoncli agentic-campaign +campaign-pause` → `museoncli agentic-campaign +campaign-activate` → `museoncli agentic-campaign +campaign-archive` +- **Read and maintain Agentic Creative Campaigns** (`managed-publishing-maintain`): `museoncli agentic-campaign +get` → `museoncli agentic-campaign +plan-list` → `museoncli agentic-campaign +plan-get` → `museoncli agentic-campaign +plan-tags` → `museoncli agentic-campaign +plan-attribution` → `museoncli agentic-campaign +campaign-update` → `museoncli agentic-campaign +plan-update` → `museoncli agentic-campaign plan +extra-post` → `museoncli agentic-campaign +campaign-pause` → `museoncli agentic-campaign +campaign-activate` → `museoncli agentic-campaign +campaign-archive` ## 6. Research, analyze content and handle media diff --git a/uv.lock b/uv.lock index 2c8b679..5790524 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 5 +revision = 3 requires-python = ">=3.11" [[package]] @@ -330,7 +330,7 @@ wheels = [ [[package]] name = "museoncli" -version = "2.0.1" +version = "2.1.0" source = { editable = "." } dependencies = [ { name = "anyio" },