@vibesdotdev/cli 0.0.1 → 1.0.0-rc.2

package/dist/surface/failure-report.js

@@ -0,0 +1,229 @@
+/**
+ * The one print form of a CLI failure.
+ *
+ * Every path that prints a failure (a command failure in `CLISurface.run`, the
+ * exit-boundary disposal, a host bootstrap failure, a skipped telemetry emit
+ * under `-v`) renders it here, so they cannot disagree about what is shown:
+ *
+ * - The failure is described once by Logging's redaction walk
+ *   (`LoggedErrorSchema`): total for any thrown value (throwing getters,
+ *   Proxies, cycles), with credential-named keys and `secret()` values in
+ *   details, fields and causes redacted; retained `AggregateError` members and
+ *   causes are described within Logging's depth and breadth bounds.
+ * - Each retained `AggregateError` member, including nested aggregates, is
+ *   listed with its `details.pluginId` and its retained cause chain. By default each member and cause is value-free: its
+ *   `code`/`reason` when typed, else `Untyped failure: <class name>`, never its
+ *   message. `-v` lists each member's stack or message and the full chain.
+ *   "Runtime disposal failed for 1 plugin" therefore names the plugin and why.
+ * - Known typed refusals get friendly text by code and reason
+ *   ({@link mapKnownError}); nothing parses a message.
+ * - The whole text then passes Logging's one-pass credential scrubber with the
+ *   credential values the host env carries (keys Logging's `isSecretKey` calls
+ *   secret), in normal and verbose modes alike.
+ */
+import * as z from 'zod/v4';
+import { createEndpointTextSchema, isSecretKey, LoggedErrorSchema } from '@vibesdotdev/logging';
+import { isCapabilityErrorCode } from '@vibesdotdev/kernel';
+/** What a failure description is read as: the detached JSON the redaction walk produced. */
+const DescriptionSchema = z.object({
+    name: z.string(),
+    message: z.string(),
+    code: z.union([z.string(), z.number()]).optional(),
+    reason: z.string().optional(),
+    details: z.unknown().optional(),
+    fields: z.record(z.string(), z.unknown()).optional(),
+    stack: z.string().optional(),
+    cause: z.unknown().optional(),
+    errors: z.array(z.unknown()).optional()
+});
+const PluginDetailsSchema = z.object({ pluginId: z.string() });
+const NotRegisteredDetailsSchema = z.object({ kind: z.string(), id: z.string().optional() });
+const AdapterDetailsSchema = z.object({ ownerId: z.string(), allowedAdapters: z.array(z.string()) });
+const RecoveryHintSchema = z.object({ recoveryHint: z.string().min(1) });
+/** How deep a cause chain is printed: the redaction walk itself stops at five. */
+const MAX_PRINTED_CAUSES = 5;
+/**
+ * A host env value shorter than this is not scrubbed from failure text: a
+ * credential is long, and replacing every short value (`true`, `1`) under a
+ * credential-named key would rewrite ordinary words.
+ */
+export const MIN_SCRUBBED_CREDENTIAL_LENGTH = 8;
+/** The credential values an env carries: values of keys Logging calls secret, long enough to be a credential. */
+export function credentialValuesOf(env) {
+    if (env === undefined)
+        return [];
+    const values = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined || !isSecretKey(key))
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length >= MIN_SCRUBBED_CREDENTIAL_LENGTH)
+            values.push(trimmed);
+    }
+    return values;
+}
+/** Remove every credential value `env` carries from `text` (Logging's scrubber; it never throws). */
+export function scrubCliText(text, env) {
+    const values = credentialValuesOf(env);
+    if (values.length === 0)
+        return text;
+    return createEndpointTextSchema('', values).parse(text);
+}
+/**
+ * The total, redacted description of a caught failure (a catch site parses
+ * its binding with the runtime's `CaughtFailureSchema`): an `Error` is
+ * described itself, any other thrown value is described as the value it was.
+ */
+export function describeCliFailure(failure) {
+    const described = LoggedErrorSchema.parse(failure instanceof Error ? failure : failure.value);
+    const parsed = DescriptionSchema.safeParse(described);
+    return parsed.success ? parsed.data : { name: described.name, message: described.message };
+}
+/** Drop frames pointing into the `bun build --compile` virtual filesystem; they are not actionable. */
+export function stripBundlePaths(text) {
+    return text
+        .split('\n')
+        .filter((line) => !line.includes('/$bunfs/') && !line.includes('B:/~BUN/'))
+        .join('\n')
+        .trim();
+}
+/**
+ * Friendly text for the typed refusals a user can act on, chosen by code and
+ * reason only. `null` when no mapping applies (the caller prints the message).
+ */
+export function mapKnownError(failure) {
+    return mapDescription(describeCliFailure(failure));
+}
+function mapDescription(failure) {
+    const { code, reason } = failure;
+    if (code === 'NOT_FOUND' && reason === 'not-registered') {
+        const subject = NotRegisteredDetailsSchema.safeParse(failure.details);
+        const target = subject.success ? `${subject.data.kind}${subject.data.id === undefined ? '' : `#${subject.data.id}`}` : undefined;
+        return (`${target === undefined ? 'A required capability' : `"${target}"`} is not registered in this build or scope.\n` +
+            'Update the CLI (or run it where the needed plugin is registered), ' +
+            'or run with -v for the underlying resolution error.');
+    }
+    if ((code === 'INTERNAL' && reason === 'dependency-absent') ||
+        (code === 'NOT_FOUND' && (reason === 'config-manifest-unregistered' || reason === 'storage-manifest-not-registered'))) {
+        return ("This command isn't available in this build or scope.\n" +
+            'Update the CLI (or run it where the needed plugin is registered), ' +
+            'or run with -v for the underlying resolution error.');
+    }
+    if (code === 'UNAVAILABLE' && reason === 'storage-adapter-absent') {
+        const adapter = AdapterDetailsSchema.safeParse(failure.details);
+        const subject = adapter.success
+            ? `"${adapter.data.ownerId}" (checked: ${adapter.data.allowedAdapters.join(', ')})`
+            : 'this record';
+        return (`No storage adapter is initialized for ${subject}.\n` +
+            'Run `vibes os init` to set up local storage, or run with -v for details.');
+    }
+    if (code === 'NOT_FOUND' && reason === 'runtime-path-unavailable') {
+        return ('The runtime path service has not been initialized yet. ' +
+            'This is a bug — please report it. Run with -v for the full stack.');
+    }
+    return null;
+}
+/** ` [CODE reason]` for a typed description, or nothing. */
+function typedTag(failure) {
+    if (failure.code === undefined && failure.reason === undefined)
+        return '';
+    const parts = [failure.code === undefined ? undefined : String(failure.code), failure.reason].filter((part) => part !== undefined && part !== '');
+    return parts.length === 0 ? '' : ` [${parts.join(' ')}]`;
+}
+/** ` (plugin <id>)` when the description's details name one. */
+function pluginTag(failure) {
+    const plugin = PluginDetailsSchema.safeParse(failure.details);
+    return plugin.success ? ` (plugin ${plugin.data.pluginId})` : '';
+}
+/** The described causes of a description, nearest first, up to the print cap. */
+function causeChain(failure) {
+    const chain = [];
+    let cursor = failure.cause;
+    while (cursor !== undefined && chain.length < MAX_PRINTED_CAUSES) {
+        const cause = DescriptionSchema.safeParse(cursor);
+        if (!cause.success)
+            break;
+        chain.push(cause.data);
+        cursor = cause.data.cause;
+    }
+    return chain;
+}
+function describedMembers(failure) {
+    return (failure.errors ?? []).map((member) => {
+        const parsed = DescriptionSchema.safeParse(member);
+        return parsed.success ? parsed.data : { name: 'Error', message: 'An aggregate member could not be described.' };
+    });
+}
+/** `text` with `tag` appended to its first line (a stack's head line), so tags never trail the frames. */
+function tagFirstLine(text, tag) {
+    const newline = text.indexOf('\n');
+    return newline === -1 ? `${text}${tag}` : `${text.slice(0, newline)}${tag}${text.slice(newline)}`;
+}
+/** A typed description's bounded facts: a taxonomy code and a kebab-case reason. */
+const TypedFactsSchema = z.object({
+    code: z.string().refine(isCapabilityErrorCode),
+    reason: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)
+});
+/** A class name as a thrown class carries it; any other text is not printed as a name. */
+const ClassNameSchema = z.string().regex(/^[A-Z][A-Za-z0-9]{0,62}(Error|Exception)$/).catch('Error');
+/**
+ * A member or cause without its text, for the default (non-verbose) report:
+ * its code and reason when typed, else `Untyped failure: <class name>`. Its
+ * message is never printed, because an untyped one can carry the input.
+ */
+function valueFreeText(failure) {
+    const typed = TypedFactsSchema.safeParse(failure);
+    return typed.success ? `${typed.data.code} ${typed.data.reason}` : `Untyped failure: ${ClassNameSchema.parse(failure.name)}`;
+}
+function memberLines(member, verbose, indent = '  ') {
+    const text = verbose
+        ? tagFirstLine(member.stack?.trim() || member.message, `${typedTag(member)}${pluginTag(member)}`)
+        : `${valueFreeText(member)}${pluginTag(member)}`;
+    const lines = [`${indent}- ${text}`];
+    // Logging already bounded and detached this tree; render its members at every level.
+    for (const child of describedMembers(member))
+        lines.push(...memberLines(child, verbose, `${indent}    `));
+    for (const cause of causeChain(member)) {
+        const text = verbose
+            ? tagFirstLine(cause.stack?.trim() || `${cause.name}: ${cause.message}`, `${typedTag(cause)}${pluginTag(cause)}`)
+            : `${valueFreeText(cause)}${pluginTag(cause)}`;
+        lines.push(`${indent}    caused by: ${text}`);
+        for (const child of describedMembers(cause))
+            lines.push(...memberLines(child, verbose, `${indent}      `));
+    }
+    return lines;
+}
+/**
+ * The printable text of a failure (see the module comment). Never throws and
+ * never returns raw thrown text: every line is described, then scrubbed.
+ */
+export function renderCliFailure(caught, options) {
+    const failure = describeCliFailure(caught);
+    const lines = [];
+    if (options.verbose) {
+        lines.push(tagFirstLine(failure.stack?.trim() || failure.message.trim() || failure.name, typedTag(failure)));
+    }
+    else {
+        const friendly = mapDescription(failure);
+        lines.push(stripBundlePaths(friendly ?? failure.message));
+        const hint = RecoveryHintSchema.safeParse(failure.fields);
+        if (friendly === null && hint.success)
+            lines.push(hint.data.recoveryHint);
+    }
+    for (const cause of causeChain(failure)) {
+        const members = describedMembers(cause);
+        if (options.verbose) {
+            lines.push(`caused by: ${tagFirstLine(cause.stack?.trim() || `${cause.name}: ${cause.message}`, `${typedTag(cause)}${pluginTag(cause)}`)}`);
+        }
+        else {
+            lines.push(`caused by: ${valueFreeText(cause)}${pluginTag(cause)}`);
+        }
+        for (const member of members)
+            lines.push(...memberLines(member, options.verbose));
+    }
+    for (const member of describedMembers(failure))
+        lines.push(...memberLines(member, options.verbose));
+    const text = lines.filter((line) => line.trim() !== '').join('\n');
+    return scrubCliText(text, options.env);
+}
+//# sourceMappingURL=failure-report.js.map

package/dist/surface/failure-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-report.js","sourceRoot":"","sources":["../../src/surface/failure-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,WAAW,EAAE,iBAAiB,EAAoB,MAAM,sBAAsB,CAAC;AAClH,OAAO,EAAE,qBAAqB,EAAsB,MAAM,qBAAqB,CAAC;AAEhF,4FAA4F;AAC5F,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAGH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC/D,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC7F,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AACrG,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAEzE,kFAAkF;AAClF,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAahD,iHAAiH;AACjH,MAAM,UAAU,kBAAkB,CAAC,GAA6D;IAC/F,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;YAAE,SAAS;QACvD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,IAAI,8BAA8B;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,GAA6D;IACvG,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,wBAAwB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACxD,MAAM,SAAS,GAAgB,iBAAiB,CAAC,KAAK,CAAC,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3G,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;AAC5F,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC5C,OAAO,IAAI;SACT,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;SAC1E,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;AACV,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB;IACnD,OAAO,cAAc,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,cAAc,CAAC,OAAoB;IAC3C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACjC,IAAI,IAAI,KAAK,WAAW,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QACzD,MAAM,OAAO,GAAG,0BAA0B,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACjI,OAAO,CACN,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,8CAA8C;YAC/G,oEAAoE;YACpE,qDAAqD,CACrD,CAAC;IACH,CAAC;IACD,IACC,CAAC,IAAI,KAAK,UAAU,IAAI,MAAM,KAAK,mBAAmB,CAAC;QACvD,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,MAAM,KAAK,8BAA8B,IAAI,MAAM,KAAK,iCAAiC,CAAC,CAAC,EACpH,CAAC;QACF,OAAO,CACN,wDAAwD;YACxD,oEAAoE;YACpE,qDAAqD,CACrD,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,aAAa,IAAI,MAAM,KAAK,wBAAwB,EAAE,CAAC;QACnE,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO;YAC9B,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,eAAe,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YACnF,CAAC,CAAC,aAAa,CAAC;QACjB,OAAO,CACN,yCAAyC,OAAO,KAAK;YACrD,0EAA0E,CAC1E,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,WAAW,IAAI,MAAM,KAAK,0BAA0B,EAAE,CAAC;QACnE,OAAO,CACN,yDAAyD;YACzD,mEAAmE,CACnE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,4DAA4D;AAC5D,SAAS,QAAQ,CAAC,OAAoB;IACrC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1E,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CACnG,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAC3D,CAAC;IACF,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC1D,CAAC;AAED,gEAAgE;AAChE,SAAS,SAAS,CAAC,OAAoB;IACtC,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,iFAAiF;AACjF,SAAS,UAAU,CAAC,OAAoB;IACvC,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAY,OAAO,CAAC,KAAK,CAAC;IACpC,OAAO,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QAClE,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,MAAM;QAC1B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAoB;IAC7C,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;IACjH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,0GAA0G;AAC1G,SAAS,YAAY,CAAC,IAAY,EAAE,GAAW;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;AACnG,CAAC;AAED,oFAAoF;AACpF,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC;CAClD,CAAC,CAAC;AAEH,0FAA0F;AAC1F,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAErG;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAoB;IAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,oBAAoB,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;AAC9H,CAAC;AAED,SAAS,WAAW,CAAC,MAAmB,EAAE,OAAgB,EAAE,MAAM,GAAG,IAAI;IACxE,MAAM,IAAI,GAAG,OAAO;QACnB,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACjG,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IAClD,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;IACrC,qFAAqF;IACrF,KAAK,MAAM,KAAK,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,CAAC,CAAC;IAC1G,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,OAAO;YACnB,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACjH,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,kBAAkB,IAAI,EAAE,CAAC,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ,CAAC,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAqB,EAAE,OAAgC;IACvF,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9G,CAAC;SAAM,CAAC;QACP,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3E,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,cAAc,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7I,CAAC;aAAM,CAAC;YACP,KAAK,CAAC,IAAI,CAAC,cAAc,aAAa,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACpG,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnE,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC"}

package/dist/surface/group-fallback.d.ts

@@ -0,0 +1,32 @@
+/** Group-command fallbacks: output-format normalization, unknown-subcommand refusal, and group help emission. */
+import type { Command } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import type { CommandOptions } from '../schemas/surface.ts';
+/**
+ * `--json` and `--format json` are ONE contract. Impls read whichever they
+ * were written against, so both spellings must land in both fields:
+ * `--json` → `format='json'`, `--format json` → `json=true`.
+ */
+export declare function normalizeOutputFormatOptions(options: CommandOptions): void;
+export declare function wantsJsonOutput(options: CommandOptions): boolean;
+/**
+ * A group with an action handler is dispatched by Commander even when its
+ * operands match no subcommand — the action fires and the operands are
+ * checked against the group's own (empty) argument list, which is how
+ * `vibes pm describe x` produced "too many arguments for 'pm'. Expected 0
+ * arguments but got 2." Groups without an action get Commander's proper
+ * `unknownCommand()` error and did-you-mean suggestion; give action-bearing
+ * groups the same one. `unknownCommand` is Commander's own (undocumented but
+ * stable since v7) implementation; fall back to its message format if a
+ * future version renames it.
+ */
+export declare function rejectUnknownSubcommand(command: Command): void;
+/**
+ * Group fallback when the TUI cannot launch and no subcommand was given.
+ * Under JSON output, help prose on stdout breaks every `JSON.parse(stdout)`
+ * consumer, so emit an envelope listing the subcommands and exit non-zero
+ * (the caller asked for data and there is none). Otherwise print help to
+ * stderr, keeping stdout clean for pipes.
+ */
+export declare function emitGroupHelpFallback(runtime: VibesRuntime, command: Command, options: CommandOptions): Promise<void>;
+//# sourceMappingURL=group-fallback.d.ts.map

package/dist/surface/group-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-fallback.d.ts","sourceRoot":"","sources":["../../src/surface/group-fallback.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAM1E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAS9D;AAOD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3H"}

package/dist/surface/group-fallback.js

@@ -0,0 +1,78 @@
+import { writeJson } from "../commands/output.js";
+import { requestCLIExit } from "./exit.js";
+/**
+ * `--json` and `--format json` are ONE contract. Impls read whichever they
+ * were written against, so both spellings must land in both fields:
+ * `--json` → `format='json'`, `--format json` → `json=true`.
+ */
+export function normalizeOutputFormatOptions(options) {
+    if (options.json === true && options.format !== 'json') {
+        options.format = 'json';
+    }
+    else if (options.format === 'json' && options.json !== true) {
+        options.json = true;
+    }
+}
+export function wantsJsonOutput(options) {
+    return options.json === true || options.format === 'json';
+}
+/**
+ * A group with an action handler is dispatched by Commander even when its
+ * operands match no subcommand — the action fires and the operands are
+ * checked against the group's own (empty) argument list, which is how
+ * `vibes pm describe x` produced "too many arguments for 'pm'. Expected 0
+ * arguments but got 2." Groups without an action get Commander's proper
+ * `unknownCommand()` error and did-you-mean suggestion; give action-bearing
+ * groups the same one. `unknownCommand` is Commander's own (undocumented but
+ * stable since v7) implementation; fall back to its message format if a
+ * future version renames it.
+ */
+export function rejectUnknownSubcommand(command) {
+    const [candidate] = command.args;
+    if (candidate === undefined || command.commands.length === 0)
+        return;
+    const known = command.commands.some((sub) => sub.name() === candidate || sub.aliases().includes(candidate));
+    if (known)
+        return;
+    if (hasUnknownCommand(command))
+        command.unknownCommand();
+    command.error(`error: unknown command '${candidate}'`, { code: 'commander.unknownCommand' });
+}
+/** Commander's internal `unknownCommand()` (present since v7, not in its typings). */
+function hasUnknownCommand(command) {
+    return 'unknownCommand' in command && typeof command.unknownCommand === 'function';
+}
+/**
+ * Group fallback when the TUI cannot launch and no subcommand was given.
+ * Under JSON output, help prose on stdout breaks every `JSON.parse(stdout)`
+ * consumer, so emit an envelope listing the subcommands and exit non-zero
+ * (the caller asked for data and there is none). Otherwise print help to
+ * stderr, keeping stdout clean for pipes.
+ */
+export async function emitGroupHelpFallback(runtime, command, options) {
+    if (wantsJsonOutput(options)) {
+        await writeJson(runtime, {
+            ok: false,
+            error: 'no subcommand',
+            command: commandPath(command).join(' '),
+            commands: command
+                .createHelp()
+                .visibleCommands(command)
+                .map((sub) => ({
+                name: sub.name(),
+                aliases: sub.aliases(),
+                description: sub.description()
+            }))
+        });
+        requestCLIExit(1);
+    }
+    command.outputHelp({ error: true });
+}
+function commandPath(command) {
+    const path = [];
+    for (let cursor = command; cursor; cursor = cursor.parent) {
+        path.unshift(cursor.name());
+    }
+    return path;
+}
+//# sourceMappingURL=group-fallback.js.map

package/dist/surface/group-fallback.js.map

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

package/dist/surface/index.d.ts

@@ -0,0 +1,10 @@
+/** Explicit Commander surface. Metadata consumers use the root or ./kinds. */
+export { CLISurface } from './CLISurface.ts';
+export { reportBootstrapFailure, type ReportBootstrapFailureOptions } from './failure-output.ts';
+export { renderCliFailure, scrubCliText, mapKnownError, type CliFailureRenderOptions } from './failure-report.ts';
+export type { CLISurfaceOptions, CommandContext, CommandOptions, CommandOptionValue, CLIInvocationEndInfo, CLIInvocationInfo, CLIInvocationObserver, CLIInvocationPreparer, CLIResolvedEffects } from '../schemas/surface.ts';
+export { CommandOptionValueSchema, CommandOptionsSchema } from '../schemas/surface.ts';
+export { defineCommandImplementation, parseCommandOptions, type CommandImplementation, type TypedCommandImplementation } from './command-options.ts';
+export { resolveCommandImplementation, type CliCommandExecute, type CommandImplementationResolution } from './command-implementation.ts';
+export type { CliHostOutput } from '../boot/providers.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/surface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surface/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,KAAK,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAClH,YAAY,EACX,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EACrE,oBAAoB,EAAE,iBAAiB,EAAE,qBAAqB,EAC9D,qBAAqB,EAAE,kBAAkB,EACzC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,KAAK,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AACrJ,OAAO,EAAE,4BAA4B,EAAE,KAAK,iBAAiB,EAAE,KAAK,+BAA+B,EAAE,MAAM,6BAA6B,CAAC;AACzI,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/surface/index.js

@@ -0,0 +1,8 @@
+/** Explicit Commander surface. Metadata consumers use the root or ./kinds. */
+export { CLISurface } from "./CLISurface.js";
+export { reportBootstrapFailure } from "./failure-output.js";
+export { renderCliFailure, scrubCliText, mapKnownError } from "./failure-report.js";
+export { CommandOptionValueSchema, CommandOptionsSchema } from "../schemas/surface.js";
+export { defineCommandImplementation, parseCommandOptions } from "./command-options.js";
+export { resolveCommandImplementation } from "./command-implementation.js";
+//# sourceMappingURL=index.js.map

package/dist/surface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surface/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAsC,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAgC,MAAM,qBAAqB,CAAC;AAMlH,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAA+D,MAAM,sBAAsB,CAAC;AACrJ,OAAO,EAAE,4BAA4B,EAAgE,MAAM,6BAA6B,CAAC"}

package/dist/surface/inherited-options.d.ts

@@ -0,0 +1,28 @@
+import { type Command } from 'commander';
+import type { CommandOptions } from '../schemas/surface.ts';
+/**
+ * Give command scopes their own copy of root global options.
+ *
+ * Commander normally lets a root option consume matching flags anywhere in
+ * argv. That makes a root `--version` steal a subcommand's own `--version`.
+ * Positional option parsing restores command ownership, while hidden inherited
+ * copies preserve the existing convenience of global flags after a subcommand.
+ */
+export declare function configureInheritedGlobalOptions(program: Command): void;
+/**
+ * Merge an action command's option scopes without letting ancestor defaults
+ * overwrite values explicitly parsed by the selected command.
+ *
+ * Commander deliberately makes ancestors win in optsWithGlobals(). That is
+ * wrong once globals are cloned into command scopes: root `format=table` and
+ * `color=true` defaults would erase leaf `--format json` and `--no-color`.
+ * Source priority wins first; the deeper command wins equal-source ties.
+ */
+export declare function resolveScopedCommandOptions(command: Command): CommandOptions;
+/**
+ * Whether any scope of the selected command received `key` from something
+ * other than a declared default: the invocation asked for it, rather than
+ * Commander filling in the option's default (root `format=table`).
+ */
+export declare function optionValueIsExplicit(command: Command, key: string): boolean;
+//# sourceMappingURL=inherited-options.d.ts.map

package/dist/surface/inherited-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inherited-options.d.ts","sourceRoot":"","sources":["../../src/surface/inherited-options.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAkC,MAAM,WAAW,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ5D;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CActE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CA0B5E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAK5E"}

package/dist/surface/inherited-options.js

@@ -0,0 +1,108 @@
+import { parseCommandOptionBag } from "./command-options.js";
+import { Option } from 'commander';
+/**
+ * Give command scopes their own copy of root global options.
+ *
+ * Commander normally lets a root option consume matching flags anywhere in
+ * argv. That makes a root `--version` steal a subcommand's own `--version`.
+ * Positional option parsing restores command ownership, while hidden inherited
+ * copies preserve the existing convenience of global flags after a subcommand.
+ */
+export function configureInheritedGlobalOptions(program) {
+    const inherited = program.options.filter((option) => !isRootVersionOption(option));
+    program.enablePositionalOptions();
+    const visit = (command) => {
+        command.enablePositionalOptions();
+        for (const source of inherited) {
+            if (hasFlagConflict(command, source))
+                continue;
+            command.addOption(cloneInheritedOption(source));
+        }
+        for (const child of command.commands)
+            visit(child);
+    };
+    for (const command of program.commands)
+        visit(command);
+}
+/**
+ * Merge an action command's option scopes without letting ancestor defaults
+ * overwrite values explicitly parsed by the selected command.
+ *
+ * Commander deliberately makes ancestors win in optsWithGlobals(). That is
+ * wrong once globals are cloned into command scopes: root `format=table` and
+ * `color=true` defaults would erase leaf `--format json` and `--no-color`.
+ * Source priority wins first; the deeper command wins equal-source ties.
+ */
+export function resolveScopedCommandOptions(command) {
+    const chain = [];
+    for (let cursor = command; cursor; cursor = cursor.parent) {
+        chain.unshift(cursor);
+    }
+    const selected = new Map();
+    for (const [depth, scope] of chain.entries()) {
+        for (const [key, value] of Object.entries(scope.opts())) {
+            const candidate = {
+                value,
+                sourcePriority: optionSourcePriority(scope.getOptionValueSource(key)),
+                depth
+            };
+            const current = selected.get(key);
+            if (!current ||
+                candidate.sourcePriority > current.sourcePriority ||
+                (candidate.sourcePriority === current.sourcePriority && candidate.depth > current.depth)) {
+                selected.set(key, candidate);
+            }
+        }
+    }
+    return parseCommandOptionBag(Object.fromEntries(Array.from(selected, ([key, candidate]) => [key, candidate.value])));
+}
+/**
+ * Whether any scope of the selected command received `key` from something
+ * other than a declared default: the invocation asked for it, rather than
+ * Commander filling in the option's default (root `format=table`).
+ */
+export function optionValueIsExplicit(command, key) {
+    for (let cursor = command; cursor; cursor = cursor.parent) {
+        if (optionSourcePriority(cursor.getOptionValueSource(key)) > optionSourcePriority('default'))
+            return true;
+    }
+    return false;
+}
+function optionSourcePriority(source) {
+    switch (source) {
+        case 'cli':
+            return 5;
+        case 'env':
+            return 4;
+        case 'config':
+            return 3;
+        case 'implied':
+            return 2;
+        case 'default':
+            return 1;
+        case undefined:
+            return 0;
+        default:
+            // Commander permits author-defined sources. Treat them as stronger
+            // than defaults but weaker than its explicit CLI/env/config sources.
+            return 2;
+    }
+}
+function isRootVersionOption(option) {
+    return option.short === '-V' && option.long === '--version';
+}
+function hasFlagConflict(command, source) {
+    return command.options.some((option) => (source.short !== undefined && option.short === source.short) ||
+        (source.long !== undefined && option.long === source.long));
+}
+function cloneInheritedOption(source) {
+    const option = new Option(source.flags, source.description).hideHelp();
+    if (source.argChoices)
+        option.choices(source.argChoices);
+    if (source.parseArg)
+        option.argParser(source.parseArg);
+    if (source.presetArg !== undefined)
+        option.preset(source.presetArg);
+    return option;
+}
+//# sourceMappingURL=inherited-options.js.map

package/dist/surface/inherited-options.js.map

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

package/dist/surface/interactive-gate.d.ts

@@ -0,0 +1,41 @@
+import type { Command } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import { type CommandArguments } from './commander-action.ts';
+import type { CommandOptions } from '../schemas/surface.ts';
+interface TuiActionHooks {
+    beforeExecute?: (params: {
+        args: CommandArguments;
+        options: CommandOptions;
+    }) => Promise<void>;
+}
+/**
+ * Minimal descriptor shape needed to attach an interactive launcher
+ * action. Both `cli/command` and `cli/group` descriptors satisfy it.
+ *
+ * `kind` decides what a positional means: a `cli/group` owns a subcommand
+ * tree, so a positional that is not a subcommand is an unknown command; a
+ * `cli/command` owns its declared arguments and keeps Commander's arity
+ * check. Omitted `kind` is treated as a command (the historical shape).
+ */
+export type { TuiActionDescriptor, TuiFallback, InteractiveGateInput } from './schemas/interactive-gate.ts';
+import type { TuiActionDescriptor, TuiFallback, InteractiveGateInput } from './schemas/interactive-gate.ts';
+/**
+ * Pure decision function for whether the CLI surface should launch the
+ * TUI given the runtime signals. Exported for unit testing — the live
+ * `cmd.action` handler reads host TTY/argv/env signals from the bun
+ * adapter and forwards them into this.
+ */
+export declare function shouldLaunchInteractive(input: InteractiveGateInput): boolean;
+/**
+ * Register-time interactive action. Contains no TUI package import literals so `--help` / `--version` / MCP initialize can build the Commander
+ * tree without resolving TUI. The launch module is imported only after the
+ * gate decides to start the TUI.
+ */
+export declare function attachTuiAction(cmd: Command, 
+/**
+ * The runtime the TUI app launches on, or a getter for it. A serve command's
+ * transition replaces the surface's runtime before the action runs
+ * (rc02-rc03 §2.3), so the surface passes a getter.
+ */
+runtime: () => VibesRuntime, descriptor: TuiActionDescriptor, hooks?: TuiActionHooks, fallback?: TuiFallback): Promise<void>;
+//# sourceMappingURL=interactive-gate.d.ts.map

package/dist/surface/interactive-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-gate.d.ts","sourceRoot":"","sources":["../../src/surface/interactive-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,KAAK,EAAsB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEhF,UAAU,cAAc;IACvB,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACxB,IAAI,EAAE,gBAAgB,CAAC;QACvB,OAAO,EAAE,cAAc,CAAC;KACxB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC5G,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE5G;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAqB5E;AAyBD;;;;GAIG;AACH,wBAAsB,eAAe,CACpC,GAAG,EAAE,OAAO;AACZ;;;;GAIG;AACH,OAAO,EAAE,MAAM,YAAY,EAC3B,UAAU,EAAE,mBAAmB,EAC/B,KAAK,GAAE,cAAmB,EAC1B,QAAQ,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CAkEf"}