@vibesdotdev/cli 0.0.1 → 0.0.2

package/README.md

@@ -1,41 +1,22 @@
 # @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:
-
-- 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.
-
-## How it's consumed
-
-```ts
-import { CLISurface } from '@vibesdotdev/cli';
-import { cliPlugin } from '@vibesdotdev/cli/plugin';
-
-// 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
+bun add @vibesdotdev/cli
+# or
+npm install @vibesdotdev/cli
 ```
 
-Hosts also commonly import:
-
-- `@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.
-
-Shell completions for the live descriptor tree are emitted via `vibes completion bash|zsh|fish|fig`, implemented inside this package.
-
-## Known issues
+## Documentation
 
-- 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.
+- Package guide: https://docs.vibes.dev/packages/cli
+- Vibes docs: https://docs.vibes.dev
 
-## Authoritative spec
+## License
 
-For ownership boundaries, runtime contract, and non-goals, see [SPEC.md](./SPEC.md).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibesdotdev/cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "bin": {
     "vibes": "./bin/vibes.ts"
@@ -121,34 +121,29 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vibesdotdev/monorepo.git",
-    "directory": "packages/cli"
-  },
   "peerDependencies": {
-    "@vibesdotdev/config": "0.0.1",
-    "@vibesdotdev/localdb": "0.0.1",
-    "@vibesdotdev/runtime": "0.0.1",
-    "@vibesdotdev/logging": "0.0.1",
-    "@vibesdotdev/runtime-surface-cli": "0.0.1",
-    "@vibesdotdev/storage": "0.0.1",
-    "@vibesdotdev/tui": "0.0.1"
+    "@vibesdotdev/config": "0.0.2",
+    "@vibesdotdev/localdb": "0.0.2",
+    "@vibesdotdev/runtime": "0.0.2",
+    "@vibesdotdev/logging": "0.0.2",
+    "@vibesdotdev/runtime-surface-cli": "0.0.2",
+    "@vibesdotdev/storage": "0.0.2",
+    "@vibesdotdev/tui": "0.0.2"
   },
   "dependencies": {
-    "@vibesdotdev/client": "0.1.0",
-    "@vibesdotdev/config": "0.0.1",
-    "@vibesdotdev/localdb": "0.0.1",
-    "@vibesdotdev/logging": "0.0.1",
-    "@vibesdotdev/runtime": "0.0.1",
-    "@vibesdotdev/runtime-bun": "0.0.0",
-    "@vibesdotdev/runtime-environment-bun": "0.0.0",
-    "@vibesdotdev/storage": "0.0.1",
-    "@vibesdotdev/tui": "0.0.1",
+    "@vibesdotdev/client": "0.1.1",
+    "@vibesdotdev/config": "0.0.2",
+    "@vibesdotdev/localdb": "0.0.2",
+    "@vibesdotdev/logging": "0.0.2",
+    "@vibesdotdev/runtime": "0.0.2",
+    "@vibesdotdev/runtime-bun": "0.0.1",
+    "@vibesdotdev/runtime-environment-bun": "0.0.1",
+    "@vibesdotdev/storage": "0.0.2",
+    "@vibesdotdev/tui": "0.0.2",
     "commander": "^14.0.3",
     "yaml": "^2.9.0",
     "zod": "^4.3.6",
-    "@vibesdotdev/runtime-surface-cli": "0.0.1"
+    "@vibesdotdev/runtime-surface-cli": "0.0.2"
   },
   "scripts": {
     "test": "bun test",
@@ -161,7 +156,6 @@
     "src",
     "bin",
     "README.md",
-    "SPEC.md",
     "LICENSE",
     "!src/**/__tests__/**",
     "!src/**/__stubs__/**",
@@ -182,5 +176,10 @@
   ],
   "vibes": {
     "visibility": "public-framework"
+  },
+  "description": "Descriptor-driven CLI framework for composing Vibes command groups and commands.",
+  "homepage": "https://docs.vibes.dev/packages/cli",
+  "bugs": {
+    "url": "https://docs.vibes.dev/packages/cli#support"
   }
 }

package/SPEC.md

@@ -1,97 +0,0 @@
-# @vibesdotdev/cli
-
-Command-surface substrate: turns runtime `cli/group` and `cli/command` descriptors into a Commander.js CLI tree. Registers the CLI kinds, discovers and renders commands from the live descriptor graph, provides pattern-based command generation (CRUD, config-namespace, tool-wrapper, log-viewer, process-manager), shell completion, and CLI-scoped context providers (UI, logger, app, output-format). Does not own domain behavior — every command's logic lives in the owning feature package; cli only adapts and renders it.
-
-## Owns
-
-- **Bootstrap composition** (`./bootstrap`): `createVibesCliApp({ loader, defaultPlugins, ... })` — composes the runtime loader, core plugins, project-config plugin overrides, and the CLISurface. Accepts a statically-imported `defaultPlugins` set so `bun build --compile` can satisfy the Bundle Selection Rule.
-- **Binary entrypoint** (`./bin/vibes.ts`): `#!/usr/bin/env bun` wrapper calling `createVibesCliApp({ defaultPlugins })`; used by `bunx @vibesdotdev/cli` and the compiled binary wrapper at `apps/cli-bin/src/bin/vibes.ts`.
-- **Runtime kinds:** `cli/group`, `cli/command`
-- **Plugin descriptors:** `cli.plugin` registers the two CLI kinds + the built-in `completion` (`cli/command`) descriptor; depends on `context` kind
-- **CLISurface** (`./surface`): Commander.js program lifecycle — initialize (register providers → resolve patterns → discover groups → discover commands), run (parse argv, dispatch, handle errors)
-  - `register-groups.ts` — depth-first group sorting, parent-chain resolution, pattern delegation
-  - `register-commands.ts` — argument/option mapping, pattern detection, TUI bridging, implementation resolution via `runtime.query().resolve()`
-  - `build-context.ts` — assembles `CommandContext` (runtime + ui + logger + app + config) with fallback lookups
-  - `attach-tui-action.ts` — dynamic import bridge for commands with `tuiAppId`
-  - `command-group-policy.ts` — allowed root-fallback groups; orphan detection
-- **Pattern system** (`./patterns`): declarative command generation from descriptors
-  - `resolver.ts` — `PatternResolver` registry + factory wiring all 5 built-in patterns
-  - `crud.ts` — list/get/create/update/delete against any storage kind
-  - `config-namespace.ts` — get/set/reset/list for a config namespace
-  - `tool-wrapper.ts` — wraps a `tools/tool` asset as a CLI command
-  - `log-viewer.ts` — tail/search/levels for log streaming
-  - `process-manager.ts` — start/stop/restart/status/logs for daemon processes
-  - `schemas.ts` — Zod schemas + type guards for all 5 pattern variants
-- **Descriptor schemas** (`./schemas`): Zod schemas for `cli/group`, `cli/command`; TypeScript module augmentation for the runtime registry; `CLISurfaceOptions`, `CommandContext`
-- **CLI context providers** (`./providers`): registers 5 context loaders with the runtime — `cli/ui` (terminal output), `cli/logger` (cli-namespaced logging), `cli/app` (app-level state), `cli/invocation` (invocation metadata), `cli/output-format` (json/yaml/text detection); also exports `detectOutputFormat()`, `requestCLIExit()`, `shouldKeepAlive()`, `resetKeepAlive()`, `CLIExitSignal`
-- **Error types** (`./errors`): `CLIError` hierarchy — `CommandNotFound`, `InvalidArgument`, `MissingArgument`, `AuthRequired`, `PermissionDenied`, `NotFound`, `Config`, `Network`, `Timeout`, `UserCancelled`
-- **Shell completion** (`./commands/completion`): bash, zsh (including widget), fish, Fig spec generators — rendered from the live descriptor tree
-- **UI toolkit** (`./support/ui-toolkit`): `VibesUIToolkit` — terminal formatting (json/yaml/table/markdown), interactive prompts (prompt/confirm/select/multiselect), progress reporting
-- **Binary path resolution** (`./bin`): monorepo-aware `vibes` binary discovery + worker invocation command builder
-- **Config facade** (`./config`): re-exports `VibesAppConfig`/`PluginsConfig` from `@vibesdotdev/runtime/config` and provides `defineConfig()` typed for project-level `vibes.config.ts`. The CLI does not own the config schema — that lives in `runtime/config`; the facade exists so projects don't need to import from `runtime` directly.
-- **Logging shim** (`./logging`): `'cli'`-namespaced logger singleton wrapping `@vibesdotdev/logging`
-- **Open utility** (`./utils/open`): cross-platform `open(url)`
-- **CLI-startup logger descriptor** (`./logging/cli-startup.logger.descriptor.ts`): registers `'cli-startup'` logger under `'cli:startup'`
-- **UI context descriptor** (`./ui.context.descriptor.ts`): declares `cli/ui` as consumer-hardware-only
-
-## Does not own
-
-- Domain business logic, data access layers, storage engines, encryption, or CRUD services → owning feature packages (e.g., config domain → [`config`](../config/SPEC.md), auth → [`auth-system`](../auth-system/SPEC.md)). CLI is a rendering adapter only.
-- Binary compilation/distribution → [`cli-bin`](../cli-bin/SPEC.md) (wraps `packages/cli/bin/vibes.ts`).
-- Runtime loader implementation → [`runtime-bun`](../runtime-bun/SPEC.md) (Bun), [`runtime`](../runtime/SPEC.md) (interface).
-- TUI substrate (gateway, dispatcher, kinds, React hosting) → [`tui`](../tui/SPEC.md). CLI bridges to TUI via `attach-tui-action.ts` but does not own it.
-- Runtime plugin infrastructure, kind registration protocol, resolver chain → [`runtime`](../runtime/SPEC.md). CLI consumes kinds; it does not define the plugin contract.
-- Workspace data model, project state, active-project tracking → [`workspace`](../workspace/SPEC.md).
-- Auth credentials, session tokens, login flows → [`auth-system`](../auth-system/SPEC.md).
-- HTTP client construction, API connection testing, session refresh → [`client`](../client/SPEC.md). CLI may consume a resolved client; it must not build one.
-- Config storage backends (LocalDB, JSON file, encryption) → [`config`](../config/SPEC.md) + [`storage`](../storage/SPEC.md).
-- MCP protocol, transport, server lifecycle → [`mcp`](../mcp/SPEC.md).
-- Process manager engine, daemon lifecycle, resource registry → [`pm`](../pm/SPEC.md). CLI wraps PM via the `process-manager` pattern only.
-
-## Hard rules
-
-- **CLI is a descriptor rendering layer, not a domain owner.** Every command's execute path must resolve to an implementation owned by a feature package. CLI code must not contain business logic, validation rules, data transformations, or state mutations that belong in a domain package.
-- **All commands register through the descriptor surface.** Imperative `parent.command(...)` calls outside of `patterns/*` and `commands/completion/` are forbidden. Feature packages export `cli/command` descriptors; CLISurface discovers and renders them.
-- **No upstream package may import domain code from CLI.** `packages/cli` is a leaf/consumer package. New imports into `src/app/`, `src/api/`, or `src/core/` from any non-CLI package are blocked.
-- **No direct storage / database access.** CLI code must not import `@vibesdotdev/localdb`, run raw SQL, construct database connections, or manage migration scripts. All data access flows through runtime-resolved assets or context-provided services.
-- **No mutable global singletons.** The `getContext()/setContext()` pattern in `core/runtime/context.ts` is banned for new code. All context flows through the runtime's context injection system.
-- **Patterns are pure CLI translation layers.** Pattern implementations must only map descriptors to Commander.js arguments/options and delegate execution to the resolved implementation. No business logic beyond CLI input coercion.
-- **Completion is derived from the live descriptor tree.** Shell completion output reflects the current registered descriptors without changes to the completion module when new commands are added.
-- **Error types map to deterministic exit codes.** Every `CLIError` subclass has a deterministic exit code. Domain errors are wrapped, not raw. CLI layer formats user-facing errors; it must not expose internal stack traces in normal operation.
-- **Tolerant surface, strict audit.** `strictCommandGroups` and `strictGroupParents` default to off — a config-driven plugin set will routinely produce orphaned descriptors and the surface drops them quietly (warns under `--verbose`). Strict mode is opt-in via the bootstrap `strict` option or `VIBES_CLI_STRICT=1` and is reserved for CI / descriptor audits.
-
-## Migration debt (not yet executed)
-
-- **`src/app/config/` (~40 files)** — full config domain module: SQLite-backed `ConfigStorageService` (raw SQL, migrations), AES-256-GCM encryption service, config business logic monolith (`executeConfig*`), config loader facade, entity config service, imperative Commander.js command registrations. Belongs in [`config`](../config/SPEC.md). **Blocked on:** config package stabilization + migration of all importers off the CLI-internal loader.
-- **`src/api/`** — HTTP client factory + API test/debug service. Belongs in [`client`](../client/SPEC.md).
-- **`src/core/`** — legacy compatibility shims: mutable global `_context` singleton, file-based JSON namespace registry, legacy plugin/hook types.
-- **`src/commands/runtime/`** — imperative codegen command registration. Should be a `cli/command` descriptor owned by [`tools`](../tools/SPEC.md).
-- **Wildcard exports** in `package.json` — `./*`, `./*/*`, `./*/*/*`, `./*/*/*/*` must be replaced with explicit named entrypoints after migration debt clears.
-
-## Public entrypoints
-
-Canonical (stable):
-- `.` — `createVibesCliApp`, `VibesCliAppOptions`, `VibesCliApp`, `CliPluginLoader`, `CLISurface`, `CLISurfaceOptions`, `CommandContext`, `cliPlugin`, pattern types/errors/providers/bin utilities
-- `./bootstrap` — `createVibesCliApp`, types (also re-exported from `.`)
-- `./plugin` — default export: `cliPlugin`
-- `./config` — `VibesAppConfig`, `PluginsConfig`, `VibesConfig`, `defineConfig()`
-
-Migration-era (do not normalize new code against):
-- `./app/config/loader*` — domain leak; target home is [`config`](../config/SPEC.md)
-- `./core` — legacy shim; do not import in new code
-- Wildcard `./*` paths — will be replaced after migration debt clears
-
-## Verification
-
-`bun test` from package root. Covers descriptor schema validation, pattern resolution (all 5 built-in patterns), group registration ordering, command scope filtering, completion generation (bash/zsh/fish/fig), error-type exit-code mapping, context provider registration.
-
-## Links
-
-- [runtime/SPEC.md](../runtime/SPEC.md)
-- [config/SPEC.md](../config/SPEC.md)
-- [tui/SPEC.md](../tui/SPEC.md)
-- [tools/SPEC.md](../tools/SPEC.md)
-- [cli-bin/SPEC.md](../cli-bin/SPEC.md)
-- [storage/SPEC.md](../storage/SPEC.md)
-- [SPEC-AUDIT.md](../../docs/architecture/SPEC-AUDIT.md)
-- [RUNTIME-FIRST-MODULES.md](../../docs/architecture/RUNTIME-FIRST-MODULES.md)