@silvermoon-work/task-builder-cli 0.1.0-canary-261109-3 → 0.1.0-canary-261111-1

package/README.md

@@ -1,150 +1,196 @@
 # @silvermoon-work/task-builder-cli
 
-Independent Commander 14 CLI and reusable command runner for
-[@silvermoon-work/task-builder](../task-builder/README.md).
-The core owns read-only tree transformations; this package owns argument parsing,
-help, version, output rendering, host paths, file writes and executable signals.
-It does not implement bundling or CAR encoding itself.
-
-The preceding release was `0.1.0-canary-261109-1`, depending on
-`task-builder@0.1.0-canary-261109-2`. CLI version `0.1.0-canary-261109-3`
-requires core `0.1.0-canary-261109-3` and generates the migrated SDK template.
-The older core package's binary is not
-this Commander CLI. See the
-[published-package verification guide](../../docs/end-to-end-verification.md).
+Task production CLI and reusable command runner. Node >=22.13 is required.
+This document describes the redesigned source interface; registry acceptance
+requires separately publishing compatible Builder and CLI packages.
 
 ## Commands
 
 ```text
-task-builder init <new-directory> [--name <name>] [--cli-version <specifier>] [--builder-version <specifier>]
-task-builder build <task.build.yaml> [--root <directory>] [--trusted-contract]
-task-builder car <bundle-directory> <output.car> [--cid-file <output.cid>]
-task-builder check <bundle.car> [--expected-cid <cid>]
-```
-
-The original `task-builder <task.build.yaml> [build options]` shorthand is
-Commander's default build command, not a second hand-written parser.
-
-```text
+task-builder init <directory> [--package-name <name>] [--task-name <name>]
+task-builder build [build-file] [--out-dir <directory>] [--no-car]
+task-builder car <task-file> [--output <file>]
 task-builder --help
 task-builder build --help
-task-builder help car
 task-builder --version
-task-builder check bundle.car --format text
-task-builder --format json check bundle.car
 ```
 
-Commander provides required arguments, allowed choices, option parsing and help.
-Duplicate options are rejected through Commander option events.
-`--format json|text` works before or after a subcommand. Results/errors default
-to JSON for compatibility with the original CLI; `--format text` selects
-human-readable summaries. Help/version remain text.
-
-Success result shapes are unchanged:
-
-| Command | JSON result |
-| --- | --- |
-| init | `{ directory, files, nextSteps }` |
-| build | `{ directory, files }` |
-| car | `{ car, cid, cidFile? }` |
-| check | `{ cid, declaration, bytes, files }` |
-
-Failures go to stderr, never success-shaped stdout. JSON errors use
-`{ error: { code, message } }`. Exit codes are 0 for success/help/version,
-2 for Commander usage errors, 1 for operation errors, 130 for SIGINT and
-143 for SIGTERM. There is no automatic install, overwrite, upload, pin or publish.
+Only these three commands exist. No arguments prints help, without building.
+There is no `help` command, implicit build, `check`, `--root`, `--format`,
+`--trusted-contract`, dependency-version selection, CID sidecar, or business
+field override. Unknown, extra and duplicate options/arguments fail.
+No command prompts, reads stdin, installs dependencies, uploads or publishes.
+TTY and redirected invocations have the same behavior.
+
+Successful business commands write one newline-terminated
+`{ "ok": true, "data": ... }` object to stdout. Failures write one
+`{ "ok": false, "error": { "code": "...", "message": "..." } }` object to stdout;
+`error` has exactly those two nonempty fields. Verified partial delivery can
+also appear as `data` in that same failure object.
+Stderr is reserved for CLI diagnostics and is empty by default. Help and root
+version are text on stdout. Exit status is 0 for success/help/version, 1 for
+ordinary failures. Confirmed cancellation and cleanup use 130 (SIGINT) or 143
+(SIGTERM); an uncertain delivery or cleanup always uses 1.
 
 ## Init composition
 
-Core init returns a package-manager-neutral private project with Task sources,
-JSON contract, shared text Schema, greeting resource and a dependency on
-[@silvermoon-work/task-sdk](../task-sdk/README.md).
-The CLI adds:
-
-- build/CAR/check npm scripts referencing the `task-builder` binary;
-- direct dev dependencies on **both** CLI and core;
-- the pnpm version, scoped esbuild approval and release-age exceptions.
-
-The current template uses SDK `0.1.0-canary-261109-2`.
-The preceding CLI/core releases still generate the old SDK template; use
-CLI version 3 with core version 3 for this default.
-`createCliTaskProject({ sdkVersion: "file:task-sdk.tgz" })` can still
-select a local SDK tarball for development. SDK/protocol release-age exceptions
-now use `@silvermoon-work` names.
-
-Default CLI/core versions come from the installed package metadata, not a moving
-`canary` tag. `--cli-version` selects the CLI dependency. An explicit
-`--builder-version` also adds a scoped pnpm override so a local core tarball is
-used by the CLI's transitive dependency as well. This is useful before publication
-and avoids accidentally mixing the new CLI with the old published core.
-The override and scoped release-age exceptions live in `pnpm-workspace.yaml`,
-not the obsolete `package.json#pnpm` configuration. Exemptions use selected
-package names, so local `file:` specs are not incorrectly treated as npm versions.
-
-Init only writes into a new directory whose parent exists and is canonical.
-It does not merge with an existing project or modify an ancestor package.
-`--name` defaults to `task-project`. Additional Task template settings are
-available through the library's `createCliTaskProject` options, not new CLI flags.
-
-## Reusable runner
-
-```ts
-import { runTaskBuilderCli } from "@silvermoon-work/task-builder-cli";
+The target must not exist and its parent must exist. Package name defaults to
+the target directory basename; invalid names require `--package-name` rather
+than silent sanitization. Task name defaults to the package's unscoped name.
+The editable template includes:
+
+- `package.json`, `.gitignore`, `pnpm-workspace.yaml`;
+- `task.build.yaml`, explicit `src/main.ts` and `src/helper.ts`;
+- a TypeBox `src/contract.ts` with a shared Schema and `assets/greeting.txt`;
+- Node minimum 22.13.0, `assets/**` → `resources/`, no binary rules;
+- build, standalone CAR and explicit `clean` scripts; no dependency installation.
+
+The contract exports `Input` and `Result` via `Static<typeof ...>`; the Worker
+imports those types with `import type` rather than repeating the data shapes.
+The shared nonempty text reference retains its string type, and the runtime
+Schemas still reject extra properties and enforce integer byte/chunk counts
+with minima 0/1. Messages remain disabled. The generated package explicitly
+depends on `@sinclair/typebox@0.34.52`, not Builder's transitive dependencies.
+Build evaluates this TS contract as trusted code; esbuild transpiles but does
+not typecheck it. JSON contracts remain supported when selected in the build
+description.
+
+Init fixes `outDirectory` to `dist/<derived-name>` using the final package name,
+not the Task name: `echo-task` → `dist/echo-task`, `@acme/echo-task` →
+`dist/acme-echo-task`. Only the leading `@` is removed and the scope separator
+`/` becomes `-`. Invalid npm names and unsafe derived paths (such as Windows
+device names or trailing dots) are rejected, never silently sanitized.
+Later package-name changes do not rewrite the build description or scripts.
+
+`pnpm build` writes that module and its sibling `dist/<derived-name>.car`.
+`pnpm car` reads `dist/<derived-name>/task.yaml` and targets the same CAR,
+refusing to overwrite an existing archive, including one produced by build.
+Use `pnpm build --no-car` before `pnpm car` when no archive already exists.
+`pnpm clean` runs `rimraf dist`, deleting all modules and CARs under `dist`;
+rimraf 6.1.4 is a generated devDependency compatible with Node >=22.13.0.
+Build never runs clean automatically: validation still precedes delivery,
+and stale unselected files remain until explicitly cleaned.
+
+CLI and Builder dependency versions come from their actual installed metadata;
+the SDK version comes from that Builder release's template. They need not
+match. No remote tag lookup or version override is performed.
+The pnpm template allows only esbuild's postinstall (`allowBuilds.esbuild: true`);
+no other dependency build scripts are approved. Do not omit optional dependencies.
+
+## Build and delivery
+
+`build-file` defaults to `task.build.yaml`. Source, contract, Task identity,
+runtime and resource rules come only from that file, which is not rewritten.
+Output precedence is `--out-dir` > `outDirectory` > description-directory `dist`.
+CLI paths are relative to cwd; description paths are relative to the description.
+Within pnpm workspaces, the existing workspace tree supplies installed
+dependencies; imports never fall back to the CLI's dependencies.
+
+The default CAR is the module directory's sibling `<directory-basename>.car`.
+Both the module and CAR remain after success. `--no-car` does not update or
+delete an older CAR: `data.car: null` describes this invocation only.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "module": {
+      "directory": "<absolute module directory>",
+      "declaration": "<absolute task.yaml>",
+      "files": ["task.yaml", "worker.cjs", "schemas/input.json", "schemas/result.json", "schemas/message.json"]
+    },
+    "cid": "<verified module CID>",
+    "car": { "path": "<absolute CAR>" }
+  }
+}
+```
 
-const exitCode = await runTaskBuilderCli(
-  ["build", "task.build.yaml", "--format", "json"],
-  {
-    cwd: projectDirectory,
-    signal,
-    stdout: { write: (text) => output.write(text) },
-    stderr: { write: (text) => diagnostics.write(text) },
-  },
-);
+Files list exactly the current declaration's selection, including any selected
+resources/shared Schemas, using protocol `/` paths. Other paths are host
+absolute paths. Old unselected files stay on disk but are excluded from
+validation and CAR. No output directory is recursively cleared.
+
+All generated bytes are staged and validated before replacing any outputs.
+Each file replacement uses complete sibling bytes rather than truncating the
+old file. Delivered module bytes and CAR bytes are validated again.
+A failure during module updates can leave some replaced files and reports
+`DELIVERY_UNCERTAIN`, not a claimed rollback or a trusted module. A valid new
+module survives CAR failure, reported with its module/CID, `car: null` and an
+explanation that any unreplaced old CAR is not a new delivery.
+Staging belongs only to the invocation and is released on completion/failure.
+Input/output overlap, observable destination races and linked output paths are
+rejected. Filesystem checks are not an OS sandbox against a malicious author.
+
+JS/TS contracts execute automatically as trusted Node code, in a short-lived
+process with captured standard streams and a 30-second internal evaluation
+budget. Console calls and direct stdout/stderr writes, including caught or
+deferred attempts and evaluating dependencies, fail with
+`CONTRACT_OUTPUT_FORBIDDEN`; output is never forwarded or silently accepted.
+JSON contracts do not execute. This is **not a security sandbox**; other host
+side effects remain possible. Task runtime logging is unaffected.
+
+## Standalone CAR
+
+`car` accepts an existing `task.yaml` file, never a directory. Only its declared
+files are read and validated; unselected notes, stale files and archives are
+not read. It never reads the build description, compiles, runs contracts or
+installs packages. Links cannot escape the module tree, and reads detect
+observable input changes.
+The input module directory and all its ancestors must be canonical, without
+symlinks or Windows junctions. Linked module/ancestor aliases are rejected
+before choosing or writing an output, so they cannot disguise an internal CAR
+destination as an external one.
+
+The default destination uses the same sibling naming rule as build; `--output`
+is cwd-relative and must be outside the input module. Existing destinations
+are always refused, including during competing creation.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "car": "<absolute CAR>",
+    "cid": "<verified CID>",
+    "declaration": "<absolute input task.yaml>",
+    "files": ["<complete declared selection>"]
+  }
+}
 ```
 
-Each invocation has its own Commander instance and returns an exit code.
-Importing the library does not run a command, change `process.exitCode`, install
-signal handlers or start a service. Programmatic abort returns 130; only `bin.js`
-owns process SIGINT/SIGTERM and their corresponding executable exit codes.
-`createCliTaskProject(options)` can be used independently to decorate a template
-without writing it to disk or installing packages.
+Use the compiler-free `@silvermoon-work/task-builder/car` subpath for standalone
+CAR inspection or the Engine CLI for actual consumption, not a removed
+`task-builder check` command.
 
-## Node adapters
+## Reusable runner and adapters
 
 ```ts
-import { buildTaskBundle } from "@silvermoon-work/task-builder";
-import {
-  directoryTree,
-  writeDirectory,
-  writeStreamFile,
-} from "@silvermoon-work/task-builder-cli/node";
-
-const input = await directoryTree(projectDirectory);
-const output = await buildTaskBundle(input, options);
-await writeDirectory(output, newOutputDirectory);
+import { runTaskBuilderCli } from "@silvermoon-work/task-builder-cli";
+
+const exitCode = await runTaskBuilderCli(["build", "task.build.yaml"], {
+  cwd: projectDirectory,
+  signal,
+  stdout: { write: (text) => output.write(text) },
+});
 ```
 
-The directory adapter is a live view, not an atomic snapshot or OS sandbox.
-Confined links support pnpm's virtual store; escaping links and special files
-are rejected. Writes use backpressure, cancellation and exclusive file creation.
-Only newly created files/directories are removed on failure; existing output
-is never overwritten. CAR and CID paths cannot be inside the Bundle directory
-or equal each other. A failed CID sidecar write removes the newly created CAR.
+The runner does not exit the host, read stdin or install signal handlers.
+Programmatic cancellation defaults to 130; executable signal ownership belongs
+to `bin.js`. `createCliTaskProject({ name, taskName })` creates a template without
+writing files. `./node` exports `directoryTree`, `writeDirectory` and
+`writeStreamFile`: these lower-level writers retain exclusive-create semantics.
+The CLI's build delivery layer implements replacement separately.
 
-## Repository development
+## Development and distribution
 
 ```text
 pnpm --filter @silvermoon-work/task-builder-cli... build
-node packages/task-builder-cli/dist/bin.js --help
-node packages/task-builder-cli/dist/bin.js build packages/task-builder/examples/echo/task.build.yaml
-pnpm --filter @silvermoon-work/task-builder-cli test
+pnpm --filter @silvermoon-work/task-builder --filter @silvermoon-work/task-builder-cli test
 pnpm check
 ```
 
-The example build fails explicitly if its output already exists.
-CLI and core are separately mapped publishable libraries. Publish the exact
-core dependency before tagging this CLI; this package needs its own npm package
-identity and Trusted Publisher configuration. No release is performed by build.
-The modified core must receive a new version first: do not publish this CLI
-against the old `task-builder@0.1.0-canary-261109-1`, which lacks `./tree` and
-the current init/CAR APIs.
+Published packages contain precompiled `dist`, including the contract evaluation
+process entrypoint. CLI bin is `dist/bin.js`; consumers do not compile the CLI.
+Builder and CLI are separate releases. Required internal versions must already
+exist in the configured registry; never auto-publish dependencies. The
+[consumer guide](../../docs/end-to-end-verification.md) distinguishes local
+development from an actual registry-installed Canary verification.

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { runTaskBuilderCli } from "./index.js";
 const controller = new AbortController();
-let interrupted;
+let interrupted = 130;
 const interrupt = () => {
     interrupted = 130;
     controller.abort(new Error("Task builder interrupted by SIGINT."));
@@ -13,8 +13,10 @@ const terminate = () => {
 process.once("SIGINT", interrupt);
 process.once("SIGTERM", terminate);
 try {
-    const code = await runTaskBuilderCli(process.argv.slice(2), { signal: controller.signal });
-    process.exitCode = interrupted ?? code;
+    process.exitCode = await runTaskBuilderCli(process.argv.slice(2), {
+        signal: controller.signal,
+        signalExitCode: () => interrupted,
+    });
 }
 finally {
     process.removeListener("SIGINT", interrupt);

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;AACzC,IAAI,WAA+B,CAAC;AACpC,MAAM,SAAS,GAAG,GAAG,EAAE;IACrB,WAAW,GAAG,GAAG,CAAC;IAClB,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AACF,MAAM,SAAS,GAAG,GAAG,EAAE;IACrB,WAAW,GAAG,GAAG,CAAC;IAClB,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC,CAAC;AACtE,CAAC,CAAC;AACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAClC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACnC,IAAI,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3F,OAAO,CAAC,QAAQ,GAAG,WAAW,IAAI,IAAI,CAAC;AACzC,CAAC;QAAS,CAAC;IACT,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC5C,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;AACzC,IAAI,WAAW,GAAc,GAAG,CAAC;AACjC,MAAM,SAAS,GAAG,GAAG,EAAE;IACrB,WAAW,GAAG,GAAG,CAAC;IAClB,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AACF,MAAM,SAAS,GAAG,GAAG,EAAE;IACrB,WAAW,GAAG,GAAG,CAAC;IAClB,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC,CAAC;AACtE,CAAC,CAAC;AACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAClC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACnC,IAAI,CAAC;IACH,OAAO,CAAC,QAAQ,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QAChE,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,cAAc,EAAE,GAAG,EAAE,CAAC,WAAW;KAClC,CAAC,CAAC;AACL,CAAC;QAAS,CAAC;IACT,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC5C,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC"}

package/dist/delivery.d.ts

@@ -0,0 +1,28 @@
+import { type ReadonlyFileTree, type ReadOptions } from "@silvermoon-work/task-builder/tree";
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly data?: object | undefined;
+    constructor(code: string, message: string, data?: object | undefined);
+}
+export declare function inside(root: string, path: string): boolean;
+export declare function defaultCar(directory: string): string;
+export declare function info(path: string): Promise<import("fs").BigIntStats | undefined>;
+/** Reject links in every existing component, including links inside output directories. */
+export declare function safePath(path: string): Promise<void>;
+export declare function selectedModule(directory: string, options?: ReadOptions): Promise<{
+    tree: ReadonlyFileTree;
+    files: string[];
+}>;
+export declare function verifyModule(directory: string, options?: ReadOptions): Promise<{
+    archive: import("@silvermoon-work/task-builder/car").EncodedTaskBundleCar;
+    tree: ReadonlyFileTree;
+    files: string[];
+}>;
+/** Complete and validate a sibling before atomic replacement; never truncate an old target. */
+export declare function deliverFile(stream: ReadableStream<Uint8Array>, destination: string, options: ReadOptions & {
+    replace: boolean;
+    cid?: string;
+}): Promise<void>;
+export declare function installModule(tree: ReadonlyFileTree, files: readonly string[], directory: string, options: ReadOptions): Promise<void>;
+export declare function cleanup(directory: string): Promise<void>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAI5C,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAFb,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA;CAIzB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,iDAOtC;AAED,2FAA2F;AAC3F,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ1D;AAED,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB;;;GAyBhF;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB;;;;GAI9E;AAED,+FAA+F;AAC/F,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,WAAW,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CA0Df;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,WAAW,iBAUrB;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9D"}

package/dist/delivery.js

@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, realpath, rename, rm, unlink } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { encodeTaskBundleCar, readTaskBundleCar } from "@silvermoon-work/task-builder/car";
+import { fileTree, readBytes, } from "@silvermoon-work/task-builder/tree";
+import { parseTaskBundleYaml, validateTaskBundle } from "@silvermoon-work/task-protocol";
+import { directoryTree, writeStreamFile } from "./node.js";
+export class CliError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+}
+export function inside(root, path) {
+    const distance = relative(root, path);
+    return (!distance || (distance !== ".." && !distance.startsWith(`..${sep}`) && !distance.includes(":")));
+}
+export function defaultCar(directory) {
+    const name = basename(directory);
+    if (!name || dirname(directory) === directory)
+        throw new CliError("INVALID_ARGUMENT", "Cannot derive a CAR name from the module directory; choose another directory or an explicit car --output.");
+    return join(dirname(directory), `${name}.car`);
+}
+export async function info(path) {
+    try {
+        return await lstat(path, { bigint: true });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** Reject links in every existing component, including links inside output directories. */
+export async function safePath(path) {
+    const parent = dirname(path);
+    if (parent !== path)
+        await safePath(parent);
+    const value = await info(path);
+    if (value?.isSymbolicLink())
+        throw new CliError("UNSAFE_PATH", "Paths must not contain symbolic links.");
+    if (value && (await realpath(path)).toLowerCase() !== resolve(path).toLowerCase())
+        throw new CliError("UNSAFE_PATH", "Paths must be canonical.");
+}
+export async function selectedModule(directory, options = {}) {
+    const input = await directoryTree(directory);
+    const bytes = await readBytes(input, "task.yaml", 65_536, options);
+    const declaration = validateTaskBundle(parseTaskBundleYaml(bytes));
+    const files = [...declaration.include];
+    const tree = fileTree(new Map(files.map((file) => [
+        file,
+        async (readOptions) => {
+            try {
+                return await input.read(file, readOptions);
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                    throw new CliError("MODULE_FILE_MISSING", `Declared module file is missing: ${file}. No CAR was delivered.`);
+                throw error;
+            }
+        },
+    ])));
+    return { tree, files };
+}
+export async function verifyModule(directory, options = {}) {
+    const selected = await selectedModule(directory, options);
+    const archive = await encodeTaskBundleCar(selected.tree, options);
+    return { ...selected, archive };
+}
+/** Complete and validate a sibling before atomic replacement; never truncate an old target. */
+export async function deliverFile(stream, destination, options) {
+    const temporary = join(dirname(destination), `.task-builder-${randomUUID()}`);
+    let owned = false;
+    let installed = false;
+    try {
+        await safePath(destination);
+        const previous = await info(destination);
+        if (previous && !options.replace)
+            throw new CliError("OUTPUT_EXISTS", "Output already exists; nothing was overwritten.");
+        if (previous && !previous.isFile())
+            throw new CliError("INVALID_ARGUMENT", "Output must be a regular file.");
+        await writeStreamFile(stream, temporary, options);
+        owned = true;
+        if (options.cid) {
+            const tree = await directoryTree(dirname(temporary));
+            const archive = await readTaskBundleCar(await tree.read(basename(temporary), options), {
+                ...options,
+                expectedCid: options.cid,
+            });
+            await archive.close();
+        }
+        options.signal?.throwIfAborted();
+        await safePath(destination);
+        const current = await info(destination);
+        if (current?.ino !== previous?.ino ||
+            current?.dev !== previous?.dev ||
+            current?.mtimeNs !== previous?.mtimeNs)
+            throw new CliError("OUTPUT_CHANGED", "Output changed during delivery; it was not replaced.");
+        if (options.replace)
+            await rename(temporary, destination);
+        else {
+            // Exclusive creation remains mandatory even if another producer races this invocation.
+            const { link } = await import("node:fs/promises");
+            await link(temporary, destination);
+            installed = true;
+            await unlink(temporary);
+        }
+        owned = false;
+    }
+    catch (error) {
+        await stream.cancel().catch(() => undefined);
+        if (owned) {
+            try {
+                await unlink(temporary);
+            }
+            catch {
+                throw new CliError("DELIVERY_UNCERTAIN", "Delivery failed and temporary-file cleanup could not be confirmed.");
+            }
+        }
+        if (installed)
+            throw new CliError("DELIVERY_UNCERTAIN", "CAR was installed but delivery cleanup reported an error; verify the destination before retrying.");
+        throw error;
+    }
+}
+export async function installModule(tree, files, directory, options) {
+    await safePath(directory);
+    await mkdir(directory, { recursive: true });
+    for (const file of files) {
+        const target = join(directory, ...file.split("/"));
+        await safePath(target);
+        await mkdir(dirname(target), { recursive: true });
+        await deliverFile(await tree.read(file, options), target, { ...options, replace: true });
+    }
+}
+export async function cleanup(directory) {
+    try {
+        await rm(directory, { recursive: true, force: true });
+    }
+    catch {
+        throw new CliError("CLEANUP_UNCERTAIN", "Operation-owned staging cleanup could not be confirmed.");
+    }
+}
+//# sourceMappingURL=delivery.js.map

package/dist/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type ReadOptions } from "@silvermoon-work/task-builder/tree";
+import type { ReadOptions } from "@silvermoon-work/task-builder/tree";
 export { createCliTaskProject, type CliTaskProjectOptions } from "./project.js";
 export interface CliWriter {
     write(text: string): void | boolean;
@@ -7,7 +7,8 @@ export interface TaskBuilderCliOptions extends ReadOptions {
     readonly cwd?: string;
     readonly stdout?: CliWriter;
     readonly stderr?: CliWriter;
+    readonly signalExitCode?: () => 130 | 143;
 }
-/** Run one invocation without starting listeners, installing signal handlers or exiting the process. */
+/** One noninteractive invocation: one JSON result, no process exit or signal listeners. */
 export declare function runTaskBuilderCli(argv: readonly string[], options?: TaskBuilderCliOptions): Promise<number>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAIlF,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;CACrC;AACD,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAuBD,wGAAwG;AACxG,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAsNjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,oCAAoC,CAAC;AAexF,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;CACrC;AACD,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,CAAC;CAC3C;AAkOD,2FAA2F;AAC3F,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAgKjB"}