stitchkit 0.103.13 → 0.104.1

package/dist/entrypoints/cli.js

@@ -18,25 +18,40 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-8zfsgar0.js";
+} from "../index-6drst9sg.js";
 import {
   AppError2
-} from "../index-n53mswt3.js";
-import"../index-b2bz0kdm.js";
-import"../index-m2xqkv55.js";
+} from "../index-x928baz2.js";
+import"../index-kb8styz3.js";
+import"../index-2vnh05w4.js";
 import"../index-ct75c3at.js";
-import"../index-x87j7csh.js";
+import"../index-77nxk6ay.js";
 import"../index-yex7eg1v.js";
-import"../index-r956rndn.js";
+import"../index-2hyavjjj.js";
+import"../index-xqhede6x.js";
 import {
+  ManagedFileError2,
+  createManagedFileBoundary2
+} from "../index-hbd32c6a.js";
+import"../index-za6j7nwy.js";
+import"../index-5csmzesf.js";
+import"../index-v5ee8ath.js";
+import {
+  withExclusiveLock2
+} from "../index-g95fk660.js";
+import {
+  writeFileAtomic2,
   writeFileAtomicSync2
-} from "../index-12m2v2a9.js";
-import"../index-dnn9z96q.js";
+} from "../index-s4evrmp5.js";
+import {
+  AtomicFilePublicationError2
+} from "../index-8a9ksm91.js";
+import"../index-a0zzh8ak.js";
+import"../index-cvda079a.js";
 import {
   argumentsDigest
 } from "../index-r7a7r7ha.js";
 import"../index-7n68nmc6.js";
-import"../index-tgzhq07n.js";
 import {
   serializeCanonicalJson
 } from "../index-zsvzhjtk.js";
@@ -409,142 +424,378 @@ 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/stream.ts
+// src/tools/cli/publication.ts
+import { createHash as createHash3 } from "node:crypto";
+import { lstat as lstat2, mkdtemp, rename, rm as rm2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+import { z as z5 } from "zod";
+
+// src/tools/cli/publication-assets.ts
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
+import { setImmediate as nextTurn } from "node:timers/promises";
+import { createGunzip, createGzip } from "node:zlib";
+
+// src/tools/cli/publication-control.ts
+function waitForPublication(operation, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    operation.then((value) => {
+      signal.removeEventListener("abort", abort);
+      if (signal.aborted) {
+        if (value instanceof ReadableStream && !value.locked)
+          value.cancel(signal.reason).catch(() => {
+            return;
+          });
+        reject(signal.reason);
+      } else
+        resolve(value);
+    }, (error) => {
+      signal.removeEventListener("abort", abort);
+      reject(error);
+    });
+    if (signal.aborted)
+      abort();
+  });
+}
+async function withPublicationDeadline(timeoutMs, caller, body) {
+  caller?.throwIfAborted();
+  const controller = new AbortController;
+  const abort = () => controller.abort(caller?.reason);
+  caller?.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(() => controller.abort(new Error(`CLI publication exceeded ${timeoutMs} ms`)), timeoutMs);
+  try {
+    return await body(controller.signal);
+  } finally {
+    clearTimeout(timer);
+    caller?.removeEventListener("abort", abort);
+  }
+}
+
+// src/tools/cli/publication-assets.ts
+async function collectCliBytes(source, maxBytes, signal) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+    throw new RangeError("CLI asset byte cap must be a positive safe integer");
+  const blocks = [];
+  let total = 0;
+  let filled = 0;
+  let block;
+  const consume = (chunk) => {
+    signal?.throwIfAborted();
+    if (!(chunk instanceof Uint8Array))
+      throw new TypeError("CLI asset stream must contain Uint8Array chunks");
+    if (total + chunk.byteLength > maxBytes)
+      throw new RangeError(`CLI asset exceeds ${maxBytes} bytes`);
+    for (let offset = 0;offset < chunk.byteLength; ) {
+      if (!block || filled === block.length) {
+        block = new Uint8Array(Math.min(64 * 1024, maxBytes - total));
+        blocks.push(block);
+        filled = 0;
+      }
+      const count = Math.min(chunk.byteLength - offset, block.length - filled);
+      block.set(chunk.subarray(offset, offset + count), filled);
+      filled += count;
+      total += count;
+      offset += count;
+    }
+  };
+  if (source instanceof Uint8Array)
+    consume(source);
+  else {
+    const reader = source.getReader();
+    let chunks = 0;
+    try {
+      for (;; ) {
+        const next = signal ? await waitForPublication(reader.read(), signal) : await reader.read();
+        if (next.done)
+          break;
+        consume(next.value);
+        if (++chunks % 128 === 0) {
+          if (signal)
+            await waitForPublication(nextTurn(), signal);
+          else
+            await nextTurn();
+        }
+      }
+    } catch (error) {
+      reader.cancel(error).catch(() => {
+        return;
+      });
+      throw error;
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  signal?.throwIfAborted();
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of blocks) {
+    const count = Math.min(chunk.length, total - offset);
+    bytes.set(chunk.subarray(0, count), offset);
+    offset += count;
+  }
+  return bytes;
+}
+async function transformAsset(bytes, kind, maxBytes, signal) {
+  const codec = kind === "gzip" ? createGzip() : createGunzip();
+  const output = Readable.toWeb(codec);
+  codec.end(bytes);
+  try {
+    return await collectCliBytes(output, maxBytes, signal);
+  } finally {
+    codec.destroy();
+  }
+}
+function gzipCliAsset(bytes, maxBytes, signal) {
+  return transformAsset(bytes, "gzip", maxBytes, signal);
+}
+async function decodeCliAsset(transferred, asset, maxBytes, signal) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || !Number.isSafeInteger(asset.size) || asset.size <= 0)
+    throw new RangeError("CLI asset size and cap must be positive safe integers");
+  if (asset.size > maxBytes)
+    throw new RangeError(`CLI asset declared size exceeds ${maxBytes} bytes`);
+  const bytes = asset.compression === "gzip" ? await transformAsset(transferred, "gunzip", asset.size, signal) : transferred;
+  if (bytes.length !== asset.size)
+    throw new Error(`CLI asset is ${bytes.length} bytes, manifest says ${asset.size}`);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sha256 !== asset.sha256)
+    throw new Error("CLI asset digest does not match the manifest (checksum mismatch) — refusing to install it");
+  return { bytes, sha256 };
+}
+
+// src/tools/cli/publication-contract.ts
+import { isAbsolute } from "node:path";
 import { z as z3 } from "zod";
-var LineSchema = z3.object({
-  id: z3.string().min(1),
-  command: z3.string().min(1),
-  args: z3.record(z3.string(), z3.unknown()).default({})
+var positive = z3.int().positive().max(Number.MAX_SAFE_INTEGER);
+var timer = positive.max(2147483647);
+var component = z3.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
+var PublicationTargetSchema = CliBuildTargetSchema.extend({
+  platform: component,
+  arch: component
 });
-async function* readStdinLines(source = process.stdin) {
-  const decoder = new TextDecoder;
-  let pending = "";
-  for await (const chunk of source) {
-    pending += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
-    let newline = pending.indexOf(`
-`);
-    while (newline !== -1) {
-      const line = pending.slice(0, newline);
-      pending = pending.slice(newline + 1);
-      yield line.endsWith("\r") ? line.slice(0, -1) : line;
-      newline = pending.indexOf(`
-`);
-    }
+var PublicationVersionSchema = z3.string().max(128).regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/).refine((value) => {
+  const core = value.split(/[+-]/)[0];
+  if (!core || core.split(".").some((part) => !Number.isSafeInteger(Number(part))))
+    return false;
+  const prerelease = value.split("+")[0]?.split("-").slice(1).join("-");
+  return !prerelease || prerelease.split(".").every((part) => !/^\d+$/.test(part) || part === "0" || !part.startsWith("0"));
+}, "version must use finite canonical semver numbers");
+var limitsSchema = z3.object({
+  maxTargets: positive.default(16),
+  maxManifestBytes: positive.default(256 * 1024),
+  maxAssetBytes: positive.default(256 * 1024 * 1024),
+  maxCompressedBytes: positive.default(256 * 1024 * 1024),
+  maxDirectoryEntries: positive.default(128),
+  maxStoredVersions: positive.min(3).default(16),
+  lockTimeoutMs: timer.default(1e4),
+  timeoutMs: timer.default(600000)
+});
+var dataSchema = CliBuildManifestSchema.pick({
+  name: true,
+  version: true,
+  commit: true
+}).extend({
+  name: component,
+  version: PublicationVersionSchema,
+  commit: z3.string().min(1).max(128),
+  storageRoot: z3.string().min(1).refine(isAbsolute, "storageRoot must be absolute"),
+  baseUrl: z3.url().refine((raw) => {
+    const url = new URL(raw);
+    return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash;
+  }, "baseUrl must be an http(s) directory URL without credentials/query/fragment"),
+  targets: z3.array(PublicationTargetSchema).min(1),
+  limits: limitsSchema.prefault({}),
+  retention: positive.min(2).default(2)
+});
+var phaseSchema = z3.enum(["prepare", "build", "commit", "promote"]);
+function publicationData(options) {
+  const data = dataSchema.parse(options);
+  if (data.targets.length > data.limits.maxTargets)
+    throw new RangeError("CLI publication target cap exceeded");
+  if (data.targets.length + 1 > data.limits.maxDirectoryEntries)
+    throw new RangeError("CLI version layout exceeds directory entry cap");
+  if (data.retention >= data.limits.maxStoredVersions)
+    throw new RangeError("retention must leave one recovery slot below maxStoredVersions");
+  const names = data.targets.map((target) => assetFilename(data.name, target));
+  if (new Set(names).size !== names.length)
+    throw new TypeError("CLI publication targets must be unique");
+  if (typeof options.admit !== "function" || typeof options.build !== "function")
+    throw new TypeError("CLI publication needs build and admit callbacks");
+  return data;
+}
+function assetFilename(name, target) {
+  return `${name}-${target.platform}-${target.arch}.gz`;
+}
+function assetUrl(baseUrl, version, filename) {
+  return new URL(`${encodeURIComponent(version)}/${encodeURIComponent(filename)}`, `${baseUrl.replace(/\/+$/, "")}/`).toString();
+}
+
+// src/tools/cli/publication-storage.ts
+import { lstat, mkdir, open, opendir, realpath, rm } from "node:fs/promises";
+import { join as join2, resolve } from "node:path";
+import { z as z4 } from "zod";
+async function directoryGeneration(path) {
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink())
+    throw new Error("CLI storage directory must not be a link or non-directory");
+  return { dev: info.dev, ino: info.ino };
+}
+async function assertDirectory(path, generation) {
+  const current = await directoryGeneration(path);
+  if (current.dev !== generation.dev || current.ino !== generation.ino)
+    throw new Error("CLI storage directory generation changed");
+}
+async function bindPublicationStorage(data, signal) {
+  signal.throwIfAborted();
+  if (process.platform === "win32")
+    throw new Error("CLI publication needs directory durability, unsupported on Windows");
+  const requested = resolve(data.storageRoot);
+  try {
+    await mkdir(requested, { mode: 448 });
+  } catch (error) {
+    if (!(error instanceof Error && ("code" in error) && error.code === "EEXIST"))
+      throw error;
   }
-  if (pending !== "")
-    yield pending.endsWith("\r") ? pending.slice(0, -1) : pending;
+  await directoryGeneration(requested);
+  const root = await realpath(requested);
+  const generation = await directoryGeneration(root);
+  const files = await createManagedFileBoundary2({
+    root,
+    maxReadBytes: Math.max(data.limits.maxManifestBytes, data.limits.maxCompressedBytes),
+    maxWriteBytes: Math.max(data.limits.maxManifestBytes, data.limits.maxCompressedBytes)
+  });
+  return {
+    root,
+    files,
+    async assertRoot() {
+      await assertDirectory(requested, generation);
+      await assertDirectory(root, generation);
+    }
+  };
 }
-function parseLine(line) {
-  let parsed;
+async function directoryNames(path, maxEntries, signal) {
+  const names = [];
+  const directory = await opendir(path);
   try {
-    parsed = safeJsonParse(line);
-  } catch {
-    return { ok: false, answer: malformed("the line is not JSON") };
+    for await (const entry of directory) {
+      signal.throwIfAborted();
+      names.push(entry.name);
+      if (names.length > maxEntries)
+        throw new RangeError("CLI publication directory entry cap exceeded");
+    }
+  } finally {
+    await directory.close().catch(() => {
+      return;
+    });
   }
-  const result = LineSchema.safeParse(parsed);
-  if (!result.success) {
-    const id = isRecord(parsed) && typeof parsed.id === "string" ? parsed.id : undefined;
+  return names.sort();
+}
+async function readPublicationManifest(storage, path, data, signal) {
+  try {
+    const read = await storage.files.read(path, {
+      rejectSymlinks: true,
+      singleLink: true,
+      stable: true,
+      maxBytes: data.limits.maxManifestBytes,
+      signal
+    });
     return {
-      ok: false,
-      answer: {
-        ...malformed("the line needs `id` and `command`"),
-        ...id !== undefined && { id }
-      }
+      manifest: CliBuildManifestSchema.parse(JSON.parse(new TextDecoder().decode(read.bytes))),
+      bytes: read.bytes
     };
+  } catch (error) {
+    if (error instanceof ManagedFileError2 && error.code === "FILE_NOT_FOUND")
+      return;
+    throw error;
   }
-  return { ok: true, value: result.data };
 }
-function malformed(message) {
-  return {
-    id: "",
-    ok: false,
-    exitCode: 2,
-    error: { code: "BAD_REQUEST", message }
-  };
+async function verifyPublicationVersion(storage, record, data, signal, exactTargets) {
+  const { manifest } = record;
+  PublicationVersionSchema.parse(manifest.version);
+  if (manifest.name !== data.name || manifest.assets.length === 0 || manifest.assets.length > data.limits.maxTargets)
+    throw new Error("CLI version identity or target count is invalid");
+  const directory = join2(storage.root, manifest.version);
+  const generation = await directoryGeneration(directory);
+  const expected = manifest.assets.map((asset) => assetFilename(data.name, asset));
+  if (new Set(expected).size !== expected.length || manifest.assets.some((asset) => !PublicationTargetSchema.safeParse(asset).success || asset.compression !== "gzip"))
+    throw new Error("CLI version targets or compression do not match publisher layout");
+  if (exactTargets) {
+    const requested = data.targets.map((target) => assetFilename(data.name, target)).sort();
+    if (JSON.stringify(requested) !== JSON.stringify([...expected].sort()))
+      throw new Error("CLI publication target set differs from existing version");
+  }
+  const names = await directoryNames(directory, data.limits.maxDirectoryEntries, signal);
+  if (JSON.stringify(names) !== JSON.stringify([...expected, "manifest.json"].sort()))
+    throw new Error("CLI version has unknown or missing files");
+  const saved = await readPublicationManifest(storage, `${manifest.version}/manifest.json`, data, signal);
+  if (!saved || !Buffer.from(saved.bytes).equals(Buffer.from(record.bytes)))
+    throw new Error("CLI version manifest differs from publication");
+  for (const asset of manifest.assets) {
+    const file = assetFilename(data.name, asset);
+    const url = new URL(asset.url);
+    const suffix = `/${encodeURIComponent(manifest.version)}/${encodeURIComponent(file)}`;
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || !url.pathname.endsWith(suffix) || url.search || url.hash || exactTargets && asset.url !== assetUrl(data.baseUrl, manifest.version, file))
+      throw new Error("CLI asset URL differs from owned version layout");
+    const archived = await storage.files.read(`${manifest.version}/${file}`, {
+      rejectSymlinks: true,
+      singleLink: true,
+      stable: true,
+      maxBytes: data.limits.maxCompressedBytes,
+      signal
+    });
+    await decodeCliAsset(archived.bytes, asset, data.limits.maxAssetBytes, signal);
+  }
+  await assertDirectory(directory, generation);
 }
-async function runCliStream(invoker, lines, onAnswer, hooks = {}) {
-  for await (const line of lines) {
-    if (line.trim() === "")
+async function publicationHistory(storage, data, signal) {
+  const history = [];
+  for (const name of await directoryNames(storage.root, data.limits.maxDirectoryEntries, signal)) {
+    if (!PublicationVersionSchema.safeParse(name).success)
       continue;
-    const parsed = parseLine(line);
-    if (!parsed.ok) {
-      onAnswer(parsed.answer);
+    const path = join2(storage.root, name);
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
       continue;
+    let record;
+    try {
+      record = await readPublicationManifest(storage, `${name}/manifest.json`, data, signal);
+    } catch (error) {
+      if (error instanceof SyntaxError || error instanceof z4.ZodError)
+        continue;
+      throw error;
     }
-    const { id, command, args } = parsed.value;
-    const answered = hooks.before?.(id, { command, args });
-    if (answered) {
-      onAnswer(answered);
+    if (!record || record.manifest.name !== data.name || record.manifest.version !== name)
       continue;
-    }
-    const outcome = await invoker.invoke(command, args);
-    hooks.after?.(id, { command, args }, outcome);
-    onAnswer({ id, ...outcome });
+    await verifyPublicationVersion(storage, record, data, signal, false);
+    history.push({ ...record, directory: path });
+    if (history.length > data.limits.maxStoredVersions)
+      throw new RangeError("CLI publication stored version cap exceeded");
   }
+  return history;
 }
-function defineCliStreamCommand(config) {
-  return defineCliCommand2({
-    name: config.name ?? "stream",
-    description: config.description ?? "Run one operation per JSON line of stdin, answering each",
-    input: z3.object({}),
-    handler: async (context) => {
-      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
-      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
-        context.stdout(`${JSON.stringify(answer)}
-`);
-      });
-    }
-  });
+async function syncPublicationDirectory(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
 }
-function defineCliBatchCommand(config) {
-  return defineCliCommand2({
-    name: config.name ?? "batch",
-    description: config.description ?? "Run one operation per JSON line of stdin, resuming from a checkpoint",
-    input: z3.object({
-      checkpoint: z3.string().optional()
-    }),
-    handler: async (context) => {
-      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
-      const path = context.input.checkpoint ?? config.checkpointPath ?? ".stitchkit-batch.json";
-      const checkpoint = readCliCheckpoint(path);
-      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
-        context.stdout(`${JSON.stringify(answer)}
-`);
-      }, {
-        before: (id, line) => {
-          const digest = checkpoint.digestOf(line);
-          const recorded = checkpoint.entries[id];
-          if (!recorded)
-            return;
-          if (recorded.digest !== digest) {
-            return {
-              id,
-              ok: false,
-              exitCode: 2,
-              error: {
-                code: "CONFLICT",
-                message: "this id was already run with different content — change the id or start a new checkpoint"
-              }
-            };
-          }
-          const replay = isRecord(recorded.answer) ? recorded.answer : {};
-          return { ...replay, id, replayed: true };
-        },
-        after: (id, line, outcome) => {
-          if (!outcome.ok)
-            return;
-          checkpoint.record(id, checkpoint.digestOf(line), outcome);
-          writeCliCheckpoint(path, checkpoint);
-        }
-      });
-    }
-  });
+async function removePublicationVersion(storage, version, data, signal) {
+  await storage.assertRoot();
+  await verifyPublicationVersion(storage, version, data, signal, false);
+  await rm(version.directory, { recursive: true });
+  await syncPublicationDirectory(storage.root);
 }
+
 // src/tools/cli/update.ts
-import { createHash, randomBytes } from "node:crypto";
+import { createHash as createHash2, randomBytes } from "node:crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync2, unlinkSync } from "node:fs";
-import { basename, dirname, extname, join as join2 } from "node:path";
-import { gunzipSync } from "node:zlib";
+import { basename, dirname, extname, join as join3 } from "node:path";
 var DEFAULT_CHECK_TIMEOUT_MS = 2000;
 var DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 var DEFAULT_DOWNLOAD_TIMEOUT_MS = 120000;
@@ -576,7 +827,33 @@ function compareCliVersions(left, right) {
     return 1;
   if (b.prerelease === undefined)
     return -1;
-  return a.prerelease < b.prerelease ? -1 : 1;
+  const leftParts = a.prerelease.split(".");
+  const rightParts = b.prerelease.split(".");
+  for (let index = 0;index < Math.max(leftParts.length, rightParts.length); index++) {
+    const leftPart = leftParts[index];
+    const rightPart = rightParts[index];
+    if (leftPart === rightPart)
+      continue;
+    if (leftPart === undefined)
+      return -1;
+    if (rightPart === undefined)
+      return 1;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric !== rightNumeric)
+      return leftNumeric ? -1 : 1;
+    if (leftNumeric) {
+      const leftDigits = leftPart.replace(/^0+(?=\d)/, "");
+      const rightDigits = rightPart.replace(/^0+(?=\d)/, "");
+      if (leftDigits.length !== rightDigits.length)
+        return leftDigits.length < rightDigits.length ? -1 : 1;
+      if (leftDigits === rightDigits)
+        continue;
+      return leftDigits < rightDigits ? -1 : 1;
+    }
+    return leftPart < rightPart ? -1 : 1;
+  }
+  return 0;
 }
 async function checkCliUpdate(config) {
   const now = config.now ?? Date.now();
@@ -656,14 +933,7 @@ async function applyCliUpdate(config) {
   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, { maxOutputLength: config.asset.size }) : 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 { bytes, sha256 } = await decodeCliAsset(transferred, config.asset, config.maxBytes ?? DEFAULT_MAX_ASSET_BYTES);
   if (config.verify)
     await verifyCandidate(target, bytes, config.verify, config.verifyTimeoutMs);
   const backup = config.backupPath ? keepReplacedBinary(target, config.backupPath) : undefined;
@@ -679,7 +949,7 @@ async function verifyCandidate(target, bytes, verify, timeoutMs = DEFAULT_VERIFY
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
     throw new RangeError("[stitchkit] update: verifyTimeoutMs must be a positive number");
   }
-  const candidate = join2(dirname(target), `.${basename(target)}.candidate-${randomBytes(8).toString("hex")}${extname(target)}`);
+  const candidate = join3(dirname(target), `.${basename(target)}.candidate-${randomBytes(8).toString("hex")}${extname(target)}`);
   writeFileAtomicSync2(candidate, bytes, { mode: 493 });
   const controller = new AbortController;
   let timer;
@@ -712,7 +982,7 @@ function keepReplacedBinary(target, backupPath) {
     return;
   const previous = readFileSync3(target);
   writeFileAtomicSync2(backupPath, previous, { mode: statSync2(target).mode & 511 });
-  return { path: backupPath, sha256: createHash("sha256").update(previous).digest("hex") };
+  return { path: backupPath, sha256: createHash2("sha256").update(previous).digest("hex") };
 }
 function rollbackCliUpdate(config) {
   const target = config.targetPath ?? process.execPath;
@@ -720,13 +990,363 @@ function rollbackCliUpdate(config) {
     throw new Error(`[stitchkit] rollback: no backup at ${config.backupPath}`);
   }
   const bytes = readFileSync3(config.backupPath);
-  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const sha256 = createHash2("sha256").update(bytes).digest("hex");
   if (sha256 !== config.expectedSha256) {
     throw new Error(`[stitchkit] rollback: backup digest ${sha256} does not match the expected ${config.expectedSha256} — refusing to restore it`);
   }
   writeFileAtomicSync2(target, bytes, { mode: statSync2(config.backupPath).mode & 511 });
   return { path: target, bytes: bytes.length, sha256 };
 }
+
+// src/tools/cli/publication.ts
+var resultSchema = z5.object({
+  outcome: z5.enum(["published", "existing"]),
+  manifest: CliBuildManifestSchema
+});
+function trustPublication(manifest, options) {
+  const verdict = verifyCliManifest(manifest, manifest.signature, options.trust);
+  if (!cliSignatureAccepted(verdict))
+    throw new Error(`CLI publication manifest signature ${verdict}`);
+  if (options.signing && !manifest.signature)
+    throw new Error("CLI publication requires a signed manifest");
+}
+function sameManifest(left, right) {
+  return left === undefined ? right === undefined : right !== undefined && Buffer.from(left.bytes).equals(Buffer.from(right.bytes));
+}
+async function admission(options, data, phase, signal) {
+  signal.throwIfAborted();
+  await waitForPublication(Promise.resolve().then(() => {
+    signal.throwIfAborted();
+    return options.admit({
+      phase,
+      identity: Object.freeze({
+        name: data.name,
+        version: data.version,
+        commit: data.commit
+      }),
+      signal
+    });
+  }), signal);
+}
+async function unchanged(storage, prior, data, lock, signal) {
+  signal.throwIfAborted();
+  await lock.assertHeld();
+  await storage.assertRoot();
+  if (!sameManifest(prior, await readPublicationManifest(storage, "manifest.json", data, signal)))
+    throw new Error("CLI public manifest changed during publication");
+}
+function newest(versions) {
+  return [...versions].sort((a, b) => compareCliVersions(b.manifest.version, a.manifest.version) ?? 0);
+}
+async function retainVersions(storage, history, keep, count, data, lock, signal) {
+  const retained = newest(history).filter((item) => !keep.has(item.manifest.version));
+  const spare = Math.max(0, count - keep.size);
+  for (const version of retained.slice(spare)) {
+    await lock.assertHeld();
+    await removePublicationVersion(storage, version, data, signal);
+  }
+}
+async function promote(storage, record, prior, data, options, lock, signal) {
+  await admission(options, data, "promote", signal);
+  await verifyPublicationVersion(storage, record, data, signal, true);
+  trustPublication(record.manifest, options);
+  await unchanged(storage, prior, data, lock, signal);
+  const names = await directoryNames(storage.root, data.limits.maxDirectoryEntries, signal);
+  if (names.length + 1 > data.limits.maxDirectoryEntries)
+    throw new RangeError("CLI publication directory entry cap leaves no pointer space");
+  signal.throwIfAborted();
+  await writeFileAtomic2(join4(storage.root, "manifest.json"), record.bytes, {
+    mode: 420,
+    durability: "directory"
+  });
+  const current = await readPublicationManifest(storage, "manifest.json", data, signal);
+  if (!sameManifest(record, current))
+    throw new Error("CLI public manifest readback differs after promotion");
+}
+async function buildVersion(storage, data, options, lock, prior, signal) {
+  const names = await directoryNames(storage.root, data.limits.maxDirectoryEntries, signal);
+  if (names.length + 2 > data.limits.maxDirectoryEntries)
+    throw new RangeError("CLI publication directory entry cap leaves no commit space");
+  const staged = await mkdtemp(join4(storage.root, ".publish-"));
+  const generation = await directoryGeneration(staged);
+  let committed = false;
+  try {
+    const files = await createManagedFileBoundary2({
+      root: staged,
+      maxWriteBytes: Math.max(data.limits.maxCompressedBytes, data.limits.maxManifestBytes)
+    });
+    const stamp = Object.freeze({
+      version: data.version,
+      commit: data.commit,
+      builtAt: new Date().toISOString()
+    });
+    const assets = [];
+    for (const target of data.targets) {
+      await admission(options, data, "build", signal);
+      signal.throwIfAborted();
+      const source = await waitForPublication(Promise.resolve().then(() => {
+        signal.throwIfAborted();
+        return options.build({ target: Object.freeze({ ...target }), stamp, signal });
+      }), signal);
+      if (!(source instanceof Uint8Array) && !(source instanceof ReadableStream))
+        throw new TypeError("CLI builder must return bytes or a stream");
+      const bytes = await collectCliBytes(source, data.limits.maxAssetBytes, signal);
+      if (bytes.byteLength === 0)
+        throw new Error("CLI asset must not be empty");
+      const archived = await gzipCliAsset(bytes, data.limits.maxCompressedBytes, signal);
+      await lock.assertHeld();
+      await storage.assertRoot();
+      await assertDirectory(staged, generation);
+      const file = assetFilename(data.name, target);
+      await files.write(file, archived, { durable: true, signal });
+      assets.push({
+        ...target,
+        compression: "gzip",
+        size: bytes.byteLength,
+        sha256: createHash3("sha256").update(bytes).digest("hex"),
+        url: assetUrl(data.baseUrl, data.version, file)
+      });
+    }
+    const manifest = CliBuildManifestSchema.parse({ name: data.name, ...stamp, assets });
+    if (options.signing)
+      manifest.signature = signCliManifest(manifest, options.signing);
+    trustPublication(manifest, options);
+    const bytes = new TextEncoder().encode(`${JSON.stringify(manifest)}
+`);
+    if (bytes.byteLength > data.limits.maxManifestBytes)
+      throw new RangeError("CLI publication manifest byte cap exceeded");
+    await assertDirectory(staged, generation);
+    await files.write("manifest.json", bytes, {
+      durable: true,
+      maxBytes: data.limits.maxManifestBytes,
+      signal
+    });
+    await admission(options, data, "commit", signal);
+    await unchanged(storage, prior, data, lock, signal);
+    await assertDirectory(staged, generation);
+    try {
+      await lstat2(join4(storage.root, data.version));
+      throw new Error("CLI version directory already exists");
+    } catch (error) {
+      if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
+        throw error;
+    }
+    signal.throwIfAborted();
+    await rename(staged, join4(storage.root, data.version));
+    committed = true;
+    await syncPublicationDirectory(storage.root);
+    return { manifest, bytes };
+  } catch (error) {
+    if (!committed) {
+      try {
+        await storage.assertRoot();
+        await assertDirectory(staged, generation);
+        await rm2(staged, { recursive: true });
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "CLI publication failed and safe staging cleanup was refused");
+      }
+    }
+    if (committed && !(error instanceof AtomicFilePublicationError2))
+      throw new Error("CLI version committed; publication outcome must be checked", {
+        cause: error
+      });
+    throw error;
+  }
+}
+async function publishLocked(storage, data, options, lock, signal) {
+  await lock.assertHeld();
+  await admission(options, data, "prepare", signal);
+  const prior = await readPublicationManifest(storage, "manifest.json", data, signal);
+  if (prior && prior.manifest.name !== data.name)
+    throw new Error("CLI public manifest belongs to another CLI");
+  const history = await publicationHistory(storage, data, signal);
+  const candidate = {
+    name: data.name,
+    version: data.version,
+    commit: data.commit,
+    builtAt: new Date().toISOString(),
+    assets: []
+  };
+  assertCliPublishable([...prior ? [prior.manifest] : [], ...history.map((item) => item.manifest)], candidate);
+  if (prior) {
+    await verifyPublicationVersion(storage, prior, data, signal, prior.manifest.version === data.version);
+    trustPublication(prior.manifest, options);
+    const order = compareCliVersions(data.version, prior.manifest.version) ?? -1;
+    if (order < 0 || order === 0 && data.version !== prior.manifest.version)
+      throw new Error("CLI publication downgrade or non-advancing version refused");
+    if (prior.manifest.version === data.version) {
+      await admission(options, data, "promote", signal);
+      await verifyPublicationVersion(storage, prior, data, signal, true);
+      await unchanged(storage, prior, data, lock, signal);
+      return { outcome: "existing", manifest: prior.manifest };
+    }
+  }
+  let record = history.find((item) => item.manifest.version === data.version);
+  if (record) {
+    await verifyPublicationVersion(storage, record, data, signal, true);
+    trustPublication(record.manifest, options);
+  } else {
+    const protect = new Set(prior ? [prior.manifest.version] : []);
+    const previous = newest(history).find((item) => prior && (compareCliVersions(item.manifest.version, prior.manifest.version) ?? 0) < 0);
+    if (previous)
+      protect.add(previous.manifest.version);
+    await retainVersions(storage, history, protect, data.limits.maxStoredVersions - 1, data, lock, signal);
+    record = {
+      ...await buildVersion(storage, data, options, lock, prior, signal),
+      directory: join4(storage.root, data.version)
+    };
+  }
+  try {
+    await promote(storage, record, prior, data, options, lock, signal);
+    const updated = await publicationHistory(storage, data, signal);
+    await retainVersions(storage, updated, new Set([data.version, ...prior ? [prior.manifest.version] : []]), data.retention, data, lock, signal);
+  } catch (error) {
+    if (error instanceof AtomicFilePublicationError2)
+      throw error;
+    throw new Error("CLI version committed; publication outcome must be checked", {
+      cause: error
+    });
+  }
+  return { outcome: "published", manifest: record.manifest };
+}
+async function publishCli(options) {
+  const data = publicationData(options);
+  return withPublicationDeadline(data.limits.timeoutMs, options.signal, async (signal) => {
+    const storage = await bindPublicationStorage(data, signal);
+    return withExclusiveLock2(join4(storage.root, ".publication.lock"), (lock) => publishLocked(storage, data, options, lock, signal), { timeoutMs: data.limits.lockTimeoutMs, signal, label: "CLI publication" });
+  });
+}
+// src/tools/cli/stream.ts
+import { z as z6 } from "zod";
+var LineSchema = z6.object({
+  id: z6.string().min(1),
+  command: z6.string().min(1),
+  args: z6.record(z6.string(), z6.unknown()).default({})
+});
+async function* readStdinLines(source = process.stdin) {
+  const decoder = new TextDecoder;
+  let pending = "";
+  for await (const chunk of source) {
+    pending += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    let newline = pending.indexOf(`
+`);
+    while (newline !== -1) {
+      const line = pending.slice(0, newline);
+      pending = pending.slice(newline + 1);
+      yield line.endsWith("\r") ? line.slice(0, -1) : line;
+      newline = pending.indexOf(`
+`);
+    }
+  }
+  if (pending !== "")
+    yield pending.endsWith("\r") ? pending.slice(0, -1) : pending;
+}
+function parseLine(line) {
+  let parsed;
+  try {
+    parsed = safeJsonParse(line);
+  } catch {
+    return { ok: false, answer: malformed("the line is not JSON") };
+  }
+  const result = LineSchema.safeParse(parsed);
+  if (!result.success) {
+    const id = isRecord(parsed) && typeof parsed.id === "string" ? parsed.id : undefined;
+    return {
+      ok: false,
+      answer: {
+        ...malformed("the line needs `id` and `command`"),
+        ...id !== undefined && { id }
+      }
+    };
+  }
+  return { ok: true, value: result.data };
+}
+function malformed(message) {
+  return {
+    id: "",
+    ok: false,
+    exitCode: 2,
+    error: { code: "BAD_REQUEST", message }
+  };
+}
+async function runCliStream(invoker, lines, onAnswer, hooks = {}) {
+  for await (const line of lines) {
+    if (line.trim() === "")
+      continue;
+    const parsed = parseLine(line);
+    if (!parsed.ok) {
+      onAnswer(parsed.answer);
+      continue;
+    }
+    const { id, command, args } = parsed.value;
+    const answered = hooks.before?.(id, { command, args });
+    if (answered) {
+      onAnswer(answered);
+      continue;
+    }
+    const outcome = await invoker.invoke(command, args);
+    hooks.after?.(id, { command, args }, outcome);
+    onAnswer({ id, ...outcome });
+  }
+}
+function defineCliStreamCommand(config) {
+  return defineCliCommand2({
+    name: config.name ?? "stream",
+    description: config.description ?? "Run one operation per JSON line of stdin, answering each",
+    input: z6.object({}),
+    handler: async (context) => {
+      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
+      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
+        context.stdout(`${JSON.stringify(answer)}
+`);
+      });
+    }
+  });
+}
+function defineCliBatchCommand(config) {
+  return defineCliCommand2({
+    name: config.name ?? "batch",
+    description: config.description ?? "Run one operation per JSON line of stdin, resuming from a checkpoint",
+    input: z6.object({
+      checkpoint: z6.string().optional()
+    }),
+    handler: async (context) => {
+      const invoker = typeof config.invoker === "function" ? await config.invoker() : config.invoker;
+      const path = context.input.checkpoint ?? config.checkpointPath ?? ".stitchkit-batch.json";
+      const checkpoint = readCliCheckpoint(path);
+      await runCliStream(invoker, (config.readLines ?? readStdinLines)(), (answer) => {
+        context.stdout(`${JSON.stringify(answer)}
+`);
+      }, {
+        before: (id, line) => {
+          const digest = checkpoint.digestOf(line);
+          const recorded = checkpoint.entries[id];
+          if (!recorded)
+            return;
+          if (recorded.digest !== digest) {
+            return {
+              id,
+              ok: false,
+              exitCode: 2,
+              error: {
+                code: "CONFLICT",
+                message: "this id was already run with different content — change the id or start a new checkpoint"
+              }
+            };
+          }
+          const replay = isRecord(recorded.answer) ? recorded.answer : {};
+          return { ...replay, id, replayed: true };
+        },
+        after: (id, line, outcome) => {
+          if (!outcome.ok)
+            return;
+          checkpoint.record(id, checkpoint.digestOf(line), outcome);
+          writeCliCheckpoint(path, checkpoint);
+        }
+      });
+    }
+  });
+}
 export {
   CliArgumentError2 as CliArgumentError,
   CliBuildAssetSchema,
@@ -757,6 +1377,7 @@ export {
   formatCliBuildStamp,
   parseCliArgs2 as parseCliArgs,
   pollUntilDone2 as pollUntilDone,
+  publishCli,
   readCliCheckpoint,
   renderCliInstaller,
   renderCliView2 as renderCliView,