octwin-cli 0.1.20 → 0.1.21

package/CHANGELOG.md

@@ -5,6 +5,37 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.1.21] - 2026-07-30
+
+### Added
+- **`deploy` and `status` report the marketplace-listing verdict.** A manifest carrying
+  `listing.public: true` put the pack into an operator review queue, and the state existed only in
+  the console — so an author working from the CLI got no acknowledgement that the request had
+  registered, and never saw a rejection note (which the platform *requires* precisely because it is
+  their only feedback). Both commands now print it via `printPublicListing`, and stay silent for a
+  pack that never asked. `status` also distinguishes *approved* from *actually public*: an approval
+  pins the content sha it reviewed, so any edit returns the pack to the queue on its own.
+- **`octwin pull` is discoverable.** It was implemented and answered `--help`, but appeared in
+  neither `octwin help` nor the README — the one command that recovers a deployed pack's only source
+  copy was invisible unless you already knew its name. Also added to the scope-requirement table, so
+  a 403 names `pack:deploy` instead of printing the generic hint.
+
+### Fixed
+- **The capability-reference drift check no longer fails silently on a narrow token.** The `?meta=1`
+  poll needs `pack:deploy`, but it rides on every networked command — so an author inspecting data
+  with a `records:read`-only token got no drift signal at all, and a stale reference is exactly what
+  leads to inventing a primitive from memory. A 401/403 there now says so once.
+- **README: casework is declared in `worklist.yaml`, not a `cases.yaml`.** That grammar was retired;
+  following the README produced a pack whose casework silently never loaded. `octwin media generate`
+  was also missing from the command table.
+- **`records` no longer blames the plan for a route the plan does not gate.** `GET /xrm/entities`
+  carries only the scope guard, so a 403 on the entity list wrongly cited the `records` plan feature.
+
+### Removed
+- **Unreachable rename branches in `init`.** The agent-id and `main`-flow renames sat behind
+  `--agent` / `--flow` options the CLI never parsed, against a template that ships no `main` flow —
+  both branches could never fire, and their patterns would have matched nothing if they had.
+
 ## [0.1.20] - 2026-07-29
 
 ### Added

package/README.md

@@ -64,8 +64,9 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin validate` | Check the pack locally (structure + pure-YAML rules). The platform re-validates the full manifest/flow schema on deploy. |
 | `octwin login` | Save a deploy token for a platform URL **and make that URL the default target** (both stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
 | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
-| `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. |
-| `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), and its flows. |
+| `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. Reports the **marketplace-listing verdict** when the manifest carries `listing.public: true`. |
+| `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), its flows, and whether it is live on the public marketplace. |
+| `octwin pull <packId>` | Write a **deployed** pack's source back to disk — the inverse of `deploy`, and how a pack pushed from one machine is recovered. Defaults to the version installed on the target project; `--version` overrides, `--dir` defaults to `./<packId>`, a non-empty dir needs `--force`. You may pull a pack your tenant **owns**. |
 | `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
 | `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
 | `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |
@@ -75,6 +76,7 @@ octwin status               # "✓ live and current" once it's warm
 | `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. |
 | `octwin catalog` | Commerce products with price / availability / stock, plus the WhatsApp catalog binding. `--readiness` runs the Meta Graph checklist. Needs `catalog:read` + the `catalog` plan feature. |
 | `octwin scheduling` | The scheduling engine's state, or `--slots <resourceRecordId>` for the slots one bookable resource actually computes — how you verify the availability rules `deploy --seed` created. Needs `scheduling:read`. |
+| `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--size`; `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
 | `octwin platform-kb pull` | Pull the platform's capability reference into `.octwin/platform-kb/` for the **`octwin-pack`** Claude Code authoring plugin: guides as markdown, plus **one JSON file per capability** (`primitives/record_list.json`, `render-intents/carousel.json`, `declarations/xrm.json`, …) and an **`INDEX.md`** mapping every entry to its file — so a lookup is a small targeted read, not a whole catalog. |
 | `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
 | `octwin help` | Show usage. Every subcommand also answers `--help`. |
@@ -170,8 +172,10 @@ A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.sql` / `.js
 code (`.ts`/`.js`), HTTP routes, DB clients, and custom primitives are **not** allowed (this is what
 makes an external pack safe to run on a shared platform; the server enforces it on deploy). For
 domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
-**catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` / `cases.yaml`, so a pack
-needs **no database of its own**.
+**catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` and `worklist.yaml`, so a
+pack needs **no database of its own**. (Casework rides `worklist.yaml`'s `work.<entity>` block;
+there is no ~~`cases.yaml`~~ grammar. `octwin platform-kb pull` ships the authoritative list of
+declaration files — read its `INDEX.md` rather than this paragraph.)
 
 ## Links
 

package/dist/index.js

@@ -135,9 +135,16 @@ const COMMAND_REQUIREMENTS = {
     validate: { scope: 'pack:deploy' },
     status: { scope: 'pack:deploy' },
     test: { scope: 'pack:deploy' },
+    // `pull` reads a stored artifact through the deploy route's sibling, so it needs the
+    // same scope. Omitting it here meant a 403 on the one command that recovers a pack's
+    // only source copy printed the generic hint WITHOUT naming the scope to grant.
+    pull: { scope: 'pack:deploy' },
     'platform-kb': { scope: 'pack:deploy' },
     media: { scope: 'media:generate' },
-    records: { scope: 'records:read', feature: 'records' },
+    // The plan feature gates RECORD reads, not the entity list (`/xrm/entities` carries only
+    // the scope guard) — so the hint says which half it applies to rather than blaming the
+    // plan for a 403 the plan did not cause.
+    records: { scope: 'records:read', feature: 'records', featureAppliesTo: 'reading records (listing entities needs only the scope)' },
     analytics: { scope: 'records:read', feature: 'records' },
     cases: { scope: 'cases:read', feature: 'cases' },
     logs: { scope: 'conversations:read' },
@@ -158,7 +165,10 @@ function scopeRequirementHint() {
     const special = req.scope === 'pack:deploy' || req.scope === 'media:generate';
     return `needs the \`${req.scope}\` scope`
         + (special ? ' (granted DIRECTLY only — a `tenant:admin` token does not confer it)' : '')
-        + (req.feature ? `, and the \`${req.feature}\` plan feature on this workspace` : '');
+        + (req.feature
+            ? `, and the \`${req.feature}\` plan feature on this workspace`
+                + (req.featureAppliesTo ? ` for ${req.featureAppliesTo}` : '')
+            : '');
 }
 /** Print the auth hints below an HTTP-failure line when it's a 401/403 — so every
  *  command explains a token problem, not just the inspect family (author-feedback A7):
@@ -442,8 +452,18 @@ async function notifyIfKbStale(flags) {
             headers: authHeaders(t), signal: ctrl.signal,
         });
         clearTimeout(timer);
-        if (!res.ok)
+        if (!res.ok) {
+            // The meta poll needs `pack:deploy`, but this nudge rides on every networked
+            // command — so an author inspecting data with a narrow (`records:read`-only) token
+            // got NO drift signal at all, silently, and a stale reference is exactly what makes
+            // an author invent a primitive from memory. Say so once; stay silent for every other
+            // failure (offline, timeout, a platform without the route).
+            if (res.status === 401 || res.status === 403) {
+                console.error('\nⓘ can\'t check whether the platform capability reference drifted — that needs a `pack:deploy` token.');
+                console.error('  Refresh it directly with a deploy token: octwin platform-kb --token oct_…');
+            }
             return;
+        }
         const meta = await res.json();
         if (meta.content_hash && meta.content_hash !== local.content_hash) {
             // Per-entry summary (now that the index carries per-entry hashes) — the
@@ -505,8 +525,6 @@ function cmdInit(flags) {
     cpSync(TEMPLATE_DIR, dir, { recursive: true });
     applyRenames(dir, {
         packId: id,
-        flowId: 'main',
-        agentId: 'assistant',
         description: flags.description ?? undefined,
         displayName: flags['display-name'] ?? undefined,
     });
@@ -842,6 +860,36 @@ async function readDeployProgress(body) {
     }
     return { terminal, stepErrors };
 }
+/**
+ * The anonymous-marketplace verdict, for `deploy` and `status` alike.
+ *
+ * `listing.public: true` in the manifest puts a pack into an operator review queue, and the
+ * state lived only in the console — so an author working from the CLI got no acknowledgement
+ * that the request had registered, and no sight of a rejection note (which the platform
+ * REQUIRES precisely because it is their only feedback). Silent for `none`/absent, so a pack
+ * that never asked prints nothing.
+ *
+ * `pending` after a redeploy is normal rather than a regression: an approval pins the sha it
+ * reviewed, so any content edit returns the pack to the queue on its own.
+ */
+function printPublicListing(state, note, live) {
+    const n = typeof note === 'string' && note ? ` — operator note: ${note}` : '';
+    switch (state) {
+        case 'pending':
+            console.log('  ⓘ marketplace listing: PENDING operator review (any content edit re-queues it — the approval pins a content sha).');
+            break;
+        case 'approved':
+            console.log(live === false
+                ? '  ⓘ marketplace listing: approved, but NOT currently public — the approved content sha no longer matches what you publish. It is back in the review queue.'
+                : '  ✓ marketplace listing: live on the public marketplace.');
+            break;
+        case 'rejected':
+            console.log(`  ⚠ marketplace listing: REJECTED${n}`);
+            break;
+        default: // 'none' | null | absent → never asked
+            break;
+    }
+}
 function printDeploySuccess(id, version, t, r) {
     console.log(`✓ Deployed ${id}@${version} and installed onto ${targetLabel(t)}`);
     if (r?.warning)
@@ -867,6 +915,7 @@ function printDeploySuccess(id, version, t, r) {
     if (dropped > 0) {
         console.log(`  ⓘ ${dropped} suspended run(s) invalidated — a tap on any card rendered before this deploy will report a stale run. Start those conversations again.`);
     }
+    printPublicListing(r?.public_listing, r?.public_review_note);
     console.log(`\nChat with it: octwin chat "hi" --as tester   (or the web widget / console test page).`);
 }
 async function cmdDeploy(flags) {
@@ -974,6 +1023,10 @@ async function cmdStatus(flags) {
     else {
         console.log('\n✓ live and current.');
     }
+    // Independent of the runtime verdict above: a listing decision controls anonymous
+    // visibility only and never touches a running install, so it is reported alongside
+    // rather than folded into that ladder.
+    printPublicListing(json.public_listing, json.public_review_note, json.publicly_listed);
     if (localVersion !== '?' && localVersion !== json.installed_version) {
         console.log(`  (local manifest is ${localVersion}; deployed is ${json.installed_version} — \`octwin deploy\` to push local edits.)`);
     }
@@ -2320,6 +2373,7 @@ function help() {
   octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
+  octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
   octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
   octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
   octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline

package/dist/lib/rename.js

@@ -1,20 +1,21 @@
 /**
  * rename.ts — rename map + safe substitution over a copied starter tree.
  *
- * A VENDORED, platform-free copy of the platform scaffolder's rename module
- * (`scripts/pack-scaffold/rename.ts`). `octwin init` copies the in-package
- * `templates/starter/` tree (packId `starter-kit`, flow `main`, agent
- * `assistant`) then this rewrites the copy into a fresh pack:
+ * Platform-free by construction — the CLI ships with zero platform imports. (It began as a
+ * vendored copy of ~~`scripts/pack-scaffold/rename.ts`~~, deleted with the in-repo packs;
+ * this is the only copy now.) `octwin init` copies the in-package
+ * `templates/starter/` tree (packId `starter-kit`, agent `assistant`, flows
+ * `home` + `browse`) then this rewrites the copy into a fresh pack:
  *   • `starter-kit` → <pack-id>            (manifest id, comments, README)
- *   • agent display name + id              (when --display-name / --agent given)
+ *   • agent display name                   (when --display-name given)
  *   • manifest description                 (when --description given)
- *   • the `main` flow → <flow-id>          (when --flow given): file renames + scoped edits
  *
- * Flow renaming is scoped to the exact syntactic forms the template uses
- * (flow_id, manifest flows/tools entries, `$t("main.…")` / `'main.…'` locale
- * namespaces) — never a blind `main` substring replace.
+ * ~~It also renamed the agent id and a `main` flow~~ behind `--agent` / `--flow` options
+ * the CLI never parsed: `octwin init` passes the template's own ids, and the template ships
+ * no `main` flow at all, so both branches were unreachable and their patterns would have
+ * matched nothing. Renaming a flow is an EDIT after scaffolding, not an init flag.
  */
-import { readdirSync, statSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { readdirSync, statSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 const TEXT_EXT = /\.(ya?ml|md|sql|json)$/;
 function walkFiles(dir) {
@@ -49,30 +50,9 @@ function contentReplacements(opts) {
         const safe = opts.displayName.replace(/'/g, "''");
         edits.push([/^(\s*display_name:\s*).*$/m, `$1'${safe}'`]);
     }
-    // 4. Agent id — the manifest agents[] list item and the messages.<lang>.yaml key.
-    if (opts.agentId !== 'assistant') {
-        edits.push([/^(\s*-\s*id:\s+)assistant\s*$/m, `$1${opts.agentId}`]); // manifest agents[].id
-        edits.push([/^(\s+)assistant:(\s*)$/m, `$1${opts.agentId}:$2`]); // messages.<lang>.yaml agents.<id>
-    }
-    // 5. Flow id — scoped forms only (never a blind `main` substring replace).
-    if (opts.flowId !== 'main') {
-        const f = opts.flowId;
-        edits.push([/^flow_id:(\s*)main\s*$/m, `flow_id:$1${f}`]); // flow + locale headers
-        edits.push([/^(\s*-\s*)main\s*$/gm, `$1${f}`]); // manifest flows: + tools: entries
-        edits.push([new RegExp(`(\\$t\\(["'])main\\.`, 'g'), `$1${f}.`]); // $t("main.…")
-    }
     return { global, manifestOnly };
 }
-/** File-basename prefix renames (e.g. `main.flow.yaml` → `<flow>.flow.yaml`). */
-function fileRenames(opts) {
-    if (opts.flowId === 'main')
-        return [];
-    return [['main.', `${opts.flowId}.`]];
-}
-/**
- * Apply all renames in-place to a freshly-copied pack tree at `destDir`.
- * Content edits run first, then file renames (so edits see original names).
- */
+/** Apply all renames in-place to a freshly-copied pack tree at `destDir`. */
 export function applyRenames(destDir, opts) {
     const { global, manifestOnly } = contentReplacements(opts);
     for (const file of walkFiles(destDir)) {
@@ -91,15 +71,6 @@ export function applyRenames(destDir, opts) {
         if (changed)
             writeFileSync(file, text, 'utf8');
     }
-    for (const [fromPrefix, toPrefix] of fileRenames(opts)) {
-        for (const file of walkFiles(destDir)) {
-            const dir = file.slice(0, file.length - basename(file).length);
-            const base = basename(file);
-            if (base.startsWith(fromPrefix)) {
-                renameSync(file, join(dir, toPrefix + base.slice(fromPrefix.length)));
-            }
-        }
-    }
 }
 function basename(p) {
     const i = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {