@blocofy/cli 0.14.0 → 0.16.0

package/README.md

@@ -5,9 +5,10 @@ instant preview, and publish. The CLI does **not** build assets — generate the
 own tools (npm/Vite/Tailwind); the platform serves plain Liquid + static assets.
 
 ```bash
-npx @blocofy/cli login          # site URL + dev token (admin panel: Settings → Theme CLI tokens)
-cd path/to/theme
-npx @blocofy/cli theme dev       # http://localhost:3030 — local theme + live data, livereload
+npx @blocofy/cli login           # browser login: pick your site, approve (draft-only)
+npx @blocofy/cli init my-site    # a theme work of its own + its files + a preview link; live site unchanged
+cd my-site
+npx @blocofy/cli theme push --draft --work <wk_…>
 ```
 
 `login` saves the site under a named **context** (default: the site's slug) in
@@ -20,18 +21,44 @@ targets the right one — see [Contexts and project binding](#contexts-and-proje
 ### Login & contexts
 
 ```
-blocofy login [--context <name>] [--url <url>] [--token <bcf_…>] [--keychain]
-```
-Verify a dev token against its site (`GET /api/dev/whoami`) and save it as a named context
-(default name: the site's slug). Nothing is saved if verification fails. Get a token from the
-admin panel → Settings → Theme CLI tokens.
+blocofy login [--context <name>] [--site <handle|slug>] [--api-url <url>] [--no-browser] [--insecure-storage]
+```
+**Browser login (default, 0.16.0).** The CLI opens your system browser on the platform
+(Authorization Code + PKCE S256), you pick the site and approve; the browser comes back to a
+one-shot listener on `http://127.0.0.1:<port>/callback` (or `[::1]`; `localhost` is never used).
+The CLI checks `state` and the RFC 9207 `iss` against the platform's discovery metadata before
+it exchanges the code, and says "connected" only after `GET /api/v1/ping` confirms the site, the
+profile and the CLI audience. The login is **draft-only** ("Tema geliştirme", `theme-dev@1`): it
+can start and fill theme works, push to its own work's draft and create preview links, but it can
+never change the live site or publish — publishing is the panel's (or a human approval's) job.
+- Storage: the OS secure store — macOS Keychain, Windows DPAPI-protected file
+  (`%APPDATA%\blocofy\secrets.dpapi`), Linux Secret Service (`secret-tool`). With no OS store the
+  login is **refused**, never silently written to a plain file; `--insecure-storage` (or
+  `BLOCOFY_SECRET_STORE=file`) chooses `~/.blocofy/secrets.json` (0600) explicitly and is announced.
+- The access token lives 10 minutes and renews itself with a single-use refresh token, one
+  renewal at a time across every running `blocofy` (lock `~/.blocofy/.refresh-<context>.lock`,
+  `/token` timeout 10 s). A refused renewal (revoked, expired, reused) marks the context
+  `reauth_required`: run `blocofy login --context <name>` again.
+- `--site` refuses (and revokes) a login for any other site; `--no-browser` prints the URL only;
+  `--api-url` names the platform (default `https://app.blocofy.com`).
+- Needs a terminal. CI (`CI` set, no TTY) and SSH sessions never open a browser: use env
+  credentials or the advanced options below.
+
+```
+blocofy login --url <url> --token [--context <name>] [--keychain]      # advanced: pasted dev token
+```
+Verify a dev token (`bcf_…`, or a profiled `bcf2_…` — needs CLI 0.16.0+) against its site
+(`GET /api/dev/whoami`) and save it as a named context (default name: the site's slug). Nothing
+is saved if verification fails. `--token` without a value reads it from a hidden prompt;
+`--token <value>` still works but warns (`TOKEN_IN_ARGV`: argv is visible in `ps` and shell
+history). Get a token from the admin panel → Settings → Theme CLI tokens.
 - `--keychain` — keep the secret in the macOS keychain (or `BLOCOFY_SECRET_STORE=keychain`);
-  default is `~/.blocofy/secrets.json` (0600).
+  default is `~/.blocofy/secrets.json` (0600). The output names the store used.
 
 ```
 blocofy login --api-key [--context <name>] [--api-url <url>]
 ```
-Verify a v1 API key (`blcf_live_…`, `GET /api/v1/ping`) and add it to a context. The key is
+Verify a v1 API key (`blcf_live_…` or a profiled `blcf_k2_…`, `GET /api/v1/ping`) and add it to a context. The key is
 read from a **hidden prompt** — the flag takes no value, so it never lands in argv or shell
 history. If the context already has a dev token for another site, nothing is saved
 (`TARGET_CREDENTIAL_MISMATCH`).
@@ -41,8 +68,43 @@ history. If the context already has a dev token for another site, nothing is sav
 ```
 blocofy contexts [--json]          # list saved contexts (never prints secrets)
 blocofy use <name>                 # default context for status / target / pages check outside a project
-blocofy logout --context <name>    # remove a context and its secrets
-```
+blocofy logout [--context <name>]  # remove a context and its secrets (default: the `use` context)
+```
+`logout` reports two separate results. **Server** (browser logins only): `revoked` (the platform's
+RFC 7009 `/revoke` answered 200), `unreachable` / `refused` / `unavailable` (NOT revoked — the
+output names the panel page where you cut it: Settings → Connections and keys), or
+`not_applicable` (a pasted token/key: revoke it in the panel). **Local**: `cleared` | `failed`,
+done whatever the server said. Exit 0 only when both are done; otherwise exit 4.
+
+### New project: `blocofy init`
+
+```
+blocofy init [dir] [--site <handle|slug>] [--context <name>] [--api-url <url>] [--no-browser] [--insecure-storage]
+```
+Sets up a new project directory end to end, without touching the live site:
+1. Pre-checks, before any request: a missing or empty directory starts; a directory this CLI
+   initialised resumes; a non-empty directory that is not a project is refused
+   (`INIT_DIR_NOT_EMPTY`, exit 3, nothing written); a directory bound to another site is refused
+   (`INIT_SITE_MISMATCH`, exit 3); a project bound by `link`/`pull` is not taken over
+   (`INIT_ALREADY_BOUND`).
+2. The credential: `--context`, env credentials, the directory's saved context, or (on a terminal)
+   a browser login. Non-interactive runs never open a browser and need `--site`.
+3. Reads the live theme, starts a theme work (`POST /api/v1/theme-work`, idempotency key
+   `init:<key>` from `.blocofy/init.json` — written before the first request), downloads the
+   work's theme files, writes `.blocofy/project.json` (+ the additive `profile`) and
+   `.blocofy/local.json` (context + the work), creates a preview link for the work's home page,
+   and reads the live theme again.
+4. Success = the preview link exists **and** the live theme read back is the one read before:
+   "Taslak hazır. Canlı siten değişmedi." If the live theme changed meanwhile (not by init),
+   nothing is called a success: exit 5.
+
+`.blocofy/init.json` (git-ignored, no secret, no link) records the step reached
+(`started → work_created → files_pulled → pinned → previewed`). Run the same command again after a
+timeout, a crash or Ctrl-C: it reads the work back from the platform and continues — the same key
+always returns the same work, never a second one. Two `init`s in one directory at once: one runs,
+the other is refused (`INIT_IN_PROGRESS`). Do not delete `init.json` to "start over": use a new,
+empty directory.
+
 
 ### Project binding
 
@@ -80,8 +142,10 @@ changing credentials, context or the project binding).
 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`).
 
@@ -130,6 +194,20 @@ create a new draft theme in the admin panel and pass its handle with `--instance
 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.
@@ -184,6 +262,65 @@ theme publish ./shop` always publishes `./shop`'s site, whatever directory you r
   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
 
 ```
@@ -469,7 +606,8 @@ untouched.
 | 1 | Usage / network / HTTP 5xx / a local check that refuses before any request (e.g. a `site migrate` conflict, a `pages migrate-layout` ambiguity). |
 | 2 | The server refused the request (HTTP 4xx) — its `{error}` JSON is printed. |
 | 3 | Target/binding refusal — nothing was read or written (see [Contexts and project binding](#contexts-and-project-binding)). |
-| 4 | `site apply` only: not finished within its bounded pass count. Every step already applied is safe — re-run the same command to resume. |
+| 4 | `site apply`: not finished within its bounded pass count. Every step already applied is safe — re-run the same command to resume. `logout`: the local login could not be removed, or the platform login was NOT revoked (cut it in the panel). |
+| 5 | `init`: the live theme changed while init ran (init never writes it) — not reported as a success. |
 
 `--json`: every failure prints `{"error":{"code","message","details"}}` as the **last** stderr
 line; the target block (`{"target":…}`) and any warning lines are printed on stderr before it.
@@ -485,6 +623,82 @@ Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.16.0** (unreleased) — Browser login, `blocofy init`, honest `logout` (ADR-0014 wave P4).
+  Pairs with the platform release of the credential profiles (draft-only "Tema geliştirme" by
+  default). **Minimum platform:** the browser login needs a platform that publishes the CLI client
+  (`blocofy-cli`), RFC 9207 `iss`, `/revoke` and the `profile` / `audience` / `dev_endpoint` fields of
+  `GET /api/v1/ping`; an older platform is told apart and refused with "use `login --token`".
+  - **`blocofy login` opens the browser** (PKCE S256, loopback `127.0.0.1`/`[::1]` only, `state`
+    and `iss` checked, `resource=<origin>/api/v1`). Connected = the identity probe, not a config
+    write. Unattended (CI / no TTY) and SSH runs never open a browser. The pasted dev token stays as
+    the advanced path (`login --url <site> --token`, hidden prompt; a token in argv warns).
+  - **Secure storage**: OS store by default (Keychain / DPAPI / Secret Service); no store → refused;
+    the 0600 file only with `--insecure-storage` / `BLOCOFY_SECRET_STORE=file`. **Unverified on real
+    machines:** the Windows (DPAPI via PowerShell) and Linux (Secret Service via `secret-tool`) stores
+    are covered only by tests with a stand-in for those programs; macOS Keychain uses the existing,
+    field-tested adapter.
+  - **Draft-only logins default to their saved work**: for a browser login (or any draft-only profile)
+    `theme push` and `theme dev` write into the theme work saved by `init` / `theme work start`
+    (`.blocofy/local.json`, else `.blocofy/init.json`); `--work` / `--instance` still win. Without a
+    saved work they stop with a hint (`THEME_WORK_REQUIRED`, exit 3) before any request.
+  - **Refresh single-flight** across processes (lock with pid/hostname/acquired_at, ESRCH or 30 s
+    staleness, 10 s `/token` timeout, never retried); reuse/revocation → `reauth_required`. The
+    platform's explicit `error_description: "refresh_token_reused"` is honoured first; a 503 without
+    `Retry-After` is treated as spent only as a fallback for older platforms.
+  - **`init` preview**: uses the work-level `POST /api/v1/theme-work/{handle}/preview-links` when the
+    platform has it (an older platform's 404/405 falls back to finding the work theme's home page).
+  - **`blocofy logout`** reports the platform revocation and the local removal separately (exit 4
+    when either is not done); `--context` defaults to the `use` context.
+  - **`blocofy init [dir]`** (see above): idempotent theme-work start, secret-free
+    `.blocofy/init.json`, refuses dirty / other-site directories, resumes from every step, success
+    only with a preview and the live theme read back unchanged (exit 5 otherwise).
+  - **New platform refusals in plain Turkish**, printed before the usual `error [code]` line and
+    never retried: `live_effect_not_permitted`, `credential_reapproval_required` (due date +
+    re-approval link), `profile_unsupported`, `audience_mismatch`, `ai_draft`,
+    `work_copy_not_writable`.
+  - **Profiled credentials**: `bcf2_` dev tokens and `blcf_k2_` API keys are accepted (0.15 and
+    older refuse `bcf2_` tokens: upgrade the CLI before using one).
+- **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