@vibesdotdev/cli 0.0.1 → 1.0.0-rc.2

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,41 +1,282 @@
 # @vibesdotdev/cli
 
-The CLI surface for **vibes**. This is a library, not a binary — host apps (`apps/cli-bin`) compose it to produce the `vibes` executable.
+Descriptor-driven CLI framework for composing Vibes command groups and commands.
 
-## What it is
+This package is part of the public Vibes framework package set. The source repository is private while the public repository split is being prepared, so package documentation is published on the Vibes docs site.
 
-`packages/cli` turns runtime descriptors into a Commander.js command tree. Feature packages register `cli/group` and `cli/command` descriptors against the runtime; this package walks those descriptors, applies scope filters, and renders them as commands, help text, and shell completions.
+## Install
 
-It does **not** own:
+```sh
+bun add @vibesdotdev/cli
+# or
+npm install @vibesdotdev/cli
+```
 
-- The compiled binary or startup glue → `apps/cli-bin`.
-- The published npm wrapper → `packages/cli-bin`.
-- Any specific command's behavior — domain logic lives in the feature package that registered it.
+## Documentation
 
-## How it's consumed
+- Package guide: https://docs.vibes.dev/cli
+- Vibes docs: https://docs.vibes.dev
+- Generated CLI reference: [`docs-generated/README.md`](./docs-generated/README.md)
 
-```ts
-import { CLISurface } from '@vibesdotdev/cli';
-import { cliPlugin } from '@vibesdotdev/cli/plugin';
+## Reference docs (generated)
+
+The `docs-generated/` tree is produced from the live `cli/group` and `cli/command` descriptor registry — never edit it by hand. The renderer (`generateCliDocs`, `readGeneratedDocs`, `defaultOutDir`) lives here at `src/commands/docs/generate.ts` and takes a booted runtime. The runtime-bootstrap that loads the full aggregator plugin set and the standalone `[--out <dir>]` entrypoint belong to the cli-bin app repository (which depends on `@vibesdotdev/plugins`), so this package keeps no dependency edge to the aggregator. Two invariants keep the tree honest:
+
+- **Idempotency** — running the generator twice on a clean tree produces a byte-identical result. The cli-bin app's docs-generation suite re-generates into a temp dir and asserts no diff against this checked-in tree.
+- **Examples are executable** — any `examples[]` entry that sets `expectExit` and/or `expectStdoutContains` opts into the cli-bin app's docs-example suite, which runs the documented command via the real `vibes` binary and asserts the contract.
+
+Workflow:
 
-// Register the CLI plugin with the runtime, then build the surface
-// against the runtime's resolved descriptor tree.
-const surface = new CLISurface({ runtime, scope });
-await surface.run(process.argv);
+```sh
+# From the cli-bin app repository (the app tier boots the full plugin set)
+bun run docs:generate            # regenerate cli/docs-generated/
+git diff --exit-code -- cli/docs-generated/   # CI invariant — exit 0 on a clean run
+bun test src/__tests__/docs-generation.test.ts   # idempotency + structural checks
+bun test src/__tests__/docs-examples.test.ts     # executes opted-in examples
+```
+
+To opt a command into the example-execution test, add fields on the descriptor's `examples[]`:
+
+```ts
+examples: [
+  {
+    command: 'vibes foo bar',
+    description: 'What this example shows the user',
+    expectExit: 0,
+    expectStdoutContains: 'expected substring',
+    // Optional. Gate behind VIBES_DOCS_TEST_SLOW=1 if the example boots a
+    // server, hits the network, etc.
+    slow: true
+  }
+]
 ```
 
-Hosts also commonly import:
+The generator owns reference material (synopsis, options, examples). Hand-authored prose (HOW-TO, concepts) lives elsewhere and is not touched by `docs:generate`.
+
+## Design inventory
+
+Import `readCliDesignInventory` and `generateCliDesignInventory` from
+`@vibesdotdev/cli/design-inventory`. Pass a runtime with filesystem and paths
+owners plus an absolute `{ root }`. Reading
+returns live toolkit methods, formats and observed showcase coverage. The canonical showcase lives at `src/support/ui/showcase.ts`; coverage awaits real toolkit calls and reports omissions. Generation owns `src/support/cli-inventory.generated.ts`
+and returns owner-relative `written` and `stale` paths; `check: true` reports
+drift without writing. This narrow entrypoint requires no CLI bootstrap.
+
+## Host composition
+
+`createVibesCliApp` uses the executable host declarations for package selection,
+root fallback groups, host output and captured environment. Hosts provide
+`rootFallbackGroups` and may add `headlessPluginSelectionPolicy` for their
+command graph. Every headless workspace composition sets
+`omitSurfaces: ['tui']`; the kernel reads each selected export's owning
+package.json `vibes.exportSurfaces`, reports matching exports as
+`not-composed` with reason `surface-omitted`, and does not import them. A host
+selection policy applies in addition to this declared surface selection.
+The TUI launcher and command palette remain runtime contributions from the
+selected plugin graph. CLI's `shouldLoadTuiPluginGraph` uses argv and captured
+terminal facts to decide whether to load the TUI-capable graph. Hosts admit
+`shell-integration` through `rootFallbackGroups` when composing CLI completion.
+The descriptor keeps its group, and strict orphan-group validation remains
+enabled.
+
+`cliPlugin` composes completion's consumer plugin and the output-format
+capability. The `./completion/kinds` subpath exposes metadata; `./completion/plugin`
+exposes the lazy consumer composition. Root exports remain the primary CLI
+contract. Global `--format <id>` resolves the selected runtime formatter before
+command work. Returned-data commands render once through the selected formatter and use
+the inherited table format by default. `--json` uses the selected JSON
+formatter, including host replacements. Runtime-UI output uses the selected
+formatter. An
+implementation that declares `outputBoundary: 'direct'` owns its bytes and
+refuses global non-JSON formats as
+`INVALID_INPUT / cli-output-format-boundary-unsupported` before execution.
+Malformed ids refuse `INVALID_INPUT / cli-output-format-invalid`; missing
+formatters refuse `NOT_FOUND / cli-output-format-unavailable`.
+`--json` wins over `--format`, and a command's declared `--format` option remains
+command-owned.
+
+Selected plugin failures report by default so unrelated and repair commands
+remain available. Kernel currently uses one workspace `failurePolicy` for both
+selected-plugin and descriptor-discovery failures; hosts can select `abort` for
+a complete graph, and the mandatory host floor always aborts. A separate default
+requires a kernel contract change; CLI exposes no discovery-only policy. `@vibesdotdev/workspace`
+is a devDependency only: no production CLI module imports it; codegen tests
+use its canonical schema and plugin. The `cli` plugin composes no Workspace plugin. `vibes runtime codegen` resolves the `workspace/static-loader` kind
+through the runtime at call time. A host that wants generation composes
+`@vibesdotdev/workspace/static-loader/plugin`; a host that did not refuses
+`UNAVAILABLE / static-loader-generator-unavailable` before writing. CLI carries no
+production dependency edge back to Workspace, so the package graph stays acyclic.
+
+`--hmr` and `--no-hmr` use the canonical `VIBES_HMR` handoff.
+
+## Runtime ownership
+
+Keep-alive decisions and JSON-output accounting belong to the executing
+runtime's `cli-invocation` client (`runtime/client`), and every reader names the
+runtime it reads. Each invocation and serve transition starts fresh; another
+runtime's reset or disposal leaves it intact. Command discovery reads the live
+descriptor graph on each query; there is no cache or invalidation adapter.
+
+Every `./output` writer names the runtime it writes through: `writeStdout`,
+`writeStdoutLine` and `writeJson` use that runtime for stdio, output-plane flush
+and the invocation ledger, and write/flush failure never records successful JSON
+delivery. There is no runtime-free overload and no CLI native stdout writer or
+client cache; pre-bootstrap native text output comes from the public
+`@vibesdotdev/host-node/stdio` owner (`createNodeRuntimeStdio`).
+
+`runtime export PATH` preserves absolute paths. Relative paths use the bound
+workspace root first, then `requireRuntimeCwd(runtime)`; without either they
+refuse `UNAVAILABLE / cwd-unavailable`. Export never borrows process cwd.
+Composed-runtime tests record output and filesystem writes with isolated
+destinations.
+
+`requestCLIExit` synchronously stops the action. Catch sites identify its
+signal with `isCLIExitSignal`; `CLIExitSignal` is a type-only contract, not a
+constructable public adapter. Nonzero exits carry a kernel settled outcome,
+while successful exits stay silent, including under `--json`.
+
+The CLI hands explicit workspace selection to `host-bun`; otherwise the host
+selects from cwd. Profile environment ids are admitted through Config before
+profile mutation or activation output. This binds `runtime/workspace-path`.
+Kernel composition separately merges root and nested workspace settings toward cwd; a bound
+`workspace.role: 'nested'` also inherits ancestor composition. More specific
+settings win, objects merge deeply, and arrays/scalars replace. The host floor
+remains available. Nested workspace string plugin selections append without
+duplicates; nested embedded app settings and function-loader selections stay
+out of workspace composition. Selected modules are still imported and validated:
+throwing or invalid configs refuse `INVALID_INPUT / config-invalid` and name
+the selected file, including under the plugin repair policy. Deleted
+`postBootstrap` remains refused and retired config-handoff variables have no
+authority. Both bootstrap suites prove this through `createVibesCliApp` with
+disposable fixtures. CLI adds no config resolver.
+
+Kernel composition binds `config['runtime.host'].environmentTier` from workspace
+settings over the executable's `hostConfig` floor. Without either declaration,
+credential reads refuse `tier-undeclared`; build flavor supplies no tier.
+A host at its declared user home can boot unbound; workspace reads alone refuse
+`NOT_FOUND / workspace-unbound`. Caller environment factories declare fresh hosts
+for MCP, worker, relay and transport re-entry. The CLI preserves their captured
+argv and environment, validates serving scope before activation, and keeps deferred
+relay activation, transport isolation and disposal under runtime ownership.
+
+## Flags and prompts
+
+Explicit `--non-interactive` / `--no-interactive` and JSON output
+(`--json`, `--format json`, `--format=json`) always disable interactivity.
+Captured `forceInteractive` and `forceTty` override only terminal autodetection
+in the interactive action gate. Runtime observations and normalized Commander
+options decide launch; JSON and explicit noninteractive options always select
+the supported fallback.
+Supplied runtime facts are authoritative: missing observations mean no terminal.
+`resolveCliFlags(argv, terminalFacts)` uses only the explicitly supplied
+terminal facts; callers pass `null` when the runtime has no observation.
+
+Prompt, password, confirm, select and multiselect validate their requests once
+through `src/schemas/prompts.ts` before terminal observation, reads or output.
+Malformed or unreadable requests refuse `INVALID_INPUT / cli-prompt-invalid`
+with a fixed message and no caller values or native exception details.
+Selection values remain opaque caller-owned references. Defaults, cancellation,
+empty choices, password masks/confirmation and required multiselect retain their
+existing behavior.
+
+Interactive terminal input uses the public `@vibesdotdev/host-node/terminal-input`
+owner. Production `createCliHostPlugin` composes its runtime-owned semantic
+client and a default `cli/terminal-input` context at priority -1. Explicit
+context overrides retain priority. `cli/ui` and profile confirmation resolve
+that context through `hasContext`/`context`; malformed or unreadable values
+refuse `INVALID_INPUT / cli-terminal-input-invalid`, and owner refusals propagate.
+The CLI context schema validates the transport's callable members and preserves
+its identity and method receivers.
+
+`readTerminalLine` and `readHiddenTerminalLine` use the explicitly resolved
+transport. With no registered transport, terminal reads refuse
+`UNAVAILABLE / cli-terminal-input-unavailable`; CLI does not create a
+runtime-free host transport. The host owns line/hidden input, masks, cancellation, EOF,
+paste handling, output completion, stream listeners and raw/flow restoration.
+CLI contains no native input implementation. Profile cancellation and input
+refusals preserve the target; piped confirmation still uses only the first
+line of a runtime stdin read bounded to 4096 bytes.
+
+## Implementation resolution and verification
+
+The kernel validates command implementations against the CLI-owned schema:
+callable `execute` and optional `transportPlugins`. Resolution preserves
+the receiver and transport plugins, reports the default stub as absent, and
+propagates loader failures. Invalid implementations refuse
+`INVALID_INPUT / implementation-invalid` with value-free `{ kind, id }` facts.
+
+`bun run check` checks all source and test TypeScript/TSX without emission.
+`bun run build` emits production
+JavaScript, declarations and declaration maps through `tsconfig.build.json`,
+excluding tests, specs, stubs and Svelte sources. `bun run test` provides
+in-process source/runtime and manifest proof. Bootstrap tests call
+`createVibesCliApp` and `CLISurface.run` with declared caller environments;
+failure-envelope tests call `reportBootstrapFailure` with recording host output.
+They preserve scope admission, disposal, output, flush and exit assertions
+without child CLI harnesses. Native execution and completion syntax tests
+exercise the actual host/shell boundary. These checks do not verify
+distributed artifacts or establish overall package acceptance.
+
+Run canonical lint with
+`node ../node_modules/@vibesdotdev/internal-oxlint-toolchain/ratchet.mjs`
+from this package; `package.json` has no `lint` script. Run the runtime
+`workspace-rules` tool with `action: "check"` and this package path.
+
+The check uses the `bun` export condition, so it also follows public sibling
+exports into their TypeScript sources. The real process-pattern fixture composes
+`@vibesdotdev/pm/plugin`, which loads PM's builtin resource-provider graph.
+PM provider errors are sibling-owner failures; the CLI keeps all tests in its
+typecheck and uses no direct PM internal imports. See
+[the kernel boundaries](./SPEC.md#kernel-boundaries).
+
+The explicit `@vibesdotdev/cli/plugin` entrypoint contributes five lazy
+`cli/pattern` implementations. `./kinds` registers metadata only.
+`PatternResolver` and `createPatternResolver(runtime)` query that runtime;
+`registerPattern` replaces through kernel registration before or after activation,
+and `getPatternTypes` reads live descriptors without loading implementations.
+Custom registrations are runtime-local. Missing patterns refuse
+`NOT_FOUND / not-registered`; malformed implementations refuse
+`INVALID_INPUT / implementation-invalid`, with only `{ kind, id }` facts.
+Loader failures propagate and register methods retain their receiver.
+
+The primary root exports CLI contracts, registration and public helpers.
+Use `./bootstrap` for `createVibesCliApp`, `./surface` for `CLISurface`,
+and `./kinds` for the default command implementation. The surface entrypoint
+has its own barrel; `@vibesdotdev/surface-cli` keeps using `./bootstrap`.
 
-- `@vibesdotdev/cli/plugin` — the runtime plugin that registers `cli/group` and `cli/command` kinds.
-- `@vibesdotdev/cli/config` — `defineConfig` and config types for user `vibes.config.*` files.
+Generated process commands resolve the handed runtime's real `pm/client`.
+Declared start preserves PM's daemon graph, stop retains timeout/force, and
+status retains state/pid. Tail selects structured levels and the exact top-level
+fields named by descriptor filter flags, such as `--namespace svc`.
 
-Shell completions for the live descriptor tree are emitted via `vibes completion bash|zsh|fish|fig`, implemented inside this package.
+Environment overrides and continuous follow require PM client extensions
+detailed in SPEC.md. Until those exist, `--env` and `--follow` report explicit
+`UNAVAILABLE` refusals instead of silently losing overrides or presenting a
+snapshot as a stream. PM's own `vibes pm logs <id> --follow` continues to follow.
+Without PM, generated commands print their documented unavailable messages
+and return. This convergence is incomplete pending the owner extensions.
 
-## Known issues
+Generate an executable static loader with `vibes runtime codegen [destination]`.
+The default is `dist/runtime-loader.generated.ts`; relative paths use the
+workspace root, then the runtime's declared cwd. The CLI resolves the
+host-composed `workspace/static-loader` generator through the runtime and writes
+through the runtime filesystem.
 
-- The **dev binary currently crashes during runtime bootstrap** with a descriptor collision (`Global ID collision for 'ai/context.ui:chat-messages.form'`). Tracked under the FIRST-LAUNCH P0 cleanup — see [docs/dx/FIRST-LAUNCH-2026-05.md](../../docs/dx/FIRST-LAUNCH-2026-05.md). Until that lands, `vibes --help` will not print help.
-- The package re-exports a wide subdirectory tree via wildcard `exports`; prefer the documented top-level entry points (`.`, `./plugin`, `./config`) when consuming from another package.
+Hosts supply optional generation input and the required canonical owner result
+schema through `cli/runtime-codegen-input`, using the context descriptor exported
+from `@vibesdotdev/cli/commands/runtime/codegen`. Workspace hosts provide
+`StaticLoaderResultSchema` from `@vibesdotdev/workspace/static-loader`. Direct
+`generate` calls can supply `input` explicitly; they still require the host
+context's result schema. Compose importable plugins for unfiltered generation, or
+declare kinds, descriptors and constrained lazy loaders to use `--scope` and
+`--hardware`. Missing declarations refuse explicitly; runtime closures are never
+serialized. The complete owner result is validated before writing. CLI uses its source
+for the generated file and omits it from the returned value; remaining owner
+fields stay flat beside destination, filters, counts and structured diagnostics. Invalid
+results refuse `INTERNAL / runtime-codegen-result-invalid`; a missing schema
+refuses `UNAVAILABLE / runtime-codegen-result-schema-unavailable`. The `options` and `generate` APIs remain available. Command composition is descriptor-driven through `./codegen/declarations` and `./codegen/command`, registered by `CLISurface`.
+See [runtime codegen](./SPEC.md#runtime-codegen).
 
-## Authoritative spec
+## License
 
-For ownership boundaries, runtime contract, and non-goals, see [SPEC.md](./SPEC.md).
+MIT

package/dist/boot/action-lifetime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Action lifetime: own the lifetime of a long-running CLI action.
+ *
+ * Signal and transport callbacks request shutdown; the action itself awaits
+ * wait(). CLISurface therefore closes invocation observers only after cleanup
+ * has genuinely completed, with no hard process exit racing a live action.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { CLIActionLifetime } from '@vibesdotdev/cli-contracts/context';
+/**
+ * Own the lifetime of a long-running CLI action (see the module note): the
+ * handed runtime's host signals are selected before the action starts, so
+ * an absent capability refuses before any cleanup or subscription exists.
+ */
+export declare function createCLIActionLifetime(runtime: RuntimeRef, cleanup: (reason: string) => void | Promise<void>): Promise<CLIActionLifetime>;
+//# sourceMappingURL=action-lifetime.d.ts.map

package/dist/boot/action-lifetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-lifetime.d.ts","sourceRoot":"","sources":["../../src/boot/action-lifetime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAwB5E;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/C,OAAO,CAAC,iBAAiB,CAAC,CA2C5B"}

package/dist/boot/action-lifetime.js

@@ -0,0 +1,80 @@
+/**
+ * Action lifetime: own the lifetime of a long-running CLI action.
+ *
+ * Signal and transport callbacks request shutdown; the action itself awaits
+ * wait(). CLISurface therefore closes invocation observers only after cleanup
+ * has genuinely completed, with no hard process exit racing a live action.
+ */
+import { getRuntimeHostSignals } from '@vibesdotdev/kernel';
+/** Run one owned step; its failure is returned as a value, exactly as thrown. */
+function carry(step) {
+    try {
+        step();
+        return null;
+    }
+    catch (thrown) {
+        return { thrown };
+    }
+}
+/** One failure stays itself; several travel together in their order. */
+function joined(failures, message) {
+    if (failures.length === 0)
+        return null;
+    if (failures.length === 1)
+        return failures[0];
+    return { thrown: new AggregateError(failures.map((failure) => failure.thrown), message) };
+}
+/**
+ * Own the lifetime of a long-running CLI action (see the module note): the
+ * handed runtime's host signals are selected before the action starts, so
+ * an absent capability refuses before any cleanup or subscription exists.
+ */
+export async function createCLIActionLifetime(runtime, cleanup) {
+    const signals = await getRuntimeHostSignals(runtime);
+    let requested = false;
+    const { promise: done, resolve: resolveDone, reject: rejectDone } = Promise.withResolvers();
+    // Observe a fired request at once; wait() retains the exact cleanup failure.
+    const outcome = done.then(() => null, (thrown) => ({ thrown }));
+    const subscriptions = new Map();
+    const request = (reason) => {
+        if (!requested) {
+            requested = true;
+            Promise.resolve().then(() => cleanup(reason)).then(resolveDone, rejectDone);
+        }
+        return done;
+    };
+    // Every owned subscription is detached; each failure is kept in order.
+    const detachAll = () => {
+        const owned = [...subscriptions.values()];
+        subscriptions.clear();
+        return joined(owned.map(carry).filter((failure) => failure !== null), 'CLI signal subscriptions failed to detach.');
+    };
+    return {
+        request,
+        bindProcessSignals() {
+            const bound = carry(() => {
+                for (const signal of ['SIGINT', 'SIGTERM']) {
+                    if (!subscriptions.has(signal))
+                        subscriptions.set(signal, signals.subscribe(signal, () => { void request(signal); }));
+                }
+            });
+            if (bound === null)
+                return;
+            const rollback = detachAll();
+            if (rollback !== null)
+                throw new AggregateError([bound.thrown, rollback.thrown], 'CLI signal binding and rollback failed.');
+            throw bound.thrown;
+        },
+        async wait() {
+            const failure = await outcome;
+            const detached = detachAll();
+            if (failure !== null && detached !== null) {
+                throw new AggregateError([failure.thrown, detached.thrown], 'CLI cleanup and signal detachment failed.');
+            }
+            const only = failure ?? detached;
+            if (only !== null)
+                throw only.thrown;
+        }
+    };
+}
+//# sourceMappingURL=action-lifetime.js.map

package/dist/boot/action-lifetime.js.map

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

package/dist/boot/bootstrap.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 { type BuildSurface, type RuntimePlugin, type RuntimePurpose } from "@vibesdotdev/kernel";
+import { Command } from "commander";
+import type { CLIServeEffect } from "../schemas/types.ts";
+import type { VibesCliAppOptions, VibesCliApp, CliHostScopeInput, CliHostWorkspace, CliHostQualifiers, HmrInvocationKind, DeclaredHotReload, CliHostFacts } from "../schemas/bootstrap.ts";
+export type { CliPluginLoader, CliPluginSelection, CliEnvironmentFactory, VibesCliAppOptions, VibesCliApp, CliServeDeclaration, CliHostScopeInput, CliHostWorkspace, CliHostQualifiers, CliHostConfig, CliExecutionComposition, HmrInvocationKind, DeclaredHotReload, CliHostFacts, } from "../schemas/bootstrap.ts";
+/**
+ * The hidden global flag a canonical help lookup child carries, so it never
+ * delegates again. It travels in argv, never the environment.
+ */
+export declare const CANONICAL_COMMAND_HELP_LOOKUP_FLAG = "--canonical-help-lookup";
+/** Shared declarations for the actual command tree and pre-activation routing. */
+export declare function registerGlobalOptions(program: Command, options?: Omit<VibesCliAppOptions, 'hostOutput' | 'argv'>): Command;
+/**
+ * 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 declare function readToolsRunPurposeFromArgv(argv: readonly string[]): RuntimePurpose | undefined;
+/**
+ * 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 declare function isFiniteInvocation(argv: readonly string[]): boolean;
+/** Whether this invocation is a canonical help lookup child ({@link CANONICAL_COMMAND_HELP_LOOKUP_FLAG}). */
+export declare function isCanonicalHelpLookup(argv: readonly string[]): boolean;
+/** Where the consumer CLI runs; also the venue a host-credentials manifest is judged against. */
+export declare const CLI_HOSTING: Readonly<{
+    readonly mode: "local";
+    readonly owner: "consumer";
+    readonly venue: "user-device";
+}>;
+/** Where a serve host runs: the same machine, serving other processes over IPC (rc01 §2.4; N1). */
+export declare const SERVE_HOSTING: Readonly<{
+    readonly mode: "local";
+    readonly owner: "consumer";
+    readonly venue: "ipc-worker";
+}>;
+export declare function declareCliHostScope(input: CliHostScopeInput): {
+    readonly surface: "cli" | "worker" | "mcp";
+    readonly hardware: "consumer" | "cloud";
+    readonly purpose: "agent" | "worker" | "mcp" | "direct" | "projection";
+    readonly lifecycle: "finite" | "persistent";
+    readonly hosting: Readonly<{
+        readonly mode: "local";
+        readonly owner: "consumer";
+        readonly venue: "user-device";
+    }> | Readonly<{
+        readonly mode: "local";
+        readonly owner: "consumer";
+        readonly venue: "ipc-worker";
+    }>;
+    readonly capabilities: {
+        requestPrincipals: boolean;
+        sharedHost: boolean;
+        hostCredentials?: undefined;
+        interactiveSession?: undefined;
+    } | {
+        hostCredentials: boolean;
+        requestPrincipals?: undefined;
+        sharedHost?: undefined;
+        interactiveSession?: undefined;
+    } | {
+        interactiveSession: boolean;
+        requestPrincipals?: undefined;
+        sharedHost?: undefined;
+        hostCredentials?: undefined;
+    };
+    readonly workspace: CliHostWorkspace;
+    readonly qualifiers: CliHostQualifiers;
+};
+export declare function isCanonicalCliHostPlugin(plugin: RuntimePlugin): boolean;
+export declare function createCliHostPlugin(buildSurface: BuildSurface): RuntimePlugin;
+/** The original executable floor, retained as data for an opt-in execution owner. */
+export declare 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 declare function createVibesCliApp(options: VibesCliAppOptions): Promise<VibesCliApp>;
+/**
+ * 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 declare function classifyHmrInvocation(serve: CLIServeEffect | undefined): HmrInvocationKind;
+/**
+ * The one stderr line `--hmr` owes this invocation, or null when the selected
+ * command arms hot reload and will report for itself.
+ */
+export declare function describeHmrInvocation(serve: CLIServeEffect | undefined, commandPath: readonly string[]): string | null;
+/**
+ * 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 declare function readHmrFromArgv(argv: ReadonlyArray<string>): "1" | "0" | 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 declare const HMR_ARGV_SPELLINGS: readonly ["--hmr", "--no-hmr"];
+/**
+ * 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 declare function registerHmrOptions(program: Command): Command;
+/** The channel key `--hmr` / `--no-hmr` publish to this host's readers and its children. */
+export declare const HMR_CHANNEL_KEY = "VIBES_HMR";
+/** Declare hot reload from the canonical channel captured by this host. */
+export declare function declaredHotReload(captured: Readonly<Record<string, string | undefined>>): DeclaredHotReload;
+/**
+ * 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 declare function readProfileFromArgv(argv: ReadonlyArray<string>): string | undefined;
+export declare function declareCliHost(host: VibesCliAppOptions["host"], facts: CliHostFacts): NonNullable<VibesCliAppOptions["host"]>;
+/**
+ * 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 declare function readWorkspaceRootFromArgv(argv: ReadonlyArray<string>): string | undefined;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/boot/bootstrap.d.ts.map

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