@kjanat/dreamcli 0.0.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/CHANGELOG.md +667 -0
  2. package/LICENSE +22 -0
  3. package/README.md +370 -0
  4. package/dist/adapter-B37d9oia.mjs +1 -0
  5. package/dist/adapter-CCSh5juX.cjs +1 -0
  6. package/dist/adapter-DIwO-q7K.d.mts +3447 -0
  7. package/dist/adapter-DQnxxLiE.d.cts +3447 -0
  8. package/dist/auto-5cjZaF9V.mjs +3 -0
  9. package/dist/auto-B0eSgoDw.cjs +3 -0
  10. package/dist/index.cjs +10 -0
  11. package/dist/index.d.cts +920 -0
  12. package/dist/index.d.mts +920 -0
  13. package/dist/index.mjs +10 -0
  14. package/dist/runtime.cjs +1 -0
  15. package/dist/runtime.d.cts +253 -0
  16. package/dist/runtime.d.mts +253 -0
  17. package/dist/runtime.mjs +1 -0
  18. package/dist/testkit-CEDYPvhF.mjs +14 -0
  19. package/dist/testkit-ClIKijxC.cjs +14 -0
  20. package/dist/testkit.cjs +1 -0
  21. package/dist/testkit.d.cts +25 -0
  22. package/dist/testkit.d.mts +25 -0
  23. package/dist/testkit.mjs +1 -0
  24. package/examples/basic.ts +33 -0
  25. package/examples/gh/package.json +48 -0
  26. package/examples/gh/src/commands/auth.ts +66 -0
  27. package/examples/gh/src/commands/issue.ts +120 -0
  28. package/examples/gh/src/commands/pr.ts +125 -0
  29. package/examples/gh/src/data/issues.yaml +5 -0
  30. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  31. package/examples/gh/src/data/pull-requests.yaml +7 -0
  32. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  33. package/examples/gh/src/lib/auth.ts +37 -0
  34. package/examples/gh/src/lib/utils.ts +17 -0
  35. package/examples/gh/src/main.test.ts +306 -0
  36. package/examples/gh/src/main.ts +38 -0
  37. package/examples/gh/tsconfig.json +37 -0
  38. package/examples/interactive.ts +66 -0
  39. package/examples/json-mode.ts +93 -0
  40. package/examples/middleware.ts +71 -0
  41. package/examples/multi-command.ts +66 -0
  42. package/examples/spinner-progress.ts +49 -0
  43. package/examples/testing.ts +145 -0
  44. package/examples/tsconfig.json +17 -0
  45. package/package.json +123 -2
  46. package/src/core/cli/AGENTS.md +72 -0
  47. package/src/core/cli/dispatch.ts +282 -0
  48. package/src/core/cli/index.ts +1425 -0
  49. package/src/core/cli/plugin.ts +111 -0
  50. package/src/core/cli/propagate.ts +97 -0
  51. package/src/core/cli/root-help.ts +269 -0
  52. package/src/core/cli/root-surface.ts +74 -0
  53. package/src/core/completion/AGENTS.md +72 -0
  54. package/src/core/completion/completion-test-helpers.ts +48 -0
  55. package/src/core/completion/index.ts +82 -0
  56. package/src/core/completion/shells/bash.ts +456 -0
  57. package/src/core/completion/shells/fish.ts +24 -0
  58. package/src/core/completion/shells/powershell.ts +24 -0
  59. package/src/core/completion/shells/shared.ts +283 -0
  60. package/src/core/completion/shells/zsh.ts +376 -0
  61. package/src/core/config/index.ts +404 -0
  62. package/src/core/config/package-json.ts +216 -0
  63. package/src/core/errors/index.ts +178 -0
  64. package/src/core/help/index.ts +559 -0
  65. package/src/core/json-schema/index.ts +705 -0
  66. package/src/core/output/AGENTS.md +69 -0
  67. package/src/core/output/activity.ts +568 -0
  68. package/src/core/output/display-value.ts +48 -0
  69. package/src/core/output/index.ts +704 -0
  70. package/src/core/output/writer.ts +46 -0
  71. package/src/core/parse/index.ts +643 -0
  72. package/src/core/prompt/index.ts +566 -0
  73. package/src/core/resolve/AGENTS.md +69 -0
  74. package/src/core/resolve/index.ts +1331 -0
  75. package/src/core/schema/AGENTS.md +61 -0
  76. package/src/core/schema/activity.ts +237 -0
  77. package/src/core/schema/arg.ts +707 -0
  78. package/src/core/schema/command.ts +1263 -0
  79. package/src/core/schema/flag.ts +651 -0
  80. package/src/core/schema/index.ts +82 -0
  81. package/src/core/schema/middleware.ts +171 -0
  82. package/src/core/schema/prompt.ts +148 -0
  83. package/src/core/schema/run.ts +187 -0
  84. package/src/core/testkit/AGENTS.md +55 -0
  85. package/src/core/testkit/index.ts +365 -0
  86. package/src/index.ts +164 -0
  87. package/src/runtime/AGENTS.md +74 -0
  88. package/src/runtime/adapter.ts +300 -0
  89. package/src/runtime/auto.ts +110 -0
  90. package/src/runtime/bun.ts +55 -0
  91. package/src/runtime/deno.ts +355 -0
  92. package/src/runtime/detect.ts +102 -0
  93. package/src/runtime/index.ts +21 -0
  94. package/src/runtime/node-builtins.d.ts +23 -0
  95. package/src/runtime/node.ts +278 -0
  96. package/src/runtime/paths.ts +56 -0
  97. package/src/runtime/support.ts +119 -0
  98. package/src/runtime/test-helpers.ts +40 -0
  99. package/src/runtime.ts +31 -0
  100. package/src/testkit.ts +23 -0
  101. package/src/version.ts +20 -0
@@ -0,0 +1,71 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Middleware patterns: auth guard, request timing, error handling.
4
+ *
5
+ * Demonstrates: middleware() with typed context, context accumulation,
6
+ * short-circuit on error, wrap-around timing.
7
+ *
8
+ * Usage:
9
+ * npx tsx examples/middleware.ts deploy production
10
+ * npx tsx examples/middleware.ts deploy production --verbose
11
+ */
12
+
13
+ import { arg, CLIError, cli, command, flag, middleware } from 'dreamcli';
14
+
15
+ // --- Auth middleware — adds `user` to context ---
16
+
17
+ interface User {
18
+ readonly id: string;
19
+ readonly name: string;
20
+ readonly role: 'admin' | 'user';
21
+ }
22
+
23
+ async function getAuthenticatedUser(): Promise<User | null> {
24
+ // In real code, read a token from env/config/keychain and return null when missing.
25
+ return { id: 'u-1', name: 'Alice', role: 'admin' };
26
+ }
27
+
28
+ const auth = middleware<{ user: User }>(async ({ next }) => {
29
+ const user = await getAuthenticatedUser();
30
+
31
+ if (!user) {
32
+ // Short-circuits the chain — action never runs.
33
+ throw new CLIError('Not authenticated', {
34
+ code: 'AUTH_REQUIRED',
35
+ suggest: 'Run `myapp login` first',
36
+ exitCode: 2,
37
+ });
38
+ }
39
+
40
+ return next({ user });
41
+ });
42
+
43
+ // --- Timing middleware — wraps the downstream chain ---
44
+
45
+ const timing = middleware<{ startTime: number }>(async ({ out, next }) => {
46
+ const start = performance.now();
47
+ await next({ startTime: start });
48
+
49
+ // Code after `next()` runs after the action completes (onion model).
50
+ const elapsed = (performance.now() - start).toFixed(0);
51
+ out.info(`Completed in ${elapsed}ms`);
52
+ });
53
+
54
+ // --- Command using both middlewares ---
55
+
56
+ const deploy = command('deploy')
57
+ .description('Deploy to an environment')
58
+ .arg('target', arg.string().describe('Deploy target'))
59
+ .flag('verbose', flag.boolean().alias('v').describe('Verbose output'))
60
+ .middleware(auth)
61
+ .middleware(timing)
62
+ .action(({ args, flags, ctx, out }) => {
63
+ // ctx.user and ctx.startTime are typed via middleware chain.
64
+ out.log(`[${ctx.user.role}] ${ctx.user.name} deploying ${args.target}`);
65
+ if (flags.verbose) {
66
+ out.info(`User ID: ${ctx.user.id}`);
67
+ out.info(`Started at: ${ctx.startTime.toFixed(0)}ms`);
68
+ }
69
+ });
70
+
71
+ void cli('myapp').default(deploy).run();
@@ -0,0 +1,66 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Multi-command CLI with nested command groups (git-like).
4
+ *
5
+ * Demonstrates: cli(), command(), group(), subcommand nesting,
6
+ * version, env binding, flag propagation.
7
+ *
8
+ * Usage:
9
+ * npx tsx examples/multi-command.ts deploy production --force
10
+ * npx tsx examples/multi-command.ts deploy production --region eu
11
+ * DEPLOY_REGION=ap npx tsx examples/multi-command.ts deploy production
12
+ * npx tsx examples/multi-command.ts db migrate --steps 3
13
+ * npx tsx examples/multi-command.ts db seed
14
+ * npx tsx examples/multi-command.ts login --token abc123
15
+ * npx tsx examples/multi-command.ts --help
16
+ * npx tsx examples/multi-command.ts --version
17
+ */
18
+
19
+ import { arg, cli, command, flag, group } from 'dreamcli';
20
+
21
+ // --- Top-level commands ---
22
+
23
+ const deploy = command('deploy')
24
+ .description('Deploy to an environment')
25
+ .arg('target', arg.string().describe('Deploy target (e.g. production, staging)'))
26
+ .flag('force', flag.boolean().alias('f').describe('Skip confirmation'))
27
+ .flag('region', flag.enum(['us', 'eu', 'ap']).env('DEPLOY_REGION').describe('Target region'))
28
+ .action(({ args, flags, out }) => {
29
+ out.log(`Deploying ${args.target} to ${flags.region ?? 'default region'}`);
30
+ if (flags.force) out.log('(forced)');
31
+ });
32
+
33
+ const login = command('login')
34
+ .description('Authenticate with the service')
35
+ .flag('token', flag.string().describe('Auth token'))
36
+ .action(({ flags, out }) => {
37
+ out.log(`Logged in with token: ${flags.token ?? 'interactive'}`);
38
+ });
39
+
40
+ // --- Nested command group (myapp db migrate, myapp db seed) ---
41
+
42
+ const migrate = command('migrate')
43
+ .description('Run database migrations')
44
+ .flag('steps', flag.number().alias('s').describe('Number of migration steps'))
45
+ .action(({ flags, out }) => {
46
+ out.log(`Migrating ${flags.steps !== undefined ? `${flags.steps} steps` : 'all pending'}`);
47
+ });
48
+
49
+ const seed = command('seed')
50
+ .description('Seed the database')
51
+ .flag('env', flag.enum(['dev', 'test']).default('dev').describe('Seed environment'))
52
+ .action(({ flags, out }) => {
53
+ out.log(`Seeding ${flags.env} database`);
54
+ });
55
+
56
+ const db = group('db').description('Database operations').command(migrate).command(seed);
57
+
58
+ // --- Wire it all up ---
59
+
60
+ void cli('myapp')
61
+ .version('1.0.0')
62
+ .description('Example multi-command CLI')
63
+ .command(deploy)
64
+ .command(login)
65
+ .command(db)
66
+ .run();
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Spinner and progress bar usage.
4
+ *
5
+ * Demonstrates: out.spinner(), out.progress(), auto-disable in
6
+ * non-TTY / --json mode, spinner.wrap() convenience.
7
+ *
8
+ * Usage:
9
+ * npx tsx examples/spinner-progress.ts
10
+ * npx tsx examples/spinner-progress.ts --json # spinners suppressed, JSON output
11
+ * echo | npx tsx examples/spinner-progress.ts # non-TTY: spinners silent
12
+ */
13
+
14
+ import { cli, command, flag } from 'dreamcli';
15
+
16
+ function sleep(ms: number): Promise<void> {
17
+ return new Promise((resolve) => setTimeout(resolve, ms));
18
+ }
19
+
20
+ const build = command('build')
21
+ .description('Build the project (demonstrates spinners and progress)')
22
+ .flag('steps', flag.number().default(5).describe('Number of build steps'))
23
+ .action(async ({ flags, out }) => {
24
+ // --- Spinner: indeterminate work ---
25
+ const spinner = out.spinner('Preparing build environment...');
26
+ await sleep(1000);
27
+ spinner.update('Installing dependencies...');
28
+ await sleep(800);
29
+ spinner.succeed('Environment ready');
30
+
31
+ // --- Spinner with wrap(): auto-succeed/fail ---
32
+ const lint = out.spinner('Linting...');
33
+ await lint.wrap(sleep(600), {
34
+ succeed: 'Lint passed',
35
+ fail: 'Lint failed',
36
+ });
37
+
38
+ // --- Progress bar: determinate work ---
39
+ const progress = out.progress({ total: flags.steps, label: 'Compiling' });
40
+ for (let i = 0; i < flags.steps; i++) {
41
+ await sleep(300);
42
+ progress.increment();
43
+ }
44
+ progress.done('Build complete');
45
+
46
+ out.log(`Built ${flags.steps} modules`);
47
+ });
48
+
49
+ void cli('build').default(build).run();
@@ -0,0 +1,145 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Testing examples using dreamcli/testkit.
4
+ *
5
+ * Demonstrates: runCommand(), prompt answers, env/config injection,
6
+ * activity event assertions. This file is structured as a vitest
7
+ * test suite — run with `bun test examples/testing.ts`.
8
+ *
9
+ * Usage:
10
+ * bun test examples/testing.ts
11
+ */
12
+
13
+ import { arg, command, flag, middleware } from 'dreamcli';
14
+ import { createTestPrompter, PROMPT_CANCEL, runCommand } from 'dreamcli/testkit';
15
+ import { describe, expect, it } from 'vitest';
16
+
17
+ // --- Command under test ---
18
+
19
+ const deploy = command('deploy')
20
+ .description('Deploy to an environment')
21
+ .arg('target', arg.string().describe('Deploy target'))
22
+ .flag(
23
+ 'region',
24
+ flag
25
+ .enum(['us', 'eu', 'ap'])
26
+ .env('DEPLOY_REGION')
27
+ .config('deploy.region')
28
+ .prompt({ kind: 'select', message: 'Which region?' })
29
+ .describe('Target region'),
30
+ )
31
+ .flag('force', flag.boolean().alias('f'))
32
+ .action(({ args, flags, out }) => {
33
+ if (!flags.force) {
34
+ out.warn('Use --force to skip confirmation');
35
+ }
36
+ out.log(`Deploying ${args.target} to ${flags.region}`);
37
+ });
38
+
39
+ // --- Tests ---
40
+
41
+ describe('deploy command', () => {
42
+ it('deploys with explicit flags', async () => {
43
+ const result = await runCommand(deploy, ['production', '--region', 'eu', '--force']);
44
+
45
+ expect(result.exitCode).toBe(0);
46
+ expect(result.stdout).toEqual(['Deploying production to eu\n']);
47
+ expect(result.stderr).toEqual([]);
48
+ });
49
+
50
+ it('resolves region from environment variable', async () => {
51
+ const result = await runCommand(deploy, ['staging', '--force'], {
52
+ env: { DEPLOY_REGION: 'ap' },
53
+ });
54
+
55
+ expect(result.exitCode).toBe(0);
56
+ expect(result.stdout).toEqual(['Deploying staging to ap\n']);
57
+ });
58
+
59
+ it('resolves region from config file', async () => {
60
+ const result = await runCommand(deploy, ['staging', '--force'], {
61
+ config: { deploy: { region: 'eu' } },
62
+ });
63
+
64
+ expect(result.exitCode).toBe(0);
65
+ expect(result.stdout).toEqual(['Deploying staging to eu\n']);
66
+ });
67
+
68
+ it('prompts for region when not provided', async () => {
69
+ const result = await runCommand(deploy, ['staging', '--force'], {
70
+ answers: ['us'],
71
+ });
72
+
73
+ expect(result.exitCode).toBe(0);
74
+ expect(result.stdout).toEqual(['Deploying staging to us\n']);
75
+ });
76
+
77
+ it('handles prompt cancellation', async () => {
78
+ const result = await runCommand(deploy, ['staging'], {
79
+ prompter: createTestPrompter([PROMPT_CANCEL]),
80
+ });
81
+
82
+ expect(result.exitCode).not.toBe(0);
83
+ });
84
+
85
+ it('shows warning when --force is not set', async () => {
86
+ const result = await runCommand(deploy, ['production', '--region', 'us']);
87
+
88
+ expect(result.exitCode).toBe(0);
89
+ expect(result.stderr).toEqual(['Use --force to skip confirmation\n']);
90
+ expect(result.stdout).toEqual(['Deploying production to us\n']);
91
+ });
92
+
93
+ it('renders help text', async () => {
94
+ const result = await runCommand(deploy, ['--help']);
95
+
96
+ expect(result.exitCode).toBe(0);
97
+ expect(result.stdout.join('')).toContain('Deploy to an environment');
98
+ expect(result.stdout.join('')).toContain('--region');
99
+ });
100
+ });
101
+
102
+ // --- Middleware testing ---
103
+
104
+ const auth = middleware<{ user: string }>(async ({ next }) => {
105
+ return next({ user: 'alice' });
106
+ });
107
+
108
+ const guarded = command('secret')
109
+ .description('Protected command')
110
+ .middleware(auth)
111
+ .action(({ ctx, out }) => {
112
+ out.log(`Hello, ${ctx.user}`);
113
+ });
114
+
115
+ describe('middleware context', () => {
116
+ it('passes context from middleware to action', async () => {
117
+ const result = await runCommand(guarded, []);
118
+
119
+ expect(result.exitCode).toBe(0);
120
+ expect(result.stdout).toEqual(['Hello, alice\n']);
121
+ });
122
+ });
123
+
124
+ // --- Spinner/progress activity events ---
125
+
126
+ const build = command('build')
127
+ .description('Build something')
128
+ .action(({ out }) => {
129
+ const spinner = out.spinner('Building...');
130
+ spinner.succeed('Done');
131
+ });
132
+
133
+ describe('activity events', () => {
134
+ it('captures spinner lifecycle in activity array', async () => {
135
+ const result = await runCommand(build, []);
136
+
137
+ expect(result.exitCode).toBe(0);
138
+ expect(result.activity).toContainEqual(
139
+ expect.objectContaining({ type: 'spinner:start', text: 'Building...' }),
140
+ );
141
+ expect(result.activity).toContainEqual(
142
+ expect.objectContaining({ type: 'spinner:succeed', text: 'Done' }),
143
+ );
144
+ });
145
+ });
@@ -0,0 +1,17 @@
1
+ {
2
+ "extends": ["../tsconfig.json"],
3
+ "compilerOptions": {
4
+ "composite": true,
5
+ "noEmit": false,
6
+ "declaration": true,
7
+ "emitDeclarationOnly": true,
8
+ "outDir": ".cache",
9
+ "declarationDir": ".cache/declarations",
10
+ "paths": {
11
+ "dreamcli": ["../src/index.ts"],
12
+ "dreamcli/testkit": ["../src/testkit.ts"],
13
+ "dreamcli/runtime": ["../src/runtime.ts"]
14
+ }
15
+ },
16
+ "exclude": ["**/dist", "**/node_modules", "**/.cache", "gh"]
17
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "0.0.0",
3
+ "version": "1.0.0",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "cli",
@@ -10,5 +10,126 @@
10
10
  "command-line"
11
11
  ],
12
12
  "homepage": "https://dreamcli.kjanat.com",
13
- "main": "package.json"
13
+ "bugs": {
14
+ "url": "https://github.com/kjanat/dreamcli/issues"
15
+ },
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/kjanat/dreamcli.git"
19
+ },
20
+ "license": "MIT",
21
+ "author": "Kaj Kowalski <info@kajkowalski.nl> (https://github.com/kjanat)",
22
+ "type": "module",
23
+ "imports": {
24
+ "#dreamcli": "./src/index.ts",
25
+ "#dreamcli/runtime": "./src/runtime.ts",
26
+ "#dreamcli/testkit": "./src/testkit.ts",
27
+ "#internals/*": "./src/*"
28
+ },
29
+ "exports": {
30
+ ".": {
31
+ "bun": "./src/index.ts",
32
+ "deno": "./src/index.ts",
33
+ "types": {
34
+ "import": "./dist/index.d.mts",
35
+ "require": "./dist/index.d.cts",
36
+ "default": "./dist/index.d.cts"
37
+ },
38
+ "import": "./dist/index.mjs",
39
+ "require": "./dist/index.cjs",
40
+ "default": "./dist/index.cjs"
41
+ },
42
+ "./runtime": {
43
+ "bun": "./src/runtime.ts",
44
+ "deno": "./src/runtime.ts",
45
+ "types": {
46
+ "import": "./dist/runtime.d.mts",
47
+ "require": "./dist/runtime.d.cts",
48
+ "default": "./dist/runtime.d.cts"
49
+ },
50
+ "import": "./dist/runtime.mjs",
51
+ "require": "./dist/runtime.cjs",
52
+ "default": "./dist/runtime.cjs"
53
+ },
54
+ "./testkit": {
55
+ "bun": "./src/testkit.ts",
56
+ "deno": "./src/testkit.ts",
57
+ "types": {
58
+ "import": "./dist/testkit.d.mts",
59
+ "require": "./dist/testkit.d.cts",
60
+ "default": "./dist/testkit.d.cts"
61
+ },
62
+ "import": "./dist/testkit.mjs",
63
+ "require": "./dist/testkit.cjs",
64
+ "default": "./dist/testkit.cjs"
65
+ },
66
+ "./package.json": "./package.json"
67
+ },
68
+ "files": [
69
+ "README.md",
70
+ "LICENSE",
71
+ "CHANGELOG.md",
72
+ "package.json",
73
+ "dist",
74
+ "examples",
75
+ "src",
76
+ "!src/**/*.test.ts"
77
+ ],
78
+ "workspaces": [
79
+ ".",
80
+ "examples/*"
81
+ ],
82
+ "scripts": {
83
+ "bd": "bun run build",
84
+ "build": "bunx --bun tsdown",
85
+ "ci": "bun typecheck && bun lint && bun run test && bun bd",
86
+ "docs:build": "vitepress build docs",
87
+ "docs:dev": "vitepress dev docs",
88
+ "docs:preview": "vitepress preview docs",
89
+ "fmt": "dprint fmt",
90
+ "format": "dprint fmt",
91
+ "format:check": "dprint check",
92
+ "lint": "biome lint",
93
+ "lint:fix": "biome lint --fix",
94
+ "prepack": "bunx --bun tsdown --logLevel silent",
95
+ "test": "vitest run",
96
+ "test:watch": "vitest",
97
+ "typecheck": "tsgo --noEmit",
98
+ "typecheck:tsc": "tsc --noEmit",
99
+ "upgrade": "bun update --latest && bun add -D vitepress@next"
100
+ },
101
+ "devDependencies": {
102
+ "@arethetypeswrong/cli": "^0.18.2",
103
+ "@arethetypeswrong/core": "^0.18.2",
104
+ "@biomejs/biome": "^2.4.10",
105
+ "@iarna/toml": "^2.2.5",
106
+ "@types/bun": "catalog:",
107
+ "@types/deno": "^2.5.0",
108
+ "@types/node": ">=22.0.0, <23.0.0",
109
+ "@typescript/native-preview": "^7.0.0-dev.20260401.1",
110
+ "@vitest/coverage-v8": "^4.1.2",
111
+ "dprint": "^0.53.1",
112
+ "mermaid": "^11.14.0",
113
+ "publint": "^0.3.18",
114
+ "tsdown": "^0.21.7",
115
+ "typescript": "catalog:",
116
+ "vitepress": "^2.0.0-alpha.17",
117
+ "vitepress-plugin-mermaid": "^2.0.17",
118
+ "vitest": "^4.1.2",
119
+ "yaml": "^2.8.3"
120
+ },
121
+ "packageManager": "bun@1.3.11",
122
+ "engines": {
123
+ "bun": ">=1.3.11",
124
+ "deno": ">=2.6.0",
125
+ "node": ">=22.22.2"
126
+ },
127
+ "volta": {
128
+ "node": "25.8.2",
129
+ "npm": "11.12.1"
130
+ },
131
+ "catalog": {
132
+ "@types/bun": "^1.3.0",
133
+ "typescript": "^6.0.2"
134
+ }
14
135
  }
@@ -0,0 +1,72 @@
1
+ # cli — CLIBuilder, multi-command dispatch
2
+
3
+ `index.ts` (~793 lines) — partially split: `dispatch.ts` + `propagate.ts` + `root-help.ts` extracted
4
+ as `@internal`.
5
+
6
+ ## KEY TYPES
7
+
8
+ | Symbol | Role |
9
+ | ------------------ | ----------------------------------------------------------- |
10
+ | `CLIBuilder` | Fluent builder: `.command()`, `.default()`, `.execute()` |
11
+ | `cli(name)` | Factory function → `CLIBuilder` |
12
+ | `CLISchema` | Runtime descriptor for the full CLI |
13
+ | `CLIRunOptions` | Extends `RunOptions` with CLI-level settings |
14
+ | `ConfigSettings` | Config file discovery settings for CLI |
15
+ | `ErasedCommand` | `@internal` — type-erased command for dispatch map |
16
+ | `formatRootHelp()` | `@internal` — root-level help rendering (in `root-help.ts`) |
17
+
18
+ ## FILES
19
+
20
+ | File | Lines | Purpose |
21
+ | -------------- | ----: | --------------------------------------------------------------------------- |
22
+ | `index.ts` | 793 | CLIBuilder class + cli() factory + JSON error handling |
23
+ | `root-help.ts` | 133 | `@internal` — root-level help text + text helpers, structural CLISchemaLike |
24
+ | `dispatch.ts` | 285 | `@internal` — command dispatch, nested resolution, levenshtein |
25
+ | `propagate.ts` | 87 | `@internal` — flag propagation through command tree |
26
+
27
+ ## DISPATCH FLOW
28
+
29
+ ```
30
+ argv → strip --json flag → match subcommand (nested) → resolve → middleware → action → output
31
+ ↓ (no match)
32
+ → error (unknown command / no action) → render as JSON if --json
33
+ ```
34
+
35
+ Nested dispatch: `group('db').command(migrate).command(seed)` → `mycli db migrate --force`
36
+
37
+ ## `execute()` METHOD (~145 lines)
38
+
39
+ Handles 6 concerns sequentially: `--json` extraction, `--version`, `--help`, no-commands error,
40
+ command map building, 3-way dispatch result (`unknown` / `needs-subcommand` / `match`).
41
+
42
+ ## `--json` MODE
43
+
44
+ - Stripped from argv before command dispatch
45
+ - CLI-level errors rendered as JSON when active
46
+ - Propagated to `OutputChannel` via `jsonMode` option
47
+ - `out.log`/`out.info` redirect to stderr in JSON mode (stdout reserved for data)
48
+
49
+ ## GOTCHAS
50
+
51
+ - `root-help.ts` uses structural `CLISchemaLike` instead of importing `CLISchema` — avoids circular
52
+ dep through barrel
53
+ - `levenshtein()` in `dispatch.ts` uses `Uint16Array` rolling buffer — different impl from `parse/`
54
+ - `uniqueCommands()` deduplicates via `Set` on command name — `@internal`
55
+ - `extractConfigFlag()` handles both `--config path` and `--config=path` forms
56
+ - Direct imports: `schema/command.ts`, `schema/flag.ts`, `schema/arg.ts` (not through barrel)
57
+ - Cross-layer imports: `runtime/adapter.ts`, `runtime/auto.ts` (not through runtime barrel)
58
+
59
+ ## TEST FILES (10)
60
+
61
+ | File | Tests |
62
+ | ---------------------------- | --------------------------------------- |
63
+ | `cli.test.ts` | Core dispatch, help, errors, version |
64
+ | `cli-json.test.ts` | JSON mode output + error rendering |
65
+ | `cli-tty.test.ts` | TTY detection propagation |
66
+ | `cli-middleware.test.ts` | Middleware wiring through CLI |
67
+ | `cli-dispatch.test.ts` | Subcommand dispatch, default commands |
68
+ | `cli-nesting.test.ts` | Nested command groups, deep dispatch |
69
+ | `cli-completions.test.ts` | Completion integration in CLI context |
70
+ | `cli-completion-e2e.test.ts` | End-to-end completion script generation |
71
+ | `cli-config.test.ts` | Config discovery integration |
72
+ | `cli-propagate.test.ts` | Flag propagation through command tree |