@vibesdotdev/cli 0.0.2 → 1.0.0-rc.2

package/dist/commands/docs/generate.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CLI Reference Doc Generator
+ *
+ * Walks the descriptor registry (the same one the production CLI boots from)
+ * and emits per-command reference markdown. Idempotent: re-running on a clean
+ * tree produces a byte-identical diff.
+ *
+ * Reference docs only — synopsis, arguments, options, examples. Narrative
+ * docs (HOW-TO, concepts) stay hand-authored and are not touched.
+ *
+ * Programmatic use:
+ *   const { filesWritten } = await generateCliDocs(runtime, { outDir });
+ *
+ * The runtime-bootstrap that loads the full aggregator plugin set
+ * (`bootDocsRuntime`) and the standalone `[--out <dir>]` CLI entrypoint live in
+ * the app tier at `apps/cli-bin/src/docs/generate.ts`, which depends on
+ * `@vibesdotdev/plugins`. This module stays free of the aggregator so
+ * `@vibesdotdev/cli` keeps no dependency edge to `@vibesdotdev/plugins`. It
+ * holds only the pure rendering + a runtime parameter the caller supplies.
+ *
+ * Every file operation goes through that runtime: its unbound host
+ * `filesystem/adapter` (the output directory is a host path the caller chose,
+ * never a workspace-bound one) and its path mechanics (`paths/runtime-path`).
+ */
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+export type { GenerateOptions, GenerateResult } from './schemas/generate.ts';
+import type { GenerateOptions, GenerateResult } from './schemas/generate.ts';
+/**
+ * Generate the CLI reference docs tree from a runtime that already has its
+ * plugin set registered. Caller is responsible for booting the runtime —
+ * keeps this function side-effect-free apart from the file writes.
+ */
+export declare function generateCliDocs(runtime: VibesRuntime, options: GenerateOptions): Promise<GenerateResult>;
+/**
+ * Sanity check used by the idempotency test: re-runs the generator into a
+ * temp directory and reads every produced file back into memory. Returns a
+ * map of relative-path → content so the test can compare against the
+ * checked-in tree without invoking `git diff` itself. Reads through the
+ * handed runtime's host filesystem; an absent `rootDir` is an empty map.
+ */
+export declare function readGeneratedDocs(runtime: VibesRuntime, rootDir: string): Promise<Map<string, string>>;
+/**
+ * Default output dir for the CLI entry point: `cli/docs-generated/`.
+ * Resolved from this module through the handed runtime's path mechanics, so
+ * the path is stable regardless of CWD.
+ */
+export declare function defaultOutDir(runtime: VibesRuntime): Promise<string>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/docs/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAMpE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,eAAe,GACtB,OAAO,CAAC,cAAc,CAAC,CAoDzB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAiB5G;AAUD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/commands/docs/generate.js

@@ -0,0 +1,121 @@
+/**
+ * CLI Reference Doc Generator
+ *
+ * Walks the descriptor registry (the same one the production CLI boots from)
+ * and emits per-command reference markdown. Idempotent: re-running on a clean
+ * tree produces a byte-identical diff.
+ *
+ * Reference docs only — synopsis, arguments, options, examples. Narrative
+ * docs (HOW-TO, concepts) stay hand-authored and are not touched.
+ *
+ * Programmatic use:
+ *   const { filesWritten } = await generateCliDocs(runtime, { outDir });
+ *
+ * The runtime-bootstrap that loads the full aggregator plugin set
+ * (`bootDocsRuntime`) and the standalone `[--out <dir>]` CLI entrypoint live in
+ * the app tier at `apps/cli-bin/src/docs/generate.ts`, which depends on
+ * `@vibesdotdev/plugins`. This module stays free of the aggregator so
+ * `@vibesdotdev/cli` keeps no dependency edge to `@vibesdotdev/plugins`. It
+ * holds only the pure rendering + a runtime parameter the caller supplies.
+ *
+ * Every file operation goes through that runtime: its unbound host
+ * `filesystem/adapter` (the output directory is a host path the caller chose,
+ * never a workspace-bound one) and its path mechanics (`paths/runtime-path`).
+ */
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem/client';
+import { getRuntimePath } from '@vibesdotdev/paths';
+import { getCLIDiscovery } from "../../surface/discovery-cache.js";
+import { commandDocPath, groupDocPath } from "./doc-paths.js";
+import { renderCommandPage } from "./render-command.js";
+import { renderGroupPage, renderTopLevelIndex } from "./render-group.js";
+/**
+ * Generate the CLI reference docs tree from a runtime that already has its
+ * plugin set registered. Caller is responsible for booting the runtime —
+ * keeps this function side-effect-free apart from the file writes.
+ */
+export async function generateCliDocs(runtime, options) {
+    const runtimePath = await getRuntimePath(runtime);
+    const outDir = runtimePath.resolve(options.outDir);
+    const discovery = getCLIDiscovery(runtime, { includeInternal: options.includeInternal ?? true });
+    // Build the set of all docs files we'll emit, in-memory. Only when the
+    // full map is built do we touch the filesystem — that way a generator
+    // failure mid-flight can't leave the tree half-written.
+    const files = new Map();
+    const sortedGroups = [...discovery.allGroups].sort((a, b) => a.id.localeCompare(b.id));
+    const sortedCommands = [...discovery.allCommands].sort((a, b) => a.id.localeCompare(b.id));
+    const groupsById = discovery.groupsById;
+    // Per-command pages.
+    for (const command of sortedCommands) {
+        const relPath = commandDocPath(command, groupsById);
+        files.set(relPath, renderCommandPage(command, groupsById));
+    }
+    // Per-group index pages (commands in this group + nested subgroups).
+    for (const group of sortedGroups) {
+        const relPath = groupDocPath(group, groupsById);
+        files.set(relPath, renderGroupPage(group, sortedGroups, sortedCommands, groupsById));
+    }
+    // Top-level index.
+    files.set('README.md', renderTopLevelIndex(sortedGroups, sortedCommands, groupsById));
+    const fs = await resolveFileSystemAdapter(runtime, { binding: false });
+    // Reset the output dir so removed commands disappear from the tree.
+    if (await fs.exists(outDir)) {
+        await fs.remove(outDir, { recursive: true });
+    }
+    await fs.mkdir(outDir, { recursive: true });
+    // Write all files. Sort the keys (code-unit order) for stable ordering of mkdir calls.
+    const written = [];
+    for (const [relPath, content] of [...files.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        const abs = runtimePath.join(outDir, relPath);
+        await fs.mkdir(runtimePath.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, content, 'utf8');
+        written.push(relPath);
+    }
+    return {
+        outDir,
+        filesWritten: written,
+        commandsDocumented: sortedCommands.length,
+        groupsDocumented: sortedGroups.length
+    };
+}
+/**
+ * Sanity check used by the idempotency test: re-runs the generator into a
+ * temp directory and reads every produced file back into memory. Returns a
+ * map of relative-path → content so the test can compare against the
+ * checked-in tree without invoking `git diff` itself. Reads through the
+ * handed runtime's host filesystem; an absent `rootDir` is an empty map.
+ */
+export async function readGeneratedDocs(runtime, rootDir) {
+    const runtimePath = await getRuntimePath(runtime);
+    const fs = await resolveFileSystemAdapter(runtime, { binding: false });
+    const out = new Map();
+    if (!(await fs.exists(rootDir)))
+        return out;
+    async function walk(dir) {
+        for (const entry of await fs.list(dir)) {
+            const abs = runtimePath.join(dir, entry.name);
+            if (entry.kind === 'directory') {
+                await walk(abs);
+            }
+            else if (entry.kind === 'file' && entry.name.endsWith('.md')) {
+                out.set(runtimePath.relative(rootDir, abs), await readText(fs, abs));
+            }
+        }
+    }
+    await walk(rootDir);
+    return out;
+}
+async function readText(fs, path) {
+    const raw = await fs.readFile(path, 'utf8');
+    return raw instanceof Uint8Array ? new TextDecoder().decode(raw) : raw;
+}
+/** The checked-in generated tree, `cli/docs-generated/`, located from this module. */
+const GENERATED_DOCS_URL = new URL('../../../docs-generated', import.meta.url);
+/**
+ * Default output dir for the CLI entry point: `cli/docs-generated/`.
+ * Resolved from this module through the handed runtime's path mechanics, so
+ * the path is stable regardless of CWD.
+ */
+export async function defaultOutDir(runtime) {
+    return (await getRuntimePath(runtime)).fileURLToPath(GENERATED_DOCS_URL.href);
+}
+//# sourceMappingURL=generate.js.map

package/dist/commands/docs/generate.js.map

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

package/dist/commands/docs/render-command.d.ts

@@ -0,0 +1,5 @@
+/** Per-command reference pages: synopsis, aliases, argument and option tables, examples. */
+import type { CLICommandAssetDescriptor, CLIGroupAssetDescriptor } from '../../schemas/descriptors.ts';
+export declare function renderCommandPage(command: CLICommandAssetDescriptor, groupsById: Map<string, CLIGroupAssetDescriptor>): string;
+export declare function safeCell(value: string): string;
+//# sourceMappingURL=render-command.d.ts.map

package/dist/commands/docs/render-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-command.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/render-command.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,OAAO,KAAK,EAEX,yBAAyB,EAGzB,uBAAuB,EACvB,MAAM,8BAA8B,CAAC;AAGtC,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,GAC9C,MAAM,CAkER;AAyDD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/commands/docs/render-command.js

@@ -0,0 +1,117 @@
+import { commandInvocation } from "./doc-paths.js";
+export function renderCommandPage(command, groupsById) {
+    const invocation = commandInvocation(command, groupsById);
+    const lines = [];
+    lines.push(`# \`${invocation}\``);
+    lines.push('');
+    lines.push('> Reference doc generated from `cli/command` descriptor — do not edit by hand.');
+    lines.push(`> Source descriptor id: \`${command.id}\``);
+    lines.push('');
+    lines.push(command.description.trim());
+    lines.push('');
+    lines.push('## Synopsis');
+    lines.push('');
+    lines.push('```');
+    lines.push(renderSynopsis(invocation, command));
+    lines.push('```');
+    lines.push('');
+    if (command.aliases && command.aliases.length > 0) {
+        lines.push('## Aliases');
+        lines.push('');
+        for (const alias of [...command.aliases].sort()) {
+            lines.push(`- \`${alias}\``);
+        }
+        lines.push('');
+    }
+    if (command.arguments && command.arguments.length > 0) {
+        lines.push('## Arguments');
+        lines.push('');
+        lines.push(renderArgumentsTable(command.arguments));
+        lines.push('');
+    }
+    if (command.options && command.options.length > 0) {
+        lines.push('## Options');
+        lines.push('');
+        lines.push(renderOptionsTable(command.options));
+        lines.push('');
+    }
+    if (command.examples && command.examples.length > 0) {
+        lines.push('## Examples');
+        lines.push('');
+        for (const example of command.examples) {
+            lines.push(renderExample(example));
+            lines.push('');
+        }
+    }
+    if (command.surfaces && command.surfaces.length > 0) {
+        lines.push('## Surfaces');
+        lines.push('');
+        lines.push([...command.surfaces].sort().map((s) => `\`${s}\``).join(', '));
+        lines.push('');
+    }
+    if (command.internal === true) {
+        lines.push('## Visibility');
+        lines.push('');
+        lines.push('`internal` — hidden from default CLI help; available when the CLI surface opts in.');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function renderSynopsis(invocation, command) {
+    const parts = [invocation];
+    if (command.options && command.options.length > 0)
+        parts.push('[options]');
+    for (const arg of command.arguments ?? []) {
+        const name = arg.variadic ? `${arg.name}...` : arg.name;
+        parts.push(arg.required ? `<${name}>` : `[${name}]`);
+    }
+    return parts.join(' ');
+}
+function renderArgumentsTable(args) {
+    const header = '| Name | Required | Variadic | Default | Description |';
+    const sep = '|------|----------|----------|---------|-------------|';
+    const rows = args.map((arg) => {
+        const def = arg.default === undefined ? '' : '`' + safeCell(JSON.stringify(arg.default)) + '`';
+        return `| \`${safeCell(arg.name)}\` | ${arg.required ? 'yes' : 'no'} | ${arg.variadic ? 'yes' : 'no'} | ${def} | ${safeCell(arg.description)} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}
+function renderOptionsTable(options) {
+    const header = '| Flag | Type | Choices | Default | Description |';
+    const sep = '|------|------|---------|---------|-------------|';
+    const sorted = [...options].sort((a, b) => a.flags.localeCompare(b.flags));
+    const rows = sorted.map((opt) => {
+        const choices = opt.choices && opt.choices.length > 0
+            ? opt.choices.map((c) => '`' + safeCell(c) + '`').join(', ')
+            : '';
+        const def = opt.default === undefined ? '' : '`' + safeCell(JSON.stringify(opt.default)) + '`';
+        const type = opt.type ?? '';
+        return `| \`${safeCell(opt.flags)}\` | ${type} | ${choices} | ${def} | ${safeCell(opt.description)} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}
+function renderExample(example) {
+    const lines = [];
+    lines.push(`### ${example.description.trim()}`);
+    lines.push('');
+    lines.push('```sh');
+    lines.push(example.command.trim());
+    lines.push('```');
+    const tags = [];
+    if (example.expectExit !== undefined)
+        tags.push(`exit ${example.expectExit}`);
+    if (example.expectStdoutContains !== undefined) {
+        tags.push(`stdout contains ${'`' + safeCell(example.expectStdoutContains) + '`'}`);
+    }
+    if (example.slow)
+        tags.push('slow (gated behind `VIBES_DOCS_TEST_SLOW=1`)');
+    if (tags.length > 0) {
+        lines.push('');
+        lines.push(`*Verified: ${tags.join('; ')}.*`);
+    }
+    return lines.join('\n');
+}
+export function safeCell(value) {
+    return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+//# sourceMappingURL=render-command.js.map

package/dist/commands/docs/render-command.js.map

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

package/dist/commands/docs/render-group.d.ts

@@ -0,0 +1,5 @@
+/** Group index pages and the docs tree's top-level README. */
+import type { CLICommandAssetDescriptor, CLIGroupAssetDescriptor } from '../../schemas/descriptors.ts';
+export declare function renderGroupPage(group: CLIGroupAssetDescriptor, allGroups: readonly CLIGroupAssetDescriptor[], allCommands: readonly CLICommandAssetDescriptor[], groupsById: Map<string, CLIGroupAssetDescriptor>): string;
+export declare function renderTopLevelIndex(allGroups: readonly CLIGroupAssetDescriptor[], allCommands: readonly CLICommandAssetDescriptor[], _groupsById: Map<string, CLIGroupAssetDescriptor>): string;
+//# sourceMappingURL=render-group.d.ts.map

package/dist/commands/docs/render-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-group.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/render-group.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvG,wBAAgB,eAAe,CAC9B,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,WAAW,EAAE,SAAS,yBAAyB,EAAE,EACjD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,GAC9C,MAAM,CA4CR;AAED,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,SAAS,uBAAuB,EAAE,EAC7C,WAAW,EAAE,SAAS,yBAAyB,EAAE,EACjD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,GAC/C,MAAM,CAoBR"}

package/dist/commands/docs/render-group.js

@@ -0,0 +1,62 @@
+import { groupPathSegments, sanitizeForPath } from "./doc-paths.js";
+export function renderGroupPage(group, allGroups, allCommands, groupsById) {
+    const path = groupPathSegments(group, groupsById);
+    const lines = [];
+    lines.push(`# \`vibes ${path.join(' ')}\``);
+    lines.push('');
+    lines.push('> Reference doc generated from `cli/group` descriptor.');
+    lines.push(`> Source descriptor id: \`${group.id}\``);
+    lines.push('');
+    lines.push(group.description.trim());
+    lines.push('');
+    const childGroups = allGroups.filter((g) => g.parent === group.id);
+    const childCommands = allCommands.filter((c) => c.group === group.id);
+    if (childCommands.length > 0) {
+        lines.push('## Commands');
+        lines.push('');
+        for (const cmd of [...childCommands].sort((a, b) => a.name.localeCompare(b.name))) {
+            const cmdRel = encodeURI(`./${sanitizeForPath(cmd.name)}.md`);
+            lines.push(`- [\`${cmd.name}\`](${cmdRel}) — ${cmd.description.trim()}`);
+        }
+        lines.push('');
+    }
+    if (childGroups.length > 0) {
+        lines.push('## Subgroups');
+        lines.push('');
+        for (const sub of [...childGroups].sort((a, b) => a.name.localeCompare(b.name))) {
+            const subRel = encodeURI(`./${sub.name}/README.md`);
+            lines.push(`- [\`${sub.name}\`](${subRel}) — ${sub.description.trim()}`);
+        }
+        lines.push('');
+    }
+    if (group.aliases && group.aliases.length > 0) {
+        lines.push('## Aliases');
+        lines.push('');
+        for (const alias of [...group.aliases].sort()) {
+            lines.push(`- \`${alias}\``);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderTopLevelIndex(allGroups, allCommands, _groupsById) {
+    const topLevelGroups = [...allGroups]
+        .filter((g) => !g.parent)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const lines = [];
+    lines.push('# Vibes CLI — Reference');
+    lines.push('');
+    lines.push('> Generated from the `cli/group` and `cli/command` descriptor registry.');
+    lines.push(`> Groups: **${allGroups.length}** · Commands: **${allCommands.length}**`);
+    lines.push('');
+    lines.push('Run `bun run --cwd repos/apps/cli-bin docs:generate` from the developer repository to refresh this tree.');
+    lines.push('');
+    lines.push('## Top-level groups');
+    lines.push('');
+    for (const group of topLevelGroups) {
+        lines.push(`- [\`${group.name}\`](${encodeURI(`./commands/${group.name}/README.md`)}) — ${group.description.trim()}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=render-group.js.map

package/dist/commands/docs/render-group.js.map

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

package/dist/commands/docs/schemas/generate.d.ts

@@ -0,0 +1,14 @@
+/** Docs-generation contracts: options for one run and the counts it reports. */
+export interface GenerateOptions {
+    /** Absolute path to the output directory (will be created / overwritten). */
+    outDir: string;
+    /** Include `internal: true` descriptors (default: true — these are linkable for contributors). */
+    includeInternal?: boolean;
+}
+export interface GenerateResult {
+    outDir: string;
+    filesWritten: string[];
+    commandsDocumented: number;
+    groupsDocumented: number;
+}
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/docs/schemas/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/schemas/generate.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,WAAW,eAAe;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CACzB"}

package/dist/commands/docs/schemas/generate.js

@@ -0,0 +1,3 @@
+/** Docs-generation contracts: options for one run and the counts it reports. */
+export {};
+//# sourceMappingURL=generate.js.map

package/dist/commands/docs/schemas/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../../src/commands/docs/schemas/generate.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

package/dist/commands/output.d.ts

@@ -0,0 +1,27 @@
+export type { CommandOutputRuntime, CommandWriters, OutputOptions } from './schemas/output.ts';
+import type { CommandOutputRuntime, CommandWriters, OutputOptions } from './schemas/output.ts';
+import type { CliHostOutput } from '../boot/schemas/providers.ts';
+/** The handed runtime's stdout and stderr writers; a runtime with no text output refuses `UNAVAILABLE` `stdio-unavailable`. */
+export declare function commandWriters(runtime: CommandOutputRuntime): Promise<CommandWriters>;
+/** Write `content` to the handed runtime's stdout. */
+export declare function writeStdout(runtime: CommandOutputRuntime, content: string): Promise<void>;
+/** Write a line through the handed runtime, or an explicit executable-owned surface sink. */
+export declare function writeStdoutLine(runtime: CommandOutputRuntime, content: string, hostOutput?: CliHostOutput): Promise<void>;
+/** Whether the handed runtime's current invocation wrote its JSON document. */
+export declare function hasWrittenJsonPayload(runtime: CommandOutputRuntime): boolean;
+/** Open a new invocation on the handed runtime: its lifetime and output accounting start empty. */
+export declare function beginJsonPayloadLedger(runtime: CommandOutputRuntime): Promise<void>;
+/** Clear only the handed runtime's JSON document entry. */
+export declare function resetJsonPayloadLedger(runtime: CommandOutputRuntime): void;
+/**
+ * Write `payload` as the handed runtime's invocation JSON document.
+ *
+ * The runtime is validated before any byte is written: a first argument without
+ * the output surface, or options outside their schema, refuses `INVALID_INPUT`
+ * `cli-output-runtime-invalid` with nothing written and no accounting recorded.
+ * The document is recorded only once delivery (write and flush) succeeded.
+ */
+export declare function writeJson<Payload>(runtime: CommandOutputRuntime, payload: Payload, options?: OutputOptions): Promise<void>;
+/** Write rendered JSON once; record delivery only after the selected sink has flushed. */
+export declare function writeRenderedJson(runtime: CommandOutputRuntime, document: string, hostOutput?: CliHostOutput): Promise<void>;
+//# sourceMappingURL=output.d.ts.map

package/dist/commands/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/commands/output.ts"],"names":[],"mappings":"AAoBA,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAalE,+HAA+H;AAC/H,wBAAsB,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAO3F;AAED,sDAAsD;AACtD,wBAAsB,WAAW,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,6FAA6F;AAC7F,wBAAsB,eAAe,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/H;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAE5E;AAED,mGAAmG;AACnG,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAE1E;AAWD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAahI;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlI"}

package/dist/commands/output.js

@@ -0,0 +1,104 @@
+/**
+ * A command's stdout. Every writer is handed the runtime whose output it uses:
+ * bytes go through that runtime's host text output (`runtime/stdio`) and the
+ * call settles once the host's output plane has joined them (when the host has
+ * one), so the bytes are out before the host exits; a write or flush failure
+ * rejects unchanged. A runtime with no text output refuses `UNAVAILABLE`
+ * `stdio-unavailable`.
+ *
+ * JSON accounting is per runtime and per invocation: the ledger entry only the
+ * handed runtime's invocation moves, so one runtime's document never redirects
+ * another runtime's failure envelope. `resetJsonPayloadLedger(runtime)` clears
+ * one runtime's entry; `beginJsonPayloadLedger(runtime)` opens a new invocation
+ * on it. A runtime that has not booted has no ledger and no output: free text
+ * before boot comes from the public host output owner
+ * `@vibesdotdev/host-node/stdio` (`createNodeRuntimeStdio`).
+ */
+import { CapabilityError, getRuntimeStdio, getRuntimeStdioOutputPlane, hasRuntimeStdioOutputPlane } from '@vibesdotdev/kernel';
+import { OutputRuntimeFormSchema as RuntimeFormSchema } from "./schemas/output.js";
+import { getCLIInvocationClient, tryCLIInvocationClient } from "../invocation/state.js";
+/** Join an explicit surface sink, or the handed runtime's output plane when none was supplied. */
+async function writeThroughRuntime(runtime, content, hostOutput) {
+    if (hostOutput) {
+        hostOutput.write('stdout', content);
+        await hostOutput.flush();
+        return;
+    }
+    (await getRuntimeStdio(runtime)).write('stdout', content);
+    if (await hasRuntimeStdioOutputPlane(runtime))
+        await (await getRuntimeStdioOutputPlane(runtime)).flush();
+}
+/** The handed runtime's stdout and stderr writers; a runtime with no text output refuses `UNAVAILABLE` `stdio-unavailable`. */
+export async function commandWriters(runtime) {
+    const stdio = await getRuntimeStdio(runtime);
+    return {
+        out: (text) => stdio.write('stdout', text),
+        err: (text) => stdio.write('stderr', text),
+        log: (line) => stdio.write('stderr', `${line}\n`)
+    };
+}
+/** Write `content` to the handed runtime's stdout. */
+export async function writeStdout(runtime, content) {
+    await writeThroughRuntime(runtime, content);
+}
+/** Write a line through the handed runtime, or an explicit executable-owned surface sink. */
+export async function writeStdoutLine(runtime, content, hostOutput) {
+    await writeThroughRuntime(runtime, `${content}\n`, hostOutput);
+}
+/** Whether the handed runtime's current invocation wrote its JSON document. */
+export function hasWrittenJsonPayload(runtime) {
+    return tryCLIInvocationClient(runtime)?.hasWrittenJsonPayload() ?? false;
+}
+/** Open a new invocation on the handed runtime: its lifetime and output accounting start empty. */
+export async function beginJsonPayloadLedger(runtime) {
+    await (await getCLIInvocationClient(runtime)).begin();
+}
+/** Clear only the handed runtime's JSON document entry. */
+export function resetJsonPayloadLedger(runtime) {
+    tryCLIInvocationClient(runtime)?.resetJsonPayload();
+}
+/** Serialize `payload` as the one JSON document; `undefined` cannot be one. */
+function serializeJson(payload, options) {
+    const serialized = JSON.stringify(payload, null, options.pretty === false ? 0 : 2);
+    if (serialized === undefined) {
+        throw new Error('Cannot write undefined as JSON output');
+    }
+    return serialized;
+}
+/**
+ * Write `payload` as the handed runtime's invocation JSON document.
+ *
+ * The runtime is validated before any byte is written: a first argument without
+ * the output surface, or options outside their schema, refuses `INVALID_INPUT`
+ * `cli-output-runtime-invalid` with nothing written and no accounting recorded.
+ * The document is recorded only once delivery (write and flush) succeeded.
+ */
+export async function writeJson(runtime, payload, options) {
+    const form = RuntimeFormSchema.safeParse([runtime, payload, options]);
+    if (!form.success) {
+        throw new CapabilityError('writeJson was handed a runtime that cannot host command output, or options outside its schema.', 'INVALID_INPUT', {
+            reason: 'cli-output-runtime-invalid',
+            retryable: false,
+            details: { issues: form.error.issues.map((issue) => issue.path.join('.')) }
+        });
+    }
+    const [, , parsedOptions] = form.data;
+    const state = await getCLIInvocationClient(runtime);
+    await writeThroughRuntime(runtime, `${serializeJson(payload, parsedOptions ?? {})}\n`);
+    state.recordJsonPayload();
+}
+/** Write rendered JSON once; record delivery only after the selected sink has flushed. */
+export async function writeRenderedJson(runtime, document, hostOutput) {
+    const form = RuntimeFormSchema.safeParse([runtime, document, undefined]);
+    if (!form.success) {
+        throw new CapabilityError('writeRenderedJson was handed a runtime that cannot host command output.', 'INVALID_INPUT', {
+            reason: 'cli-output-runtime-invalid',
+            retryable: false,
+            details: { issues: form.error.issues.map((issue) => issue.path.join('.')) }
+        });
+    }
+    const state = await getCLIInvocationClient(runtime);
+    await writeThroughRuntime(runtime, `${document}\n`, hostOutput);
+    state.recordJsonPayload();
+}
+//# sourceMappingURL=output.js.map

package/dist/commands/output.js.map

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