@vibesdotdev/cli 0.0.2 → 1.0.0-rc.3

package/dist/surface/interactive-gate.js

@@ -0,0 +1,112 @@
+import { normalizeCLIArgumentName } from "./argument-name.js";
+import { emitGroupHelpFallback, normalizeOutputFormatOptions, rejectUnknownSubcommand } from "./group-fallback.js";
+import { readCommanderAction } from "./commander-action.js";
+/**
+ * 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 function shouldLaunchInteractive(input) {
+    const { launchWhen, hasPositionalArgs, stdoutIsTTY, stdinIsTTY, nonInteractiveFlag, forceTtyEnv } = input;
+    if (nonInteractiveFlag)
+        return false;
+    if (launchWhen === 'explicit')
+        return false;
+    // `VIBES_FORCE_TTY=1` bypasses TTY checks for E2E and headless tooling.
+    const ttyOk = forceTtyEnv || (stdoutIsTTY && stdinIsTTY);
+    if (!ttyOk)
+        return false;
+    if (launchWhen === 'always')
+        return true;
+    if (launchWhen === 'noArgsAndTty')
+        return !hasPositionalArgs;
+    return false;
+}
+function readInteractiveSignals(descriptor, actionArgs) {
+    const args = {};
+    let hasPositionalArgs = false;
+    if (descriptor.arguments) {
+        descriptor.arguments.forEach((arg, i) => {
+            if (i < actionArgs.length) {
+                const value = actionArgs[i];
+                args[normalizeCLIArgumentName(arg.name)] = value;
+                if (value !== undefined && value !== '') {
+                    hasPositionalArgs = true;
+                }
+            }
+        });
+    }
+    return { args, hasPositionalArgs };
+}
+/**
+ * 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 async function attachTuiAction(cmd, 
+/**
+ * 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, descriptor, hooks = {}, fallback) {
+    const interactive = descriptor.interactive;
+    if (!interactive) {
+        throw new Error('[CLI] attachTuiAction called without an `interactive` descriptor.');
+    }
+    const appId = interactive.appId;
+    const isGroup = descriptor.kind === 'cli/group';
+    if (isGroup) {
+        // Let operands reach the action instead of Commander's arity check so
+        // `rejectUnknownSubcommand` can answer with the unknown-command error.
+        // A variadic argument (not `allowExcessArguments`) because children
+        // created later copy the excess-arguments setting from their parent,
+        // which would have silenced arity errors on every leaf command. The
+        // argument carries no description so help does not list it, and the
+        // usage line is pinned to what a group shows anyway.
+        cmd.argument('[subcommand...]');
+        cmd.usage('[options] [command]');
+    }
+    cmd.action(async (...actionArgs) => {
+        // Commander passes (...positionals, options, command). Pop in
+        // reverse so we can merge globals by source the same way the
+        // non-interactive path does.
+        const { positionals, options, command: commandObj } = readCommanderAction(actionArgs);
+        normalizeOutputFormatOptions(options);
+        if (isGroup && commandObj)
+            rejectUnknownSubcommand(commandObj);
+        const { args, hasPositionalArgs } = readInteractiveSignals(descriptor, positionals);
+        if (hooks.beforeExecute) {
+            await hooks.beforeExecute({ args, options });
+        }
+        const { readInteractiveHostSignals } = await import("../bun/interactive-host.js");
+        const activeRuntime = runtime();
+        const host = readInteractiveHostSignals(activeRuntime);
+        const launchInteractive = shouldLaunchInteractive({
+            launchWhen: interactive.launchWhen,
+            hasPositionalArgs,
+            stdoutIsTTY: host.stdoutIsTTY,
+            stdinIsTTY: host.stdinIsTTY,
+            nonInteractiveFlag: options.nonInteractive === true || options.interactive === false ||
+                options.json === true || options.format === 'json' || host.argvIncludesNonInteractive,
+            forceTtyEnv: host.forceTtyEnv
+        });
+        if (!launchInteractive) {
+            if (fallback) {
+                await fallback({ args, options });
+                return;
+            }
+            await emitGroupHelpFallback(activeRuntime, cmd, options);
+            return;
+        }
+        const { launchAttachedTui } = await import("./attach-tui-action.js");
+        await launchAttachedTui({
+            runtime: activeRuntime,
+            appId,
+            args,
+            options
+        });
+    });
+}
+//# sourceMappingURL=interactive-gate.js.map

package/dist/surface/interactive-gate.js.map

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

package/dist/surface/invocation-actions.d.ts

@@ -0,0 +1,40 @@
+import type { Command } from 'commander';
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import { type RuntimeActor } from '@vibesdotdev/kernel/schemas';
+import type { CLIInvocationInfo } from '../schemas/surface.ts';
+type ActionRunner = <T>(action: () => T) => T;
+/**
+ * Route every Commander action registered under `command` through `run`.
+ *
+ * Commander calls an action from a promise chain created while parsing, so an
+ * invocation opened in a `preAction` hook never reaches the action. Wrapping
+ * the action itself is the only boundary that runs inside the action's own
+ * async context. Children inherit the wrapper through `createCommand`, which
+ * `command()` uses for every subcommand, so groups and pattern-registered
+ * commands are covered without each registration site knowing about it.
+ */
+export declare function routeActionsThrough(command: Command, run: ActionRunner): void;
+/**
+ * Who one CLI action acts for (rc01 §2.1, `interactiveSession`): the signed-in
+ * user from `auth/identity` plus the agent its launching harness declared for
+ * the shell (the host's `launchIdentity()` fact: `VIBES_AGENT_ID` and
+ * `VIBES_AGENT_HOME`, captured once). A shared host (MCP host, daemon)
+ * acts for none: each invocation it serves names its own actor, so an
+ * inherited shell identity can never become every client's identity.
+ *
+ * The user is read only for an action whose host preparation ran (it declares
+ * a home write): reading the stored session is storage work that
+ * metadata-only actions never do.
+ *
+ * Admission runs through the kernel's `admitInvokeCaller` (RC08/D-RC08 U7),
+ * never a hand-rolled equivalent. The CLI host is a single-process, one-caller
+ * surface: `launchIdentity()` is captured once, at host construction, from
+ * the launching harness's own shell environment — the same trust boundary a
+ * verified transport establishes at connection time for a shared host (MCP,
+ * daemon), not a per-call value a caller can redeclare. So the host's own
+ * capture is the verified fact here; there is no separate "declared" source
+ * to disagree with it.
+ */
+export declare function resolveCliInvocationActor(runtime: VibesRuntime, info: CLIInvocationInfo): Promise<RuntimeActor | undefined>;
+export {};
+//# sourceMappingURL=invocation-actions.d.ts.map

package/dist/surface/invocation-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-actions.d.ts","sourceRoot":"","sources":["../../src/surface/invocation-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAEN,KAAK,YAAY,EAGjB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,KAAK,YAAY,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAe7E;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAoBnC"}

package/dist/surface/invocation-actions.js

@@ -0,0 +1,78 @@
+import { admitInvokeCaller } from '@vibesdotdev/kernel/schemas';
+/**
+ * Route every Commander action registered under `command` through `run`.
+ *
+ * Commander calls an action from a promise chain created while parsing, so an
+ * invocation opened in a `preAction` hook never reaches the action. Wrapping
+ * the action itself is the only boundary that runs inside the action's own
+ * async context. Children inherit the wrapper through `createCommand`, which
+ * `command()` uses for every subcommand, so groups and pattern-registered
+ * commands are covered without each registration site knowing about it.
+ */
+export function routeActionsThrough(command, run) {
+    const setAction = command.action.bind(command);
+    const createCommand = command.createCommand.bind(command);
+    Object.assign(command, {
+        action(fn) {
+            return setAction(function (...args) {
+                return run(() => fn.apply(this, args));
+            });
+        },
+        createCommand(name) {
+            const child = createCommand(name);
+            routeActionsThrough(child, run);
+            return child;
+        }
+    });
+}
+const AGENT_HOMES = new Set(['user', 'organization', 'team']);
+/** A declared agent home the kernel admits (`user`, `organization` or `team`). */
+function isAgentHome(home) {
+    return AGENT_HOMES.has(home);
+}
+/**
+ * Who one CLI action acts for (rc01 §2.1, `interactiveSession`): the signed-in
+ * user from `auth/identity` plus the agent its launching harness declared for
+ * the shell (the host's `launchIdentity()` fact: `VIBES_AGENT_ID` and
+ * `VIBES_AGENT_HOME`, captured once). A shared host (MCP host, daemon)
+ * acts for none: each invocation it serves names its own actor, so an
+ * inherited shell identity can never become every client's identity.
+ *
+ * The user is read only for an action whose host preparation ran (it declares
+ * a home write): reading the stored session is storage work that
+ * metadata-only actions never do.
+ *
+ * Admission runs through the kernel's `admitInvokeCaller` (RC08/D-RC08 U7),
+ * never a hand-rolled equivalent. The CLI host is a single-process, one-caller
+ * surface: `launchIdentity()` is captured once, at host construction, from
+ * the launching harness's own shell environment — the same trust boundary a
+ * verified transport establishes at connection time for a shared host (MCP,
+ * daemon), not a per-call value a caller can redeclare. So the host's own
+ * capture is the verified fact here; there is no separate "declared" source
+ * to disagree with it.
+ */
+export async function resolveCliInvocationActor(runtime, info) {
+    if (info.effects.sharedHost)
+        return undefined;
+    const launch = runtime.localEnvironment.launchIdentity?.();
+    const agentId = launch?.agentId?.trim() || undefined;
+    const declaredHome = agentId ? launch?.agentHome?.trim() : undefined;
+    const home = declaredHome && isAgentHome(declaredHome) ? declaredHome : undefined;
+    let userId;
+    if (info.effects.homeWrite && runtime.hasContext('auth/identity')) {
+        const identity = await runtime.context('auth/identity');
+        userId = identity?.isAuthenticated === true ? identity.userId?.trim() || undefined : undefined;
+    }
+    if (!agentId && !userId)
+        return undefined;
+    const caller = {};
+    if (userId)
+        caller.userId = userId;
+    if (agentId)
+        caller.agentId = agentId;
+    if (home)
+        caller.home = home;
+    const verified = { source: 'cli-host-launch-identity', caller };
+    return admitInvokeCaller(caller, verified);
+}
+//# sourceMappingURL=invocation-actions.js.map

package/dist/surface/invocation-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-actions.js","sourceRoot":"","sources":["../../src/surface/invocation-actions.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,iBAAiB,EAIjB,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,GAAiB;IACtE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE;QACtB,MAAM,CAAC,EAAiB;YACvB,OAAO,SAAS,CAAC,UAAyB,GAAG,IAAe;gBAC3D,OAAO,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACJ,CAAC;QACD,aAAa,CAAC,IAAa;YAC1B,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAClC,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAChC,OAAO,KAAK,CAAC;QACd,CAAC;KACD,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9F,kFAAkF;AAClF,SAAS,WAAW,CAAC,IAAY;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC9C,OAAqB,EACrB,IAAuB;IAEvB,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,cAAc,EAAE,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACrD,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,MAAM,IAAI,GAAG,YAAY,IAAI,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,IAAI,MAA0B,CAAC;IAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACnE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CACrC,eAAe,CACf,CAAC;QACF,MAAM,GAAG,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAmF,EAAE,CAAC;IAClG,IAAI,MAAM;QAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACnC,IAAI,OAAO;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACtC,IAAI,IAAI;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IAC7B,MAAM,QAAQ,GAA8B,EAAE,MAAM,EAAE,0BAA0B,EAAE,MAAM,EAAE,CAAC;IAC3F,OAAO,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC"}

package/dist/surface/invocation-effects.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import type { CLICommandEffects } from '../schemas/descriptors.ts';
+import type { CLIResolvedEffects } from '../schemas/surface.ts';
+/**
+ * Evaluate descriptor-declared effects inside the CLI surface.
+ *
+ * Raw parsed options never cross this boundary. Hosts receive only the
+ * resolved booleans they need to prepare the action.
+ */
+export declare function resolveCLIInvocationEffects(command: Command, declared?: CLICommandEffects): CLIResolvedEffects;
+//# sourceMappingURL=invocation-effects.d.ts.map

package/dist/surface/invocation-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-effects.d.ts","sourceRoot":"","sources":["../../src/surface/invocation-effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,OAAO,EAChB,QAAQ,CAAC,EAAE,iBAAiB,GAC1B,kBAAkB,CAOpB"}

package/dist/surface/invocation-effects.js

@@ -0,0 +1,52 @@
+import { resolveScopedCommandOptions } from "./inherited-options.js";
+/**
+ * Evaluate descriptor-declared effects inside the CLI surface.
+ *
+ * Raw parsed options never cross this boundary. Hosts receive only the
+ * resolved booleans they need to prepare the action.
+ */
+export function resolveCLIInvocationEffects(command, declared) {
+    // A serve host acts for many agents (rc02-rc03 §2.3).
+    const serve = resolveServeEffect(command, declared?.serve);
+    const effects = { homeWrite: resolveHomeWrite(command, declared?.homeWrite), sharedHost: serve !== undefined };
+    if (serve)
+        effects.serve = { ...serve };
+    if (declared?.launches)
+        effects.launches = declared.launches;
+    return effects;
+}
+/** Whether the action writes home: omission is conservative (the action requires writable home storage). */
+function resolveHomeWrite(command, homeWrite) {
+    if (homeWrite === 'none')
+        return false;
+    if (homeWrite === undefined || homeWrite === 'required')
+        return true;
+    const options = resolveScopedCommandOptions(command);
+    const expected = homeWrite.equals ?? true;
+    return options[homeWrite.whenOption] === expected;
+}
+/** Resolve a declared relay mode before host boot; the serving body keeps activation. */
+function resolveServeEffect(command, serve) {
+    if (!serve)
+        return undefined;
+    const { deferActivationWhen, compositionWhen, ...host } = serve;
+    if (!deferActivationWhen && !compositionWhen) {
+        return host.composition === 'transport' ? { ...host, deferActivation: true } : host;
+    }
+    const options = resolveScopedCommandOptions(command);
+    const isTransport = host.composition === 'transport' || (compositionWhen !== undefined &&
+        options[compositionWhen.whenOption] === compositionWhen.equals &&
+        !(compositionWhen.unlessOptions ?? []).some((option) => options[option] === true));
+    const deferActivation = isTransport || host.composition === 'transport' || (deferActivationWhen !== undefined &&
+        options[deferActivationWhen.whenOption] === deferActivationWhen.equals &&
+        !(deferActivationWhen.unlessOptions ?? []).some((option) => options[option] === true));
+    const result = {
+        ...host,
+        deferActivation
+    };
+    if (isTransport) {
+        result.composition = 'transport';
+    }
+    return result;
+}
+//# sourceMappingURL=invocation-effects.js.map

package/dist/surface/invocation-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-effects.js","sourceRoot":"","sources":["../../src/surface/invocation-effects.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAC1C,OAAgB,EAChB,QAA4B;IAE5B,sDAAsD;IACtD,MAAM,KAAK,GAAG,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAuB,EAAE,SAAS,EAAE,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,UAAU,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;IACnI,IAAI,KAAK;QAAE,OAAO,CAAC,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IACxC,IAAI,QAAQ,EAAE,QAAQ;QAAE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAC7D,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,4GAA4G;AAC5G,SAAS,gBAAgB,CAAC,OAAgB,EAAE,SAAyC;IACpF,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACrE,MAAM,OAAO,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC;IAC1C,OAAO,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC;AACnD,CAAC;AAED,yFAAyF;AACzF,SAAS,kBAAkB,CAC1B,OAAgB,EAChB,KAAiC;IAEjC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,EAAE,mBAAmB,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IAChE,IAAI,CAAC,mBAAmB,IAAI,CAAC,eAAe,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,CAAC;IACD,MAAM,OAAO,GAAG,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,KAAK,WAAW,IAAI,CACvD,eAAe,KAAK,SAAS;QAC7B,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC,KAAK,eAAe,CAAC,MAAM;QAC9D,CAAC,CAAC,eAAe,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CACjF,CAAC;IACF,MAAM,eAAe,GAAG,WAAW,IAAI,IAAI,CAAC,WAAW,KAAK,WAAW,IAAI,CAC1E,mBAAmB,KAAK,SAAS;QACjC,OAAO,CAAC,mBAAmB,CAAC,UAAU,CAAC,KAAK,mBAAmB,CAAC,MAAM;QACtE,CAAC,CAAC,mBAAmB,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CACrF,CAAC;IACF,MAAM,MAAM,GAAyD;QACpE,GAAG,IAAI;QACP,eAAe;KACf,CAAC;IACF,IAAI,WAAW,EAAE,CAAC;QACjB,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/surface/invocation-lifecycle.d.ts

@@ -0,0 +1,49 @@
+import { CapabilityError, type CaughtFailure, type RuntimeRef, type ValueFreeFailure } from '@vibesdotdev/kernel';
+import type { CLIInvocationFailureCode, CLIInvocationInfo, CLIInvocationObserver } from '../schemas/surface.ts';
+/**
+ * Pairs a host observer to Commander's actual action dispatch.
+ *
+ * Help, version, parse failures, and a bare program never call `start` because
+ * Commander never dispatches an action for them. This is deliberately
+ * action-based rather than an argv-name allow/deny list.
+ *
+ * Observer failures never change the command's outcome: neither `start` nor
+ * `finish` rejects because an observer did.
+ */
+export declare class CLIInvocationController {
+    private readonly runtimeOf?;
+    private readonly describe?;
+    private observer;
+    private active;
+    /** Whether this invocation already reported an observer failure (one report per invocation). */
+    private reported;
+    private readonly undelivered;
+    /**
+     * Observer failures are reported once per invocation through the runtime
+     * logger with their value-free facts (class, code, reason: never thrown
+     * text). A runtime whose logging cannot take the entry (not prepared, or
+     * already closed) leaves the report as a typed diagnostic in
+     * {@link undeliveredDiagnostics} instead; the warn never throws.
+     *
+     * @param runtimeOf The runtime whose logger reports an observer failure
+     * (the action's runtime: after a serve transition, the serve host). Absent,
+     * the logger binds to the default runtime at emit.
+     * @param describe The host's redacted rendering of the failure for the
+     * report's `detail` (the CLI supplies it under `-v`); absent or `undefined`,
+     * the report carries the value-free facts alone.
+     */
+    constructor(runtimeOf?: (() => RuntimeRef | undefined) | undefined, describe?: ((failure: CaughtFailure) => string | undefined) | undefined);
+    setObserver<Token>(observer: CLIInvocationObserver<Token> | undefined): void;
+    /**
+     * Observer failures whose report logging could not take: each a
+     * `CapabilityError` `UNAVAILABLE` `observer-failure-unlogged` whose
+     * `details` hold the observer failure's value-free facts and whose `cause`
+     * is the logging refusal. In order; never cleared by the controller.
+     */
+    get undeliveredDiagnostics(): readonly CapabilityError[];
+    start(info: CLIInvocationInfo): Promise<void>;
+    finish(outcome: 'success' | 'failure', failureCode?: CLIInvocationFailureCode, failureCause?: ValueFreeFailure): Promise<void>;
+    /** Report one observer failure: the runtime logger's warn, else a carried typed diagnostic. */
+    private report;
+}
+//# sourceMappingURL=invocation-lifecycle.d.ts.map

package/dist/surface/invocation-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-lifecycle.d.ts","sourceRoot":"","sources":["../../src/surface/invocation-lifecycle.ts"],"names":[],"mappings":"AACA,OAAO,EACN,eAAe,EAGf,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAEX,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,uBAAuB,CAAC;AAmC/B;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAsBlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAtB3B,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,MAAM,CAA+B;IAC7C,gGAAgG;IAChG,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IAErD;;;;;;;;;;;;;OAaG;gBAEe,SAAS,CAAC,GAAE,MAAM,UAAU,GAAG,SAAS,aAAA,EACxC,QAAQ,CAAC,GAAE,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,aAAA;IAG3E,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI;IAI5E;;;;;OAKG;IACH,IAAI,sBAAsB,IAAI,SAAS,eAAe,EAAE,CAEvD;IAEK,KAAK,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7C,MAAM,CACX,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,WAAW,CAAC,EAAE,wBAAwB,EACtC,YAAY,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAYhB,+FAA+F;IAC/F,OAAO,CAAC,MAAM;CAoBd"}

package/dist/surface/invocation-lifecycle.js

@@ -0,0 +1,127 @@
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { failureOf } from "./failure-of.js";
+function pairObserver(observer) {
+    return {
+        async start(info) {
+            const token = await observer.start(info);
+            return (endInfo) => observer.end(endInfo, token);
+        }
+    };
+}
+const OBSERVER_FAILURE_MESSAGES = {
+    start: 'CLI invocation observer start failed',
+    end: 'CLI invocation observer end failed'
+};
+/**
+ * Pairs a host observer to Commander's actual action dispatch.
+ *
+ * Help, version, parse failures, and a bare program never call `start` because
+ * Commander never dispatches an action for them. This is deliberately
+ * action-based rather than an argv-name allow/deny list.
+ *
+ * Observer failures never change the command's outcome: neither `start` nor
+ * `finish` rejects because an observer did.
+ */
+export class CLIInvocationController {
+    runtimeOf;
+    describe;
+    observer;
+    active;
+    /** Whether this invocation already reported an observer failure (one report per invocation). */
+    reported = false;
+    undelivered = [];
+    /**
+     * Observer failures are reported once per invocation through the runtime
+     * logger with their value-free facts (class, code, reason: never thrown
+     * text). A runtime whose logging cannot take the entry (not prepared, or
+     * already closed) leaves the report as a typed diagnostic in
+     * {@link undeliveredDiagnostics} instead; the warn never throws.
+     *
+     * @param runtimeOf The runtime whose logger reports an observer failure
+     * (the action's runtime: after a serve transition, the serve host). Absent,
+     * the logger binds to the default runtime at emit.
+     * @param describe The host's redacted rendering of the failure for the
+     * report's `detail` (the CLI supplies it under `-v`); absent or `undefined`,
+     * the report carries the value-free facts alone.
+     */
+    constructor(runtimeOf, describe) {
+        this.runtimeOf = runtimeOf;
+        this.describe = describe;
+    }
+    setObserver(observer) {
+        this.observer = observer ? pairObserver(observer) : undefined;
+    }
+    /**
+     * Observer failures whose report logging could not take: each a
+     * `CapabilityError` `UNAVAILABLE` `observer-failure-unlogged` whose
+     * `details` hold the observer failure's value-free facts and whose `cause`
+     * is the logging refusal. In order; never cleared by the controller.
+     */
+    get undeliveredDiagnostics() {
+        return this.undelivered;
+    }
+    async start(info) {
+        const observer = this.observer;
+        if (!observer)
+            return;
+        if (this.active) {
+            throw new Error('CLI invocation observer already has an active action');
+        }
+        this.reported = false;
+        const failure = await failureOf(async () => {
+            const end = await observer.start(info);
+            this.active = { info, end };
+        });
+        if (failure)
+            this.report('start', failure);
+    }
+    async finish(outcome, failureCode, failureCause) {
+        const active = this.active;
+        if (!active)
+            return;
+        this.active = undefined;
+        const info = { ...active.info, outcome };
+        if (failureCode !== undefined)
+            info.failureCode = failureCode;
+        if (failureCause !== undefined)
+            info.failureCause = failureCause;
+        const failure = await failureOf(() => active.end(info));
+        if (failure)
+            this.report('end', failure);
+    }
+    /** Report one observer failure: the runtime logger's warn, else a carried typed diagnostic. */
+    report(phase, failure) {
+        if (this.reported)
+            return;
+        this.reported = true;
+        const facts = valueFreeFailure(failure);
+        const unlogged = warnFailure(this.runtimeOf?.(), OBSERVER_FAILURE_MESSAGES[phase], {
+            error: facts,
+            detail: this.describe?.(failure)
+        });
+        if (!unlogged)
+            return;
+        this.undelivered.push(new CapabilityError(`${OBSERVER_FAILURE_MESSAGES[phase]}, and logging could not take the report.`, 'UNAVAILABLE', {
+            reason: 'observer-failure-unlogged',
+            retryable: false,
+            details: { phase, observerFailure: { name: facts.name, code: facts.code, reason: facts.reason } },
+            cause: unlogged
+        }));
+    }
+}
+/**
+ * Warn through the runtime's `cli` logger: `null` once the entry is taken,
+ * else the logging failure (logging not prepared on this runtime, or closed),
+ * parsed at the catch for the caller to carry. Never throws.
+ */
+function warnFailure(runtime, message, context) {
+    try {
+        getLogger('cli', runtime).warn(message, context);
+        return null;
+    }
+    catch (error) {
+        return CaughtFailureSchema.parse(error);
+    }
+}
+//# sourceMappingURL=invocation-lifecycle.js.map

package/dist/surface/invocation-lifecycle.js.map

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

package/dist/surface/output-format-request.d.ts

@@ -0,0 +1,23 @@
+import type { JsonValue } from '@vibesdotdev/kernel/schemas/json';
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import type { CLICommandAssetDescriptor } from '../schemas/descriptors.ts';
+import type { CommandOptions } from '../schemas/surface.ts';
+import type { CommandOutputBoundary } from '../schemas/command-implementation.ts';
+import type { CliHostOutput } from '../boot/schemas/providers.ts';
+/** Whether the command declares its own `--format` option (and owns its contract). */
+export declare function commandOwnsOutputFormat(options: readonly {
+    flags: string;
+}[] | undefined): boolean;
+/**
+ * Resolve and admit the format before dispatch. Data commands use the inherited
+ * default format when no explicit request was typed; runtime-UI and direct
+ * commands keep their own default output path.
+ */
+export declare function resolveGlobalOutputFormat(runtime: VibesRuntime, descriptor: CLICommandAssetDescriptor, options: CommandOptions, formatExplicit: boolean, outputBoundary?: CommandOutputBoundary): Promise<string | undefined>;
+/**
+ * Run one action under its resolved output request. Only a `data` command's
+ * returned value is rendered here. Runtime-UI and direct commands retain their
+ * output ownership, even if an implementation also returns data.
+ */
+export declare function runWithGlobalOutputFormat(runtime: VibesRuntime, format: string | undefined, action: () => Promise<JsonValue | void>, outputBoundary?: CommandOutputBoundary, formatExplicit?: boolean, commandOwnsFormat?: boolean, hostOutput?: CliHostOutput): Promise<void>;
+//# sourceMappingURL=output-format-request.d.ts.map

package/dist/surface/output-format-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-format-request.d.ts","sourceRoot":"","sources":["../../src/surface/output-format-request.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIpE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,GAAG,OAAO,CAElG;AAwCD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,yBAAyB,EACrC,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,OAAO,EACvB,cAAc,CAAC,EAAE,qBAAqB,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,EACvC,cAAc,CAAC,EAAE,qBAAqB,EACtC,cAAc,UAAuB,EACrC,iBAAiB,UAAQ,EACzB,UAAU,CAAC,EAAE,aAAa,GACxB,OAAO,CAAC,IAAI,CAAC,CAuBf"}