@jini-ai/cli 0.3.1 → 0.4.1

package/dist/errors.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured error / exit-code handling, generalized from OD's
  * `apps/daemon/src/cli.ts` `exitWithStructuredError`/`structuredHttpFailure`
- * (see `source-map.md`). The mechanism — map a stable error `code` to a
+ * (see `archived provenance ledger`). The mechanism — map a stable error `code` to a
  * process exit code, write a `{ error: { code, message, data } }` envelope
  * to stderr — is generic CLI transport plumbing; OD's own exit-code table
  * (`plugin-not-found`, `snapshot-stale`, …) is product-specific and was not
@@ -23,15 +23,19 @@ export interface StructuredErrorEnvelope {
 export interface ExitWithStructuredErrorInput {
     code: string;
     message: string;
-    data?: Record<string, unknown>;
 }
 export interface StructuredErrorOptions {
+    data?: Record<string, unknown>;
     /** Extra/overriding `code -> exitCode` entries layered on {@link DEFAULT_CLI_EXIT_CODES}. */
     exitCodes?: ExitCodeTable;
     /** Defaults to `process.stderr.write`; inject for tests. */
-    write?: (text: string) => void;
+    write?: (requiredArgs: {
+        text: string;
+    }) => void;
     /** Defaults to `process.exit`; inject for tests (must not return). */
-    exit?: (code: number) => never;
+    exit?: (requiredArgs: {
+        code: number;
+    }) => never;
 }
 /**
  * Write a `{ error }` envelope to stderr and exit with the code mapped from
@@ -60,7 +64,9 @@ export interface HttpFailureLike {
  * control-sequence-stripped, and secret-redacted before it can reach a
  * printed envelope (CR-004/SEC-RB-009).
  */
-export declare function structuredErrorData(error: DaemonErrorBody | undefined): Record<string, unknown> | undefined;
+export declare function structuredErrorData({ error }: {
+    error: DaemonErrorBody | undefined;
+}): Record<string, unknown> | undefined;
 /**
  * Map a daemon HTTP error response into the structured exit-code envelope.
  * Daemon error bodies come in two shapes in practice: `{ error: { code,
@@ -77,6 +83,10 @@ export declare function structuredErrorData(error: DaemonErrorBody | undefined):
  * structured `message` (when present) is still sanitized — it originates
  * from the same untrusted response.
  */
-export declare function structuredHttpFailure(resp: HttpFailureLike, fallbackCode?: string, options?: StructuredErrorOptions): Promise<never>;
+export declare function structuredHttpFailure({ resp }: {
+    resp: HttpFailureLike;
+}, { fallbackCode, ...options }?: StructuredErrorOptions & {
+    fallbackCode?: string;
+}): Promise<never>;
 export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -3,14 +3,15 @@
  *
  * Structured error / exit-code handling, generalized from OD's
  * `apps/daemon/src/cli.ts` `exitWithStructuredError`/`structuredHttpFailure`
- * (see `source-map.md`). The mechanism — map a stable error `code` to a
+ * (see `archived provenance ledger`). The mechanism — map a stable error `code` to a
  * process exit code, write a `{ error: { code, message, data } }` envelope
  * to stderr — is generic CLI transport plumbing; OD's own exit-code table
  * (`plugin-not-found`, `snapshot-stale`, …) is product-specific and was not
  * ported. Callers extend {@link DEFAULT_CLI_EXIT_CODES} with their own pack's
  * codes rather than this package hosting one global mutable map.
  */
-import { sanitizeUnknownDeep, sanitizeUntrustedText, stripControlSequences } from './redact.js';
+import { sanitizeUnknownDeep } from './redact.js';
+import { sanitizeUntrustedText, stripControlSequences } from '@jini-ai/core/text';
 /** A minimal, product-neutral starting table. Packs extend this with their own codes. */
 export const DEFAULT_CLI_EXIT_CODES = {
     'daemon-not-running': 64,
@@ -25,12 +26,12 @@ export function exitWithStructuredError(input, options = {}) {
     const exitCodes = { ...DEFAULT_CLI_EXIT_CODES, ...options.exitCodes };
     const exitCode = exitCodes[input.code] ?? 1;
     const envelope = {
-        error: { code: input.code, message: input.message, data: input.data ?? {} },
+        error: { code: input.code, message: input.message, data: options.data ?? {} },
     };
-    const write = options.write ?? ((text) => { process.stderr.write(text); });
-    const exit = options.exit ?? ((code) => process.exit(code));
-    write(`${JSON.stringify(envelope)}\n`);
-    return exit(exitCode);
+    const write = options.write ?? (({ text }) => { process.stderr.write(text); });
+    const exit = options.exit ?? (({ code }) => process.exit(code));
+    write({ text: `${JSON.stringify(envelope)}\n` });
+    return exit({ code: exitCode });
 }
 /**
  * Extract `{ data }` worth surfacing to the structured envelope from a
@@ -42,15 +43,15 @@ export function exitWithStructuredError(input, options = {}) {
  * control-sequence-stripped, and secret-redacted before it can reach a
  * printed envelope (CR-004/SEC-RB-009).
  */
-export function structuredErrorData(error) {
+export function structuredErrorData({ error }) {
     if (error === undefined)
         return undefined;
     const data = {};
     if (error.data !== undefined && typeof error.data === 'object' && error.data !== null) {
-        Object.assign(data, sanitizeUnknownDeep(error.data));
+        Object.assign(data, sanitizeUnknownDeep({ value: error.data }));
     }
     if (error.details !== undefined)
-        data.details = sanitizeUnknownDeep(error.details);
+        data.details = sanitizeUnknownDeep({ value: error.details });
     if (typeof error.retryable === 'boolean')
         data.retryable = error.retryable;
     return Object.keys(data).length > 0 ? data : undefined;
@@ -81,7 +82,7 @@ function extractErrorObject(parsed) {
  * structured `message` (when present) is still sanitized — it originates
  * from the same untrusted response.
  */
-export async function structuredHttpFailure(resp, fallbackCode = 'daemon-not-running', options = {}) {
+export async function structuredHttpFailure({ resp }, { fallbackCode = 'daemon-not-running', ...options } = {}) {
     let raw = '';
     let parsed = {};
     try {
@@ -92,12 +93,12 @@ export async function structuredHttpFailure(resp, fallbackCode = 'daemon-not-run
         parsed = {};
     }
     const errorObj = extractErrorObject(parsed);
-    const data = structuredErrorData(errorObj);
-    const code = typeof errorObj?.code === 'string' ? stripControlSequences(errorObj.code) : fallbackCode;
-    const structuredMessage = typeof errorObj?.message === 'string' ? sanitizeUntrustedText(errorObj.message) : undefined;
+    const data = structuredErrorData({ error: errorObj });
+    const code = typeof errorObj?.code === 'string' ? stripControlSequences({ text: errorObj.code }) : fallbackCode;
+    const structuredMessage = typeof errorObj?.message === 'string' ? sanitizeUntrustedText({ text: errorObj.message }) : undefined;
     const message = structuredMessage ?? `HTTP ${resp.status}`;
-    const rawExcerpt = structuredMessage === undefined && raw.length > 0 ? sanitizeUntrustedText(raw) : undefined;
+    const rawExcerpt = structuredMessage === undefined && raw.length > 0 ? sanitizeUntrustedText({ text: raw }) : undefined;
     const mergedData = rawExcerpt !== undefined ? { ...(data ?? {}), rawExcerpt } : data;
-    return exitWithStructuredError({ code, message, ...(mergedData !== undefined ? { data: mergedData } : {}) }, options);
+    return exitWithStructuredError({ code, message }, { ...(mergedData !== undefined ? { data: mergedData } : {}), ...options });
 }
 //# sourceMappingURL=errors.js.map

package/dist/flags.d.ts

@@ -2,7 +2,7 @@
  * @module flags
  *
  * Generic `argv` → flags parsing, ported from OD's `apps/daemon/src/cli.ts`
- * `parseFlags`/`positionalArgs`/`collectCliPositionals` (see `source-map.md`).
+ * `parseFlags`/`positionalArgs`/`collectCliPositionals` (see `archived provenance ledger`).
  * Zero product nouns: callers declare which `--flag` names take a string
  * value vs. are booleans, and get back a flat map plus the leftover
  * positional tokens.
@@ -28,7 +28,9 @@ export interface ParseFlagsOptions {
  * `--flag` is accepted and a heuristic decides string-vs-boolean: if the
  * next token doesn't itself look like a flag, it's consumed as the value.
  */
-export declare function parseFlags(argv: readonly string[], opts?: ParseFlagsOptions): ParsedFlags;
+export declare function parseFlags({ argv }: {
+    argv: readonly string[];
+}, opts?: ParseFlagsOptions): ParsedFlags;
 export interface PositionalArgsOptions {
     /** String-valued flag names whose value token must be skipped, not collected as a positional. */
     string?: ReadonlySet<string>;
@@ -45,17 +47,21 @@ export interface PositionalArgsOptions {
  * follows a known string flag (so `od run start --project p1 foo` yields
  * `['foo']`, not `['p1', 'foo']`).
  */
-export declare function positionalArgs(argv: readonly string[], opts?: PositionalArgsOptions): string[];
+export declare function positionalArgs({ argv }: {
+    argv: readonly string[];
+}, opts?: PositionalArgsOptions): string[];
 /** The native type {@link coerceCliValue} can produce from a raw string flag value. */
 export type CoercedCliValue = boolean | number | string;
 /**
  * Coerce a raw `--flag <value>` string into its likely native type:
  * `'true'`/`'false'` become booleans, a numeric-looking string becomes a
  * `number`, and anything else passes through unchanged. Ported from OD's
- * `cli.ts` `coerceCliValue` (see `source-map.md`) — used wherever a CLI
+ * `cli.ts` `coerceCliValue` (see `archived provenance ledger`) — used wherever a CLI
  * accepts an untyped string flag value that application code should receive
  * as its natural type (e.g. a config `set` command, or a plugin's dynamic
  * `--input` flags forwarded as a JSON-typed payload).
  */
-export declare function coerceCliValue(raw: string): CoercedCliValue;
+export declare function coerceCliValue({ raw }: {
+    raw: string;
+}): CoercedCliValue;
 //# sourceMappingURL=flags.d.ts.map

package/dist/flags.js

@@ -2,7 +2,7 @@
  * @module flags
  *
  * Generic `argv` → flags parsing, ported from OD's `apps/daemon/src/cli.ts`
- * `parseFlags`/`positionalArgs`/`collectCliPositionals` (see `source-map.md`).
+ * `parseFlags`/`positionalArgs`/`collectCliPositionals` (see `archived provenance ledger`).
  * Zero product nouns: callers declare which `--flag` names take a string
  * value vs. are booleans, and get back a flat map plus the leftover
  * positional tokens.
@@ -18,7 +18,7 @@
  * `--flag` is accepted and a heuristic decides string-vs-boolean: if the
  * next token doesn't itself look like a flag, it's consumed as the value.
  */
-export function parseFlags(argv, opts = {}) {
+export function parseFlags({ argv }, opts = {}) {
     const stringFlags = opts.string ?? new Set();
     const booleanFlags = opts.boolean ?? new Set();
     const knownFlags = new Set([...stringFlags, ...booleanFlags]);
@@ -67,7 +67,7 @@ export function parseFlags(argv, opts = {}) {
  * follows a known string flag (so `od run start --project p1 foo` yields
  * `['foo']`, not `['p1', 'foo']`).
  */
-export function positionalArgs(argv, opts = {}) {
+export function positionalArgs({ argv }, opts = {}) {
     const stringFlags = opts.string ?? new Set();
     const out = [];
     for (let i = 0; i < argv.length; i++) {
@@ -94,12 +94,12 @@ const NUMERIC_LITERAL_RE = /^-?\d+(\.\d+)?$/;
  * Coerce a raw `--flag <value>` string into its likely native type:
  * `'true'`/`'false'` become booleans, a numeric-looking string becomes a
  * `number`, and anything else passes through unchanged. Ported from OD's
- * `cli.ts` `coerceCliValue` (see `source-map.md`) — used wherever a CLI
+ * `cli.ts` `coerceCliValue` (see `archived provenance ledger`) — used wherever a CLI
  * accepts an untyped string flag value that application code should receive
  * as its natural type (e.g. a config `set` command, or a plugin's dynamic
  * `--input` flags forwarded as a JSON-typed payload).
  */
-export function coerceCliValue(raw) {
+export function coerceCliValue({ raw }) {
     if (raw === 'true')
         return true;
     if (raw === 'false')

package/dist/http.d.ts

@@ -3,7 +3,7 @@
  *
  * HTTP-client-mode transport plumbing, ported from OD's
  * `apps/daemon/src/cli.ts` `surfaceFetchError`/`postJsonToDaemon` (see
- * `source-map.md`). This is the "HTTP-client mode default" half of
+ * `archived provenance ledger`). This is the "HTTP-client mode default" half of
  * extraction-plan §3's `@jini-ai/cli` spec: fetch a daemon route, translate a
  * network failure or a daemon error envelope into the structured exit-code
  * contract from `errors.ts`.
@@ -11,7 +11,9 @@
 import { type ExitCodeTable } from './errors.js';
 export interface SurfaceFetchErrorOptions {
     /** Defaults to `process.stderr.write`; inject for tests. */
-    write?: (text: string) => void;
+    write?: (requiredArgs: {
+        text: string;
+    }) => void;
 }
 /**
  * Format a `fetch()` rejection (network-unreachable, sandbox-denied) into a
@@ -22,16 +24,23 @@ export interface SurfaceFetchErrorOptions {
  * embeds terminal control sequences or a leaked credential, must not be
  * printed verbatim.
  */
-export declare function surfaceFetchError(err: unknown, daemonUrl: string, options?: SurfaceFetchErrorOptions): void;
+export declare function surfaceFetchError({ err, daemonUrl }: {
+    err: unknown;
+    daemonUrl: string;
+}, options?: SurfaceFetchErrorOptions): void;
 export interface PostJsonToDaemonOptions {
     headers?: Record<string, string>;
     exitCodes?: ExitCodeTable;
     /** Defaults to the global `fetch`; inject for tests. */
     fetchImpl?: typeof fetch;
-    /** Defaults to `process.stderr.write`; inject for tests. Used only for the unrecognized-error-code fallback path. */
-    write?: (text: string) => void;
-    /** Defaults to `process.exit`; inject for tests (must not return). Used only for the unrecognized-error-code fallback path. */
-    exit?: (code: number) => never;
+    /** Defaults to `process.stderr.write`; inject for every structured failure path. */
+    write?: (requiredArgs: {
+        text: string;
+    }) => void;
+    /** Defaults to `process.exit`; inject for every structured failure path (must not return). */
+    exit?: (requiredArgs: {
+        code: number;
+    }) => never;
     /** Caller-supplied cancellation signal; combined with the internal timeout signal, so either one aborts the request. */
     signal?: AbortSignal;
     /** Request deadline in ms. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
@@ -52,12 +61,19 @@ export type GetJsonFromDaemonOptions = PostJsonToDaemonOptions;
  * daemon-supplied error detail before it reaches stderr instead of dumping
  * it verbatim.
  */
-export declare function postJsonToDaemon(base: string, route: string, body: unknown, options?: PostJsonToDaemonOptions): Promise<unknown>;
+export declare function postJsonToDaemon({ base, route, body }: {
+    base: string;
+    route: string;
+    body: unknown;
+}, options?: PostJsonToDaemonOptions): Promise<unknown>;
 /**
  * `GET` `<base><route>` and return the parsed JSON response. Same transport contract as
  * {@link postJsonToDaemon} (timeout, response-size cap, structured-error mapping, redaction) with
  * no request body — for read-only daemon routes such as `@jini-ai/http-kit`'s `GET /api/runs` and
  * `GET /api/runs/:runId`.
  */
-export declare function getJsonFromDaemon(base: string, route: string, options?: GetJsonFromDaemonOptions): Promise<unknown>;
+export declare function getJsonFromDaemon({ base, route }: {
+    base: string;
+    route: string;
+}, options?: GetJsonFromDaemonOptions): Promise<unknown>;
 //# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -3,14 +3,14 @@
  *
  * HTTP-client-mode transport plumbing, ported from OD's
  * `apps/daemon/src/cli.ts` `surfaceFetchError`/`postJsonToDaemon` (see
- * `source-map.md`). This is the "HTTP-client mode default" half of
+ * `archived provenance ledger`). This is the "HTTP-client mode default" half of
  * extraction-plan §3's `@jini-ai/cli` spec: fetch a daemon route, translate a
  * network failure or a daemon error envelope into the structured exit-code
  * contract from `errors.ts`.
  */
 import { DEFAULT_CLI_EXIT_CODES, exitWithStructuredError, structuredErrorData } from './errors.js';
 import { sanitizeDaemonUrlForDisplay } from './daemon-url.js';
-import { sanitizeUntrustedText } from './redact.js';
+import { sanitizeUntrustedText } from '@jini-ai/core/text';
 /**
  * Format a `fetch()` rejection (network-unreachable, sandbox-denied) into a
  * human-readable stderr line, with a hint when the underlying cause looks
@@ -20,8 +20,8 @@ import { sanitizeUntrustedText } from './redact.js';
  * embeds terminal control sequences or a leaked credential, must not be
  * printed verbatim.
  */
-export function surfaceFetchError(err, daemonUrl, options = {}) {
-    const write = options.write ?? ((text) => { process.stderr.write(text); });
+export function surfaceFetchError({ err, daemonUrl }, options = {}) {
+    const write = options.write ?? (({ text }) => { process.stderr.write(text); });
     const cause = err !== null && typeof err === 'object' ? err.cause : null;
     const code = cause !== null && typeof cause === 'object' && typeof cause.code === 'string'
         ? cause.code
@@ -34,11 +34,12 @@ export function surfaceFetchError(err, daemonUrl, options = {}) {
         detail = `${code}${causeMessage.length > 0 ? ` — ${causeMessage}` : ''}`;
     else if (causeMessage.length > 0)
         detail = causeMessage;
-    write(`failed to reach daemon at ${sanitizeDaemonUrlForDisplay(daemonUrl)}: ${sanitizeUntrustedText(detail)}\n`);
+    write({ text: `failed to reach daemon at ${sanitizeDaemonUrlForDisplay({ url: daemonUrl })}: ${sanitizeUntrustedText({ text: detail })}\n` });
     if (code === 'EPERM' || code === 'ENETUNREACH') {
-        write('hint: outbound connect was denied, likely by a sandbox policy. ' +
-            'If this command ran inside an agent sandbox, check its network policy — ' +
-            'the daemon itself is unaffected and can be reached from a regular shell.\n');
+        write({ text: 'hint: outbound connect was denied, likely by a sandbox policy. ' +
+                'If this command ran inside an agent sandbox, check its network policy — ' +
+                'the daemon itself is unaffected and can be reached from a regular shell.\n',
+        });
     }
 }
 /** Default request deadline. Generous enough for a slow agent run kickoff, short enough that a stalled daemon doesn't hang a CLI invocation forever. */
@@ -123,8 +124,8 @@ async function readJsonWithLimit(resp, maxBytes) {
  */
 async function requestJsonFromDaemon(base, route, init, options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    const write = options.write ?? ((text) => { process.stderr.write(text); });
-    const exit = options.exit ?? ((exitCode) => process.exit(exitCode));
+    const write = options.write ?? (({ text }) => { process.stderr.write(text); });
+    const exit = options.exit ?? (({ code }) => process.exit(code));
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
     const structuredOptions = {
@@ -154,36 +155,38 @@ async function requestJsonFromDaemon(base, route, init, options = {}) {
             });
         }
         catch (err) {
-            surfaceFetchError(err, base, { write });
-            return exitWithStructuredError({ code: 'daemon-not-running', message: `Cannot reach daemon at ${sanitizeDaemonUrlForDisplay(base)}` }, structuredOptions);
+            const diagnostics = [];
+            surfaceFetchError({ err, daemonUrl: base }, { write: ({ text }) => { diagnostics.push(text.trimEnd()); } });
+            return exitWithStructuredError({ code: 'daemon-not-running', message: `Cannot reach daemon at ${sanitizeDaemonUrlForDisplay({ url: base })}` }, { data: { diagnostics }, ...structuredOptions });
         }
         try {
             data = await readJsonWithLimit(resp, maxResponseBytes);
         }
         catch (err) {
             if (err instanceof ResponseTooLargeError) {
-                write(`response from ${sanitizeDaemonUrlForDisplay(base)}${route} exceeded the ${err.limitBytes}-byte limit; aborting.\n`);
-                return exit(1);
+                timeoutController.abort(err);
+                return exitWithStructuredError({ code: 'response-too-large', message: `response from ${sanitizeDaemonUrlForDisplay({ url: base })}${route} exceeded the ${err.limitBytes}-byte limit; aborting.` }, structuredOptions);
             }
-            throw err;
+            const detail = err instanceof Error ? err.message : String(err);
+            return exitWithStructuredError({ code: 'request-failed', message: sanitizeUntrustedText({ text: detail }) }, structuredOptions);
         }
     }
     finally {
         clearTimeout(timeoutHandle);
     }
     if (!resp.ok) {
-        const errorObj = data.error;
+        const errorObj = data?.error;
         const exitCodes = { ...DEFAULT_CLI_EXIT_CODES, ...options.exitCodes };
         const code = typeof errorObj?.code === 'string' && errorObj.code in exitCodes ? errorObj.code : null;
         if (code !== null) {
             const rawMessage = typeof errorObj?.message === 'string' ? errorObj.message : `HTTP ${resp.status}`;
-            const message = sanitizeUntrustedText(rawMessage);
-            const errorData = structuredErrorData(errorObj);
-            return exitWithStructuredError({ code, message, ...(errorData !== undefined ? { data: errorData } : {}) }, structuredOptions);
+            const message = sanitizeUntrustedText({ text: rawMessage });
+            const errorData = structuredErrorData({ error: errorObj });
+            return exitWithStructuredError({ code, message }, { ...(errorData !== undefined ? { data: errorData } : {}), ...structuredOptions });
         }
         const rawExcerpt = describeUnrecognizedDaemonPayload(data);
-        write(`${init.method} ${route} failed: ${resp.status}${rawExcerpt}\n`);
-        return exit(1);
+        const fallbackCode = typeof errorObj?.code === 'string' ? sanitizeUntrustedText({ text: errorObj.code }) : 'http-error';
+        return exitWithStructuredError({ code: fallbackCode, message: `${init.method} ${route} failed: ${resp.status}${rawExcerpt}` }, structuredOptions);
     }
     return data;
 }
@@ -198,7 +201,7 @@ async function requestJsonFromDaemon(base, route, init, options = {}) {
  * daemon-supplied error detail before it reaches stderr instead of dumping
  * it verbatim.
  */
-export async function postJsonToDaemon(base, route, body, options = {}) {
+export async function postJsonToDaemon({ base, route, body }, options = {}) {
     return requestJsonFromDaemon(base, route, { method: 'POST', body }, options);
 }
 /**
@@ -207,7 +210,7 @@ export async function postJsonToDaemon(base, route, body, options = {}) {
  * no request body — for read-only daemon routes such as `@jini-ai/http-kit`'s `GET /api/runs` and
  * `GET /api/runs/:runId`.
  */
-export async function getJsonFromDaemon(base, route, options = {}) {
+export async function getJsonFromDaemon({ base, route }, options = {}) {
     return requestJsonFromDaemon(base, route, { method: 'GET' }, options);
 }
 /** A bounded, redacted excerpt of an unrecognized daemon error payload — never the full raw body. */
@@ -221,6 +224,6 @@ function describeUnrecognizedDaemonPayload(data) {
     }
     if (raw.length === 0)
         return '';
-    return ` (daemon response, redacted/truncated): ${sanitizeUntrustedText(raw)}`;
+    return ` (daemon response, redacted/truncated): ${sanitizeUntrustedText({ text: raw })}`;
 }
 //# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * CLI transport-shell: HTTP-client-mode generic transport/infra ported from
  * OD's `apps/daemon/src/cli.ts` (extraction-plan §3 / §8 task 9). See
- * `source-map.md` for the full classification of what was and wasn't
+ * `archived provenance ledger` for the full classification of what was and wasn't
  * ported. This is a first generic slice, not the full `@jini-ai/cli` package.
  * This barrel itself registers nothing against `CommandRegistry` — see the
  * NOTE below for `main.ts`, this package's own bootable entrypoint, which does.
@@ -21,4 +21,5 @@ export * from './daemon-command.js';
 export * from './version-command.js';
 export * from './local-daemon-discovery.js';
 export * from './tokens.js';
+export * from './introspection.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * CLI transport-shell: HTTP-client-mode generic transport/infra ported from
  * OD's `apps/daemon/src/cli.ts` (extraction-plan §3 / §8 task 9). See
- * `source-map.md` for the full classification of what was and wasn't
+ * `archived provenance ledger` for the full classification of what was and wasn't
  * ported. This is a first generic slice, not the full `@jini-ai/cli` package.
  * This barrel itself registers nothing against `CommandRegistry` — see the
  * NOTE below for `main.ts`, this package's own bootable entrypoint, which does.
@@ -27,4 +27,5 @@ export * from './tokens.js';
 // imported for real (guarded so that merely importing its named `main` export does not trigger
 // that side effect — see `main.ts`'s own module doc) — bundling it into this barrel would mean
 // `import '@jini-ai/cli'` could start behaving like a CLI invocation.
+export * from './introspection.js';
 //# sourceMappingURL=index.js.map

package/dist/introspection.d.ts

@@ -0,0 +1,75 @@
+/** Structural Commander port: accepts a real Command tree without a runtime dependency. */
+export interface IntrospectionCommand {
+    name(): string;
+    description(): string;
+    readonly commands: readonly IntrospectionCommand[];
+    readonly registeredArguments: readonly {
+        name(): string;
+        required: boolean;
+        description?: string;
+    }[];
+    readonly options: readonly {
+        flags: string;
+        attributeName(): string;
+        description?: string;
+        mandatory: boolean;
+        defaultValue?: unknown;
+    }[];
+}
+export interface IntrospectedArgument {
+    name: string;
+    required: boolean;
+    description: string;
+}
+export interface IntrospectedOption {
+    flags: string;
+    attributeName: string;
+    description: string;
+    required: boolean;
+    defaultValue?: unknown;
+    takesValue: boolean;
+}
+export interface IntrospectedCommand {
+    name: string;
+    description: string;
+    arguments: IntrospectedArgument[];
+    options: IntrospectedOption[];
+}
+export interface CliManifest {
+    name: string;
+    description: string;
+    commands: IntrospectedCommand[];
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: "string";
+            description: string;
+        }>;
+        required: string[];
+    };
+}
+/**
+ * Read invocable leaves from a live command tree, using full space-separated paths.
+ * @param required Program port and the host's explicitly excluded command names.
+ * @returns A plain manifest preserving command/argument/option order and defaults.
+ * @complexity O(c + f), where c is the number of commands and f the total fields.
+ */
+export declare function introspectProgram({ program, excludedCommands }: {
+    program: IntrospectionCommand;
+    excludedCommands: readonly string[];
+}): CliManifest;
+/**
+ * Project a CLI manifest into string-valued MCP input schemas; boolean switches are omitted.
+ * @param required Manifest and caller-owned prefix (including any desired separator).
+ * @returns One tool per leaf command, with spaces in invocation paths replaced by underscores.
+ * @complexity O(c + f), for commands and argument/option fields.
+ */
+export declare function toMcpTools({ manifest, toolNamePrefix }: {
+    manifest: CliManifest;
+    toolNamePrefix: string;
+}): McpToolDefinition[];
+//# sourceMappingURL=introspection.d.ts.map

package/dist/introspection.js

@@ -0,0 +1,63 @@
+/**
+ * Read invocable leaves from a live command tree, using full space-separated paths.
+ * @param required Program port and the host's explicitly excluded command names.
+ * @returns A plain manifest preserving command/argument/option order and defaults.
+ * @complexity O(c + f), where c is the number of commands and f the total fields.
+ */
+export function introspectProgram({ program, excludedCommands }) {
+    const excluded = new Set(excludedCommands);
+    const commands = [];
+    function visit(command, path) {
+        // Root meta commands describe the CLI itself; nested namesakes remain invocable capabilities.
+        if (path.length === 0 && excluded.has(command.name()))
+            return;
+        const fullPath = [...path, command.name()];
+        // Group commands only print usage in this command model; expose their invocable leaves.
+        // Full paths still fit the flat manifest consumed by callers written before nesting existed.
+        if (command.commands.length > 0) {
+            for (const child of command.commands)
+                visit(child, fullPath);
+            return;
+        }
+        commands.push({
+            name: fullPath.join(" "), description: command.description() ?? "",
+            arguments: command.registeredArguments.map((arg) => ({ name: arg.name(), required: arg.required, description: arg.description ?? "" })),
+            options: command.options.map((opt) => ({
+                flags: opt.flags, attributeName: opt.attributeName(), description: opt.description ?? "",
+                required: opt.mandatory, defaultValue: opt.defaultValue,
+                takesValue: opt.flags.includes("<") || opt.flags.includes("["),
+            })),
+        });
+    }
+    for (const command of program.commands)
+        visit(command, []);
+    return { name: program.name(), description: program.description() ?? "", commands };
+}
+/**
+ * Project a CLI manifest into string-valued MCP input schemas; boolean switches are omitted.
+ * @param required Manifest and caller-owned prefix (including any desired separator).
+ * @returns One tool per leaf command, with spaces in invocation paths replaced by underscores.
+ * @complexity O(c + f), for commands and argument/option fields.
+ */
+export function toMcpTools({ manifest, toolNamePrefix }) {
+    // argv supplies strings; numeric/enum validation belongs to command handlers, not this projection.
+    // Invocation paths remain space-separated in the manifest, but tool names must be single tokens.
+    return manifest.commands.map((command) => {
+        const properties = {};
+        const required = [];
+        for (const arg of command.arguments) {
+            Object.defineProperty(properties, arg.name, { value: { type: "string", description: arg.description }, enumerable: true, configurable: true, writable: true });
+            if (arg.required)
+                required.push(arg.name);
+        }
+        for (const option of command.options) {
+            if (!option.takesValue)
+                continue;
+            Object.defineProperty(properties, option.attributeName, { value: { type: "string", description: option.description }, enumerable: true, configurable: true, writable: true });
+            if (option.required)
+                required.push(option.attributeName);
+        }
+        return { name: `${toolNamePrefix}${command.name.replace(/\s+/g, "_")}`, description: command.description, inputSchema: { type: "object", properties, required } };
+    });
+}
+//# sourceMappingURL=introspection.js.map

package/dist/local-daemon-discovery.d.ts

@@ -1,20 +1,12 @@
 import type { ResolveDaemonUrlOptions } from './daemon-url.js';
-export interface LocalDaemonDiscoveryOptions {
-    /**
-     * The same `dataDir` the target `createLocalNodeDaemon({ dataDir, ... })` call was given. The
-     * registry path is derived from it via `@jini-ai/sidecar`'s `resolveDaemonRegistryPath` — the
-     * identical derivation `@jini-ai/server` uses for its own `discoveryFile` default. Ignored when
-     * `registryPath` is also given.
-     */
-    dataDir?: string;
-    /**
-     * The exact registry file path, for when the host overrode `createLocalNodeDaemon`'s
-     * `discoveryFile` away from its `dataDir`-derived default. Takes precedence over `dataDir`.
-     */
-    registryPath?: string;
-}
+/** Explicit registry path or the daemon data directory; neither is defaulted. */
+export type LocalDaemonDiscoveryOptions = {
+    registryPath: string;
+} | {
+    dataDir: string;
+};
 /**
- * Build a `resolveDaemonUrl({ discover })`-compatible probe backed by a local, on-disk daemon
+ * Build a `resolveDaemonUrl({}, { discover })`-compatible probe backed by a local, on-disk daemon
  * registry record: reads the record at the resolved registry path, confirms the recording
  * process's pid is still alive (a stale record left behind by a daemon that crashed rather than
  * shut down cleanly is never trusted — see `readLiveDaemonRegistryRecord`), and returns its