octwin-cli 0.1.16 → 0.1.21

package/CHANGELOG.md

@@ -5,6 +5,142 @@ 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
+- **`octwin validate` catches primitive arguments the platform would drop — offline, no token.** A
+  primitive takes the arguments it declares and silently ignored the rest, so an invented or
+  misspelled `args:` key deployed clean, ran clean, and simply did nothing: `record_list args: {
+  order: … }` (the argument is `sort`) never ordered, and `booking_cancel args: { booking_record_id:
+  … }` meant the REQUIRED `record_id` never arrived, so cancelling just failed. Validate now replays
+  the platform's contract from the pulled KB (`primitives/*.json` → `inputSchema`) and names the bad
+  argument, what the primitive takes, and any required argument that is missing. Scanning the 21
+  shipped marketplace packs found **ten** such errors across five packs. Keys are checked, values are
+  not — an `args:` value is normally an expression string resolved at runtime.
+  [`args-check.ts`](src/lib/args-check.ts).
+  - Silently skipped when the KB has not been pulled yet, like the render-intent check beside it.
+  - It cannot see inside a `use:` template body (expanding one is the platform's job) — `octwin
+    validate --remote` covers that case, and now also reports unreachable `$bind.<path>` reads and
+    `outputs:` port typos, which have no offline equivalent.
+
+## [0.1.19] - 2026-07-29
+
+### Added
+- **`octwin validate` catches render-intent fields the platform would drop — offline, no token.** Each
+  render intent takes a fixed field set; a key outside it used to be swallowed at load and dropped at
+  render, with no error anywhere — just a card missing what the author wrote. Validate now replays the
+  platform's own contract from the pulled KB (`render-intents/*.json` → `allowed_keys`) and names the
+  bad field, the intent, and what is allowed. Scanning the 21 shipped marketplace packs found two real
+  instances in 223 intents: a `text_card` carrying `buttons` (the fallback's only escape button never
+  rendered) and a `list_picker` carrying a non-existent `group_by` (a whole mapper step feeding a
+  fabricated parameter). Silently skipped when the KB has not been pulled yet.
+
+### Changed
+- **`octwin platform-kb pull` now explodes the reference and writes an `INDEX.md`.** A pull used to
+  write ~787 KB across 34 flat files — about 225k tokens, more than the pack being authored — so
+  finding one primitive meant reading a 122 KB catalog. Catalogs the platform describes as
+  enumerable are now written **one file per entry** (`primitives/record_list.json`,
+  `render-intents/carousel.json`, `declarations/xrm.json`, …), with `INDEX.md` mapping every doc and
+  all 171 entries to its file with a one-line summary. Reading one primitive went from ~38k tokens to
+  ~700. The layout comes from the platform (an `entries` descriptor on the bundle index) rather than
+  being hardcoded here, so this CLI keeps working against any platform version and a platform that
+  adds a catalog needs no CLI release. The pulled directory is cleared each pull, so a withdrawn
+  capability cannot linger as a file the authoring agent reads as current — its *contents* are
+  cleared rather than the directory itself, since on Windows a directory that is any shell's working
+  directory cannot be removed.
+
+## [0.1.18] - 2026-07-29
+
+### Fixed
+- **The bundle collector and the platform's repo import disagreed about what a pack directory
+  contains.** `collectBundleFiles` had its own rule and kept three things the operator's GitHub
+  import drops: `*.ts`/`*.tsx`, `__snapshots__/` and `*.example`. Because the server rejects a
+  `.ts` outright, the same directory imported cleanly from GitHub and failed to deploy from
+  disk with `'…': executable code is not allowed` — an error blaming a file that was never
+  meant to ship (a snapshot test beside a flow, or the documented `xrm.yaml.example` template).
+  The rule now lives in a vendored `lib/pack-source.ts` beside the vendored validator, and a
+  parity test in the platform drives both copies over one table.
+
+### Removed
+- **`pack.json` is gone — the saved login IS the deploy target.** The file had eroded to a single
+  field, `platform_url`, which `octwin login --url … --token …` already states; `tenant`/`project`
+  became optional overrides once deploy tokens started carrying their own tenant and project pin.
+  So it was a second home for a fact `login` knew, and it cost real things: a machine-specific file
+  committed into every pack repo, a four-link config-precedence chain to document, and an
+  exclusion rule duplicated in the bundler and the server (which had already drifted apart).
+  `octwin init` and `octwin pull` no longer write one, and nothing reads one. **A pack directory is
+  now pack content and nothing else** — the same repo deploys from any machine, and a pulled pack
+  redeploys with no flags.
+
+### Changed
+- **`octwin login` now sets the default deploy target**, not just the token: it writes a
+  `default_url` key alongside the token in `~/.octwin/credentials.json`. Every command resolves
+  **flags → env (`PACK_PLATFORM_URL`/`PACK_TENANT`/`PACK_PROJECT`/`PACK_TOKEN`) → saved login**.
+  An existing credentials file simply has no `default_url` until the next `octwin login` — which is
+  exactly what the "no platform url" error now tells you to run. CI is unaffected (it passes
+  `PACK_PLATFORM_URL` + `PACK_TOKEN` as env and never had a `pack.json`).
+
+## [0.1.17] - 2026-07-27
+
+### Added
+- **`octwin pull <packId>` — write a DEPLOYED pack's source back to disk.** The inverse of
+  `deploy`. A pack pushed with the CLI lived on the platform as an artifact the runtime served
+  but nothing could hand back, so its only source copy was the machine that pushed it. Pull it,
+  fix it, redeploy it. Writes a `pack.json` (retired in 0.1.18 — the saved login is now the
+  target) so the pulled directory redeploys where it came from; `--version` picks a version,
+  `--force` overwrites a non-empty dir. You may pull a pack
+  your tenant OWNS (an operator token pulls any) — a pack you merely installed is not yours to
+  read.
+- **`octwin chat --script <file>` — drive a whole conversation from one invocation.** One turn per
+  line, in order, in a single process over a single SSE connection, waiting for each turn to settle
+  before sending the next. Blank lines and `#` comments are skipped; `tap:<id>` presses a rendered
+  row/button (the rest of the line is kept verbatim, since a tap id is itself colon-delimited),
+  `media:<path>` uploads a file, and `media:<path> | caption` attaches one.
+
+  This exists because **chaining invocations races the agent loop.** A turn ends on a quiet gap
+  (`TURN_SETTLE_MS`), which can arrive while the server-side loop is still running — so
+  `chat A && chat B` lets B's inbound land mid-turn, and the agent fills required fields with
+  placeholder text (`service_id: "service-id"`) or starts a second workflow run. Those look exactly
+  like flow bugs and cost a field author three separate investigations. The one-turn-per-invocation
+  rule is now stated in `chat --help` and the header usage as well.
+
+### Changed
+- **`octwin deploy` reports the suspended runs it invalidated.** A redeploy rebuilds the pack's
+  tools, and in-flight flow runs live in those tools — so every suspended conversation is dropped.
+  The deploy prints `ⓘ N suspended run(s) invalidated` when N > 0, instead of leaving the author to
+  discover it as a `workflow_resume_stale` on the next tap.
+
 ## [0.1.16] - 2026-07-26
 
 ### Added

package/README.md

@@ -43,7 +43,7 @@ git init && git add -A && git commit -m "init pack"
 # 2. Author it — edit manifest.yaml, flows/tools/main.flow.yaml (+ its locale),
 #    and prompts/identity.md. Everything is pure YAML.
 
-# 3. Point it at your platform: edit pack.json, then log in with a deploy token
+# 3. Point it at your platform — one command, no config file
 #    (Octwin console → your workspace → API tokens → Generate)
 octwin login --url https://your-octwin.example.com --token oct_…
 
@@ -60,12 +60,13 @@ octwin status               # "✓ live and current" once it's warm
 
 | Command | What it does |
 | --- | --- |
-| `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, and `pack.json`). Options: `--id`, `--description`, `--display-name`. |
+| `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
 | `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 (stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
+| `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,7 +76,8 @@ 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 platform-kb pull` | Pull the platform's capability reference (built-ins, primitives, render intents, flow-DSL — as markdown + JSON) into `.octwin/platform-kb/`, for the **`octwin-pack`** Claude Code authoring plugin to consult. |
+| `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`. |
 
@@ -121,33 +123,37 @@ Three things worth knowing when you read the output:
 
 ## Configuration
 
-The deploy target has four settings. Three live in a committed **`pack.json`** at the root of your
-pack; the **token is a secret** and is kept out of `pack.json` (set it with `octwin login`).
+**`octwin login` is the configuration.** There is no config file in your pack — a pack directory
+holds pack content and nothing else, so the same repo deploys from any machine:
+
+```bash
+octwin login --url https://your-octwin.example.com --token oct_…
+```
+
+That stores the token *and* makes the URL your default target, in `~/.octwin/credentials.json`:
 
 ```jsonc
-// pack.json  — created by `octwin init`
 {
-  "platform_url": "https://your-octwin.example.com",  // your Octwin platform
-  "tenant":       "my-tenant-slug",                    // your workspace (required)
-  "project":      "main"                               // defaults to "main"
+  "default_url": "https://your-octwin.example.com",  // set by the last `octwin login`
+  "https://your-octwin.example.com": "oct_…"          // token, keyed by platform url
 }
 ```
 
-```bash
-octwin login --url https://your-octwin.example.com --token oct_…   # saves the token once
-```
+Tenant and project need no setting at all — the **token carries its own tenant**, plus an optional
+project pin. `--tenant` / `--project` exist only as overrides (a multi-workspace human, or an
+unpinned token that must name a project).
 
-Each setting resolves in this order — **flag → environment variable → `pack.json` → default**:
+Each setting resolves **flag → environment variable → saved login**:
 
-| Setting | Flag | Env var | `pack.json` key |
+| Setting | Flag | Env var | Saved login |
 | --- | --- | --- | --- |
-| Platform URL | `--url` | `PACK_PLATFORM_URL` | `platform_url` |
-| Tenant slug | `--tenant` | `PACK_TENANT` | `tenant` |
-| Project slug | `--project` | `PACK_PROJECT` | `project` (default `main`) |
-| Deploy token | `--token` | `PACK_TOKEN` | — *(use `octwin login`)* |
+| Platform URL | `--url` | `PACK_PLATFORM_URL` | `default_url` |
+| Deploy token | `--token` | `PACK_TOKEN` | token for that URL |
+| Tenant slug *(override)* | `--tenant` | `PACK_TENANT` | — *(from the token)* |
+| Project slug *(override)* | `--project` | `PACK_PROJECT` | — *(from the token's pin)* |
 
-For **CI**, skip `pack.json`/`login` entirely and pass `PACK_PLATFORM_URL`, `PACK_TENANT`,
-`PACK_PROJECT`, and `PACK_TOKEN` as environment variables.
+For **CI**, skip `login` entirely and pass `PACK_PLATFORM_URL` + `PACK_TOKEN` as environment
+variables (add `PACK_PROJECT` only if the token isn't pinned).
 
 ## Authentication
 
@@ -166,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