@blocofy/cli 0.13.0 → 0.15.0

package/README.md

@@ -61,7 +61,7 @@ Show which site a command in `[dir]` would hit (verified), without writing anyth
 ### Theme
 
 ```
-blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
+blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>] [--instance <handle>]
 ```
 Start a local dev server that renders your local theme files with the site's live content.
 Press `l` to open it, `q` to quit. Edit a file and save → the view reloads. Saves sync to a
@@ -73,13 +73,17 @@ changing credentials, context or the project binding).
 - `--port <n>` — local port (default 3030).
 - `--no-sync` — local preview only (skip draft sync).
 - `--name <name>` — name the draft when it is first created (ignored if it already exists).
+- `--instance <handle>` — sync into this draft. Needed when the platform cannot tell which draft is the
+  CLI draft (see "Which draft a draft command writes to" below); the live theme's handle is refused.
 
 ```
 blocofy theme pull [dir] [--draft] [--instance <handle>]
 ```
 Download the live theme to disk. `dir` defaults to cwd.
-- `--draft` — pull the draft theme (what `theme dev` syncs into) instead of live; creates the
-  draft if missing, so it needs a bound project.
+- `--draft` — pull the CLI draft (what `theme dev` and `theme push --draft` write into) instead of
+  live. Read-only: it never creates the draft. With no CLI draft yet the platform answers
+  `target_missing` and the CLI stops (exit 2, nothing written) and tells you to run
+  `blocofy theme push --draft` first. It still needs a bound project.
 - `--instance <handle>` — pull a specific theme by its handle (admin panel theme card, or
   `blocofy status`).
 
@@ -94,11 +98,19 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
   non-interactive shells must add `--yes`.
 - `--draft` — explicit draft (same as the default; safe).
 - `--yes` — confirm a `--live` push without prompting (CI/agents).
-- `--instance <handle>` — push to a specific theme by its handle (safe targeted write — no
-  live-confirmation prompt).
-- `--name <name>` — name the new draft (draft mode only; ignored on `--live`/`--instance`). A draft
-  push reuses the existing CLI draft whatever its name; then the push says `--name` was not applied
-  and prints the `blocofy theme rename` command for it.
+- `--instance <handle>` — push to a specific theme by its handle. The live theme's handle asks for
+  the same confirmation as `--live` (non-interactive shells add `--yes`); so does any handle the CLI
+  cannot tell apart from the live theme (the live theme is unknown, or a raw numeric id was given).
+  With `--draft --instance <handle>` the push is a draft write to that draft: it never writes the
+  live theme (refused locally and by the platform, `draft_target_is_live`).
+  On a site with **no live theme** (or when the live theme cannot be read) the CLI cannot tell any
+  handle apart from the live one, so it stays on the safe side by design: every `--instance` push
+  asks for confirmation (`--yes` in non-interactive shells), and `--draft --instance` and
+  `theme dev --instance` refuse.
+- `--name <name>` — name the new draft: it is created as `CLI Draft — <name>` (draft mode only;
+  ignored on `--live`/`--instance`). When the push reuses the existing CLI draft instead, it says
+  `--name` was not applied. Do not rename the CLI draft by hand to a name that does not start with
+  `CLI Draft — `: the next draft push would refuse it and ask for `--instance`.
 - `--dry-run` / `--validate` — check the push on the server without writing; the two flags are
   aliases. The dry run covers exactly the files the push would send (remote-only files it keeps
   included; with `--prune`, without the ones it would remove). A current platform plans the whole
@@ -108,6 +120,32 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
   compares with the CLI draft it writes to (named by handle); with no CLI draft yet, with the live
   theme (the push would create the draft). `--live` compares with live, `--instance` with that theme.
 
+**Which draft a draft command writes to.** A draft push, `theme pull --draft` and the `theme dev`
+sync write to (or read) the CLI draft only when the platform can tell which draft that is: exactly
+one draft created by a CLI push, still carrying a name the platform gives it (`CLI Draft`,
+`CLI Draft — YYYY-MM-DD` or `CLI Draft — <name>`), and not a draft a site-state restore built.
+Otherwise — two such drafts, a site-state restore draft, or a CLI draft renamed by hand — the command
+writes nothing, lists the candidate drafts and exits 2 (`draft_target_ambiguous`). The message
+pre-fills `--instance <handle>` only for a CLI-named draft that is not a restore draft; naming any
+other listed draft would overwrite it. On a site whose only candidate is a site-state restore draft,
+create a new draft theme in the admin panel and pass its handle with `--instance`, or publish or
+delete the restore draft first. `theme publish` without `--instance` uses the same rule and never
+publishes a guessed draft. With no draft at all, the first push creates one as before.
+
+**When the platform cannot create the new draft.** A draft push (or the `theme dev` sync) that needs
+a new CLI draft can be refused by the platform's capacity check. Nothing is written in any of these
+cases; the CLI explains it in plain words first, then prints the `error [code]` line (the `--json`
+envelope keeps the code and details):
+- `quota_exceeded` (exit 2) — worded by `details.resource`, with the usage the platform reports: the
+  site's theme space is full (`theme_bytes`) or a site not on theme space reached its old draft count
+  (`theme_drafts`) — remove a draft you no longer need (neither is a plan limit); the plan's storage
+  is full (`storage_mb`) — the plan message.
+- `capacity_unavailable` / `resource_busy` (exit 1) — temporary. The CLI has already retried within
+  its normal retry policy (waiting as long as the server's `Retry-After` asks); try again later.
+- `source_stale` (exit 2) — the live theme the new draft copies changed meanwhile; run the command
+  again.
+`theme dev` reports each of them in one line and tries again on the next save.
+
 After a draft push the CLI prints the draft it wrote to (`Draft: <handle> "<name>" (new)` or
 `(existing CLI draft, updated)`) and the `blocofy theme publish --instance <handle>` command.
 - `--idempotency-key <k>` — attach a key so a retried push is not double-applied.
@@ -158,7 +196,68 @@ flag, publishes the draft that `theme dev` / `theme push --draft` writes into. T
 refuses to publish a theme that has no pages (it would 404); preview first. The site is the one
 `[dir]`'s project is bound to (`dir` defaults to cwd), so `blocofy theme push ./shop && blocofy
 theme publish ./shop` always publishes `./shop`'s site, whatever directory you run it from.
-- `--instance <handle>` — publish a specific theme.
+- `--instance <handle>` — publish a specific theme. Without it the platform publishes only the
+  site's CLI draft; any other theme (a site-state restore draft, a renamed or panel-copied theme) is
+  refused with `publish_target_unconfirmed` (exit 2, nothing published) — name it with `--instance`.
+
+### Theme work (new)
+
+A **work** is a private, safe copy of the site's current live theme: you change it, visitors never
+see it, and a person approves its publication in the admin panel (the CLI never publishes a work).
+Work commands use the **v1 API key** (`blocofy login --api-key`, or `BLOCOFY_API_KEY` +
+`BLOCOFY_API_URL`): the work belongs to the key that started it. The dev token alone is refused
+(`LOGIN_REQUIRED`) before any request.
+
+```
+blocofy theme work start [dir] [--intent "<text>"] [--idempotency-key <k>]
+blocofy theme work status <wk_…> [--dir <dir>]
+blocofy theme work resume <wk_…> [--dir <dir>] [--require-fresh]
+blocofy theme work cancel <wk_…> [--dir <dir>]
+blocofy theme work seal <wk_…> [--dir <dir>]
+blocofy theme work request-approval <wk_…> [--dir <dir>] [--open] [--wait [--interval <s>]]
+blocofy theme push [dir] --draft --work <wk_…>
+```
+- `seal` prepares the work for review: its content is frozen and can no longer change. It asks for
+  no approval and publishes nothing. On a platform without this step it says so (`seal_unsupported`,
+  exit 2); `request-approval` prepares the work itself.
+- `request-approval` asks a person to publish the work (an open work is prepared for review first)
+  and prints the **approval URL**. A signed-in site owner, or a team member with the theme permission,
+  approves on that Blocofy page. The URL carries no token: having it is not a permission to publish.
+  `--open` also opens it in your browser (only when it is this platform's approval page). `--wait`
+  polls the read-only publish status until the work is published or the request ends; the CLI never
+  publishes a work. How `--wait` ends:
+
+  | Exit | Code (`--json` envelope) | Meaning |
+  | --- | --- | --- |
+  | 0 | — | Approved and published; the work is live. |
+  | 2 | `approval_stale` | The live site changed after the request; nothing published. Start a new work from the current live site and ask again. |
+  | 2 | `approval_expired` | Nobody decided within 15 minutes; nothing published. Ask again. |
+  | 2 | `approval_declined` | The request was declined; nothing published. |
+  | 2 | `approval_superseded` | The work was reopened for changes; this request is no longer valid. Ask again. |
+  | 2 | `work_cancelled` | The work was cancelled; nothing published. |
+  | 1 | `publish_failed` | The work could not be completed; nothing published. Check `theme work status`. |
+  | 1 | `wait_timeout` | No decision yet; the CLI stopped waiting. The request stays valid until it expires. |
+
+  A refusal before the wait starts (for example `work_state_conflict`) exits as usual (2 for a 4xx,
+  1 for a 5xx); see [Exit codes](#exit-codes).
+- `status` also shows where the publication stands (preparing, ready for review, waiting for
+  approval with its URL, published, needs update).
+- `start` prints the work's handle (`wk_…`) and saves it in `.blocofy/local.json` (git-ignored; the
+  handle alone grants nothing). It sends an `Idempotency-Key` (yours, or a printed `cli-work-<uuid>`):
+  the same key returns the same work, never a second one. When the answer is lost (network, 5xx),
+  the CLI prints the exact command to run again with the same key.
+- `status`, `resume` and `cancel` always take the handle; with none they suggest the project's saved
+  work and stop. `status` and `resume` say whether the site changed since the work started; a changed
+  site is never overwritten. `resume --require-fresh` refuses (`work_stale`) instead.
+- `cancel` reads the work's `state_version` and sends it; the live site is untouched and the work's
+  theme stays in the theme library.
+- `theme push --work <wk_…>` writes into that work's own draft theme (`--work` implies `--draft`; it
+  cannot be combined with `--live` or `--instance`). It needs **both** the dev token and the API key of
+  the same site, and refuses unless the work is open (`work_state_conflict`, nothing written).
+- Refusals print a plain Turkish explanation first, then the `error [code]` line (`--json`: the
+  envelope only): `not_found`, `work_forbidden`, `work_state_conflict`, `work_stale`, `work_sealed`,
+  `work_base_unavailable`, `quota_exceeded`, `capacity_unavailable`, `resource_busy`,
+  `idempotency_key_reuse` (exit 2 for a 4xx, 1 for a 5xx).
 
 ### Status
 
@@ -461,6 +560,71 @@ Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.15.0** (2026-10-05) — Theme space, theme work and human-approved
+  publishing. Pairs with the platform release that replaces the 5-draft limit with a per-site theme
+  space.
+  - **Capacity refusals in plain words.** A theme write refused by the platform explains why in
+    plain Turkish first, then prints the usual `error [code]` line (`--json`: the envelope only):
+    - `quota_exceeded` (exit 2) is worded by `details.resource`. `theme_bytes`: the site's theme space
+      is full — on any push, a push to an existing draft with `--instance` included. It shows used /
+      allowance from `details`, says to free space by deleting unused draft themes from the theme
+      library (cancelled works' themes included; cancelling an open work also releases its reserved
+      publish space; an archived work's theme still counts), or to contact support, and never suggests a plan upgrade or says "new draft" (theme space is not
+      a plan quota). `theme_drafts` (the old draft count, on sites that have not moved to theme space)
+      is not a plan limit either: it says to remove a draft you no longer need, never to upgrade.
+      Only `storage_mb` keeps the plan message. The envelope carries the server's `details`.
+    - `work_revision_limit` (exit 2; `theme work seal`, or `request-approval` when it prepares the
+      work): a work can be sent for review at most 20 times (`details.limit`); start a new work.
+    - `capacity_unavailable` / `resource_busy` (exit 1, after the usual retries that honour
+      `Retry-After`; the envelope carries `retryAfterSeconds`): a temporary refusal, try again later.
+      A 503 on the write is no longer reported as "outcome unknown" (the platform wrote nothing),
+      unless an earlier attempt of the same push got no answer.
+    - `source_stale` (exit 2): the live theme changed while a new draft was copied; run it again.
+    - `theme dev` reports the same refusals in one line per save.
+  - **`theme pull --draft` is read-only.** Help and README no longer claim it creates the draft. With
+    no CLI draft the platform answers 404 `target_missing`; the CLI tells you to run
+    `blocofy theme push --draft` first (exit 2, nothing written). The command still needs a bound
+    project (kept for platforms from before this change).
+  - **New: theme work.** `theme work start|status|resume|cancel` and `theme push --work <wk_…>`
+    (v1 API key; see "Theme work"). A work is a private copy of the current live theme, named only by
+    its handle; the handle is saved in `.blocofy/local.json`. A plain `theme push` is unchanged and
+    never calls the work API.
+  - **New: human-approved publishing.** `theme work seal` (prepare for review, asks for no approval)
+    and `theme work request-approval [--open] [--wait [--interval <s>]]`: prints the approval URL (no
+    token in it), optionally opens it, and `--wait` polls the status read-only — exit 0 when
+    published, 2 when the request ends without a publication (`approval_stale`, `approval_expired`,
+    `approval_declined`, `approval_superseded`, `work_cancelled`), 1 on `wait_timeout` or
+    `publish_failed` (table under "Theme work"). `theme work status` shows the publish status. The CLI
+    never publishes a work.
+  - **`theme publish` names a work copy's refusal.** Publishing a theme work's copy directly is refused
+    by the platform (`work_not_publishable`, exit 2, nothing published); the CLI now keeps that code
+    (it printed `HTTP_409` before) and says to send the work for review and ask for approval.
+  - Unchanged: retry classes, `draft_target_ambiguous` handling, idempotency keys, target guards and
+    protocol headers.
+- **0.14.0** — Draft commands no longer guess their draft (platform #989).
+  - **Behaviour change:** `theme push` (draft), `theme push --diff`, `theme pull --draft` and the
+    `theme dev` sync refuse, writing nothing, when the platform answers `draft_target_ambiguous` (or the
+    site status shows the same case): the message lists the candidate drafts and the exact
+    `--instance <handle>` command; exit code 2; never retried. A CLI draft you renamed is refused too.
+  - The refusal pre-fills `--instance` only for a safe candidate (CLI-named, not a restore draft) and
+    otherwise warns that naming a listed draft would overwrite it.
+  - `theme dev --instance <handle>` and `theme push --draft --instance <handle>` write to a chosen draft
+    (sent with `draft: true`; never the live theme).
+  - `theme dev` reports a draft-sync failure in one line, also at startup (it was silent there):
+    `draft_target_unverifiable` (the next save tries again) and `draft_target_is_live` (stops).
+  - **Behaviour change:** `theme publish` without `--instance` uses the same rule; it never publishes
+    a guessed draft.
+  - **Behaviour change:** `--name X` creates the draft as `CLI Draft — X`; the rename advice after a
+    reused draft is gone (a draft renamed by hand to another name is refused).
+  - **Behaviour change (CI):** `theme push --instance <the live theme's handle>` asks for the same
+    confirmation as `--live` (`--yes` in non-interactive shells); so does a handle the CLI cannot tell
+    apart from the live theme (live theme unknown, or a raw numeric id).
+  - `theme publish --instance <handle>` tells the platform the theme was named explicitly
+    (`explicit: true`); the automatic pick sends no flag and the platform re-checks it. A theme that is
+    not the site's CLI draft (a site-state restore draft, a renamed or panel-copied theme) is published
+    through the CLI only with `--instance`; otherwise the platform refuses with
+    `publish_target_unconfirmed` (exit 2, nothing published). Older CLIs get that refusal as a generic
+    error and can never publish such a theme.
 - **0.13.0** — Draft push names its target (customer items PS-22/PS-23/PS-26).
   - `theme push` (draft) prints the draft it wrote to — handle, name, new or existing — and
     `blocofy theme publish --instance <handle>`. When it updated the existing CLI draft, it says