@vibesdotdev/cli 0.0.2 → 1.0.0-rc.3

package/src/docs/cli.commands.docs.descriptor.ts

@@ -1,210 +0,0 @@
-import type { DocsTopicDescriptor } from './types.ts';
-
-/**
- * Descriptor for cli.commands
- * Auto-generated by `vibes docs generate`
- */
-const cli_commandsMarkdown = `---
-title: CLI Commands
-summary: Complete reference for vibes CLI commands and groups
-tags: [cli, commands, reference, man-pages]
-parent: cli
-order: 1
----
-
-# CLI Commands
-
-The vibes CLI provides command-line access to runtime features, documentation, and development tools.
-
-## Overview
-
-The CLI is organized into **groups** and **commands**:
-
-\`\`\`
-vibes <group> <command> [options]
-\`\`\`
-
-## Available groups
-
-### \`vibes tools\`
-
-Tool management and invocation:
-
-- \`vibes tools list\` — List all registered tools
-- \`vibes tools invoke <id>\` — Invoke a tool by id
-- \`vibes tools info <id>\` — Show tool metadata
-
-### \`vibes docs\`
-
-Documentation browsing:
-
-- \`vibes docs show <topic>\` — Render a topic to stdout
-- \`vibes docs list\` — List all topics
-- \`vibes docs search <query>\` — Search topics
-- \`vibes docs open <topic>\` — Open topic in browser
-- \`vibes docs generate <package> <topic>\` — Scaffold new descriptor
-
-### \`vibes man\`
-
-Manual pages (alias for \`vibes docs show\`):
-
-- \`vibes man <topic>\` — Show man-page for topic
-- \`vibes man <kind> <id>\` — Show by subject reference
-
-### \`vibes dev\`
-
-Development commands:
-
-- \`vibes dev start\` — Start development server
-- \`vibes dev build\` — Build for production
-- \`vibes dev test\` — Run tests
-- \`vibes dev lint\` — Run linter
-
-### \`vibes workspace\`
-
-Workspace management:
-
-- \`vibes workspace info\` — Show workspace metadata
-- \`vibes workspace list\` — List workspace slices
-- \`vibes workspace switch <slice>\` — Switch active slice
-
-## Common options
-
-These options are available across most commands:
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| \`--help\` | Show help for command | \`vibes tools list --help\` |
-| \`--json\` | Output as JSON | \`vibes tools list --json\` |
-| \`--verbose\` | Enable verbose logging | \`vibes dev start --verbose\` |
-| \`--no-color\` | Disable ANSI colors | \`vibes man tools.list --no-color\` |
-| \`--bare\` | Skip envelope/formatting | \`vibes man tools.list --bare\` |
-
-## Examples
-
-### List all tools as JSON
-
-\`\`\`bash
-vibes tools list --json | jq '.[] | { id: .id, description: .description }'
-\`\`\`
-
-### View documentation
-
-\`\`\`bash
-# By topic id
-vibes man tools.list
-
-# By subject reference
-vibes man tools/tool tools.list
-
-# Open in browser
-vibes docs open tools.list
-\`\`\`
-
-### Search documentation
-
-\`\`\`bash
-# Search by keyword
-vibes docs search "runtime query"
-
-# Filter by tag
-vibes docs list --tag=tools
-
-# Filter by parent
-vibes docs list --parent=runtime
-\`\`\`
-
-### Generate new descriptor
-
-\`\`\`bash
-# Inline pattern (default)
-vibes docs generate ai providers.anthropic
-
-# Package-sourced pattern
-vibes docs generate storage adapters.drizzle --pattern package
-
-# With custom metadata
-vibes docs generate tools my-tool \\
-  --parent tools \\
-  --title "My Custom Tool" \\
-  --dry-run
-\`\`\`
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Invalid arguments |
-| 3 | Topic not found |
-| 4 | Permission denied |
-
-## Environment variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| \`VIBES_HOME\` | Vibes configuration directory | \`~/.vibes\` |
-| \`VIBES_LOG_LEVEL\` | Logging level | \`info\` |
-| \`VIBES_NO_COLOR\` | Disable colors | \`false\` |
-| \`VIBES_HARDWARE\` | Hardware surface | \`consumer\` |
-
-## Related
-
-:::card{title="See also"}
-- [\`cli.groups\`](cli.groups) — Command group structure
-- [\`runtime.query\`](runtime.query) — Runtime discovery API
-- [\`docs.topic\`](docs.topic) — Descriptor schema
-:::
-`;
-
-const descriptor: DocsTopicDescriptor = {
-  kind: 'docs/topic',
-  id: 'cli.commands',
-  title: 'CLI Commands',
-  summary: 'Complete reference for vibes CLI commands and groups',
-  body: {
-    type: 'markdown',
-    sourceType: 'raw',
-    source: cli_commandsMarkdown
-  },
-  parent: 'cli',
-  order: 1,
-  tags: ['cli', 'commands', 'reference', 'man-pages'],
-  surfaces: ['cli', 'web', 'in-app'],
-  hardware: ['consumer'],
-  enabled: true,
-  man: {
-    name: 'vibes — CLI command reference',
-    section: 1,
-    synopsis: 'vibes <group> <command> [options]',
-    options: [
-      { flag: '--help', description: 'Show help for command' },
-      { flag: '--json', description: 'Output as JSON' },
-      { flag: '--verbose', description: 'Enable verbose logging' },
-      { flag: '--no-color', description: 'Disable ANSI colors' },
-      { flag: '--bare', description: 'Skip envelope/formatting' }
-    ],
-    examples: [
-      {
-        description: 'List all tools',
-        command: 'vibes tools list'
-      },
-      {
-        description: 'View man-page for a topic',
-        command: 'vibes man tools.list'
-      },
-      {
-        description: 'Search documentation',
-        command: 'vibes docs search "runtime query"'
-      },
-      {
-        description: 'Generate new descriptor',
-        command: 'vibes docs generate ai providers.anthropic'
-      }
-    ],
-    seeAlso: ['cli.groups', 'runtime.query', 'docs.topic']
-  }
-};
-
-export default descriptor;

package/src/docs/cli.groups.docs.descriptor.ts

@@ -1,333 +0,0 @@
-import type { DocsTopicDescriptor } from './types.ts';
-
-const cli_groupsMarkdown = `---
-title: CLI Groups
-summary: Command group structure, nesting, and help display
-tags: [cli, groups, commands, organization, help]
-parent: cli
-order: 2
----
-
-# CLI Groups
-
-Command groups organize CLI commands into logical subcommand trees. Groups provide structure, discoverability, and consistent help display across the vibes CLI.
-
-## Overview
-
-Groups are registered as \`cli/group\` runtime assets. Each group can contain commands or nested subgroups, forming a hierarchical command tree.
-
-\`\`\`
-vibes <group> <subgroup> <command> [options]
-\`\`\`
-
-## Group descriptor structure
-
-Groups are defined with a descriptor that specifies metadata:
-
-\`\`\`ts
-import type { CLIGroupAssetDescriptor } from '@vibesdotdev/cli/schemas/descriptors';
-
-const profileGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'profile',
-  name: 'profile',
-  description: 'Manage configuration profiles',
-  parent: 'config',  // optional — creates 'vibes config profile'
-  aliases: ['prof'], // optional aliases
-  surfaces: ['cli'],
-  order: 2,          // sort order within parent
-  internal: false    // if true, hidden unless --internal flag
-};
-\`\`\`
-
-### Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| \`id\` | string | ✅ | Unique identifier (dot-separated for nesting) |
-| \`name\` | string | ✅ | Command name as typed |
-| \`description\` | string | ✅ | Help text shown in parent's help |
-| \`parent\` | string | ❌ | Parent group id for nesting |
-| \`aliases\` | string[] | ❌ | Alternative names |
-| \`surfaces\` | \`'cli' | 'web' | 'worker' | 'bridge'\`[] | ❌ | Where group appears |
-| \`order\` | number | ❌ | Sibling sort order (lower = earlier) |
-| \`internal\` | boolean | ❌ | If true, hidden by default |
-
-## Group registration
-
-Groups are registered via the runtime plugin:
-
-\`\`\`ts
-// packages/cli/src/cli.plugin.ts
-import profileGroup from './commands/profile/profile-group.descriptor';
-
-export default createRuntimePlugin({
-  id: 'cli',
-  kinds: [cliGroupKind, cliCommandKind],
-  descriptors: [
-    profileGroup,
-    // ... other groups and commands
-  ]
-});
-\`\`\`
-
-## Nested groups
-
-Groups can nest by referencing a parent:
-
-\`\`\`ts
-// Parent group
-const configGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'config',
-  name: 'config',
-  description: 'Configuration management'
-};
-
-// Child group
-const profileGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'config.profile',
-  name: 'profile',
-  description: 'Manage configuration profiles',
-  parent: 'config'  // → 'vibes config profile'
-};
-\`\`\`
-
-**Result:**
-
-\`\`\`bash
-vibes config           # parent group
-vibes config profile   # nested group
-vibes config profile list
-vibes config profile create
-\`\`\`
-
-## Help display
-
-Groups automatically generate help text:
-
-\`\`\`bash
-# Parent group help — shows subgroups and commands
-$ vibes config --help
-
-Usage: vibes config [options] [command]
-
-Configuration management
-
-Commands:
-  profile     Manage configuration profiles
-  env         Environment variable management
-  help [command]  display help for command
-
-# Nested group help
-$ vibes config profile --help
-
-Usage: vibes config profile [options] [command]
-
-Manage configuration profiles
-
-Commands:
-  list      List all profiles
-  create    Create a new profile
-  use       Switch active profile
-  delete    Delete a profile
-  info      Show profile details
-  help [command]  display help for command
-\`\`\`
-
-## Group resolution
-
-The CLI surface resolves groups at runtime:
-
-1. **Discovery** — Query \`runtime.assets('cli/group')\` for all group descriptors
-2. **Filtering** — Apply surface and hardware filters
-3. **Sorting** — Order by \`descriptor.order\`
-4. **Registration** — Attach to Commander.js parent command
-
-\`\`\`ts
-// packages/cli/src/surface/register-groups.ts
-const discovery = getCLIDiscovery(runtime, options);
-const groups = discovery.sortedGroups;
-
-for (const group of groups) {
-  await registerGroup(params, group);
-}
-\`\`\`
-
-### Parent resolution
-
-If a group references a missing parent:
-
-- **Strict mode** (\`VIBES_CLI_STRICT=1\` or \`CLISurfaceOptions.strictGroupParents\`): throws error
-- **Lenient mode** (default): logs warning, attaches to root
-
-## Pattern-based groups
-
-Groups can use patterns for dynamic behavior:
-
-\`\`\`ts
-const runtimeGroup: CLIPatternDescriptor = {
-  kind: 'cli/group',
-  id: 'runtime',
-  name: 'runtime',
-  description: 'Runtime management',
-  pattern: 'crud',  // auto-generates list/create/delete commands
-  patternConfig: {
-    entityType: 'runtime/plugin',
-    listFields: ['id', 'name', 'version']
-  }
-};
-\`\`\`
-
-Patterns are resolved by the pattern resolver:
-
-\`\`\`ts
-// packages/cli/src/surface/register-groups.ts
-if (params.patternResolver && isPatternDescriptor(descriptor)) {
-  const ctx = await params.buildContext();
-  await params.patternResolver.resolve(
-    descriptor as CLIPatternDescriptor,
-    groupCmd,
-    ctx
-  );
-}
-\`\`\`
-
-## Common patterns
-
-### Flat structure
-
-Simple commands without nesting:
-
-\`\`\`ts
-const completionGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'shell-integration',
-  name: 'shell-integration',
-  description: 'Shell completions and integrations'
-};
-\`\`\`
-
-### Deep nesting
-
-Multi-level command trees:
-
-\`\`\`ts
-// vibes → dev → server → start
-const serverGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'dev.server',
-  name: 'server',
-  description: 'Development server',
-  parent: 'dev'
-};
-\`\`\`
-
-### Aliased groups
-
-Multiple access paths:
-
-\`\`\`ts
-const profileGroup: CLIGroupAssetDescriptor = {
-  kind: 'cli/group',
-  id: 'profile',
-  name: 'profile',
-  description: 'Manage profiles',
-  aliases: ['prof', 'p']
-};
-
-// All equivalent:
-vibes profile list
-vibes prof list
-vibes p list
-\`\`\`
-
-## WRONG patterns
-
-### ❌ Missing description
-
-\`\`\`ts
-// BAD — help text is empty
-const group = {
-  kind: 'cli/group',
-  id: 'mystery',
-  name: 'mystery',
-  description: ''  // ← shows as blank in help
-};
-\`\`\`
-
-### ❌ Circular parent references
-
-\`\`\`ts
-// BAD — creates infinite loop
-const groupA = { id: 'a', parent: 'b' };
-const groupB = { id: 'b', parent: 'a' };  // ← circular!
-\`\`\`
-
-### ❌ Duplicate IDs
-
-\`\`\`ts
-// BAD — second registration overwrites first
-const group1 = { id: 'profile', name: 'profile' };
-const group2 = { id: 'profile', name: 'prof' };  // ← conflict!
-\`\`\`
-
-### ❌ Non-existent parent
-
-\`\`\`ts
-// BAD — parent 'config' doesn't exist
-const profileGroup = {
-  id: 'profile',
-  parent: 'config'  // ← warning in lenient mode, error in strict
-};
-\`\`\`
-
-## Related
-
-:::card{title="See also"}
-- [\`cli.commands\`](cli.commands) — Command structure and execution
-- [\`cli.output\`](cli.output) — Output formatting and display
-- [\`runtime.assets\`](runtime.assets) — Asset discovery API
-:::
-`;
-
-const descriptor: DocsTopicDescriptor = {
-	kind: 'docs/topic',
-	id: 'cli.groups',
-	title: 'CLI Groups',
-	summary: 'Command group structure, nesting, and help display',
-	body: {
-		type: 'markdown',
-		sourceType: 'raw',
-		source: cli_groupsMarkdown
-	},
-	parent: 'cli',
-	order: 2,
-	tags: ['cli', 'groups', 'commands', 'organization', 'help'],
-	surfaces: ['cli', 'web', 'in-app'],
-	hardware: ['consumer'],
-	enabled: true,
-	man: {
-		name: 'cli.groups — CLI command group structure',
-		section: 1,
-		synopsis: 'vibes man cli.groups',
-		examples: [
-			{
-				description: 'View group structure documentation',
-				command: 'vibes man cli.groups'
-			},
-			{
-				description: 'List all registered groups',
-				command: 'vibes runtime assets cli/group'
-			},
-			{
-				description: 'Show help for a group',
-				command: 'vibes profile --help'
-			}
-		],
-		seeAlso: ['cli.commands', 'cli.output', 'runtime.assets']
-	}
-};
-
-export default descriptor;