@vibesdotdev/cli 0.0.2 → 1.0.0-rc.3

package/dist/boot/bootstrap.js

@@ -0,0 +1,737 @@
+/**
+ * CLI Bootstrap
+ *
+ * Composition function for initializing the Vibes CLI application.
+ * Handles runtime initialization, plugin loading, and CLISurface setup.
+ *
+ * Public hosts import this factory from `@vibesdotdev/cli/bootstrap` or
+ * `@vibesdotdev/surface-cli`, which re-exports it. The executable belongs to
+ * cli-bin; this package supplies composition and the command surface.
+ *
+ * Usage:
+ * ```typescript
+ * import { createVibesCliApp } from '@vibesdotdev/surface-cli';
+ *
+ * import type { VibesCliAppOptions } from '@vibesdotdev/cli/bootstrap';
+ *
+ * // The executable supplies its environment, host declaration, output and argv.
+ * export async function runHost({ environment, host, hostOutput, argv }: VibesCliAppOptions) {
+ *   const app = await createVibesCliApp({ environment, host, hostOutput, argv });
+ *   await app.cli.run([...argv]);
+ * }
+ * ```
+ */
+import { CapabilityError, CaughtFailureSchema, RuntimeHardwareSchema, RuntimePurposeSchema, VibesRuntime, bootstrapVibesRuntime, composeChildEnv, createRuntimePlugin, createContextDescriptor, formatPluginFailureDiagnostic, parseBuildSurface, readPluginConfig, registerBuildSurface, requireRuntimeCwd, runtimeStdioContextDescriptor, } from "@vibesdotdev/kernel";
+import { shouldLoadTuiPluginGraph } from "./tui-plugin-policy.js";
+import { Command, CommanderError, Option } from "commander";
+import { getVibesClient } from "@vibesdotdev/kernel/client";
+import { CLISurface } from "../surface/CLISurface.js";
+import { CLIPluginConfigSchema } from "../schemas/command-recommendations.js";
+import { readVibesVersion } from "../boot/version.js";
+import { registerCliExternalUrlContext } from "../boot/external-url.js";
+import { detectOutputFormat, hostArgv } from "../boot/providers.js";
+import { commandWriters } from "../commands/output.js";
+import { renderCliFailure } from "../surface/failure-report.js";
+import { resolveCommandImplementation } from "../surface/command-implementation.js";
+import * as z from "zod/v4";
+function isCliEnvironmentFactory(value) {
+    return z.function().safeParse(value).success;
+}
+function writeEssentialPluginDiagnostic(output, input) {
+    output.write("stderr", `${formatPluginFailureDiagnostic(input)}\n`);
+}
+/**
+ * The hidden global flag a canonical help lookup child carries, so it never
+ * delegates again. It travels in argv, never the environment.
+ */
+export const CANONICAL_COMMAND_HELP_LOOKUP_FLAG = "--canonical-help-lookup";
+/**
+ * Re-enter the declared CLI host once, bound to R (`--workspace-root <R>`),
+ * when the materialized scoped tree cannot resolve a requested help path.
+ *
+ * The child is the authority: it either renders the exact command help or its
+ * own materialized tree rejects the path. The marker prevents recursive
+ * delegation; the child is bound to R by `--workspace-root`, and its env is
+ * the kernel's host set only, so it composes R's own config (RC04: no config
+ * handoff exists to outrank it). Action execution never delegates: the
+ * selected project plugin graph retains custody.
+ */
+function createCanonicalCommandHelpDelegate(runtime, hostRoot, selfSpawnArgv, isLookupChild) {
+    if (isLookupChild) {
+        return undefined;
+    }
+    return async (argv) => {
+        if (!hostRoot || !selfSpawnArgv?.length)
+            throw new CapabilityError('Canonical command help requires the runtime host\'s declared root and re-entry command.', 'UNAVAILABLE', { reason: 'cli-host-reentry-unavailable', retryable: false });
+        const [command, ...prefixArgs] = selfSpawnArgv;
+        if (!command)
+            throw new CapabilityError('Canonical command help has no declared re-entry command.', 'UNAVAILABLE', {
+                reason: 'cli-host-reentry-unavailable', retryable: false,
+            });
+        // The child runs through the host's own execution capability, with the
+        // kernel's host set (never the live env) and the lookup marker in argv. It
+        // is a help render: its output is relayed verbatim and its exit code is the answer.
+        const execution = await runtime
+            .query("runtime/execution")
+            .resolve();
+        // The child re-enters from this host's own working directory; a host
+        // without one cannot re-enter (`cwd-unavailable`).
+        const result = await execution.execute({
+            command,
+            args: [...prefixArgs, CANONICAL_COMMAND_HELP_LOOKUP_FLAG, "--workspace-root", hostRoot, ...argv.slice(2)],
+            cwd: requireRuntimeCwd(runtime),
+            env: composeChildEnv(runtime, {}),
+            envMode: "replace",
+        });
+        const { out, err } = await commandWriters(runtime);
+        if (result.stdout)
+            out(result.stdout);
+        if (result.stderr)
+            err(result.stderr);
+        return result.exitCode ?? 1;
+    };
+}
+/** Shared declarations for the actual command tree and pre-activation routing. */
+export function registerGlobalOptions(program, options = {}) {
+    return registerHmrOptions(program
+        .addOption(new Option(CANONICAL_COMMAND_HELP_LOOKUP_FLAG, "Internal: this invocation is a canonical help lookup").hideHelp())
+        .option("--finite", "Do not start autonomous background work (does not bypass authority or isolate filesystem access)")
+        .option("-v, --verbose", "Enable verbose logging")
+        .option("-q, --quiet", "Suppress non-essential output (errors still surface on stderr)")
+        .option("--format <format>", "Output format id resolved from this runtime's registered formatters (commands may own --format)", options.format ?? "table")
+        .option("--json", "Shorthand for --format json (machine-readable output to stdout)")
+        .option("--no-color", "Disable ANSI color codes (also honors NO_COLOR env)")
+        .option("--non-interactive", "Never prompt; fail or pick safe defaults instead (autodetected from non-TTY pipes; override with VIBES_FORCE_INTERACTIVE=1)")
+        .option("--no-interactive", "Alias for --non-interactive")
+        .option("-y, --yes", "Assume \"yes\" to confirmation prompts (per-command CRUD)")
+        .option("--profile <name>", "Active vibes profile (overrides $VIBES_PROFILE for this invocation)")
+        .option("--workspace-root <dir>", "Bind this invocation to <dir> instead of the nearest workspace above the current directory"));
+}
+function parseRootInvocation(argv) {
+    const program = registerGlobalOptions(new Command().exitOverride().configureOutput({ writeErr: () => { } }));
+    try {
+        const { operands } = program.parseOptions(argv.slice(2));
+        return {
+            finite: program.opts().finite === true,
+            canonicalHelpLookup: program.opts().canonicalHelpLookup === true,
+            operands,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        throw new CapabilityError(`The command line cannot be parsed: ${error.message}`, "INVALID_INPUT", {
+            reason: "argv-invalid",
+            details: { commanderCode: error.code },
+            cause: error,
+        });
+    }
+}
+/**
+ * Pre-parse `vibes tools run <tool> --purpose <p>` and return the purpose this
+ * host declares (rc02-rc03 C7). Like `--profile` and `--workspace-root`, it is
+ * read before any runtime exists: the declaration states it once, at boot, and
+ * nothing patches the scope afterwards. Only `tools run` declares a purpose
+ * this way; every other command declares `direct`. The command path comes from
+ * the global option declarations; the flag is read only before a `--`.
+ *
+ * An unknown purpose is `INVALID_INPUT` `scope-invalid`, the same refusal the
+ * command gives it; a blank or missing value declares none.
+ */
+export function readToolsRunPurposeFromArgv(argv) {
+    const [group, command] = parseRootInvocation(argv).operands;
+    if (group !== "tools" || command !== "run")
+        return undefined;
+    let value;
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            break;
+        if (token === "--purpose") {
+            const next = argv[i + 1];
+            value = next && !next.startsWith("-") ? next : undefined;
+            break;
+        }
+        if (token.startsWith("--purpose=")) {
+            value = token.slice("--purpose=".length);
+            break;
+        }
+    }
+    const purpose = value?.trim();
+    if (!purpose)
+        return undefined;
+    const parsed = RuntimePurposeSchema.safeParse(purpose);
+    if (!parsed.success) {
+        throw new CapabilityError(`Unknown purpose '${purpose}'. Purposes: ${RuntimePurposeSchema.options.join(", ")}.`, "INVALID_INPUT", { reason: "scope-invalid", details: { purpose } });
+    }
+    return parsed.data;
+}
+/**
+ * Whether the global `--finite` flag was passed, parsed against the global
+ * declarations only (an option after `--` is not the flag). Every command,
+ * serve included, declares `--finite ? finite : persistent` from this, once,
+ * before boot (rc02-rc03 §2.3); nothing patches it afterwards.
+ */
+export function isFiniteInvocation(argv) {
+    return parseRootInvocation(argv).finite;
+}
+/** Whether this invocation is a canonical help lookup child ({@link CANONICAL_COMMAND_HELP_LOOKUP_FLAG}). */
+export function isCanonicalHelpLookup(argv) {
+    return parseRootInvocation(argv).canonicalHelpLookup;
+}
+/** Where the consumer CLI runs; also the venue a host-credentials manifest is judged against. */
+export const CLI_HOSTING = Object.freeze({ mode: "local", owner: "consumer", venue: "user-device" });
+/** Where a serve host runs: the same machine, serving other processes over IPC (rc01 §2.4; N1). */
+export const SERVE_HOSTING = Object.freeze({ mode: "local", owner: "consumer", venue: "ipc-worker" });
+export function declareCliHostScope(input) {
+    // The CLI serves file tools on the workspace it bound for itself.
+    const workspace = { access: "write" };
+    if (input.workspaceRoot)
+        workspace.root = input.workspaceRoot;
+    // No `environmentTier`: kernel bootstrap binds it from the composition
+    // (`config['runtime.host'].environmentTier`: workspace layers over floor),
+    // never from the build flavor.
+    const qualifiers = {};
+    if (input.profile)
+        qualifiers.profile = input.profile;
+    if (input.hotReload)
+        qualifiers.hotReload = input.hotReload;
+    if (input.serve)
+        qualifiers.serve = input.serve.descriptorId;
+    return {
+        surface: input.serve?.surface ?? "cli",
+        hardware: input.hardware ?? "consumer",
+        purpose: input.serve?.purpose ?? input.purpose ?? "direct",
+        lifecycle: isFiniteInvocation(input.argv) ? "finite" : "persistent",
+        hosting: input.serve ? SERVE_HOSTING : CLI_HOSTING,
+        capabilities: input.serve
+            ? { requestPrincipals: true, sharedHost: true }
+            : input.hostCredentials
+                ? { hostCredentials: true }
+                : { interactiveSession: true },
+        workspace,
+        qualifiers,
+    };
+}
+/**
+ * The hardware a shim-launched host was baked for, parsed against the
+ * runtime's hardware schema; absent when nothing was baked. A baked value the
+ * runtime does not know is refused typed here, at the boundary that read it.
+ */
+function bakedHardware(value) {
+    const text = value?.trim();
+    if (!text)
+        return undefined;
+    const parsed = RuntimeHardwareSchema.safeParse(text);
+    if (!parsed.success) {
+        throw new CapabilityError(`The shim baked an unknown runtime hardware '${text}'.`, "INVALID_INPUT", {
+            reason: "hardware-invalid",
+            retryable: false,
+            details: { hardware: text },
+        });
+    }
+    return parsed.data;
+}
+/**
+ * The CLI host's own plugins, first in the floor: Logging's Config-free boot
+ * preparation, the CLI plugin (its kinds and providers), the build surface,
+ * the external-URL context, and the host's own consumer filesystem. The CLI
+ * surface emits its own diagnostics through Logging, and an emit on an
+ * unprepared Root refuses `logger-not-initialized`. No plane need select the
+ * `logging` plugin (a specialized, repair or serve host may not), so the floor
+ * prepares Logging on the console the host declares, by the same declared
+ * fact Logging's own plugin reads (C082a). A host that declares no console
+ * offers no diagnostics, and an emit there keeps the strict refusal. The
+ * home-write probe (and any consumer CLI filesystem need) reads
+ * `filesystem/adapter`; a workspace that declares its own plugin list without
+ * a consumer adapter (a cloud-only app checkout) must not take the host's
+ * writable home away, so the floor guarantees the Bun/Node adapter every CLI
+ * host runs on. First registration wins, so a workspace that composes the same
+ * plugins is unchanged.
+ */
+const CANONICAL_CLI_HOST_PLUGINS = new WeakSet();
+export function isCanonicalCliHostPlugin(plugin) {
+    return CANONICAL_CLI_HOST_PLUGINS.has(plugin);
+}
+export function createCliHostPlugin(buildSurface) {
+    const plugin = createRuntimePlugin({
+        id: "cli.host",
+        name: "CLI host",
+        description: "The Vibes CLI host's own Logging boot preparation, plugin, build surface, consumer filesystem and external URL context.",
+        dependencies: ["context"],
+        async onRegister(runtime) {
+            registerBuildSurface(runtime, buildSurface);
+            if (runtime.hasContext(runtimeStdioContextDescriptor.id)) {
+                await runtime.registerPlugin((await import("@vibesdotdev/logging/contexts")).loggingBootstrapPlugin);
+            }
+            await runtime.registerPlugin((await import("../commands/cli.plugin.js")).default);
+            await runtime.registerPlugin((await import("@vibesdotdev/filesystem/plugin")).filesystemPlugin);
+            await runtime.registerPlugin((await import("@vibesdotdev/host-node/filesystem")).bunFileSystemAdapterPlugin);
+            const inputOwner = await import("@vibesdotdev/host-node/terminal-input");
+            await runtime.registerPlugin(inputOwner.nodeTerminalInputPlugin());
+            runtime.registerLoader("context", "cli/terminal-input", async () => ({
+                meta: { id: "cli/terminal-input", kind: "context", priority: -1 },
+                impl: { provide: async () => (await getVibesClient(inputOwner.nodeTerminalInputDescriptor.id, runtime)).input },
+            }), { constraint: { surfaces: ["cli"] }, priority: -1 });
+            registerCliExternalUrlContext(runtime);
+        },
+    });
+    CANONICAL_CLI_HOST_PLUGINS.add(plugin);
+    return plugin;
+}
+/** The original executable floor, retained as data for an opt-in execution owner. */
+export const CLI_EXECUTION_COMPOSITION_CONTEXT_ID = "cli/execution-composition";
+/**
+ * Create the Vibes CLI application: one boot through the entry
+ * (`bootstrapVibesRuntime`, rc02-rc03 §2.1), a workspace composition bound as
+ * the host's default runtime, deferred until a command is selected. Workspace
+ * binding is host-owned; root/nested config layering and embedded app exclusion
+ * remain kernel-owned. The CLI forwards the real cwd and selected loader.
+ */
+export async function createVibesCliApp(options) {
+    const buildSurface = options.buildSurface ?? parseBuildSurface(undefined);
+    const shimChannel = options.host?.shimChannel === true;
+    const verbose = options.verbose ?? false;
+    const floorPlugins = [
+        async () => createCliHostPlugin(buildSurface),
+        ...(options.surfaceFloorPlugins ?? []),
+        ...(options.hostPlugins ?? []),
+    ];
+    const floor = options.hostConfig
+        ? { plugins: floorPlugins, config: options.hostConfig }
+        : { plugins: floorPlugins };
+    const quietReport = {
+        warn: (message) => options.hostOutput.write("stderr", `${message}\n`),
+        error: (message) => options.hostOutput.write("stderr", `${message}\n`),
+        skipped: ({ plugin, error }) => {
+            writeEssentialPluginDiagnostic(options.hostOutput, { scope: "cli", action: "Skipped plugin", plugin, error });
+            // Under -v the skip also carries its cause, through the one failure
+            // renderer (cause chain, key redaction); the default line stays value-free.
+            if (verbose)
+                options.hostOutput.write("stderr", `${renderCliFailure(CaughtFailureSchema.parse(error), { verbose: true })}\n`);
+        },
+    };
+    const report = verbose
+        ? { ...quietReport, info: (message) => options.hostOutput.write("stderr", `${message}\n`) }
+        : quietReport;
+    const interactiveComposition = {
+        kind: "workspace",
+        attestHostGraph: options.attestHostGraph,
+        floor,
+        global: options.globalPackagePlugins === true,
+        failurePolicy: options.pluginFailurePolicy ?? "report",
+        report,
+    };
+    // Headless boots omit exports whose package metadata declares the TUI surface.
+    // A host selection policy remains an additional filter for its own command graph.
+    const headlessOmitComposition = {
+        ...interactiveComposition,
+        omitSurfaces: ['tui'],
+    };
+    const headlessComposition = options.headlessPluginSelectionPolicy === undefined
+        ? headlessOmitComposition
+        : {
+            ...headlessOmitComposition,
+            selectionPolicy: options.headlessPluginSelectionPolicy,
+        };
+    const composition = shouldLoadTuiPluginGraph(options.argv, {
+        attachedTerminal: options.attachedTerminal === true,
+    })
+        ? interactiveComposition
+        : headlessComposition;
+    /**
+     * THE DECLARATION. The host states its scope once, per boot. The bearer
+     * capability comes from the environment's own capture: a live
+     * host-credentials manifest makes this a `hostCredentials` host.
+     */
+    const createDefaultEnvironment = async (serve) => {
+        // A caller environment needs no Bun import, construction or native producer.
+        // Only the default executable host declares scope and spawn data from its native argv.
+        const argv = [...options.argv];
+        const profile = readProfileFromArgv(argv);
+        const hmr = readHmrFromArgv(argv);
+        const workspaceRoot = options.workspaceRoot ?? readWorkspaceRootFromArgv(argv);
+        const purpose = readToolsRunPurposeFromArgv(argv);
+        const environmentModule = await import("@vibesdotdev/host-bun");
+        const hostFacts = { profile, hmr };
+        if (options.version)
+            hostFacts.version = options.version;
+        const environmentOptions = {
+            nativeLaunch: { manifestPath: environmentModule.bunNativeLaunchManifestPath },
+            scope: (captured, host) => {
+                const input = {
+                    argv,
+                    buildSurface,
+                    workspaceRoot,
+                    profile,
+                    hostCredentials: environmentModule.hasLiveHostCredentials(captured, CLI_HOSTING.venue, host),
+                    hotReload: declaredHotReload(captured).hotReload,
+                };
+                if (purpose)
+                    input.purpose = purpose;
+                // The baked hardware is a shim channel key; a host the shim did not
+                // launch declares its own.
+                const hardware = shimChannel ? bakedHardware(captured[environmentModule.SHIM_CHANNEL_KEYS.hardware]) : undefined;
+                if (hardware)
+                    input.hardware = hardware;
+                if (serve)
+                    input.serve = serve;
+                return declareCliHostScope(input);
+            },
+            host: declareCliHost(options.host, hostFacts),
+        };
+        return environmentModule.createRuntimeEnvironmentBunPlugin(profile ? { ...environmentOptions, paths: { profileName: profile } } : environmentOptions);
+    };
+    const environment = options.environment;
+    const boot = async (serve, transport) => {
+        const declared = isCliEnvironmentFactory(environment)
+            ? await environment(serve === undefined ? undefined : Object.freeze({ ...serve }))
+            : environment ?? await createDefaultEnvironment(serve);
+        const booted = await bootstrapVibesRuntime({
+            environment: declared,
+            // A transport host composes the CLI floor, what the selected command's
+            // implementation declares it needs there, and the entry; nothing else.
+            composition: transport
+                ? {
+                    kind: "literal",
+                    plugins: [
+                        async () => createCliHostPlugin(buildSurface),
+                        ...transport.plugins.map((plugin) => async () => plugin),
+                        async () => transport.entry,
+                    ],
+                }
+                : composition,
+            binding: "default",
+            // Validate the serving declaration before autonomous work can activate.
+            activation: "deferred",
+        });
+        try {
+            parseRootInvocation(hostArgv(booted));
+            if (serve) {
+                const scope = booted.declaredScope;
+                if (scope.surface !== serve.surface || scope.purpose !== serve.purpose ||
+                    scope.hosting?.mode !== SERVE_HOSTING.mode || scope.hosting?.owner !== SERVE_HOSTING.owner ||
+                    scope.hosting?.venue !== SERVE_HOSTING.venue || scope.qualifiers?.serve !== serve.descriptorId ||
+                    scope.capabilities?.requestPrincipals !== true || scope.capabilities?.sharedHost !== true ||
+                    scope.capabilities?.interactiveSession === true || scope.capabilities?.hostCredentials === true) {
+                    throw new CapabilityError("The caller environment does not declare the selected serving host.", "CONFLICT", {
+                        reason: "cli-serve-scope-mismatch", details: { descriptorId: serve.descriptorId },
+                    });
+                }
+                if (!serve.deferActivation)
+                    await booted.activatePlugins();
+            }
+            return booted;
+        }
+        catch (error) {
+            try {
+                await booted.dispose();
+            }
+            catch (disposeError) {
+                throw new AggregateError([error, disposeError], "CLI host admission and cleanup both failed", { cause: error });
+            }
+            throw error;
+        }
+    };
+    const runtime = await boot();
+    const program = new Command()
+        .name("vibes")
+        .description("Vibes Developer CLI")
+        .version(options.version ?? readVibesVersion(runtime))
+        .exitOverride();
+    registerGlobalOptions(program, options);
+    program
+        .addHelpText("after", [
+        "",
+        "Get started:",
+        "  vibes profile --help  Manage isolated profiles",
+        "  vibes runtime --help  Inspect runtime commands",
+        "  vibes completion zsh  Generate shell completion",
+    ].join("\n"));
+    const strict = options.strict === true;
+    // `--json` / `--format json` are GLOBAL flags that every command reading
+    // `cli/output-format` is documented to honour. Detect from argv when the
+    // embedding host did not pin a format.
+    const hostIdentity = runtime.localEnvironment.hostIdentity?.();
+    const surfaceOptions = {
+        verbose,
+        format: options.format ?? detectOutputFormat(hostArgv(runtime)),
+        includeInternal: options.includeInternal ?? false,
+        enablePatterns: true,
+        strictCommandGroups: strict,
+        strictGroupParents: strict,
+        canonicalCommandHelp: createCanonicalCommandHelpDelegate(runtime, hostIdentity?.hostRoot ?? null, runtime.localEnvironment.selfSpawnArgv?.() ?? null, isCanonicalHelpLookup(hostArgv(runtime))),
+        rootFallbackGroups: options.rootFallbackGroups,
+        hostOutput: options.hostOutput,
+        onBeforeAutoExit: options.onBeforeAutoExit,
+        // The serve transition (rc02-rc03 §2.3): dispose the un-activated CLI
+        // runtime, then boot the serve host through the same entry. Nothing was
+        // resolved against the CLI runtime during command selection, and any read
+        // of it after disposal throws `runtime-unbootstrapped`.
+        serveTransition: async ({ descriptorId, serve }) => {
+            let transport;
+            if (serve.composition === "transport") {
+                const descriptor = runtime.query("cli/command").withId(descriptorId).descriptors()[0];
+                const selected = await resolveCommandImplementation(runtime, descriptorId);
+                if (!descriptor || selected.kind !== "implemented") {
+                    throw new CapabilityError("The transport entry has no admitted command registration.", "UNAVAILABLE", {
+                        reason: "cli-transport-entry-unavailable", details: { descriptorId },
+                    });
+                }
+                const executionCompositionPlugin = createRuntimePlugin({
+                    id: "cli.transport-entry",
+                    dependencies: ["cli"],
+                    descriptors: selected.transportEntry ? [] : [descriptor],
+                    onRegister(current) {
+                        if (!selected.transportEntry) {
+                            current.registerLoader("cli/command", descriptorId, async () => ({ impl: { execute: selected.execute } }));
+                        }
+                        const executionFloor = options.hostConfig
+                            ? { plugins: [...(options.hostPlugins ?? [])], config: options.hostConfig }
+                            : { plugins: [...(options.hostPlugins ?? [])] };
+                        const executionComposition = {
+                            floor: executionFloor, global: composition.global, failurePolicy: composition.failurePolicy,
+                        };
+                        current.registerDescriptor("context", createContextDescriptor({
+                            id: CLI_EXECUTION_COMPOSITION_CONTEXT_ID,
+                            description: "Executable-owned composition declaration for its separate execution host.",
+                        }));
+                        current.registerLoader("context", CLI_EXECUTION_COMPOSITION_CONTEXT_ID, async () => ({ impl: executionComposition }));
+                    },
+                });
+                transport = selected.transportEntry
+                    ? {
+                        entry: selected.transportEntry,
+                        plugins: [...selected.transportPlugins, executionCompositionPlugin],
+                    }
+                    : {
+                        entry: executionCompositionPlugin,
+                        plugins: selected.transportPlugins,
+                    };
+            }
+            await runtime.dispose();
+            return boot({ descriptorId, surface: serve.surface, purpose: serve.purpose,
+                deferActivation: serve.deferActivation, composition: serve.composition }, transport);
+        },
+    };
+    let cliConfig;
+    try {
+        cliConfig = await readPluginConfig(runtime, 'cli', CLIPluginConfigSchema);
+    }
+    catch (error) {
+        try {
+            await runtime.dispose();
+        }
+        catch (disposeError) {
+            throw new AggregateError([error, disposeError], 'CLI config admission and cleanup both failed', { cause: error });
+        }
+        throw error;
+    }
+    const recommendations = cliConfig?.commandRecommendations ?? options.commandRecommendations;
+    if (recommendations !== undefined) {
+        surfaceOptions.commandRecommendations = recommendations;
+    }
+    // INVARIANT for plugin authors: activation is EFFECT-GATED, so a plugin must
+    // never register command descriptors (or command groups) from `onActivate`
+    // — do it in `onRegister`. Command visibility must not depend on what the
+    // selected action is allowed to write.
+    // The caller's bearer is not bound into the runtime environment or
+    // `process.env`. Readers call auth's `resolveCallerBearer` with their runtime.
+    const cli = new CLISurface(runtime, program, surfaceOptions);
+    cli.addInvocationPreparer({
+        prepare: async (info) => {
+            const current = cli.activeRuntime;
+            // `--hmr` owes a notice to every invocation that will not arm hot reload.
+            // A launcher is judged by the serve command it spawns.
+            if (readHmrFromArgv(hostArgv(current)) === "1") {
+                const serve = info.effects.serve ?? launchedServe(current, info.effects.launches);
+                const notice = describeHmrInvocation(serve, info.commandPath);
+                if (notice)
+                    (await commandWriters(current)).err(notice);
+            }
+            if (!info.effects.homeWrite || current.activated || info.effects.serve?.deferActivation)
+                return;
+            // Logger outputs can resolve config/environment, which in turn reads the
+            // persisted environment selection. Keep that storage path behind the
+            // selected action's declared home-write effect.
+            const { initializeLoggers } = await import("@vibesdotdev/logging");
+            await initializeLoggers(current);
+            // Boot phases 5–7: activation registers deferred runtime clients used by
+            // executable commands. Metadata-only actions consume descriptors and do
+            // not need implementations or their storage-backed activation work.
+            await current.activatePlugins();
+        },
+    });
+    return { runtime, program, cli };
+}
+/** The serve effect of the command a launcher spawns, read from its descriptor. */
+function launchedServe(runtime, launches) {
+    if (!launches || !runtime.hasKind("cli/command"))
+        return undefined;
+    const descriptor = runtime.query("cli/command").withId(launches).descriptors()[0];
+    return descriptor?.effects?.serve;
+}
+/**
+ * What will the selected command actually do with `--hmr`? A serve command
+ * that declares `hotReload` arms it; any other serve command is a long-running
+ * service that does not; everything else exits before a source can change.
+ * The command's descriptor (`effects.serve`) is the one source; no argv table.
+ */
+export function classifyHmrInvocation(serve) {
+    if (!serve)
+        return "one-shot";
+    return serve.hotReload ? "arms" : "service-without-hmr";
+}
+/**
+ * The one stderr line `--hmr` owes this invocation, or null when the selected
+ * command arms hot reload and will report for itself.
+ */
+export function describeHmrInvocation(serve, commandPath) {
+    const kind = classifyHmrInvocation(serve);
+    if (kind === "arms")
+        return null;
+    if (kind === "service-without-hmr") {
+        const command = commandPath.slice(1).join(" ");
+        return (`--hmr: \`vibes ${command}\` is a long-running service, but this surface does not arm plugin hot reload yet ` +
+            "— nothing in this process watches source, and nothing will reload. " +
+            "The surface that does is `vibes --hmr runtime daemon serve`.\n");
+    }
+    // A one-shot process exits before any source can change, so arming a watcher
+    // would be theatre; silently ignoring the flag would be worse, because the
+    // operator would believe a fleet was hot.
+    return ("--hmr: no long-running service in this invocation; nothing to hot-reload. " +
+        "Pass it to a service command (e.g. `vibes --hmr runtime daemon serve`) to arm plugin hot reload.\n");
+}
+const HMR_ON_FLAG = "--hmr";
+const HMR_OFF_FLAG = "--no-hmr";
+/**
+ * Pre-parse `--hmr` / `--no-hmr` and return what it asks for: `"1"` (on), `"0"`
+ * (an explicit veto) or `undefined` (absent).
+ *
+ * A boolean sibling of {@link readProfileFromArgv}, and for the same reason:
+ * the flag has to be readable BEFORE Commander parses anything, because
+ * `startHostHotReload` runs inside the service command that Commander is on its
+ * way to dispatching.
+ *
+ * `--no-hmr` explicitly turns it OFF (`"0"`), so a child of a `--hmr` parent
+ * can opt out without unsetting an inherited variable.
+ *
+ * ONLY the two spellings Commander declares (see {@link registerHmrOptions}).
+ * `--hmr=true` / `--hmr=false` were once honoured here, but Commander rejects
+ * `--flag=value` on a boolean option, so those two spellings used to set the
+ * flag and then die with `unknown option` before any command ran.
+ *
+ * LAST FLAG WINS, because that is what Commander does. An earlier revision
+ * returned on the FIRST recognized token, so `vibes --hmr --no-hmr runtime
+ * daemon serve` came out on while `program.parse` of the same argv yielded
+ * `{hmr: false}` — and since nothing reads Commander's `hmr` option, the
+ * pre-parser is the half that decides.
+ */
+export function readHmrFromArgv(argv) {
+    let last = null;
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            break;
+        if (token === HMR_ON_FLAG || token === HMR_OFF_FLAG)
+            last = token;
+    }
+    if (last === HMR_ON_FLAG)
+        return "1";
+    if (last === HMR_OFF_FLAG)
+        return "0";
+    return undefined;
+}
+/**
+ * Every argv spelling {@link readHmrFromArgv} honours. Exported so the test
+ * can assert that the shipping Commander declaration accepts each of them —
+ * the pre-parser and the parser drifting apart is invisible to a unit test that
+ * only calls the pure function.
+ */
+export const HMR_ARGV_SPELLINGS = [HMR_ON_FLAG, HMR_OFF_FLAG];
+/**
+ * Declare the `--hmr` / `--no-hmr` global pair on a program.
+ *
+ * ONE declaration site, called by `createVibesCliApp` and exercised directly by
+ * `hmr-global-flag.test.ts`, so "the pre-parser accepts it" and "the shipping
+ * command accepts it" cannot diverge without turning a test red.
+ */
+export function registerHmrOptions(program) {
+    return program
+        .option(HMR_ON_FLAG, "Hot-reload linked plugins when their source changes (long-running service commands; one-shot commands acknowledge and continue). Refused on cloud hardware.")
+        .option(HMR_OFF_FLAG, "Disable plugin hot reload for this invocation, overriding an inherited VIBES_HMR=1 (e.g. a service spawned by a `--hmr` parent).");
+}
+/** The channel key `--hmr` / `--no-hmr` publish to this host's readers and its children. */
+export const HMR_CHANNEL_KEY = "VIBES_HMR";
+/** Declare hot reload from the canonical channel captured by this host. */
+export function declaredHotReload(captured) {
+    const hmr = captured[HMR_CHANNEL_KEY]?.trim();
+    if (hmr === "0")
+        return { hotReload: "off" };
+    if (hmr === "1")
+        return { hotReload: "on" };
+    return {};
+}
+/**
+ * Pre-parse `--profile <name>` / `--profile=<name>` and return the name.
+ *
+ * Commander parses the same flag later when `program.parseAsync` runs, but
+ * by then `loadConfig` and `registerCorePlugins` have already chosen
+ * profile-scoped paths, so the host needs it before the environment exists.
+ *
+ * Strict: ignores anything that looks like another flag (`--profile --foo`).
+ */
+export function readProfileFromArgv(argv) {
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            break;
+        if (token === "--profile") {
+            const next = argv[i + 1];
+            return next && !next.startsWith("-") ? next : undefined;
+        }
+        if (token.startsWith("--profile=")) {
+            const value = token.slice("--profile=".length);
+            return value || undefined;
+        }
+    }
+    return undefined;
+}
+export function declareCliHost(host, facts) {
+    const spawnEnv = { ...host?.spawnEnv };
+    if (facts.profile)
+        spawnEnv.VIBES_PROFILE = facts.profile;
+    if (facts.hmr)
+        spawnEnv[HMR_CHANNEL_KEY] = facts.hmr;
+    return facts.version ? { ...host, spawnEnv, version: facts.version } : { ...host, spawnEnv };
+}
+/**
+ * Pre-parse `--workspace-root <dir>` / `--workspace-root=<dir>` and return the
+ * directory as written. Commander parses the same global flag later, but the
+ * environment captures its workspace binding when it is constructed, before
+ * any command exists. The kernel's workspace-root policy resolves a relative
+ * directory against the environment's captured cwd and validates it: an
+ * existing directory that is neither `/` nor home, else `INVALID_INPUT`
+ * `workspace-invalid`.
+ */
+export function readWorkspaceRootFromArgv(argv) {
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            break;
+        let value;
+        if (token === "--workspace-root") {
+            const next = argv[i + 1];
+            value = next && !next.startsWith("-") ? next : undefined;
+        }
+        else if (token.startsWith("--workspace-root=")) {
+            value = token.slice("--workspace-root=".length);
+        }
+        else {
+            continue;
+        }
+        return value?.trim() || undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=bootstrap.js.map