stitchkit 0.113.2 → 0.113.3

package/dist/tools/cli/format.d.ts

@@ -12,7 +12,7 @@
  * still parsing a success.
  */
 import type { ErrorHintFn } from '../execute-hooks.js';
-import type { ToolResult } from '../execute-result.js';
+import type { ToolFailure, ToolResult } from '../execute-result.js';
 /** Map a `ToolResult.code` to a process exit code. */
 export type ExitCodeMap = Record<string, number>;
 /**
@@ -47,4 +47,8 @@ export interface EmitOptions {
  */
 export declare function cliExitCode(result: ToolResult, exitCodes?: ExitCodeMap): number;
 export declare function emitResult(result: ToolResult, writers: CliWriters, opts: EmitOptions): number;
+/** A presentation failure cannot erase a successfully completed operation. */
+export declare function emitPresentationFailure(result: Extract<ToolResult, {
+    ok: true;
+}>, failure: ToolFailure, writers: CliWriters, opts: EmitOptions): number;
 //# sourceMappingURL=format.d.ts.map

package/dist/tools/cli/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAkBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGjE,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAmBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,EACzC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAmBR"}

package/dist/tools/cli/run-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA+Df"}
+{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAyEf"}

package/llms/cli.2.txt

@@ -11,6 +11,287 @@ Parts of this slice:
 # Guide: CLI  (docs/guide/cli.md)  (continued)
 ==============================================================================
 
+## Distribution and self-update
+
+`createCli` ships no executable, and that is right — but the step after the
+executable is not application logic either. It is the same problem for every
+consumer, with the same three traps:
+
+1. **The installer cannot parse the manifest.** A `curl … | sh` runs on a
+   machine where nothing is installed yet, including `jq`. So the installer is
+   generated *from* the manifest, server-side, with the URL and digest already
+   substituted — it parses no JSON at all.
+2. **Replacing a running binary is a rename, not a write.** Anything else can
+   leave a half-written executable on someone's PATH when the connection drops.
+3. **The digest covers the decompressed bytes** — the file that will actually be
+   executed, not the archive that was transferred.
+
+The framework owns the manifest shape, the installer generation and the update
+primitive. The application owns where the assets live, which platforms it
+publishes and who may download them.
+
+```ts
+import {
+  CliBuildManifestSchema, assertCliPublishable, renderCliInstaller,
+  selectCliBuildAsset, checkCliUpdate, applyCliUpdate,
+} from 'stitchkit/cli'
+
+// Publishing: refuse to republish one version from a different commit —
+// otherwise everyone who already installed it never receives the fix.
+assertCliPublishable(previous, next)
+
+// Serving: omit `asset` and one script covers every published target, selecting
+// by uname at run time — otherwise that dispatch is the last hand-written piece
+// of the install path, and every publisher writes the same x86_64 → x64 table.
+renderCliInstaller({ manifest, binaryName: 'myapp' })
+// Or pin one target explicitly:
+renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target), binaryName: 'myapp' })
+
+// Checking: bounded, at most once per interval, silent on any failure.
+const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
+if (check.status === 'outdated' && check.asset) {
+  // Replacing is always an explicit command, never a side effect of a check.
+  await applyCliUpdate({ asset: check.asset })
+}
+```
+
+`checkCliUpdate` has **four** answers, not three: `skipped`, `current`,
+`outdated` and `unknown`. "Could not ask" is not "up to date" — collapsing them
+is how a tool goes quiet about its own staleness for months. It never throws,
+and a command still exits with the code it earned.
+
+Carry the build stamp inside the binary (`CliBuildStampSchema`,
+`formatCliBuildStamp`) so the tool can say what it is rather than leaving the
+reader to infer it from behaviour.
+
+#### A manifest inside your own network
+
+The check goes through the same SSRF boundary every outbound fetch does, so a
+manifest served from `10.x`, `localhost` or a `.internal` name is refused and
+the answer is `unknown`. For a self-hosted deployment that is a wrong answer
+dressed as a careful one, and the refusal says so — it names the field that
+lifts it rather than reading like a timeout:
+
+```text
+refusing to fetch an internal host — the manifest endpoint is not public.
+Set `allowPrivateHosts` if it is your own deployment; the download keeps its
+own setting, because an asset URL comes from the document.
+```
+
+```ts
+const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
+```
+
+Set it from whether **your** endpoint is private, not as a blanket switch, and
+leave `applyCliUpdate` at its default. The two are not the same decision: the
+manifest URL is configuration you wrote, while an asset URL arrives inside a
+document the endpoint served, and a document is exactly what an SSRF boundary
+exists to distrust.
+
+### Publishing a complete version
+
+`publishCli` is an opt-in publisher for a local application-owned distribution
+directory. It commits every target and its version manifest before atomically
+replacing the public `manifest.json`. It ships from its own evolving entrypoint,
+`stitchkit/cli/publish`: release infrastructure follows how distributions are
+published, so it is not held to the stable promise of `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
+manifest, signatures, installer and updater it writes for stay in
+`stitchkit/cli`. Your application selects the CLI source identity and admits
+that snapshot at each phase:
+
+```ts
+import { publishCli } from 'stitchkit/cli/publish'
+
+const result = await publishCli({
+  storageRoot: '/srv/myapp/cli',
+  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
+  baseUrl: 'https://downloads.example.com/cli/',
+  targets: [{ platform: 'linux', arch: 'x64' }],
+  signal,
+  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
+  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
+})
+// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
+```
+
+The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
+executable. Every target receives the same immutable `{ version, commit,
+builtAt }` stamp; carry it inside the binary. The publisher owns staging,
+gzip assets, paths and manifests. Callbacks receive the cancellation signal and
+run under the publication lock. Admission phases are `prepare`, each target's
+`build`, `commit`, and `promote`; validate the selected source through commit
+and promotion. A backend release can explicitly select an unchanged older CLI
+identity. The helper never substitutes a different commit or rebuilds an
+existing version under a new identity.
+
+Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
+`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
+the exact bytes and `builtAt`, requires the same target set and base URL, and
+returns `existing` without invoking the builder. A version committed before a
+failed promotion is recovered and promoted without rebuilding. Conflicting
+same-version commits, downgrades, unsafe components, corrupt manifests and
+assets are refused. Version/name/target components are validated before any
+build; `storageRoot` is absolute and its existing parent must be trusted.
+
+All limits are finite positive safe integers; `limits` overrides these defaults:
+
+| Field | Default | Enforced boundary |
+| --- | --- | --- |
+| `maxTargets` | 16 | Requested and verified target count |
+| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
+| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
+| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
+| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
+| `maxStoredVersions` | 16 | Verified publisher-owned history |
+| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
+| `timeoutMs` | 600,000 | Whole publication deadline |
+
+`retention` defaults to 2 and keeps the current and previous published versions.
+It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
+recovery slot. Older versions are pruned only after their own identity, exact
+layout, raw size and digest are verified. Runtime folders and foreign semver
+directories remain untouched. A full or unverifiable store refuses further
+publication; repeated completed candidates stay inside the owned history cap.
+Cancelled or failed incomplete staging is removed only while its root and
+directory generations still match. The shared asynchronous gzip decoder also
+bounds updater expansion by the declared raw size and configured byte cap.
+
+The publisher rejects symlink roots/versions/assets, non-regular files and
+multiply linked files, and checks held-lock, root and prior-pointer generations
+before commit and promotion. This is cooperative publication under a trusted
+parent directory. Portable path checks do not provide an atomic comparison with
+a hostile process replacing ancestors between syscalls. Durability uses file
+and directory sync on POSIX; Windows publication is refused. A deadline stops
+callback/stream waits and blocks late promotion; trusted callbacks remain
+responsible for cancelling their own subprocesses and external effects.
+
+A failure after an immutable commit reports that the publication outcome must
+be checked. A failure after public-pointer rename may already have published;
+`AtomicFilePublicationError.published` remains available when the atomic writer
+reports that boundary. Read the durable manifest and retry the admitted same
+identity to recover; an error does not promise rollback. Optional `signing` and
+`trust` reuse the Ed25519 contract below. The generated shell installer checks
+raw digest and size; the updater checks manifest authorship when given a trust
+root.
+
+### Proving who built it — signing the manifest
+
+The asset digest proves the bytes that arrived are the bytes the manifest named.
+It proves nothing about who named them: the manifest and the assets come from
+one origin, so whoever can replace one can replace the other. Authorship needs a
+key the build carries and the server never holds.
+
+```ts
+// Publishing — the only side that holds a private key.
+const signature = signCliManifest(manifest, { keyId: 'release-2026', privateKey })
+publish({ ...manifest, signature })
+
+// Installing — the trust root is compiled into the binary. One fetched at run
+// time from the same origin as the manifest would prove nothing.
+const trust = { keys: { 'release-2026': PUBLISHED_KEY } }
+const check = await checkCliUpdate({ manifestUrl, currentVersion, trust })
+if (check.status === 'outdated' && check.asset) {
+  await applyCliUpdate({ asset: check.asset, manifest: check.manifest, trust, backupPath })
+}
+```
+
+The signature covers `{name, version, commit, builtAt, assets[]}` with **every
+asset's digest**, so the chain closes on the file that will execute rather than
+on the document describing it; moving an asset to a new URL does not invalidate
+it, changing what an asset contains does.
+
+Five verdicts, and `unenforced` is the one that earns its keep: a build with no
+pinned key keeps updating, and the fact that nothing was checked is *visible*
+rather than assumed. `missing`, `unknown-key` and `invalid` are distinguished
+because they need different answers — a key you forgot to pin is not a forged
+signature.
+
+A bad verdict does not produce a fifth status. `outdated` is an instruction to
+install, and a manifest that failed its signature has not established that there
+is a newer build worth installing — only that a document claims one. The check
+answers `unknown` with the verdict in its reason, so it is never mistaken for a
+network failure. `applyCliUpdate` checks again and refuses **before** the
+download: a signature verified after the bytes are on the machine produces a
+cleanup problem rather than a refusal.
+
+### A way back — `backupPath` and `rollbackCliUpdate`
+
+Rolling back is a property of updating, not of the application:
+
+```ts
+const applied = await applyCliUpdate({ asset, targetPath, backupPath })
+// …the new build turns out to be wrong. `backupSha256` is absent when there was
+// nothing to keep — a first install — and that is the case with nothing to roll
+// back to:
+if (applied.backupSha256) {
+  rollbackCliUpdate({ targetPath, backupPath, expectedSha256: applied.backupSha256 })
+}
+```
+
+The copy is taken between "the new bytes verified" and the replacement — earlier
+would preserve a binary about to be replaced by a download that then failed its
+digest, later has nothing left to copy — and it carries the target's file mode,
+because a backup that cannot be executed is not a way back. A first install has
+nothing to keep, which is not a failure.
+
+`expectedSha256` is required, not optional. A rollback that installs whatever
+happens to be at the backup path is a second install of an unverified binary,
+and the day it is used is the day nobody is in a position to check.
+
+### Run it before it replaces anything — `verify`
+
+A digest proves the bytes are the ones published, not that they load. A tool
+that updates itself unattended — a daemon — and installs a build that does not
+start takes its own updater down with it, and every machine is then repaired by
+hand. `verify` is the step between "digest matched" and "target replaced":
+
+```ts
+await applyCliUpdate({
+  asset, targetPath, backupPath,
+  verify: async (candidate, signal) => {
+    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
+    const printed = (await new Response(child.stdout).text()).trim()
+    if ((await child.exited) !== 0 || printed !== check.version) {
+      throw new Error(`printed ${printed}, expected ${check.version}`)
+    }
+  },
+  verifyTimeoutMs: 15_000,   // default 30 000
+})
+```
+
+The verified bytes are written beside the target as an executable candidate
+with the target's extension, and `verify` gets its path — a path rather than a
+command, because a JavaScript bundle is started through its runtime. It runs
+before the backup and the replacement. If it throws or outlives
+`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
+removed, the target and any earlier backup are untouched, and the update is
+refused with the reason as its cause. The target is written from the checked
+bytes in memory, never from the candidate file, so nothing the candidate did
+while it ran can change what is installed.
+
+### Two release tracks
+
+`assertCliPublishable` takes one manifest **or every manifest already
+published**:
+
+```ts
+assertCliPublishable([stableManifest, betaManifest], next)
+```
+
+With a single argument and two tracks the check is silently useless: `1.2.3`
+goes to beta from one commit and to stable from another, the function is called
+with the track being published and sees no conflict, and the person who
+installed the beta is told they are current forever. Nothing on their machine
+looks wrong.
+
+**The channel itself is not an argument of the framework, and will not become
+one.** The framework has no model of how your URLs are built and should not: an
+asset's address comes from the manifest, and the manifest's address belongs to
+your server. A channel is two documents at two addresses — which of them a build
+consults is your decision, and `assertCliPublishable` is told about all of them
+rather than taught the shape of any.
+
 ## One operation per line — `createCliInvoker`
 
 The most common way an agent drives a CLI is not one command: it is a stream —

package/llms/cli.txt

@@ -213,9 +213,11 @@ const doctor = defineCliCommand({
 it the canonical JSON output is unchanged. `exitCode` classifies a successfully
 validated result and must return an integer in `0..255`; failed `ToolResult`
 envelopes and the application-wide `exitCodes` mapping remain authoritative for
-failures. A throwing callback, invalid status or non-string presenter becomes a
-normalized `INTERNAL_SERVER_ERROR`, never partial success output. Void native
-commands cannot declare either callback.
+failures. A throwing or invalid exit-status callback becomes a normalized
+`INTERNAL_SERVER_ERROR`. A throwing or non-string `present` preserves the validated
+result on stdout and reports `CLI_PRESENTATION_FAILED` separately, as described
+under [Aggregate views](#aggregate-views). Void native commands cannot declare
+either callback.
 
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
@@ -430,6 +432,7 @@ newline-terminated JSON record on its respective stream; progress and CLI usage
 diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `2>/dev/null` clean. The process exit code carries the error class (`0` ok,
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+`CLI_PRESENTATION_FAILED → 8`,
 …) — override per app with `exitCodes`.
 
 ### A narrower question than "all of them"
@@ -651,7 +654,7 @@ would answer a question nobody asked.
 
 Three rules worth knowing before you rely on them:
 
-- **A field the result does not carry is an argument error.** A group of zero
+- **A field the result does not carry is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
 - **An aggregate needs a collection** — the result itself when it is an array,
@@ -665,6 +668,17 @@ Three rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
+If the command succeeds but its requested view cannot be built, the CLI writes
+the complete original result to stdout, using the normal JSON format (`--json`
+still selects compact output). It writes a separate structured
+`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
+through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
+distinguish a presentation refusal from a failed operation; `details.cause`
+preserves the safe reason. Recover the answer from stdout instead of repeating
+the mutation. Domain retry hints are not appended to this diagnostic. CLI
+argument errors detected before execution still exit with `2`
+and have no successful result to preserve.
+
 ## Named profiles
 
 A CLI that talks to a deployed server needs an address and a credential per
@@ -710,284 +724,3 @@ await createCli({
 Files are written `0600` in a `0700` directory — and a profile file other users
 can read is refused with the `chmod` that fixes it, because it holds a
 credential.
-
-## Distribution and self-update
-
-`createCli` ships no executable, and that is right — but the step after the
-executable is not application logic either. It is the same problem for every
-consumer, with the same three traps:
-
-1. **The installer cannot parse the manifest.** A `curl … | sh` runs on a
-   machine where nothing is installed yet, including `jq`. So the installer is
-   generated *from* the manifest, server-side, with the URL and digest already
-   substituted — it parses no JSON at all.
-2. **Replacing a running binary is a rename, not a write.** Anything else can
-   leave a half-written executable on someone's PATH when the connection drops.
-3. **The digest covers the decompressed bytes** — the file that will actually be
-   executed, not the archive that was transferred.
-
-The framework owns the manifest shape, the installer generation and the update
-primitive. The application owns where the assets live, which platforms it
-publishes and who may download them.
-
-```ts
-import {
-  CliBuildManifestSchema, assertCliPublishable, renderCliInstaller,
-  selectCliBuildAsset, checkCliUpdate, applyCliUpdate,
-} from 'stitchkit/cli'
-
-// Publishing: refuse to republish one version from a different commit —
-// otherwise everyone who already installed it never receives the fix.
-assertCliPublishable(previous, next)
-
-// Serving: omit `asset` and one script covers every published target, selecting
-// by uname at run time — otherwise that dispatch is the last hand-written piece
-// of the install path, and every publisher writes the same x86_64 → x64 table.
-renderCliInstaller({ manifest, binaryName: 'myapp' })
-// Or pin one target explicitly:
-renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target), binaryName: 'myapp' })
-
-// Checking: bounded, at most once per interval, silent on any failure.
-const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
-if (check.status === 'outdated' && check.asset) {
-  // Replacing is always an explicit command, never a side effect of a check.
-  await applyCliUpdate({ asset: check.asset })
-}
-```
-
-`checkCliUpdate` has **four** answers, not three: `skipped`, `current`,
-`outdated` and `unknown`. "Could not ask" is not "up to date" — collapsing them
-is how a tool goes quiet about its own staleness for months. It never throws,
-and a command still exits with the code it earned.
-
-Carry the build stamp inside the binary (`CliBuildStampSchema`,
-`formatCliBuildStamp`) so the tool can say what it is rather than leaving the
-reader to infer it from behaviour.
-
-#### A manifest inside your own network
-
-The check goes through the same SSRF boundary every outbound fetch does, so a
-manifest served from `10.x`, `localhost` or a `.internal` name is refused and
-the answer is `unknown`. For a self-hosted deployment that is a wrong answer
-dressed as a careful one, and the refusal says so — it names the field that
-lifts it rather than reading like a timeout:
-
-```text
-refusing to fetch an internal host — the manifest endpoint is not public.
-Set `allowPrivateHosts` if it is your own deployment; the download keeps its
-own setting, because an asset URL comes from the document.
-```
-
-```ts
-const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
-```
-
-Set it from whether **your** endpoint is private, not as a blanket switch, and
-leave `applyCliUpdate` at its default. The two are not the same decision: the
-manifest URL is configuration you wrote, while an asset URL arrives inside a
-document the endpoint served, and a document is exactly what an SSRF boundary
-exists to distrust.
-
-### Publishing a complete version
-
-`publishCli` is an opt-in publisher for a local application-owned distribution
-directory. It commits every target and its version manifest before atomically
-replacing the public `manifest.json`. It ships from its own evolving entrypoint,
-`stitchkit/cli/publish`: release infrastructure follows how distributions are
-published, so it is not held to the stable promise of `stitchkit/cli`
-([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
-manifest, signatures, installer and updater it writes for stay in
-`stitchkit/cli`. Your application selects the CLI source identity and admits
-that snapshot at each phase:
-
-```ts
-import { publishCli } from 'stitchkit/cli/publish'
-
-const result = await publishCli({
-  storageRoot: '/srv/myapp/cli',
-  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
-  baseUrl: 'https://downloads.example.com/cli/',
-  targets: [{ platform: 'linux', arch: 'x64' }],
-  signal,
-  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
-  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
-})
-// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
-```
-
-The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
-executable. Every target receives the same immutable `{ version, commit,
-builtAt }` stamp; carry it inside the binary. The publisher owns staging,
-gzip assets, paths and manifests. Callbacks receive the cancellation signal and
-run under the publication lock. Admission phases are `prepare`, each target's
-`build`, `commit`, and `promote`; validate the selected source through commit
-and promotion. A backend release can explicitly select an unchanged older CLI
-identity. The helper never substitutes a different commit or rebuilds an
-existing version under a new identity.
-
-Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
-`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
-the exact bytes and `builtAt`, requires the same target set and base URL, and
-returns `existing` without invoking the builder. A version committed before a
-failed promotion is recovered and promoted without rebuilding. Conflicting
-same-version commits, downgrades, unsafe components, corrupt manifests and
-assets are refused. Version/name/target components are validated before any
-build; `storageRoot` is absolute and its existing parent must be trusted.
-
-All limits are finite positive safe integers; `limits` overrides these defaults:
-
-| Field | Default | Enforced boundary |
-| --- | --- | --- |
-| `maxTargets` | 16 | Requested and verified target count |
-| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
-| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
-| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
-| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
-| `maxStoredVersions` | 16 | Verified publisher-owned history |
-| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
-| `timeoutMs` | 600,000 | Whole publication deadline |
-
-`retention` defaults to 2 and keeps the current and previous published versions.
-It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
-recovery slot. Older versions are pruned only after their own identity, exact
-layout, raw size and digest are verified. Runtime folders and foreign semver
-directories remain untouched. A full or unverifiable store refuses further
-publication; repeated completed candidates stay inside the owned history cap.
-Cancelled or failed incomplete staging is removed only while its root and
-directory generations still match. The shared asynchronous gzip decoder also
-bounds updater expansion by the declared raw size and configured byte cap.
-
-The publisher rejects symlink roots/versions/assets, non-regular files and
-multiply linked files, and checks held-lock, root and prior-pointer generations
-before commit and promotion. This is cooperative publication under a trusted
-parent directory. Portable path checks do not provide an atomic comparison with
-a hostile process replacing ancestors between syscalls. Durability uses file
-and directory sync on POSIX; Windows publication is refused. A deadline stops
-callback/stream waits and blocks late promotion; trusted callbacks remain
-responsible for cancelling their own subprocesses and external effects.
-
-A failure after an immutable commit reports that the publication outcome must
-be checked. A failure after public-pointer rename may already have published;
-`AtomicFilePublicationError.published` remains available when the atomic writer
-reports that boundary. Read the durable manifest and retry the admitted same
-identity to recover; an error does not promise rollback. Optional `signing` and
-`trust` reuse the Ed25519 contract below. The generated shell installer checks
-raw digest and size; the updater checks manifest authorship when given a trust
-root.
-
-### Proving who built it — signing the manifest
-
-The asset digest proves the bytes that arrived are the bytes the manifest named.
-It proves nothing about who named them: the manifest and the assets come from
-one origin, so whoever can replace one can replace the other. Authorship needs a
-key the build carries and the server never holds.
-
-```ts
-// Publishing — the only side that holds a private key.
-const signature = signCliManifest(manifest, { keyId: 'release-2026', privateKey })
-publish({ ...manifest, signature })
-
-// Installing — the trust root is compiled into the binary. One fetched at run
-// time from the same origin as the manifest would prove nothing.
-const trust = { keys: { 'release-2026': PUBLISHED_KEY } }
-const check = await checkCliUpdate({ manifestUrl, currentVersion, trust })
-if (check.status === 'outdated' && check.asset) {
-  await applyCliUpdate({ asset: check.asset, manifest: check.manifest, trust, backupPath })
-}
-```
-
-The signature covers `{name, version, commit, builtAt, assets[]}` with **every
-asset's digest**, so the chain closes on the file that will execute rather than
-on the document describing it; moving an asset to a new URL does not invalidate
-it, changing what an asset contains does.
-
-Five verdicts, and `unenforced` is the one that earns its keep: a build with no
-pinned key keeps updating, and the fact that nothing was checked is *visible*
-rather than assumed. `missing`, `unknown-key` and `invalid` are distinguished
-because they need different answers — a key you forgot to pin is not a forged
-signature.
-
-A bad verdict does not produce a fifth status. `outdated` is an instruction to
-install, and a manifest that failed its signature has not established that there
-is a newer build worth installing — only that a document claims one. The check
-answers `unknown` with the verdict in its reason, so it is never mistaken for a
-network failure. `applyCliUpdate` checks again and refuses **before** the
-download: a signature verified after the bytes are on the machine produces a
-cleanup problem rather than a refusal.
-
-### A way back — `backupPath` and `rollbackCliUpdate`
-
-Rolling back is a property of updating, not of the application:
-
-```ts
-const applied = await applyCliUpdate({ asset, targetPath, backupPath })
-// …the new build turns out to be wrong. `backupSha256` is absent when there was
-// nothing to keep — a first install — and that is the case with nothing to roll
-// back to:
-if (applied.backupSha256) {
-  rollbackCliUpdate({ targetPath, backupPath, expectedSha256: applied.backupSha256 })
-}
-```
-
-The copy is taken between "the new bytes verified" and the replacement — earlier
-would preserve a binary about to be replaced by a download that then failed its
-digest, later has nothing left to copy — and it carries the target's file mode,
-because a backup that cannot be executed is not a way back. A first install has
-nothing to keep, which is not a failure.
-
-`expectedSha256` is required, not optional. A rollback that installs whatever
-happens to be at the backup path is a second install of an unverified binary,
-and the day it is used is the day nobody is in a position to check.
-
-### Run it before it replaces anything — `verify`
-
-A digest proves the bytes are the ones published, not that they load. A tool
-that updates itself unattended — a daemon — and installs a build that does not
-start takes its own updater down with it, and every machine is then repaired by
-hand. `verify` is the step between "digest matched" and "target replaced":
-
-```ts
-await applyCliUpdate({
-  asset, targetPath, backupPath,
-  verify: async (candidate, signal) => {
-    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
-    const printed = (await new Response(child.stdout).text()).trim()
-    if ((await child.exited) !== 0 || printed !== check.version) {
-      throw new Error(`printed ${printed}, expected ${check.version}`)
-    }
-  },
-  verifyTimeoutMs: 15_000,   // default 30 000
-})
-```
-
-The verified bytes are written beside the target as an executable candidate
-with the target's extension, and `verify` gets its path — a path rather than a
-command, because a JavaScript bundle is started through its runtime. It runs
-before the backup and the replacement. If it throws or outlives
-`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
-removed, the target and any earlier backup are untouched, and the update is
-refused with the reason as its cause. The target is written from the checked
-bytes in memory, never from the candidate file, so nothing the candidate did
-while it ran can change what is installed.
-
-### Two release tracks
-
-`assertCliPublishable` takes one manifest **or every manifest already
-published**:
-
-```ts
-assertCliPublishable([stableManifest, betaManifest], next)
-```
-
-With a single argument and two tracks the check is silently useless: `1.2.3`
-goes to beta from one commit and to stable from another, the function is called
-with the track being published and sees no conflict, and the person who
-installed the beta is told they are current forever. Nothing on their machine
-looks wrong.
-
-**The channel itself is not an argument of the framework, and will not become
-one.** The framework has no model of how your URLs are built and should not: an
-asset's address comes from the manifest, and the manifest's address belongs to
-your server. A channel is two documents at two addresses — which of them a build
-consults is your decision, and `assertCliPublishable` is told about all of them
-rather than taught the shape of any.

package/llms/server.4.txt

@@ -553,7 +553,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `CLI_PRESENTATION_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,