@blocofy/cli 0.12.0 → 0.13.0

package/README.md

@@ -63,13 +63,15 @@ Show which site a command in `[dir]` would hit (verified), without writing anyth
 ```
 blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
 ```
-Start a dev server and print 3 auto-reloading views — Local, live-domain Preview, and the theme
-Editor. Press `l` / `p` / `e` to open each, `q` to quit. Edit a file and save → every open view
-reloads. Saves sync to a **draft** theme only (never the live site). `dir` defaults to cwd.
+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
+**draft** theme only (never the live site). `dir` defaults to cwd. The platform's remote preview
+and editor views for this command are retired; to share a draft page, create a preview link for
+it (v1 API `POST /themes/{id}/preview-links` or MCP `create_preview_link`; one page per link).
 The target site is verified once at start; a long session keeps that target (restart it after
 changing credentials, context or the project binding).
 - `--port <n>` — local port (default 3030).
-- `--no-sync` — local preview only (skip draft sync + remote views).
+- `--no-sync` — local preview only (skip draft sync).
 - `--name <name>` — name the draft when it is first created (ignored if it already exists).
 
 ```
@@ -94,13 +96,20 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
 - `--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`).
+- `--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.
 - `--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
   deploy and prints the target, its pointer version and what happens to each file
   (`+` created, `~` updated, `-` removed; unchanged files are counted).
-- `--diff` — show what a push would change vs the target (read-only), then stop.
+- `--diff` — show what a push would change vs the target (read-only), then stop. A draft push
+  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.
+
+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.
 - `--prune` — also remove target files that no longer exist locally (`locales/` included);
   lists them first, and on the live theme asks to confirm (non-interactive shells add `--yes`).
@@ -452,6 +461,17 @@ Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **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
+    `--name` was not applied and prints the rename command.
+  - **Behaviour change:** `theme push --diff` without `--live`/`--instance` now compares with the CLI
+    draft the push writes to (found read-only via the site status, never provisioned), not with the
+    live theme. With no CLI draft yet it says so and compares with live. Release it after the
+    platform's PS-22 fix (uncached theme reads): before that fix a draft read could return its
+    pre-push files for up to five minutes.
+  - `theme dev` help no longer lists the retired live-domain and editor views.
+  - `TARGET_BINDING_REQUIRED` also names `blocofy link <dir>` for env credentials.
 - **0.12.0** — Translation packages (#925).
   - `blocofy translations export --locale <tag> --out <file> [--format json|xliff] [--only …]`
     writes every text of one language that needs translating to one JSON or XLIFF 1.2 file. It
@@ -619,11 +639,9 @@ files and sends them to the platform's dev-render endpoint (`/api/dev/render`).
 renders them with the site's **live data** and returns HTML — so the CLI ships no rendering
 engine and you see exactly the production output.
 
-It also continuously syncs your local files to a **draft theme** so you can view the same work
-three ways — the local preview, a shareable live-domain preview link, and the admin theme
-editor — without affecting your published theme. Save a file and **every open view reloads**
-(the platform-rendered pages connect back to the local dev server's reload channel). Publish
-the draft from the theme editor when you're ready.
+It also continuously syncs your local files to a **draft theme**, so the same work can be opened
+in the admin theme editor without affecting your published theme. Save a file and the local view
+reloads. Publish the draft from the theme editor, or with `blocofy theme publish`, when you're ready.
 
 Credentials live in `~/.blocofy/credentials.json` (contexts, no secrets) + either
 `~/.blocofy/secrets.json` (0600) or the macOS keychain — written by `blocofy login`, or the

package/bin/blocofy.mjs

@@ -71,7 +71,7 @@ import { MANIFEST_PATH, buildManifest, validateSiteStateTree, verifyManifest } f
 import { SiteStateFsError, hashBuffer, readSiteStateTree, stagedWriteTree } from "../lib/site-state-fs.mjs";
 import { migrateSiteState } from "../lib/site-migrate.mjs";
 import { applySiteState, downloadAssetBytes, fetchSiteStateExport, planSiteState, publishSiteState, uploadMediaAsset } from "../lib/site-state-client.mjs";
-import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
+import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
 import { isAffirmative, livePushDecision, resolvePushMode } from "../lib/confirm.mjs";
 import { hyperlink, openUrl } from "../lib/term.mjs";
 import { isValidToken, isValidUrl, normalizeUrl } from "../lib/validate.mjs";
@@ -178,14 +178,15 @@ Usage
       Show which site a command in [dir] would hit (verified), without writing anything.
 
   blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
-      Start a dev server and print 3 auto-reloading views — Local, live-domain
-      Preview, and the theme Editor. Press l / p / e to open each, q to quit.
-      Edit a file and save → every open view reloads. Saves sync to a DRAFT theme
-      only (never the live site). (dir defaults to cwd)
+      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 DRAFT theme only (never the live site). (dir defaults to cwd)
+      The platform's remote preview and editor views for this command are retired; to
+      share a draft page, create a preview link for it (v1 API / MCP create_preview_link).
       The target site is verified ONCE at start; a long session keeps that target (restart
       it after changing credentials, context or the project binding).
         --port <n>   local port (default 3030)
-        --no-sync    local preview only (skip draft sync + remote views)
+        --no-sync    local preview only (skip draft sync)
         --name <name>  name the draft when it is first created (ignored if it already exists)
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
@@ -952,7 +953,7 @@ async function themePush(rest) {
   // CF-T2: `--diff` and `--dry-run` are reads; every other push is a remote mutation (binding required). The
   // target is verified (whoami, both pairs, binding) before the first theme request — no best-effort swallow.
   const readOnly = Boolean(flags.diff) || dryRun;
-  const opMode = flags.diff ? `read · diff vs ${instanceFlag ? `instance ${instanceFlag}` : "live"}` : dryRun ? `read · dry run (${mode === "instance" ? `instance ${instance}` : mode})` : mode === "instance" ? `instance ${instance}` : mode;
+  const opMode = flags.diff ? `read · diff vs ${instanceFlag ? `instance ${instanceFlag}` : mode === "draft" ? "CLI draft" : "live"}` : dryRun ? `read · dry run (${mode === "instance" ? `instance ${instance}` : mode})` : mode === "instance" ? `instance ${instance}` : mode;
   const target = await prepareTarget({ command: "theme push", commandClass: readOnly ? "read" : "remote-mutation", dir, flags, needs: "dev", mode: `${opMode}${flags.prune && !readOnly ? " · prune" : ""}` });
   const creds = target.dev;
   // 0.5.0: her push'a otomatik idempotency key — kanonik dal (protokol + key) ancak böyle seçilir; key
@@ -963,12 +964,18 @@ async function themePush(rest) {
   // ad-alanlar, önek EKLENMEZ.
   const idempotencyKey = typeof flags["idempotency-key"] === "string" ? flags["idempotency-key"] : `cli-${randomUUID()}`;
 
-  // `--diff`: read-only preview vs the LIVE theme (or --instance). No write; the draft target is not
-  // diffable (a draft GET would PROVISION the draft server-side — a read-only command must not mutate).
+  // `--diff`: read-only preview vs what the push would write to. PS-26: a draft push writes to the CLI draft, so
+  // that draft is found via `/api/dev/site` and diffed by handle — never via `?draft=1`, which PROVISIONS a draft
+  // server-side (a read-only command must not mutate). With no CLI draft yet the push would create one: vs live.
   if (flags.diff) {
     const diffTarget = ` of ${siteLabel(target.identity.site)}`;
-    const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: instanceFlag, onRetry });
-    console.log(instanceFlag ? `Diff vs theme ${instanceFlag}${diffTarget}:` : `Diff vs the LIVE theme${diffTarget} (push default writes to a DRAFT):`);
+    const cliDraft = mode === "draft" ? findCliDraft(await fetchSiteStatus({ url: creds.url, token: creds.token, onRetry })) : null;
+    const diffInstance = instanceFlag ?? cliDraft?.id ?? null;
+    const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: diffInstance, onRetry });
+    if (instanceFlag) console.log(`Diff vs theme ${instanceFlag}${diffTarget}:`);
+    else if (cliDraft) console.log(`Diff vs draft ${cliDraft.id}${cliDraft.name ? ` "${cliDraft.name}"` : ""}${diffTarget} (the CLI draft this push writes to):`);
+    else if (mode === "draft") console.log(`No CLI draft yet — this push would create one. Diff vs the LIVE theme${diffTarget}:`);
+    else console.log(`Diff vs the LIVE theme${diffTarget}:`);
     const total = d.added.length + d.changed.length + d.removed.length;
     if (total === 0) {
       console.log("No differences — local theme matches the target.");
@@ -1140,8 +1147,15 @@ async function themePush(rest) {
     }
     if (result.convergence === "converged") console.log("  (already applied by an earlier push with the same idempotency key)");
     if (mode === "draft") {
+      const h = typeof result.targetInstance === "string" ? result.targetInstance : null;
+      const label = result.targetName ? ` "${result.targetName}"` : "";
+      if (h) console.log(result.newDraft ? `Draft: ${h}${label} (new)` : `Draft: ${h}${label} (existing CLI draft, updated)`);
+      // PS-22: the server reuses the CLI draft whatever its name; --name only names a draft this push creates.
+      if (name && result.newDraft !== true) {
+        console.log(`Note: --name was not applied — this push updated the existing CLI draft${h ? ` ${h}` : ""}. Rename it with:  blocofy theme rename ${h ?? "<handle>"} "${name}"`);
+      }
       console.log("Preview & publish it in the admin panel: Theme -> Theme library -> \"Open in editor\".");
-      console.log("Publish it live with:  blocofy theme publish");
+      console.log(`Publish it live with:  blocofy theme publish${h ? ` --instance ${h}` : ""}`);
     }
     return;
   }

package/lib/target.mjs

@@ -217,13 +217,16 @@ function isEmptyOrMissing(dir) {
  * Command-class policy (before any credential or network use). Returns `{ newBinding }`: true when a local-write
  * into a missing/empty unbound dir will record provenance after it succeeds.
  */
+/** PS-22 note: with env credentials there is no context to name — `link` binds to the site those credentials reach. */
+const ENV_LINK_HINT = (dir) => `; with BLOCOFY_URL + BLOCOFY_TOKEN set: blocofy link ${dir}`;
+
 export function enforceBindingPolicy({ commandClass, binding, dir, command }) {
   if (!COMMAND_CLASSES.has(commandClass)) throw new Error(`internal: unknown command class ${commandClass}`);
   if (binding) return { newBinding: false };
   if (commandClass === "remote-mutation") {
     throw new TargetError(
       "TARGET_BINDING_REQUIRED",
-      `\`${command}\` changes a site, but ${dir} is not bound to one. Nothing was sent. Bind it first: blocofy link ${dir} --context <name>`,
+      `\`${command}\` changes a site, but ${dir} is not bound to one. Nothing was sent. Bind it first: blocofy link ${dir} --context <name>${ENV_LINK_HINT(dir)}`,
       { dir },
     );
   }
@@ -231,7 +234,7 @@ export function enforceBindingPolicy({ commandClass, binding, dir, command }) {
     if (isEmptyOrMissing(dir)) return { newBinding: true };
     throw new TargetError(
       "TARGET_BINDING_REQUIRED",
-      `${dir} is not empty and not bound to a site. Nothing was written. Bind it first (blocofy link ${dir} --context <name>) or pull into an empty directory.`,
+      `${dir} is not empty and not bound to a site. Nothing was written. Bind it first (blocofy link ${dir} --context <name>${ENV_LINK_HINT(dir)}) or pull into an empty directory.`,
       { dir },
     );
   }

package/lib/theme-sync.mjs

@@ -322,9 +322,10 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   const remoteOnlyKept = [];
   const remoteOnlyRemoved = [];
   let probeInstance = instance;
+  let cliDraft = null;
   if (!instance && draft) {
-    const status = await fetchSiteStatus({ url, token, onRetry });
-    probeInstance = (status?.drafts ?? []).find((d) => d.source === "import")?.id ?? null;
+    cliDraft = findCliDraft(await fetchSiteStatus({ url, token, onRetry }));
+    probeInstance = cliDraft?.id ?? null;
   }
   let remote = {};
   if (probeInstance || !draft) {
@@ -391,7 +392,22 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
     throw applyError(error);
   }
   if (!res.ok) throw applyError(await httpError(res));
-  return { ...(await res.json()), ...extras };
+  const applied = await res.json();
+  // PS-22: which theme received the files. A current server names it on the apply; an older one only in the plan
+  // (null for "a new draft"); oldest of all, the CLI draft looked up before the push is the one reused.
+  // A server whose plan carries no `newDraft` created one exactly when a draft push found no CLI draft to reuse.
+  const newDraft = typeof plan.newDraft === "boolean" ? plan.newDraft : Boolean(draft && !instance && cliDraft == null);
+  const targetInstance = applied.targetInstance ?? plan.targetInstance ?? (newDraft ? null : probeInstance) ?? null;
+  const targetName = newDraft ? name : cliDraft && cliDraft.id === targetInstance ? cliDraft.name ?? null : null;
+  return { ...applied, ...extras, targetInstance, newDraft, targetName };
+}
+
+/**
+ * The CLI draft a draft push writes into: the first `source: "import"` draft — `/api/dev/site` lists drafts by id,
+ * the server's `ensureDraftInstance` reuses the first non-live import instance by id. `null` = a push would create one.
+ */
+export function findCliDraft(status) {
+  return (status?.drafts ?? []).find((d) => d.source === "import") ?? null;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocofy/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Develop your Blocofy theme locally against live data with instant preview — login, theme dev, pull, push.",
   "type": "module",
   "license": "MIT",