@vibesdotdev/runtime-surface-cli 0.0.1

package/dist/cli-bootstrap.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CLI Bootstrap
+ *
+ * Composition function for initializing the Vibes CLI application.
+ * Handles runtime initialization, plugin loading, and CLISurface setup.
+ *
+ * Usage:
+ * ```typescript
+ * import { createVibesCliApp } from '@vibesdotdev/runtime-surface-cli';
+ *
+ * const app = await createVibesCliApp();
+ * await app.cli.run(process.argv);
+ * ```
+ */
+import { VibesRuntime } from "@vibesdotdev/runtime";
+import type { RuntimeLoader, RuntimePlugin } from "@vibesdotdev/runtime";
+import { Command } from "commander";
+import { CLISurface } from "@vibesdotdev/cli/surface";
+/**
+ * Plugin loader: a function returning either a `RuntimePlugin` directly or a
+ * module whose `default` export is one. Used by both `defaultPlugins` (the
+ * binary's statically-imported set) and `config.plugins` (project overrides).
+ */
+export type CliPluginLoader = () => Promise<RuntimePlugin | {
+    default: RuntimePlugin;
+}>;
+export interface VibesCliAppOptions {
+    /** Runtime loader (default: dynamic-import `@vibesdotdev/runtime-bun`) */
+    loader?: RuntimeLoader;
+    /** Verbose logging (default: false) */
+    verbose?: boolean;
+    /** Output format (default: 'table') */
+    format?: "json" | "yaml" | "table" | "markdown";
+    /** Config file path (default: vibes.config.ts in cwd) */
+    configPath?: string;
+    /** Plugin specifiers to load by import string (project overrides) */
+    plugins?: string[];
+    /**
+     * Statically-imported plugin set the binary ships with. Used when the
+     * project's config does not declare `plugins`. Required for `bun build
+     * --compile` since plugin selection must be statically analyzable.
+     */
+    defaultPlugins?: ReadonlyArray<CliPluginLoader>;
+    /** Include descriptors marked `internal: true` (default: false) */
+    includeInternal?: boolean;
+    /**
+     * Treat orphan group/command refs as errors. Default: false (warn-only).
+     * Project-level configs can produce partial plugin sets, so orphans are a
+     * routine outcome — strict mode is reserved for CI / descriptor audits.
+     * Overridable via env var `VIBES_CLI_STRICT=1`.
+     */
+    strict?: boolean;
+}
+export interface VibesCliApp {
+    runtime: VibesRuntime;
+    program: Command;
+    cli: CLISurface;
+}
+/**
+ * Create and initialize the Vibes CLI application.
+ *
+ * @param options - CLI app options
+ * @returns Initialized CLI app with runtime, program, and surface
+ */
+export declare function createVibesCliApp(options?: VibesCliAppOptions): Promise<VibesCliApp>;
+//# sourceMappingURL=cli-bootstrap.d.ts.map

package/dist/cli-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-bootstrap.d.ts","sourceRoot":"","sources":["../src/cli-bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAkC,MAAM,sBAAsB,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,UAAU,EAA0B,MAAM,0BAA0B,CAAC;AAgB9E;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CACzC,aAAa,GAAG;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,CAC3C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAChD,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAChD,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,UAAU,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA2HtB"}

package/dist/cli-bootstrap.js

@@ -0,0 +1,268 @@
+/**
+ * CLI Bootstrap
+ *
+ * Composition function for initializing the Vibes CLI application.
+ * Handles runtime initialization, plugin loading, and CLISurface setup.
+ *
+ * Usage:
+ * ```typescript
+ * import { createVibesCliApp } from '@vibesdotdev/runtime-surface-cli';
+ *
+ * const app = await createVibesCliApp();
+ * await app.cli.run(process.argv);
+ * ```
+ */
+import { VibesRuntime, getVibesRuntime, getRuntimeEnv } from "@vibesdotdev/runtime";
+import { markVibesRuntimeBootstrapped } from "@vibesdotdev/runtime/bootstrap";
+import { Command } from "commander";
+import path from "node:path";
+import { CLISurface } from "@vibesdotdev/cli/surface";
+import { registerBunEnvironment } from "@vibesdotdev/runtime-environment-bun";
+import { VIBES_VERSION } from "@vibesdotdev/cli/version";
+const BAKED_WORKSPACE_CONFIG_JSON = typeof __VIBES_BAKED_CONFIG__ !== "undefined" ? __VIBES_BAKED_CONFIG__ : "{}";
+/**
+ * Create and initialize the Vibes CLI application.
+ *
+ * @param options - CLI app options
+ * @returns Initialized CLI app with runtime, program, and surface
+ */
+export async function createVibesCliApp(options = {}) {
+    // Honor `--profile <name>` / `--profile=<name>` before any runtime/config
+    // setup that resolves storage paths from VIBES_PROFILE. Commander parses the
+    // global flag later, but by then `loadConfig`/`registerCorePlugins` have
+    // already chosen profile-scoped paths off the default profile.
+    applyProfileFromArgv(process.argv);
+    const loaderModule = await import("@vibesdotdev/runtime-bun");
+    const loader = options.loader ?? loaderModule.createBunLoader();
+    const runtime = getVibesRuntime();
+    runtime.setScope({ surface: "cli", hardware: "consumer", purpose: "direct", qualifiers: { environmentTier: "local" } });
+    registerBunEnvironment(runtime, {});
+    runtime.setLoader(loader);
+    const config = await loadConfig(options.configPath, loader);
+    const effectiveConfig = resolveEffectiveConfig(config, loader, options.verbose);
+    if (options.verbose) {
+        loader.log("info", `Config loaded: ${Object.keys(config).join(", ") || "(empty)"}`);
+        loader.log("info", `Config.plugins: ${config.plugins ? "array" : "undefined"}`);
+    }
+    await registerCorePlugins(runtime);
+    // Surface `config.config.plugins.<name>` from vibes.config.ts as
+    // `plugins.<name>` contexts so umbrella plugins (plugins-infra,
+    // plugins-comms, ...) read the project's intent instead of falling
+    // back to hardware-based defaults. Without this the CLI inherits the
+    // "consumer" defaults even when the user explicitly toggled subsystems
+    // on (e.g. `infra.cloudflare: true`).
+    registerAppConfigContexts(runtime, effectiveConfig);
+    // Plugin set: project config wins when present, otherwise the binary's
+    // statically-imported defaults. Skip defaults when config provides an
+    // explicit (even empty) array so projects can opt out of the full set.
+    const configPlugins = Array.isArray(config.plugins) ? config.plugins : null;
+    const pluginLoaders = configPlugins ?? options.defaultPlugins ?? [];
+    for (const loaderFn of pluginLoaders) {
+        try {
+            const pluginModule = await loaderFn();
+            const pluginObj = pluginModule.default ??
+                pluginModule;
+            await runtime.registerPlugin(pluginObj);
+            if (options.verbose) {
+                loader.log("info", `Loaded plugin: ${pluginObj.id}`);
+            }
+        }
+        catch (error) {
+            // Plugin-load failures are routinely informational (optional / missing
+            // peer plugins). They should only surface in default mode if the user
+            // opts in via -v. Always route to stderr (loader.log uses console.warn).
+            if (options.verbose) {
+                loader.log("warn", `Failed to load plugin`, { error: String(error) });
+            }
+        }
+    }
+    if (options.plugins) {
+        for (const specifier of options.plugins) {
+            try {
+                const plugin = await loader.importModule(specifier);
+                const pluginObj = plugin.default ??
+                    plugin;
+                await runtime.registerPlugin(pluginObj);
+                if (options.verbose) {
+                    loader.log("info", `Loaded plugin: ${specifier}`);
+                }
+            }
+            catch (error) {
+                if (options.verbose) {
+                    loader.log("warn", `Failed to load plugin ${specifier}`, {
+                        error: String(error),
+                    });
+                }
+            }
+        }
+    }
+    const program = new Command()
+        .name("vibes")
+        .description("Vibes Developer CLI")
+        .version(VIBES_VERSION)
+        .exitOverride()
+        .option("-v, --verbose", "Enable verbose logging")
+        .option("--format <format>", "Output format (json|yaml|table|markdown)", options.format ?? "table")
+        .option("--profile <name>", "Active vibes profile (overrides $VIBES_PROFILE for this invocation)");
+    const strict = options.strict ?? getRuntimeEnv('VIBES_CLI_STRICT') === "1";
+    const surfaceOptions = {
+        verbose: options.verbose ?? false,
+        format: options.format ?? "table",
+        includeInternal: options.includeInternal ?? false,
+        enablePatterns: true,
+        strictCommandGroups: strict,
+        strictGroupParents: strict,
+    };
+    // Activate plugins so onActivate hooks fire — they register the deferred
+    // `runtime/client` loaders (e.g. cloudflare-workers-deploy) that command
+    // impls resolve via `getVibesClient()`. Without this, `vibes infra deploy run`
+    // can't reach the CF Workers API client.
+    await runtime.activatePlugins();
+    markVibesRuntimeBootstrapped();
+    const cli = new CLISurface(runtime, program, surfaceOptions);
+    return { runtime, program, cli };
+}
+async function loadConfig(configPath, loader) {
+    if (configPath) {
+        try {
+            const mod = await loader.importModule(configPath);
+            const config = mod.default ??
+                mod;
+            return config;
+        }
+        catch (error) {
+            loader.log("warn", `Failed to load config from ${configPath}`, {
+                error: String(error),
+            });
+        }
+    }
+    const cwd = loader.getCwd();
+    const defaultPaths = [
+        getRuntimeEnv('VIBES_CONFIG_PATH'),
+        path.resolve(cwd, "vibes.config.ts"),
+        path.resolve(cwd, "vibes.config.js"),
+        path.resolve(cwd, "vibes.config.json"),
+    ].filter((p) => p !== undefined);
+    for (const candidate of defaultPaths) {
+        try {
+            const mod = await loader.importModule(candidate);
+            const config = mod.default ??
+                mod;
+            return config;
+        }
+        catch (error) {
+            loader.log("debug", `Config not found at ${candidate}`, {
+                error: String(error),
+            });
+        }
+    }
+    loader.log("debug", "No vibes.config.ts found, using defaultPlugins");
+    return {};
+}
+/**
+ * Pick the config object to use for plugin-umbrella context registration.
+ *
+ * Order of precedence:
+ *   1. External `vibes.config.ts` that successfully imported with a non-empty
+ *      `config` field — full user intent, treat as authoritative.
+ *   2. The build-time baked workspace config (compiled binaries only).
+ *      Used when the standalone executable can't resolve workspace specifiers
+ *      from `vibes.config.ts` at runtime, so external load returns `(empty)`.
+ *   3. Empty — fall through to hardware-tier defaults inside umbrella plugins.
+ *
+ * We deliberately do NOT merge external and baked: if the user shipped a
+ * config, their intent is total.
+ */
+function resolveEffectiveConfig(external, loader, verbose) {
+    const externalHasConfig = external.config !== undefined && external.config !== null;
+    if (externalHasConfig)
+        return external;
+    if (BAKED_WORKSPACE_CONFIG_JSON && BAKED_WORKSPACE_CONFIG_JSON !== "{}") {
+        try {
+            const baked = JSON.parse(BAKED_WORKSPACE_CONFIG_JSON);
+            if (verbose) {
+                loader.log("info", `Using baked workspace config (${Object.keys(baked).join(", ") || "(empty)"})`);
+            }
+            return { ...external, config: baked };
+        }
+        catch (error) {
+            loader.log("warn", `Failed to parse __VIBES_BAKED_CONFIG__; falling back to external/empty`, { error: String(error) });
+        }
+    }
+    return external;
+}
+/**
+ * Mirror of `registerAppConfigContexts` from `@vibesdotdev/runtime/bootstrap/app`.
+ * Inlined to avoid a circular dependency through `bootstrap/index` (which
+ * would re-register core plugins).
+ *
+ * Walks `config.config.plugins` and registers each subtree as a
+ * `plugins.<name>` context. Umbrella plugins read these contexts to
+ * decide which sub-plugins to load.
+ */
+function registerAppConfigContexts(runtime, config) {
+    const top = config.config;
+    const pluginConfig = top?.plugins;
+    if (!pluginConfig || typeof pluginConfig !== "object")
+        return;
+    if (!runtime.hasKind("context"))
+        return;
+    for (const [name, value] of Object.entries(pluginConfig)) {
+        if (value === undefined)
+            continue;
+        const id = `plugins.${name}`;
+        runtime.registerDescriptor("context", {
+            kind: "context",
+            id,
+            name: `Plugin config: ${name}`,
+            description: `Runtime app configuration for the ${name} plugin umbrella.`,
+        });
+        runtime.registerLoader("context", id, async () => ({
+            impl: {
+                provide: () => value,
+            },
+        }));
+    }
+}
+async function registerCorePlugins(runtime) {
+    // Only the true zero-dependency foundation + surface-specific CLI plugin.
+    // All other core plugins (logging, hooks, runtime-client, config, system,
+    // tools, workers, storage, filesystem, paths, workspace, resolver, runtime/docs)
+    // are owned by @vibesdotdev/plugins-core which depends on 'context'.
+    const contextPlugin = (await import("@vibesdotdev/runtime/context/context.plugin")).default;
+    await runtime.registerPlugin(contextPlugin);
+    const cliPlugin = (await import("@vibesdotdev/cli/cli.plugin")).default;
+    await runtime.registerPlugin(cliPlugin);
+}
+/**
+ * Pre-parse `--profile <name>` / `--profile=<name>` and surface it through
+ * the `VIBES_PROFILE` env var so downstream profile-aware code (path
+ * resolution, config discovery) sees the active profile on this invocation.
+ *
+ * Commander parses the same flag later when `program.parseAsync` runs, but
+ * by then `loadConfig` and `registerCorePlugins` have already chosen
+ * profile-scoped paths off whatever was set in the environment.
+ *
+ * Strict: ignores anything that looks like another flag (`--profile --foo`).
+ */
+function applyProfileFromArgv(argv) {
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--")
+            break;
+        if (token === "--profile") {
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                process.env.VIBES_PROFILE = next;
+            }
+            return;
+        }
+        if (token.startsWith("--profile=")) {
+            const value = token.slice("--profile=".length);
+            if (value)
+                process.env.VIBES_PROFILE = value;
+            return;
+        }
+    }
+}
+//# sourceMappingURL=cli-bootstrap.js.map

package/dist/cli-bootstrap.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime Surface: CLI
+ *
+ * Official blessed entrypoint for bootstrapping a Vibes CLI runtime.
+ * Re-exports the CLI application factory (createVibesCliApp) and related
+ * types after the surface layer is fully implemented.
+ *
+ * Consumers (cli-bin, shield-cli, internal CLI commands) should import from here
+ * rather than directly from @vibesdotdev/cli/bootstrap or raw runtime bootstrap symbols.
+ */
+/**
+ * Runtime Surface — CLI
+ *
+ * The blessed way to bootstrap a full Vibes CLI application.
+ * Re-exports createVibesCliApp and related types from the implementation
+ * that now lives in this surface package.
+ *
+ * All production CLI entrypoints (cli-bin, shield-cli, internal tools)
+ * should import from here.
+ */
+export { createVibesCliApp, type VibesCliAppOptions, type VibesCliApp, type CliPluginLoader } from './cli-bootstrap.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Runtime Surface: CLI
+ *
+ * Official blessed entrypoint for bootstrapping a Vibes CLI runtime.
+ * Re-exports the CLI application factory (createVibesCliApp) and related
+ * types after the surface layer is fully implemented.
+ *
+ * Consumers (cli-bin, shield-cli, internal CLI commands) should import from here
+ * rather than directly from @vibesdotdev/cli/bootstrap or raw runtime bootstrap symbols.
+ */
+/**
+ * Runtime Surface — CLI
+ *
+ * The blessed way to bootstrap a full Vibes CLI application.
+ * Re-exports createVibesCliApp and related types from the implementation
+ * that now lives in this surface package.
+ *
+ * All production CLI entrypoints (cli-bin, shield-cli, internal tools)
+ * should import from here.
+ */
+export { createVibesCliApp } from "./cli-bootstrap.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,OAAO,EAAE,iBAAiB,EAAmE,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@vibesdotdev/runtime-surface-cli",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "bun --bun tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@vibesdotdev/runtime": "0.0.1",
+    "@vibesdotdev/runtime-environment-bun": "0.0.0",
+    "@vibesdotdev/cli": "0.0.1"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "README.md",
+    "SPEC.md",
+    "LICENSE",
+    "!src/**/__tests__/**",
+    "!src/**/__stubs__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!dist/**/__tests__/**",
+    "!dist/**/__stubs__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.js.map",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.d.ts.map"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "vibes": {
+    "visibility": "public-framework"
+  }
+}

package/src/cli-bootstrap.ts

@@ -0,0 +1,380 @@
+/**
+ * CLI Bootstrap
+ *
+ * Composition function for initializing the Vibes CLI application.
+ * Handles runtime initialization, plugin loading, and CLISurface setup.
+ *
+ * Usage:
+ * ```typescript
+ * import { createVibesCliApp } from '@vibesdotdev/runtime-surface-cli';
+ *
+ * const app = await createVibesCliApp();
+ * await app.cli.run(process.argv);
+ * ```
+ */
+
+import { VibesRuntime, getVibesRuntime, getRuntimeEnv } from "@vibesdotdev/runtime";
+import type { RuntimeLoader, RuntimePlugin } from "@vibesdotdev/runtime";
+import { markVibesRuntimeBootstrapped } from "@vibesdotdev/runtime/bootstrap";
+import { Command } from "commander";
+import path from "node:path";
+import { CLISurface, type CLISurfaceOptions } from "@vibesdotdev/cli/surface";
+import { registerBunEnvironment } from "@vibesdotdev/runtime-environment-bun";
+import { VIBES_VERSION } from "@vibesdotdev/cli/version";
+
+/**
+ * Workspace `config.config` subtree captured at build time.
+ *
+ * Replaced literally by Bun's `--define` flag during `apps/cli-bin/scripts/build.ts`.
+ * Outside the compiled binary (dev mode, tests) the symbol is undefined and we
+ * fall through to the empty default. Stored as a JSON string so the substitution
+ * stays a simple literal even though the data is structured.
+ */
+declare const __VIBES_BAKED_CONFIG__: string;
+const BAKED_WORKSPACE_CONFIG_JSON: string =
+	typeof __VIBES_BAKED_CONFIG__ !== "undefined" ? __VIBES_BAKED_CONFIG__ : "{}";
+
+/**
+ * Plugin loader: a function returning either a `RuntimePlugin` directly or a
+ * module whose `default` export is one. Used by both `defaultPlugins` (the
+ * binary's statically-imported set) and `config.plugins` (project overrides).
+ */
+export type CliPluginLoader = () => Promise<
+  RuntimePlugin | { default: RuntimePlugin }
+>;
+
+export interface VibesCliAppOptions {
+  /** Runtime loader (default: dynamic-import `@vibesdotdev/runtime-bun`) */
+  loader?: RuntimeLoader;
+  /** Verbose logging (default: false) */
+  verbose?: boolean;
+  /** Output format (default: 'table') */
+  format?: "json" | "yaml" | "table" | "markdown";
+  /** Config file path (default: vibes.config.ts in cwd) */
+  configPath?: string;
+  /** Plugin specifiers to load by import string (project overrides) */
+  plugins?: string[];
+  /**
+   * Statically-imported plugin set the binary ships with. Used when the
+   * project's config does not declare `plugins`. Required for `bun build
+   * --compile` since plugin selection must be statically analyzable.
+   */
+  defaultPlugins?: ReadonlyArray<CliPluginLoader>;
+  /** Include descriptors marked `internal: true` (default: false) */
+  includeInternal?: boolean;
+  /**
+   * Treat orphan group/command refs as errors. Default: false (warn-only).
+   * Project-level configs can produce partial plugin sets, so orphans are a
+   * routine outcome — strict mode is reserved for CI / descriptor audits.
+   * Overridable via env var `VIBES_CLI_STRICT=1`.
+   */
+  strict?: boolean;
+}
+
+export interface VibesCliApp {
+  runtime: VibesRuntime;
+  program: Command;
+  cli: CLISurface;
+}
+
+/**
+ * Create and initialize the Vibes CLI application.
+ *
+ * @param options - CLI app options
+ * @returns Initialized CLI app with runtime, program, and surface
+ */
+export async function createVibesCliApp(
+  options: VibesCliAppOptions = {},
+): Promise<VibesCliApp> {
+  // Honor `--profile <name>` / `--profile=<name>` before any runtime/config
+  // setup that resolves storage paths from VIBES_PROFILE. Commander parses the
+  // global flag later, but by then `loadConfig`/`registerCorePlugins` have
+  // already chosen profile-scoped paths off the default profile.
+  applyProfileFromArgv(process.argv);
+
+  const loaderModule = await import("@vibesdotdev/runtime-bun");
+  const loader = options.loader ?? loaderModule.createBunLoader();
+
+  const runtime = getVibesRuntime();
+  runtime.setScope({ surface: "cli", hardware: "consumer", purpose: "direct", qualifiers: { environmentTier: "local" } });
+  registerBunEnvironment(runtime, {});
+  runtime.setLoader(loader);
+
+  const config = await loadConfig(options.configPath, loader);
+  const effectiveConfig = resolveEffectiveConfig(config, loader, options.verbose);
+  if (options.verbose) {
+    loader.log(
+      "info",
+      `Config loaded: ${Object.keys(config).join(", ") || "(empty)"}`,
+    );
+    loader.log(
+      "info",
+      `Config.plugins: ${config.plugins ? "array" : "undefined"}`,
+    );
+  }
+
+  await registerCorePlugins(runtime);
+
+  // Surface `config.config.plugins.<name>` from vibes.config.ts as
+  // `plugins.<name>` contexts so umbrella plugins (plugins-infra,
+  // plugins-comms, ...) read the project's intent instead of falling
+  // back to hardware-based defaults. Without this the CLI inherits the
+  // "consumer" defaults even when the user explicitly toggled subsystems
+  // on (e.g. `infra.cloudflare: true`).
+  registerAppConfigContexts(runtime, effectiveConfig);
+
+  // Plugin set: project config wins when present, otherwise the binary's
+  // statically-imported defaults. Skip defaults when config provides an
+  // explicit (even empty) array so projects can opt out of the full set.
+  const configPlugins = Array.isArray(config.plugins) ? config.plugins : null;
+  const pluginLoaders: ReadonlyArray<CliPluginLoader> =
+    configPlugins ?? options.defaultPlugins ?? [];
+
+  for (const loaderFn of pluginLoaders) {
+    try {
+      const pluginModule = await loaderFn();
+      const pluginObj =
+        (pluginModule as { default?: RuntimePlugin }).default ??
+        (pluginModule as RuntimePlugin);
+      await runtime.registerPlugin(pluginObj);
+      if (options.verbose) {
+        loader.log("info", `Loaded plugin: ${pluginObj.id}`);
+      }
+    } catch (error) {
+      // Plugin-load failures are routinely informational (optional / missing
+      // peer plugins). They should only surface in default mode if the user
+      // opts in via -v. Always route to stderr (loader.log uses console.warn).
+      if (options.verbose) {
+        loader.log("warn", `Failed to load plugin`, { error: String(error) });
+      }
+    }
+  }
+
+  if (options.plugins) {
+    for (const specifier of options.plugins) {
+      try {
+        const plugin = await loader.importModule(specifier);
+        const pluginObj =
+          (plugin as { default?: RuntimePlugin }).default ??
+          (plugin as RuntimePlugin);
+        await runtime.registerPlugin(pluginObj);
+        if (options.verbose) {
+          loader.log("info", `Loaded plugin: ${specifier}`);
+        }
+      } catch (error) {
+        if (options.verbose) {
+          loader.log("warn", `Failed to load plugin ${specifier}`, {
+            error: String(error),
+          });
+        }
+      }
+    }
+  }
+
+  const program = new Command()
+    .name("vibes")
+    .description("Vibes Developer CLI")
+    .version(VIBES_VERSION)
+    .exitOverride()
+    .option("-v, --verbose", "Enable verbose logging")
+    .option(
+      "--format <format>",
+      "Output format (json|yaml|table|markdown)",
+      options.format ?? "table",
+    )
+    .option(
+      "--profile <name>",
+      "Active vibes profile (overrides $VIBES_PROFILE for this invocation)",
+    );
+
+  const strict = options.strict ?? getRuntimeEnv('VIBES_CLI_STRICT') === "1";
+  const surfaceOptions: CLISurfaceOptions = {
+    verbose: options.verbose ?? false,
+    format: options.format ?? "table",
+    includeInternal: options.includeInternal ?? false,
+    enablePatterns: true,
+    strictCommandGroups: strict,
+    strictGroupParents: strict,
+  };
+
+  // Activate plugins so onActivate hooks fire — they register the deferred
+  // `runtime/client` loaders (e.g. cloudflare-workers-deploy) that command
+  // impls resolve via `getVibesClient()`. Without this, `vibes infra deploy run`
+  // can't reach the CF Workers API client.
+  await runtime.activatePlugins();
+
+  markVibesRuntimeBootstrapped();
+
+  const cli = new CLISurface(runtime, program, surfaceOptions);
+
+  return { runtime, program, cli };
+}
+
+async function loadConfig(
+  configPath: string | undefined,
+  loader: RuntimeLoader,
+): Promise<Record<string, unknown>> {
+  if (configPath) {
+    try {
+      const mod = await loader.importModule(configPath);
+      const config =
+        (mod as { default?: Record<string, unknown> }).default ??
+        (mod as Record<string, unknown>);
+      return config;
+    } catch (error) {
+      loader.log("warn", `Failed to load config from ${configPath}`, {
+        error: String(error),
+      });
+    }
+  }
+
+  const cwd = loader.getCwd();
+  const defaultPaths = [
+    getRuntimeEnv('VIBES_CONFIG_PATH'),
+    path.resolve(cwd, "vibes.config.ts"),
+    path.resolve(cwd, "vibes.config.js"),
+    path.resolve(cwd, "vibes.config.json"),
+  ].filter((p): p is string => p !== undefined);
+
+  for (const candidate of defaultPaths) {
+    try {
+      const mod = await loader.importModule(candidate);
+      const config =
+        (mod as { default?: Record<string, unknown> }).default ??
+        (mod as Record<string, unknown>);
+      return config;
+    } catch (error) {
+      loader.log("debug", `Config not found at ${candidate}`, {
+        error: String(error),
+      });
+    }
+  }
+
+  loader.log("debug", "No vibes.config.ts found, using defaultPlugins");
+  return {};
+}
+
+/**
+ * Pick the config object to use for plugin-umbrella context registration.
+ *
+ * Order of precedence:
+ *   1. External `vibes.config.ts` that successfully imported with a non-empty
+ *      `config` field — full user intent, treat as authoritative.
+ *   2. The build-time baked workspace config (compiled binaries only).
+ *      Used when the standalone executable can't resolve workspace specifiers
+ *      from `vibes.config.ts` at runtime, so external load returns `(empty)`.
+ *   3. Empty — fall through to hardware-tier defaults inside umbrella plugins.
+ *
+ * We deliberately do NOT merge external and baked: if the user shipped a
+ * config, their intent is total.
+ */
+function resolveEffectiveConfig(
+  external: Record<string, unknown>,
+  loader: RuntimeLoader,
+  verbose: boolean | undefined,
+): Record<string, unknown> {
+  const externalHasConfig =
+    external.config !== undefined && external.config !== null;
+  if (externalHasConfig) return external;
+
+  if (BAKED_WORKSPACE_CONFIG_JSON && BAKED_WORKSPACE_CONFIG_JSON !== "{}") {
+    try {
+      const baked = JSON.parse(BAKED_WORKSPACE_CONFIG_JSON);
+      if (verbose) {
+        loader.log(
+          "info",
+          `Using baked workspace config (${Object.keys(baked).join(", ") || "(empty)"})`,
+        );
+      }
+      return { ...external, config: baked };
+    } catch (error) {
+      loader.log(
+        "warn",
+        `Failed to parse __VIBES_BAKED_CONFIG__; falling back to external/empty`,
+        { error: String(error) },
+      );
+    }
+  }
+
+  return external;
+}
+
+/**
+ * Mirror of `registerAppConfigContexts` from `@vibesdotdev/runtime/bootstrap/app`.
+ * Inlined to avoid a circular dependency through `bootstrap/index` (which
+ * would re-register core plugins).
+ *
+ * Walks `config.config.plugins` and registers each subtree as a
+ * `plugins.<name>` context. Umbrella plugins read these contexts to
+ * decide which sub-plugins to load.
+ */
+function registerAppConfigContexts(
+  runtime: VibesRuntime,
+  config: Record<string, unknown>,
+): void {
+  const top = config.config as { plugins?: Record<string, unknown> } | undefined;
+  const pluginConfig = top?.plugins;
+  if (!pluginConfig || typeof pluginConfig !== "object") return;
+  if (!runtime.hasKind("context")) return;
+
+  for (const [name, value] of Object.entries(pluginConfig)) {
+    if (value === undefined) continue;
+
+    const id = `plugins.${name}`;
+    runtime.registerDescriptor("context", {
+      kind: "context",
+      id,
+      name: `Plugin config: ${name}`,
+      description: `Runtime app configuration for the ${name} plugin umbrella.`,
+    });
+    runtime.registerLoader("context", id, async () => ({
+      impl: {
+        provide: () => value,
+      },
+    }));
+  }
+}
+
+async function registerCorePlugins(runtime: VibesRuntime): Promise<void> {
+  // Only the true zero-dependency foundation + surface-specific CLI plugin.
+  // All other core plugins (logging, hooks, runtime-client, config, system,
+  // tools, workers, storage, filesystem, paths, workspace, resolver, runtime/docs)
+  // are owned by @vibesdotdev/plugins-core which depends on 'context'.
+  const contextPlugin = (
+    await import("@vibesdotdev/runtime/context/context.plugin")
+  ).default;
+  await runtime.registerPlugin(contextPlugin);
+
+  const cliPlugin = (await import("@vibesdotdev/cli/cli.plugin")).default;
+  await runtime.registerPlugin(cliPlugin);
+}
+
+/**
+ * Pre-parse `--profile <name>` / `--profile=<name>` and surface it through
+ * the `VIBES_PROFILE` env var so downstream profile-aware code (path
+ * resolution, config discovery) sees the active profile on this invocation.
+ *
+ * Commander parses the same flag later when `program.parseAsync` runs, but
+ * by then `loadConfig` and `registerCorePlugins` have already chosen
+ * profile-scoped paths off whatever was set in the environment.
+ *
+ * Strict: ignores anything that looks like another flag (`--profile --foo`).
+ */
+function applyProfileFromArgv(argv: ReadonlyArray<string>): void {
+  for (let i = 2; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--") break;
+    if (token === "--profile") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-")) {
+        process.env.VIBES_PROFILE = next;
+      }
+      return;
+    }
+    if (token.startsWith("--profile=")) {
+      const value = token.slice("--profile=".length);
+      if (value) process.env.VIBES_PROFILE = value;
+      return;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime Surface: CLI
+ *
+ * Official blessed entrypoint for bootstrapping a Vibes CLI runtime.
+ * Re-exports the CLI application factory (createVibesCliApp) and related
+ * types after the surface layer is fully implemented.
+ *
+ * Consumers (cli-bin, shield-cli, internal CLI commands) should import from here
+ * rather than directly from @vibesdotdev/cli/bootstrap or raw runtime bootstrap symbols.
+ */
+
+/**
+ * Runtime Surface — CLI
+ *
+ * The blessed way to bootstrap a full Vibes CLI application.
+ * Re-exports createVibesCliApp and related types from the implementation
+ * that now lives in this surface package.
+ *
+ * All production CLI entrypoints (cli-bin, shield-cli, internal tools)
+ * should import from here.
+ */
+export { createVibesCliApp, type VibesCliAppOptions, type VibesCliApp, type CliPluginLoader } from './cli-bootstrap.ts';