@jini-ai/cli 0.1.0

package/dist/main.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * @module main
+ *
+ * The bootable `jini` binary (`package.json`'s `"bin": { "jini": "./dist/main.js" }`). Every
+ * other module in this package is a library building block — `run-command.ts`,
+ * `daemon-command.ts`, and `version-command.ts` each export a `register*Commands(registry,
+ * deps)` function ready for a pack to call, but until this file, nothing actually parsed
+ * `process.argv` and called them: `packages/cli/source-map.md`'s "Not built" note on
+ * `run-command.ts`'s original addition said as much — "no wiring of this file's commands into
+ * an actual bootable CLI entrypoint." This closes that gap.
+ *
+ * Deliberately **not** re-exported from `index.ts`. `index.ts` is this package's library
+ * barrel — importing it must be side-effect-free. This file's whole purpose is a
+ * process.argv-parsing, stdout/stderr-writing, potentially process.exit-calling side effect;
+ * bundling that into the library barrel would mean simply `import`ing `@jini-ai/cli` as a
+ * dependency could start acting like a CLI invocation. The guarded top-level block at the
+ * bottom of this file (only runs `main()` for real when this module is the actual process
+ * entrypoint, not merely imported) exists for the same reason, one level down: importing the
+ * named `main` export for testing (or for a consumer that wants to build its own bin wrapper
+ * around it) must not itself trigger a real run.
+ *
+ * **Daemon-URL resolution.** `resolveDaemonUrl` (`daemon-url.ts`) has no baked-in default —
+ * this package has never had a locked default daemon port to fall back to (see
+ * `source-map.md`: `@jini-ai/node-host`'s `createLocalNodeDaemon` binds an ephemeral port, not a
+ * fixed one). This binary wires the three real, already-built pieces together instead of
+ * inventing a new one: an explicit `--daemon-url <url>` flag (highest precedence), a
+ * `JINI_DAEMON_URL` env var, and — when `--data-dir <path>` or `--registry-path <path>` is
+ * given — `local-daemon-discovery.ts`'s `createLocalDaemonDiscovery`, the CLI-side reader for
+ * a `@jini-ai/node-host`-written on-disk daemon registry record. That discovery module's own doc
+ * already flagged it as built-but-unconsumed ("no pack has registered against
+ * `CommandRegistry` yet"); this is that consumer. If none of the three resolve, there is still
+ * no silent fallback — `resolveDaemonUrl` throws, and this file's own catch boundary (below)
+ * turns that into a clean structured-error exit instead of a raw stack trace.
+ *
+ * **Global flags are stripped before dispatch, not left for `CommandRegistry`'s `valueFlags`
+ * skip-ahead.** `CommandRegistry.dispatch`'s `valueFlags` option (see `command-registry.ts`)
+ * correctly *finds* the command-name token when a global flag with a value precedes it (e.g.
+ * `--daemon-url http://x run` picks `run`, not the URL) — but the `rest` array it then hands
+ * the matched handler still *contains* that leading global flag and its value, ahead of
+ * whatever the handler expects as its own first token. That's harmless for a flat command, but
+ * `run-command.ts`/`daemon-command.ts`'s own registered handlers immediately do a *second*
+ * `const [sub, ...rest] = args` dispatch of their own, assuming `args[0]` is their immediate
+ * subcommand (`start`/`status`/etc.) with no tolerance for a stray leading flag — exactly what
+ * a global flag ahead of the command name would produce. Rather than change that (well-tested,
+ * out-of-scope) nested-dispatch assumption, {@link partitionGlobalArgv} below removes this
+ * binary's own three global flags (and their values) from `argv` in a single pass *before*
+ * dispatch, so `run`/`daemon`/`version` always land as a clean first token no matter where on
+ * the command line `--daemon-url`/`--data-dir`/`--registry-path` were typed.
+ *
+ * **`--version`/`-v`.** This package's `package.json` is `"private": true` with a placeholder
+ * `"0.0.0"` version — not a real, published semver worth printing. Rather than invent one,
+ * `jini --version`/`jini -v` (recognized only as the very first token — see {@link main}) is a
+ * plain alias for `jini version` (`version-command.ts`): it prints the *running daemon's* real
+ * version. That is arguably more useful to a user of this transport-only CLI than this
+ * package's own unpublished build number would be, and it means `--version` has exactly one
+ * implementation to keep correct, not two.
+ *
+ * **Error boundary.** `parseFlags` (`flags.ts`) throws a plain `Error` for an unrecognized
+ * `--flag` or a string flag with no value — by design (see that module's own doc: "a
+ * hallucinated flag from an LLM-driven caller should error immediately"), but every existing
+ * command handler (`run-command.ts`, `daemon-command.ts`, `version-command.ts`) calls it
+ * un-wrapped, so that throw would otherwise surface as an unhandled rejection with a raw stack
+ * trace instead of the clean `{ error: { code, message } }` envelope every *other* failure
+ * path in this package produces. {@link main} wraps its dispatch in a boundary that converts
+ * any such raw throw into the same structured-error contract. Distinguishing "a raw,
+ * unexpected throw" from "a nested command already exited cleanly through
+ * `exitWithStructuredError`" (the latter must never be re-wrapped — that would double-report
+ * the same failure, or worse, mask the original exit code with a generic one) uses a local
+ * flag set by this file's own `exit` wrapper: if the wrapped `exit` was ever invoked before the
+ * catch fires, the original error is re-thrown untouched instead of reformatted. In real
+ * operation this distinction is moot — `process.exit` never returns, so nothing downstream of
+ * a real exit call ever reaches the catch — but it matters for this file's own tests, which
+ * (like every other test in this package) inject a throwing `exit` double to make
+ * `process.exit`'s real "never returns" behavior observable without ending the test process.
+ */
+import { fileURLToPath } from 'node:url';
+import { CommandRegistry } from './command-registry.js';
+import { registerDaemonCommands } from './daemon-command.js';
+import { resolveDaemonUrl } from './daemon-url.js';
+import { exitWithStructuredError } from './errors.js';
+import { createLocalDaemonDiscovery } from './local-daemon-discovery.js';
+import { registerRunCommands } from './run-command.js';
+import { renderUsage } from './usage.js';
+import { registerVersionCommand } from './version-command.js';
+function defaultWrite(text) {
+    process.stdout.write(text);
+}
+function defaultWriteErr(text) {
+    process.stderr.write(text);
+}
+/** Name of the environment variable {@link resolveDaemonUrl} checks when `--daemon-url` is absent. */
+const DAEMON_URL_ENV_VAR = 'JINI_DAEMON_URL';
+const ROOT_USAGE = renderUsage({
+    usage: ['jini <command> [...args]'],
+    description: 'CLI transport for a Jini daemon over HTTP. Commands: run, daemon, version.',
+    options: [
+        { flag: '--daemon-url <url>', description: 'Explicit daemon base URL. Takes precedence over JINI_DAEMON_URL and local discovery.' },
+        { flag: '--data-dir <path>', description: "Resolve a locally running daemon's URL from this data directory's on-disk registry (see @jini-ai/node-host's createLocalNodeDaemon)." },
+        { flag: '--registry-path <path>', description: "Exact registry file path, overriding --data-dir's derived default." },
+        { flag: '--help, -h', description: 'Show this help.' },
+        { flag: '--version, -v', description: 'Print the running daemon\'s version (alias for "jini version"; recognized only as the first argument).' },
+    ],
+});
+const GLOBAL_FLAG_NAMES = ['daemon-url', 'data-dir', 'registry-path'];
+/**
+ * Single-pass extraction of this binary's own global `--daemon-url`/`--data-dir`/
+ * `--registry-path` flags out of the full `argv`, returning both their values and every other
+ * token untouched (including the command name and all of its own subcommand-specific flags) as
+ * `rest` — see this file's own module doc, "Global flags are stripped before dispatch," for why
+ * a dedicated single-pass scanner is used here instead of `flags.ts`'s `parseFlags` (whose
+ * strict mode would throw on an unrelated subcommand flag, and whose permissive/heuristic mode
+ * doesn't reliably agree with "always consume the very next token" for a value-taking flag
+ * immediately followed by another `--flag`).
+ *
+ * @throws A plain `Error` when a recognized global flag is the last token with no value
+ * following it — caught by {@link main}'s own error boundary, same as any other malformed-input
+ * failure.
+ */
+function partitionGlobalArgv(argv) {
+    const names = new Set(GLOBAL_FLAG_NAMES);
+    const globals = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        // Loop is bounded by argv.length, so this index is always in range —
+        // noUncheckedIndexedAccess types it as possibly-undefined regardless.
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            const key = eq >= 0 ? token.slice(2, eq) : token.slice(2);
+            if (names.has(key)) {
+                if (eq >= 0) {
+                    globals[key] = token.slice(eq + 1);
+                }
+                else {
+                    const value = argv[i + 1];
+                    if (value === undefined)
+                        throw new Error(`flag --${key} requires a value`);
+                    globals[key] = value;
+                    i++;
+                }
+                continue;
+            }
+        }
+        rest.push(token);
+    }
+    return { globals, rest };
+}
+/** Builds a `resolveDaemonUrl`-backed `resolveBaseUrl` closure from this binary's own parsed global flags. */
+function buildResolveBaseUrl(globals, env, warn) {
+    const { 'daemon-url': daemonUrl, 'data-dir': dataDir, 'registry-path': registryPath } = globals;
+    const discover = registryPath !== undefined
+        ? createLocalDaemonDiscovery({ registryPath })
+        : dataDir !== undefined
+            ? createLocalDaemonDiscovery({ dataDir })
+            : undefined;
+    return () => resolveDaemonUrl({
+        flagUrl: daemonUrl ?? null,
+        env,
+        envVarName: DAEMON_URL_ENV_VAR,
+        ...(discover !== undefined ? { discover } : {}),
+        warn,
+    });
+}
+/**
+ * Parse `argv` (already stripped of `node`/script-path, i.e. `process.argv.slice(2)`) and
+ * dispatch to the registered `run`/`daemon`/`version` commands. Never throws a raw error to its
+ * caller under normal use — usage errors and daemon failures both exit through this package's
+ * structured-error contract (`errors.ts`), via the injected (or default, real) `exit`.
+ */
+export async function main(argv, deps = {}) {
+    const write = deps.write ?? defaultWrite;
+    const writeErr = deps.writeErr ?? defaultWriteErr;
+    const rawExit = deps.exit ?? ((code) => process.exit(code));
+    const env = deps.env ?? process.env;
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        write(`${ROOT_USAGE}\n`);
+        return;
+    }
+    // `--version`/`-v` as the very first token is a plain alias for `jini version` — see this
+    // file's own module doc for why there is no separate "this package's own version" surface.
+    const effectiveArgv = argv[0] === '--version' || argv[0] === '-v' ? ['version', ...argv.slice(1)] : argv;
+    // Tracks whether `exit` was ever invoked, so the catch block below can tell "a nested command
+    // already exited cleanly" (re-throw untouched) apart from "a genuinely raw, unhandled throw"
+    // (reformat into a structured error) — see this file's own module doc, "Error boundary."
+    let exitCalled = false;
+    const exit = (code) => {
+        exitCalled = true;
+        return rawExit(code);
+    };
+    let result;
+    try {
+        const { globals, rest } = partitionGlobalArgv(effectiveArgv);
+        const resolveBaseUrl = buildResolveBaseUrl(globals, env, writeErr);
+        const commandDeps = {
+            resolveBaseUrl,
+            write,
+            writeErr,
+            exit,
+            ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+        };
+        const registry = new CommandRegistry();
+        registerRunCommands(registry, commandDeps);
+        registerDaemonCommands(registry, commandDeps);
+        registerVersionCommand(registry, commandDeps);
+        result = await registry.dispatch(rest);
+    }
+    catch (error) {
+        if (exitCalled)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        exitWithStructuredError({ code: 'invalid-flag', message }, { write: writeErr, exit });
+        return;
+    }
+    if (result.kind === 'empty') {
+        write(`${ROOT_USAGE}\n`);
+        return;
+    }
+    if (result.kind === 'not-found') {
+        exitWithStructuredError({ code: 'invalid-flag', message: `unknown command: "${result.name}". Run "jini --help" for usage.` }, { write: writeErr, exit });
+    }
+}
+// Only run for real when this module is the actual process entrypoint (`node dist/main.js
+// ...`, or the `jini` bin shim pnpm/npm links to it) — not merely imported, e.g. by this
+// file's own tests importing the named `main` export above. Mirrors Node's CommonJS
+// `require.main === module` idiom for ESM; see this file's own module doc.
+const isMainModule = process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMainModule) {
+    await main(process.argv.slice(2));
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

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

package/dist/prompt.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module prompt
+ *
+ * Long-form text intake shared across CLI domains: two sibling conventions
+ * for reading a large piece of text from an inline flag, a `--*-file <path>`
+ * flag, or stdin (`-`).
+ *
+ * `readPromptFromFlags` is the `--prompt <text>` / `--prompt-file <path>` /
+ * `--prompt-file -` convention, ported from OD's `apps/daemon/src/cli.ts`
+ * `readPromptFromFlags` (see `source-map.md`). This exact pattern recurred
+ * verbatim across many of OD's product commands (`brand create`, `run
+ * start`, `files version-create`, `automation source ingest`, …) with zero
+ * product nouns in the reading logic itself, which is what makes it a
+ * genuine reusable primitive rather than a one-off helper worth leaving in
+ * each caller.
+ *
+ * `readBodyFromFlags` is the sibling `--body`/`--body-file` convention,
+ * ported from the `cli-capability-barrels` branch's `cli/core/io.ts`
+ * `readMemoryBodyFromFlags` (see `source-map.md`'s "Barrel branch
+ * reconciliation" section). Despite the origin name, it has no memory-domain
+ * coupling — that module's own docblock confirms it is reused verbatim by
+ * both the memory and automation domains — so it is ported here under a
+ * de-branded name alongside its prompt sibling.
+ *
+ * Per CR-004/SEC-RB-009
+ * (`ADS-memory/reports/code-review/CR-remaining-backend-audit-2026-07-21.md`,
+ * `ADS-memory/reports/security/SEC-remaining-backend-audit-2026-07-21.md`),
+ * the default file/stdin readers below cap how many bytes they will read
+ * (rejecting past the cap rather than truncating silently or reading
+ * unbounded input into memory) and accept an optional `AbortSignal` so a
+ * caller can cancel an in-progress read. Both knobs only apply to the
+ * default `readFile`/`readStdin` implementations — they have no effect if a
+ * caller injects their own.
+ */
+/** Thrown by the default readers when a file or stdin stream exceeds its configured byte cap. */
+export declare class PayloadTooLargeError extends Error {
+    constructor(message: string);
+}
+export interface PromptFlags {
+    prompt?: string;
+    'prompt-file'?: string;
+}
+export interface ReadPromptFromFlagsOptions {
+    /** Defaults to a bounded, cancellable `node:fs` stream read; inject for tests. */
+    readFile?: (path: string) => Promise<string>;
+    /** Defaults to a bounded, cancellable read of `process.stdin` to EOF as utf8; inject for tests. */
+    readStdin?: () => Promise<string>;
+    /** Maximum bytes the default readFile/readStdin will read before rejecting. Defaults to 10 MiB. No effect on an injected reader. */
+    maxBytes?: number;
+    /** Cancels an in-progress default readFile/readStdin call. No effect on an injected reader. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve prompt text from `--prompt`, or `--prompt-file <path>` /
+ * `--prompt-file -` (stdin). Returns `null` when neither flag is set so the
+ * caller can fall back to its own default.
+ */
+export declare function readPromptFromFlags(flags: PromptFlags, options?: ReadPromptFromFlagsOptions): Promise<string | null>;
+export interface BodyFlags {
+    body?: string;
+    'body-file'?: string;
+}
+export interface ReadBodyFromFlagsOptions {
+    /** Defaults to a bounded, cancellable `node:fs` stream read; inject for tests. */
+    readFile?: (path: string) => Promise<string>;
+    /** Defaults to a bounded, cancellable drain of `process.stdin`'s async iterator as utf8; inject for tests. */
+    readStdin?: () => Promise<string>;
+    /** Maximum bytes the default readFile/readStdin will read before rejecting. Defaults to 10 MiB. No effect on an injected reader. */
+    maxBytes?: number;
+    /** Cancels an in-progress default readFile/readStdin call. No effect on an injected reader. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve long-form body text from `--body` (inline — an empty string counts
+ * as provided) or `--body-file <path>` / `--body-file -` (stdin). Returns
+ * `undefined` when neither flag is present, so callers can distinguish "not
+ * provided" from an intentionally empty body — unlike {@link
+ * readPromptFromFlags}, which treats an empty `--prompt` as unset, this
+ * primitive's origin caller (`od memory tree edit`) needs to allow clearing
+ * a body to an empty string.
+ */
+export declare function readBodyFromFlags(flags: BodyFlags, options?: ReadBodyFromFlagsOptions): Promise<string | undefined>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iGAAiG;AACjG,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAKD,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,oIAAoI;IACpI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AA8FD,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,8GAA8G;IAC9G,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,oIAAoI;IACpI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW7B"}

package/dist/prompt.js

@@ -0,0 +1,198 @@
+/**
+ * @module prompt
+ *
+ * Long-form text intake shared across CLI domains: two sibling conventions
+ * for reading a large piece of text from an inline flag, a `--*-file <path>`
+ * flag, or stdin (`-`).
+ *
+ * `readPromptFromFlags` is the `--prompt <text>` / `--prompt-file <path>` /
+ * `--prompt-file -` convention, ported from OD's `apps/daemon/src/cli.ts`
+ * `readPromptFromFlags` (see `source-map.md`). This exact pattern recurred
+ * verbatim across many of OD's product commands (`brand create`, `run
+ * start`, `files version-create`, `automation source ingest`, …) with zero
+ * product nouns in the reading logic itself, which is what makes it a
+ * genuine reusable primitive rather than a one-off helper worth leaving in
+ * each caller.
+ *
+ * `readBodyFromFlags` is the sibling `--body`/`--body-file` convention,
+ * ported from the `cli-capability-barrels` branch's `cli/core/io.ts`
+ * `readMemoryBodyFromFlags` (see `source-map.md`'s "Barrel branch
+ * reconciliation" section). Despite the origin name, it has no memory-domain
+ * coupling — that module's own docblock confirms it is reused verbatim by
+ * both the memory and automation domains — so it is ported here under a
+ * de-branded name alongside its prompt sibling.
+ *
+ * Per CR-004/SEC-RB-009
+ * (`ADS-memory/reports/code-review/CR-remaining-backend-audit-2026-07-21.md`,
+ * `ADS-memory/reports/security/SEC-remaining-backend-audit-2026-07-21.md`),
+ * the default file/stdin readers below cap how many bytes they will read
+ * (rejecting past the cap rather than truncating silently or reading
+ * unbounded input into memory) and accept an optional `AbortSignal` so a
+ * caller can cancel an in-progress read. Both knobs only apply to the
+ * default `readFile`/`readStdin` implementations — they have no effect if a
+ * caller injects their own.
+ */
+/** Thrown by the default readers when a file or stdin stream exceeds its configured byte cap. */
+export class PayloadTooLargeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PayloadTooLargeError';
+    }
+}
+/** Default cap for the default file/stdin readers: generous for a prompt/body payload, small enough to bound worst-case memory. */
+const DEFAULT_MAX_READ_BYTES = 10 * 1024 * 1024;
+/**
+ * Resolve prompt text from `--prompt`, or `--prompt-file <path>` /
+ * `--prompt-file -` (stdin). Returns `null` when neither flag is set so the
+ * caller can fall back to its own default.
+ */
+export async function readPromptFromFlags(flags, options = {}) {
+    if (typeof flags.prompt === 'string' && flags.prompt.length > 0) {
+        return flags.prompt;
+    }
+    const promptFile = flags['prompt-file'];
+    if (typeof promptFile !== 'string' || promptFile.length === 0) {
+        return null;
+    }
+    const readLimits = { maxBytes: options.maxBytes ?? DEFAULT_MAX_READ_BYTES, ...(options.signal !== undefined ? { signal: options.signal } : {}) };
+    if (promptFile === '-') {
+        const readStdin = options.readStdin ?? (() => defaultReadStdin(readLimits));
+        return await readStdin();
+    }
+    const readFile = options.readFile ?? ((path) => defaultReadFile(path, readLimits));
+    return await readFile(promptFile);
+}
+async function defaultReadFile(path, limits) {
+    const { createReadStream } = await import('node:fs');
+    return await new Promise((resolve, reject) => {
+        const stream = createReadStream(path, limits.signal !== undefined ? { signal: limits.signal } : {});
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        // `settled`-guarded: defensive against Node's own documented Readable
+        // contract ever being violated (a stream is only ever supposed to emit
+        // one of 'end'/'error', never both, and `stream.destroy()` with no
+        // error argument — the only way this module calls it — is documented to
+        // suppress any further 'error' from the destroy path itself). Kept as
+        // real protection against a future/third-party stream implementation
+        // bug, not something this module's own real `createReadStream` usage
+        // can trigger — see `source-map.md`'s dated entry for the full
+        // re-verification record (a single terminal event is all this file's
+        // own usage can ever produce).
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        // `@types/node` types a Readable's 'data' listener as `(chunk: string |
+        // Buffer) => void` unconditionally (accommodating a stream some other
+        // caller configured with an `encoding`), but this stream never sets one
+        // (`limits` has no such field — see `ReadLimits`), so `chunk` is always
+        // really a `Buffer` here — a plain assertion, not a runtime `typeof`
+        // branch (a prior `typeof chunk === 'string' ? ... : ...` ternary here
+        // was dead code given this file's only call site; removed rather than
+        // left uncovered).
+        stream.on('data', (rawChunk) => {
+            const chunk = rawChunk;
+            total += chunk.length;
+            if (total > limits.maxBytes) {
+                stream.destroy();
+                finish(() => reject(new PayloadTooLargeError(`file exceeded the ${limits.maxBytes}-byte limit: ${path}`)));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        stream.on('error', (err) => finish(() => reject(err)));
+        stream.on('end', () => finish(() => resolve(Buffer.concat(chunks).toString('utf8'))));
+    });
+}
+async function defaultReadStdin(limits) {
+    return await new Promise((resolve, reject) => {
+        if (limits.signal?.aborted === true) {
+            reject(limits.signal.reason ?? new Error('stdin read aborted'));
+            return;
+        }
+        let buffer = '';
+        let total = 0;
+        process.stdin.setEncoding('utf8');
+        const cleanup = () => {
+            process.stdin.off('data', onData);
+            process.stdin.off('end', onEnd);
+            process.stdin.off('error', onError);
+            limits.signal?.removeEventListener('abort', onAbort);
+        };
+        const pauseStdin = () => {
+            process.stdin.pause?.();
+        };
+        const onData = (chunk) => {
+            total += Buffer.byteLength(chunk, 'utf8');
+            if (total > limits.maxBytes) {
+                cleanup();
+                pauseStdin();
+                reject(new PayloadTooLargeError(`stdin exceeded the ${limits.maxBytes}-byte limit`));
+                return;
+            }
+            buffer += chunk;
+        };
+        const onEnd = () => { cleanup(); resolve(buffer); };
+        const onError = (err) => { cleanup(); reject(err); };
+        const onAbort = () => {
+            cleanup();
+            pauseStdin();
+            reject(limits.signal?.reason ?? new Error('stdin read aborted'));
+        };
+        process.stdin.on('data', onData);
+        process.stdin.on('end', onEnd);
+        process.stdin.on('error', onError);
+        limits.signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Resolve long-form body text from `--body` (inline — an empty string counts
+ * as provided) or `--body-file <path>` / `--body-file -` (stdin). Returns
+ * `undefined` when neither flag is present, so callers can distinguish "not
+ * provided" from an intentionally empty body — unlike {@link
+ * readPromptFromFlags}, which treats an empty `--prompt` as unset, this
+ * primitive's origin caller (`od memory tree edit`) needs to allow clearing
+ * a body to an empty string.
+ */
+export async function readBodyFromFlags(flags, options = {}) {
+    if (typeof flags.body === 'string')
+        return flags.body;
+    const bodyFile = flags['body-file'];
+    if (typeof bodyFile !== 'string')
+        return undefined;
+    const readLimits = { maxBytes: options.maxBytes ?? DEFAULT_MAX_READ_BYTES, ...(options.signal !== undefined ? { signal: options.signal } : {}) };
+    if (bodyFile === '-') {
+        const readStdin = options.readStdin ?? (() => defaultReadBodyStdin(readLimits));
+        return await readStdin();
+    }
+    const readFile = options.readFile ?? ((path) => defaultReadFile(path, readLimits));
+    return await readFile(bodyFile);
+}
+async function defaultReadBodyStdin(limits) {
+    limits.signal?.throwIfAborted();
+    const stdin = process.stdin;
+    const onAbort = () => { stdin.destroy?.(new Error('stdin read aborted')); };
+    limits.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        let body = '';
+        let total = 0;
+        for await (const chunk of stdin) {
+            limits.signal?.throwIfAborted();
+            const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            total += Buffer.byteLength(text, 'utf8');
+            if (total > limits.maxBytes) {
+                stdin.destroy?.();
+                throw new PayloadTooLargeError(`stdin exceeded the ${limits.maxBytes}-byte limit`);
+            }
+            body += text;
+        }
+        return body;
+    }
+    finally {
+        limits.signal?.removeEventListener('abort', onAbort);
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

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

package/dist/redact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module redact
+ *
+ * Bounded, redacted rendering of text that ultimately traces back to an
+ * untrusted network peer — a daemon's error body, a `fetch()` rejection's
+ * cause message — rather than to this process's own code. Three problems
+ * are addressed together because a hostile or merely buggy daemon can
+ * combine them: an unbounded body can be enormous, an arbitrary body can
+ * contain terminal control/ANSI escape sequences that manipulate the
+ * user's terminal when printed verbatim, and it can echo back secrets (an
+ * `Authorization` header, an API key, a bearer/refresh token) that were
+ * present in the request or in an upstream provider's own error.
+ *
+ * Added per CR-004 / SEC-RB-009 (`ADS-memory/reports/code-review/CR-remaining-backend-audit-2026-07-21.md`,
+ * `ADS-memory/reports/security/SEC-remaining-backend-audit-2026-07-21.md`):
+ * `http.ts` and `errors.ts` previously wrote raw fetch-cause messages,
+ * arbitrary daemon JSON, or complete non-JSON response bodies straight to
+ * the terminal.
+ */
+/**
+ * Strip ANSI/terminal escape sequences (CSI `ESC [ ... final-byte`, OSC `ESC ] ... BEL-or-ST`,
+ * and bare ESC-prefixed bytes) plus other C0/C1 control characters from `text`. Written as an
+ * explicit char-code scanner rather than a regex literal with hex escapes, so the pattern is
+ * plain ASCII source with no embedded control bytes.
+ */
+export declare function stripControlSequences(text: string): string;
+/** Redact labeled credentials and long opaque-token-looking substrings from `text`. */
+export declare function redactSecretLike(text: string): string;
+export interface SanitizeTextOptions {
+    /** Maximum output length; longer input is truncated with a trailing marker. Defaults to 500. */
+    maxLength?: number;
+}
+/**
+ * Strip terminal control sequences, redact anything that looks like a secret, and cap the
+ * length of `text` — the one function every boundary that surfaces daemon/network-derived text
+ * to stderr/stdout should route through first.
+ */
+export declare function sanitizeUntrustedText(text: string, options?: SanitizeTextOptions): string;
+/**
+ * Recursively sanitize an arbitrary parsed-JSON value (the shape a daemon error envelope's
+ * `data`/`details` field can legitimately be): every string leaf is passed through
+ * {@link sanitizeUntrustedText}, and both array length and object key count are capped per
+ * level so a maliciously wide or deep payload can't blow up the work done here. Depth beyond
+ * the cap is replaced with a placeholder rather than silently dropped, so truncation is visible
+ * instead of looking like an empty/missing value.
+ */
+export declare function sanitizeUnknownDeep(value: unknown, depth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA2BH;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA+B1D;AASD,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAM7F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAetE"}