stitchkit 0.90.2 → 0.90.4

package/CHANGELOG.md

@@ -15,6 +15,135 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.90.4] — 2026-09-16
+
+### Added
+
+- **Aggregate views on the CLI: `--count-by`, `--sum`, `--top`, `--table`.** The
+  CLI's audience is agents and scripts, which is why output is JSON — but
+  answering "how many per status" by shipping the whole collection is a separate
+  decision, and an expensive one. Measured on a live server: a 98-record listing
+  is 34 750 characters of an agent's context window; `--count-by status` is about
+  ninety. `| jq` cannot recover that, because the bytes have already been read
+  into the conversation by the time the pipe sees them. `--by` names the grouping
+  field in every form it appears in; groups come back largest first, so `--top`
+  is a defined slice. A field no record carries is an argument error naming the
+  fields that exist, never a silent empty group, and an aggregate needs a
+  collection — over a scalar it is refused rather than guessed. Without a view
+  flag the emitted bytes are unchanged, and the flags never reach a tool
+  argument.
+- **`createCliProfileStore` — named credential profiles that are never
+  substituted.** A CLI that talks to more than one deployment picks an
+  environment by name, and the convenient implementation of that is the unsafe
+  one: *the named profile does not exist, but exactly one is configured — use
+  it.* It is correct while a single profile exists and a wrong-environment
+  command the day a second appears. So a name given and not found is a refusal
+  that names the path and how to create it; substitution survives only where no
+  name was given and exactly one profile exists, and it is announced on stderr.
+  Files are `0600` in a `0700` directory, and a profile other users can read is
+  refused with the `chmod` that fixes it.
+- **CLI distribution and self-update.** A build manifest schema
+  (`CliBuildManifestSchema`), an installer generated from it
+  (`renderCliInstaller`), a bounded update check (`checkCliUpdate`) and a
+  verified atomic replace (`applyCliUpdate`). The installer parses no JSON — a
+  `curl … | sh` machine has no `jq`, so the URL and digest are substituted
+  server-side. The digest covers the **decompressed** bytes, because those are
+  what will be executed. The replace is a rename inside the target's own
+  directory, so an interrupted download can never leave a half-written
+  executable on a PATH. `assertCliPublishable` refuses republishing one version
+  from a different commit, and the check has four answers — `skipped`,
+  `current`, `outdated`, `unknown` — because "could not ask" is not "up to
+  date". Checking never replaces anything by itself. → ADR 0186
+- **`transports` on a connection — discovered tools as CLI commands.**
+  `mountConnections` and `createCli` already composed into a CLI whose surface is
+  the one the server has right now rather than the one the binary was compiled
+  against, except that discovered tools were filtered out of the CLI projection
+  with no declarative way in. Naming `transports: ['CLI']` on a connection makes
+  that server's tools commands; a connection without it still contributes
+  nothing, so exposure stays explicit.
+- **`coerceJsonArgs`, `routeCliArgv`, `extractCliGlobalOptions` and
+  `CliArgumentError` are exported from `stitchkit/cli`.** `parseCliArgs`
+  deliberately leaves array and object values as strings for the pass that runs
+  next; a consumer that parses argv and sends the call itself needs both halves,
+  and reaching for the `stitchkit/tools` barrel to get one function pulls the MCP
+  and AI peers into a binary this entrypoint is careful to avoid.
+
+### Fixed
+
+- **A stitchkit MCP surface is readable by the stitchkit MCP client again.**
+  `mountConnections` threw `Reference not found:
+  #/definitions/input/definitions/__schema0` against a server that is itself
+  built on stitchkit, and on one real surface of 205 tools five carried such a
+  reference — enough to lose the whole connection, because the mount was
+  all-or-nothing. Two defects underneath. The served document declared the
+  2020-12 dialect (the SDK stamps it) while using draft-07's `definitions`
+  keyword, so any reader that registers subschemas from the keyword its dialect
+  names found nothing to resolve against; MCP metadata now moves to `$defs` and
+  carries its pointers with it. And definitions were nested one level deeper than
+  a reader looks, because namespacing wrapped each schema instead of prefixing
+  its definition names; they are hoisted to the document root now, `allOf`
+  merges included. The client also no longer believes a contradicted stamp, which
+  is how it reaches every stitchkit server published before this release. → ADR 0185
+- **One unconvertible discovered tool no longer takes the connection down.**
+  `mountConnections` builds per tool, skips what it cannot build and names it —
+  through `onSkippedTool`, or a stderr line naming the connection, the tool and
+  the reason.
+
+## [0.90.3] — 2026-09-15
+
+### Added
+
+- **A trailing positional may be a list.** When the last field of a command's
+  declared `positionals` is an array, it takes every remaining argv token,
+  coerced by the element type: `myapp handoff proj a.md b.md` instead of
+  `--files '["a.md","b.md"]'`. One token is a one-element list, so the parsed
+  shape never depends on how many a caller happened to pass, and command help
+  says which field is the list (`<to> <files...>`). The flag form still works;
+  passing both forms in one call is an argument error rather than a silent
+  merge. Only the trailing position is variadic — an array declared earlier
+  keeps taking exactly one JSON token, unchanged.
+- **`globalOptions` — the application's own invocation context.** A CLI's
+  globals were only ever the framework's (`--json`, `--wait`, …), so an app that
+  needed `--caller <key>` or `--root <dir>` had to read an environment variable
+  or parse argv itself, next to the parser it already had. Declare them as a Zod
+  object and `createCli` lifts them out of argv wherever they stand — before or
+  after the command name — validates them, keeps them out of every operation's
+  arguments, and hands them to `resolveAuth(globals)`, `context(auth, globals)`
+  and a native command's `globals`. A name that collides with a framework option
+  or with a field of any command is refused at startup instead of shadowing it
+  silently, and both help levels list them under `Application options:`.
+
+### Fixed
+
+- **Output past the pipe buffer is no longer lost to a slow reader.** The
+  default writer called `writeSync` and ignored the byte count it returns. Once
+  anything in the process has touched `process.stdout` the descriptor is
+  non-blocking, so a write into a pipe whose reader has not started yet stores
+  what the 64 KB buffer takes, returns that count and throws nothing: the tail
+  vanished with exit code `0`, at exactly 65536 bytes — the same number as the
+  truncation the synchronous writer had been introduced to fix, which is why it
+  read as already fixed for so long. A consuming CLI saw `… | jq` fail with
+  "Unfinished string at column 65536" while the same command redirected to a
+  file wrote the whole result. The writer now loops on the returned count and
+  treats a full buffer (`EAGAIN`) as a wait rather than a failure, which is what
+  a blocking write into an undrained pipe is supposed to do; where an exotic
+  descriptor still forces the async fallback, the default `exit` waits for that
+  write instead of cutting it off, and output that could not be delivered at all
+  now exits non-zero.
+- **Help survives a managed surface that cannot resolve.** A CLI whose commands
+  come from a running server declares them with a factory, and the factory needs
+  an identity. When `resolveAuth` failed — server down, key file missing — the
+  rejection escaped `createCli` and `--help` printed *nothing*: not the native
+  commands, which never depended on identity, and not the reason. Calling such a
+  name was worse than silence, because the surface never resolved and the answer
+  would have been `Unknown command` — a claim that the name does not exist when
+  the truth is that it could not be looked up. Top-level help now lists the
+  native commands and one line naming the refusal (`Managed commands are
+  unavailable: UNREACHABLE: socket closed`), and an unresolvable name answers
+  with that refusal and the exit code its error class declares through
+  `exitCodes`. Identity is still resolved at most once per invocation, failure
+  included.
+
 ## [0.90.2] — 2026-09-15
 
 ### Fixed

package/dist/agent-runtime-coding-tools.js

@@ -3,15 +3,15 @@ import {
   AgentCodingToolLimitsSchema,
   AgentCodingToolPathAuthorizationSchema,
   createAgentCodingTools
-} from "./index-j7q0xj6d.js";
+} from "./index-8crm1srv.js";
 import"./index-bn2cjajt.js";
 import"./index-gte38nbm.js";
 import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
 import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
-import"./index-kc6h6hg0.js";
-import"./index-r159gjwy.js";
+import"./index-8z9we758.js";
+import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import"./index-77fekveh.js";
 export {

package/dist/agent-runtime-harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-f475yj00.js";
+} from "./index-6atvfjc1.js";
 import"./index-p13mwz16.js";
 import"./index-y64k3s0h.js";
 import {
@@ -19,7 +19,7 @@ import {
   walkContainedFiles
 } from "./index-bn2cjajt.js";
 import"./index-7rkhw9ec.js";
-import"./index-44ht2790.js";
+import"./index-vcnfwrtr.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
 import"./index-2hryh65w.js";
@@ -31,8 +31,8 @@ import"./index-7zbps32p.js";
 import"./index-kzfs85xp.js";
 import {
   defineRuntimeTool
-} from "./index-kc6h6hg0.js";
-import"./index-r159gjwy.js";
+} from "./index-8z9we758.js";
+import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import"./index-77fekveh.js";
 

package/dist/agent-runtime-sandbox.js

@@ -1,6 +1,6 @@
 import {
   createAgentCodingTools
-} from "./index-j7q0xj6d.js";
+} from "./index-8crm1srv.js";
 import"./index-bn2cjajt.js";
 import {
   codingRefusal,
@@ -11,8 +11,8 @@ import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
 import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
-import"./index-kc6h6hg0.js";
-import"./index-r159gjwy.js";
+import"./index-8z9we758.js";
+import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import"./index-77fekveh.js";
 

package/dist/agent-runtime.js

@@ -31,7 +31,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-f475yj00.js";
+} from "./index-6atvfjc1.js";
 import"./index-p13mwz16.js";
 import {
   AgentAdmissionEventSchema,
@@ -169,11 +169,11 @@ import {
 import {
   buildToolManifest,
   mountAgent
-} from "./index-gbqjt8jz.js";
+} from "./index-19ryv24q.js";
 import"./index-7rkhw9ec.js";
-import"./index-wb15909q.js";
-import"./index-2hrfpw2c.js";
-import"./index-44ht2790.js";
+import"./index-kzxpsf8y.js";
+import"./index-32vjke6q.js";
+import"./index-vcnfwrtr.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
 import"./index-2hryh65w.js";
@@ -188,8 +188,8 @@ import"./index-7zbps32p.js";
 import"./index-kzfs85xp.js";
 import {
   defineRuntimeTool
-} from "./index-kc6h6hg0.js";
-import"./index-r159gjwy.js";
+} from "./index-8z9we758.js";
+import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import {
   executableAgentRuntimeTools

package/dist/cli.d.ts

@@ -17,9 +17,22 @@
  * and point your app's `package.json` `bin` at it.
  */
 export { type CliConfig, type CliSurfaceSource, createCli } from './tools/cli.js';
-export { type CliRunOptions, type ParsedCliArgs, parseCliArgs } from './tools/cli-args.js';
+export { CliArgumentError, type CliArgvRoute, type CliGlobalOptionsParse, type CliResultView, type CliRunOptions, extractCliGlobalOptions, type ParsedCliArgs, parseCliArgs, routeCliArgv, } from './tools/cli-args.js';
 export { type CliCommandContext, type CliCommandDefinition, type CliCommandDefinitionBase, type CliCommandDefinitionWithOutput, type CliCommandDefinitionWithoutOutput, defineCliCommand, } from './tools/cli-command.js';
 export { type CliWriters, DEFAULT_EXIT_CODES, type EmitOptions, type ExitCodeMap, emitResult, } from './tools/cli-format.js';
+export { type CliInstallerConfig, renderCliInstaller, } from './tools/cli-installer.js';
+export { assertCliPublishable, type CliBuildAsset, CliBuildAssetSchema, type CliBuildManifest, CliBuildManifestSchema, type CliBuildStamp, CliBuildStampSchema, type CliBuildTarget, CliBuildTargetSchema, currentCliBuildTarget, formatCliBuildStamp, selectCliBuildAsset, } from './tools/cli-manifest.js';
 export type { CliPresentationPolicyConfig } from './tools/cli-policy.js';
+export { CliProfileError, type CliProfileStore, type CliProfileStoreConfig, createCliProfileStore, type ResolvedCliProfile, } from './tools/cli-profile.js';
+export { type AppliedCliUpdate, applyCliUpdate, type CliUpdateApplyConfig, type CliUpdateCheck, type CliUpdateCheckConfig, checkCliUpdate, compareCliVersions, } from './tools/cli-update.js';
+export { type CliViewOutput, renderCliView } from './tools/cli-view.js';
 export { type CliWaitConfig, type PollParams, pollUntilDone } from './tools/cli-wait.js';
+/**
+ * The second half of `parseCliArgs`. The parser leaves array and object values
+ * as strings on purpose, because `executeToolMethod` runs this pass next; a
+ * consumer that parses argv and then sends the call itself needs both halves,
+ * and reaching for the `stitchkit/tools` barrel to get one function would pull
+ * the MCP and AI peers into a binary this entrypoint keeps free of them.
+ */
+export { coerceJsonArgs } from './tools/coerce.js';
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACtC,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACtC,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,kBAAkB,EACvB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,cAAc,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,gBAAgB,EACrB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtF;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cli.js

@@ -1,33 +1,381 @@
 import {
+  CliArgumentError,
   DEFAULT_EXIT_CODES,
   createCli,
   defineCliCommand,
   emitResult,
+  extractCliGlobalOptions,
+  fetchGuarded,
   parseCliArgs,
-  pollUntilDone
-} from "./index-8dph3pw6.js";
+  pollUntilDone,
+  readCapped,
+  renderCliView,
+  routeCliArgv
+} from "./index-y47z614h.js";
 import"./index-sbdmyz75.js";
-import"./index-wb15909q.js";
-import"./index-2hrfpw2c.js";
-import"./index-44ht2790.js";
+import"./index-kzxpsf8y.js";
+import"./index-32vjke6q.js";
+import"./index-vcnfwrtr.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
 import"./index-2hryh65w.js";
 import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-scs3f1eg.js";
+import {
+  AppError
+} from "./index-scs3f1eg.js";
 import"./index-zcgf3gqf.js";
-import"./index-7zbps32p.js";
-import"./index-kzfs85xp.js";
-import"./index-kc6h6hg0.js";
-import"./index-r159gjwy.js";
+import {
+  coerceJsonArgs
+} from "./index-7zbps32p.js";
+import {
+  safeJsonParse
+} from "./index-kzfs85xp.js";
+import"./index-8z9we758.js";
+import"./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import"./index-77fekveh.js";
+// src/tools/cli-installer.ts
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function renderCliInstaller(config) {
+  const binary = config.binaryName ?? config.manifest.name;
+  const installDir = config.installDir ?? "$HOME/.local/bin";
+  const decompress = config.asset.compression === "gzip" ? `  gzip -dc "$tmp/download" > "$tmp/binary"
+` : `  mv "$tmp/download" "$tmp/binary"
+`;
+  return `#!/bin/sh
+# ${binary} ${config.manifest.version} (${config.manifest.commit})
+# Generated from the build manifest — it parses no JSON and needs no jq.
+set -eu
+
+url=${shellQuote(config.asset.url)}
+sha256=${shellQuote(config.asset.sha256)}
+size=${shellQuote(String(config.asset.size))}
+binary=${shellQuote(binary)}
+dir="\${INSTALL_DIR:-${installDir}}"
+
+fetch() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q "$1" -O "$2"
+  else
+    echo "need curl or wget" >&2
+    exit 1
+  fi
+}
+
+digest() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | cut -d' ' -f1
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | cut -d' ' -f1
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$1" | awk '{print $NF}'
+  else
+    echo "need sha256sum, shasum or openssl" >&2
+    exit 1
+  fi
+}
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+fetch "$url" "$tmp/download"
+${decompress}
+actual="$(digest "$tmp/binary")"
+if [ "$actual" != "$sha256" ]; then
+  echo "checksum mismatch: expected $sha256, got $actual" >&2
+  exit 1
+fi
+
+actual_size="$(wc -c < "$tmp/binary" | tr -d ' ')"
+if [ "$actual_size" != "$size" ]; then
+  echo "size mismatch: expected $size bytes, got $actual_size" >&2
+  exit 1
+fi
+
+mkdir -p "$dir"
+chmod 755 "$tmp/binary"
+# A rename, never a write over the file in place: anything else can leave a
+# half-written executable where a working one used to be.
+mv "$tmp/binary" "$dir/$binary"
+
+echo "installed $binary ${config.manifest.version} to $dir/$binary"
+case ":$PATH:" in
+  *":$dir:"*) ;;
+  *) echo "note: $dir is not on your PATH" >&2 ;;
+esac
+`;
+}
+// src/tools/cli-manifest.ts
+import { z } from "zod";
+var CliBuildTargetSchema = z.object({
+  platform: z.string().min(1),
+  arch: z.string().min(1)
+});
+var CliBuildAssetSchema = CliBuildTargetSchema.extend({
+  url: z.url(),
+  compression: z.enum(["gzip", "none"]).default("none"),
+  size: z.int().positive(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters")
+});
+var CliBuildManifestSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().min(1),
+  commit: z.string().min(1),
+  builtAt: z.iso.datetime(),
+  assets: z.array(CliBuildAssetSchema)
+});
+var CliBuildStampSchema = z.object({
+  version: z.string().min(1),
+  commit: z.string().min(1),
+  builtAt: z.iso.datetime()
+});
+function formatCliBuildStamp(stamp, name) {
+  const prefix = name ? `${name} ` : "";
+  return `${prefix}${stamp.version} (${stamp.commit.slice(0, 12)}, built ${stamp.builtAt})`;
+}
+function currentCliBuildTarget() {
+  return { platform: process.platform, arch: process.arch };
+}
+function selectCliBuildAsset(manifest, target = currentCliBuildTarget()) {
+  return manifest.assets.find((asset) => asset.platform === target.platform && asset.arch === target.arch);
+}
+function assertCliPublishable(previous, next) {
+  if (!previous)
+    return;
+  if (previous.version !== next.version)
+    return;
+  if (previous.commit === next.commit)
+    return;
+  throw new Error(`[stitchkit] ${next.name} ${next.version} was already published from commit ${previous.commit}; ` + `refusing to republish it from ${next.commit} — bump the version instead`);
+}
+// src/tools/cli-profile.ts
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { join } from "node:path";
+var PROFILE_SUFFIX = ".json";
+var FILE_MODE = 384;
+var DIRECTORY_MODE = 448;
+
+class CliProfileError extends AppError {
+  constructor(message, code = "NOT_FOUND") {
+    super(code, message, code === "NOT_FOUND" ? 404 : code === "FORBIDDEN" ? 403 : 400);
+    this.name = "CliProfileError";
+  }
+}
+function assertProfileName(name) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    throw new CliProfileError(`"${name}" is not a usable profile name — letters, digits, dot, dash and underscore`, "BAD_REQUEST");
+  }
+}
+function createCliProfileStore(config) {
+  const announce = config.announce ?? ((line) => process.stderr.write(`${line}
+`));
+  const pathFor = (name) => {
+    assertProfileName(name);
+    return join(config.directory, `${name}${PROFILE_SUFFIX}`);
+  };
+  const list = () => {
+    if (!existsSync(config.directory))
+      return [];
+    return readdirSync(config.directory).filter((entry) => entry.endsWith(PROFILE_SUFFIX)).map((entry) => entry.slice(0, -PROFILE_SUFFIX.length)).sort();
+  };
+  const read = (name) => {
+    const path = pathFor(name);
+    if (!existsSync(path)) {
+      throw new CliProfileError(missingMessage(name, path, config));
+    }
+    const mode = statSync(path).mode & 63;
+    if (mode !== 0) {
+      throw new CliProfileError(`profile "${name}" is readable by other users — run: chmod 600 ${path}`, "FORBIDDEN");
+    }
+    const parsed = safeJsonParse(readFileSync(path, "utf8"));
+    const result = config.schema.safeParse(parsed);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      const field = issue?.path.join(".");
+      throw new CliProfileError(`profile "${name}" (${path}) is not usable: ${field ? `${field}: ` : ""}${issue?.message ?? "invalid"}`, "BAD_REQUEST");
+    }
+    return result.data;
+  };
+  return {
+    directory: config.directory,
+    pathFor,
+    list,
+    read,
+    write(name, value) {
+      const path = pathFor(name);
+      mkdirSync(config.directory, { recursive: true, mode: DIRECTORY_MODE });
+      writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, { mode: FILE_MODE });
+      chmodSync(path, FILE_MODE);
+      return path;
+    },
+    resolve(name) {
+      if (name !== undefined) {
+        const path = pathFor(name);
+        return { name, path, value: read(name), substituted: false };
+      }
+      const configured = list();
+      const only = configured[0];
+      if (configured.length === 1 && only !== undefined) {
+        const path = pathFor(only);
+        announce(`[${only}] using the only configured profile (${path})`);
+        return { name: only, path, value: read(only), substituted: true };
+      }
+      if (configured.length === 0) {
+        const example = join(config.directory, `<name>${PROFILE_SUFFIX}`);
+        throw new CliProfileError(`no profile is configured in ${config.directory}${config.createHint ? ` — ${config.createHint("<name>", example)}` : ""}`);
+      }
+      throw new CliProfileError(`several profiles are configured (${configured.join(", ")}) — name one`, "BAD_REQUEST");
+    }
+  };
+}
+function missingMessage(name, path, config) {
+  const hint = config.createHint ? ` — ${config.createHint(name, path)}` : "";
+  return `profile "${name}" is not configured; expected ${path}${hint}`;
+}
+// src/tools/cli-update.ts
+import { createHash } from "node:crypto";
+import { chmodSync as chmodSync2, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { basename, dirname, join as join2 } from "node:path";
+import { gunzipSync } from "node:zlib";
+var DEFAULT_CHECK_TIMEOUT_MS = 2000;
+var DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+var DEFAULT_DOWNLOAD_TIMEOUT_MS = 120000;
+var MANIFEST_MAX_BYTES = 256 * 1024;
+var DEFAULT_MAX_ASSET_BYTES = 256 * 1024 * 1024;
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value.trim());
+  if (!match)
+    return;
+  const numbers = [match[1], match[2], match[3]].map((part) => Number(part));
+  if (numbers.some((part) => !Number.isFinite(part)))
+    return;
+  return { numbers, prerelease: match[4] };
+}
+function compareCliVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b)
+    return;
+  for (let index = 0;index < 3; index++) {
+    const difference = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+    if (difference !== 0)
+      return difference < 0 ? -1 : 1;
+  }
+  if (a.prerelease === b.prerelease)
+    return 0;
+  if (a.prerelease === undefined)
+    return 1;
+  if (b.prerelease === undefined)
+    return -1;
+  return a.prerelease < b.prerelease ? -1 : 1;
+}
+async function checkCliUpdate(config) {
+  const now = config.now ?? Date.now();
+  const interval = config.intervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+  if (config.lastCheckedAt !== undefined && now - config.lastCheckedAt < interval) {
+    return { status: "skipped", nextCheckAt: config.lastCheckedAt + interval };
+  }
+  try {
+    const response = await fetchGuarded(new URL(config.manifestUrl), config.allowPrivateHosts ?? false, {
+      timeoutMs: config.timeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS,
+      bodyTimeoutMs: config.timeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS
+    });
+    if (!response.ok)
+      return { status: "unknown", reason: `manifest responded ${response.status}` };
+    const body = await readCapped(response, MANIFEST_MAX_BYTES);
+    if (!body)
+      return { status: "unknown", reason: "manifest is larger than expected" };
+    const parsed = CliBuildManifestSchema.safeParse(JSON.parse(body.toString("utf8")));
+    if (!parsed.success)
+      return { status: "unknown", reason: "manifest did not validate" };
+    const manifest = parsed.data;
+    const order = compareCliVersions(config.currentVersion, manifest.version);
+    if (order === undefined) {
+      return {
+        status: "unknown",
+        reason: `cannot compare ${config.currentVersion} with ${manifest.version}`
+      };
+    }
+    if (order >= 0)
+      return { status: "current", version: manifest.version };
+    const asset = selectCliBuildAsset(manifest, config.target ?? currentCliBuildTarget());
+    return {
+      status: "outdated",
+      version: manifest.version,
+      manifest,
+      ...asset && { asset }
+    };
+  } catch (error) {
+    return {
+      status: "unknown",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function applyCliUpdate(config) {
+  const target = config.targetPath ?? process.execPath;
+  const response = await fetchGuarded(new URL(config.asset.url), config.allowPrivateHosts ?? false, {
+    timeoutMs: config.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS,
+    bodyTimeoutMs: config.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS
+  });
+  if (!response.ok) {
+    throw new Error(`[stitchkit] update download responded ${response.status}`);
+  }
+  const transferred = await readCapped(response, config.maxBytes ?? DEFAULT_MAX_ASSET_BYTES);
+  if (!transferred)
+    throw new Error("[stitchkit] update download exceeded the size ceiling");
+  const bytes = config.asset.compression === "gzip" ? gunzipSync(transferred) : transferred;
+  if (bytes.length !== config.asset.size) {
+    throw new Error(`[stitchkit] update is ${bytes.length} bytes, manifest says ${config.asset.size} — refusing to install it`);
+  }
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sha256 !== config.asset.sha256) {
+    throw new Error(`[stitchkit] update digest ${sha256} does not match the manifest — refusing to install it`);
+  }
+  const staged = join2(dirname(target), `.${basename(target)}.${process.pid}.${Date.now()}`);
+  writeFileSync2(staged, bytes, { mode: 493 });
+  chmodSync2(staged, 493);
+  renameSync(staged, target);
+  return { path: target, bytes: bytes.length, sha256 };
+}
 export {
+  selectCliBuildAsset,
+  routeCliArgv,
+  renderCliView,
+  renderCliInstaller,
   pollUntilDone,
   parseCliArgs,
+  formatCliBuildStamp,
+  extractCliGlobalOptions,
   emitResult,
   defineCliCommand,
+  currentCliBuildTarget,
+  createCliProfileStore,
   createCli,
-  DEFAULT_EXIT_CODES
+  compareCliVersions,
+  coerceJsonArgs,
+  checkCliUpdate,
+  assertCliPublishable,
+  applyCliUpdate,
+  DEFAULT_EXIT_CODES,
+  CliProfileError,
+  CliBuildTargetSchema,
+  CliBuildStampSchema,
+  CliBuildManifestSchema,
+  CliBuildAssetSchema,
+  CliArgumentError
 };