@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.
- package/CHANGELOG.md +667 -0
- package/LICENSE +22 -0
- package/README.md +370 -0
- package/dist/adapter-B37d9oia.mjs +1 -0
- package/dist/adapter-CCSh5juX.cjs +1 -0
- package/dist/adapter-DIwO-q7K.d.mts +3447 -0
- package/dist/adapter-DQnxxLiE.d.cts +3447 -0
- package/dist/auto-5cjZaF9V.mjs +3 -0
- package/dist/auto-B0eSgoDw.cjs +3 -0
- package/dist/index.cjs +10 -0
- package/dist/index.d.cts +920 -0
- package/dist/index.d.mts +920 -0
- package/dist/index.mjs +10 -0
- package/dist/runtime.cjs +1 -0
- package/dist/runtime.d.cts +253 -0
- package/dist/runtime.d.mts +253 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit-CEDYPvhF.mjs +14 -0
- package/dist/testkit-ClIKijxC.cjs +14 -0
- package/dist/testkit.cjs +1 -0
- package/dist/testkit.d.cts +25 -0
- package/dist/testkit.d.mts +25 -0
- package/dist/testkit.mjs +1 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +48 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +306 -0
- package/examples/gh/src/main.ts +38 -0
- package/examples/gh/tsconfig.json +37 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +93 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +145 -0
- package/examples/tsconfig.json +17 -0
- package/package.json +123 -2
- package/src/core/cli/AGENTS.md +72 -0
- package/src/core/cli/dispatch.ts +282 -0
- package/src/core/cli/index.ts +1425 -0
- package/src/core/cli/plugin.ts +111 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/completion/AGENTS.md +72 -0
- package/src/core/completion/completion-test-helpers.ts +48 -0
- package/src/core/completion/index.ts +82 -0
- package/src/core/completion/shells/bash.ts +456 -0
- package/src/core/completion/shells/fish.ts +24 -0
- package/src/core/completion/shells/powershell.ts +24 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +376 -0
- package/src/core/config/index.ts +404 -0
- package/src/core/config/package-json.ts +216 -0
- package/src/core/errors/index.ts +178 -0
- package/src/core/help/index.ts +559 -0
- package/src/core/json-schema/index.ts +705 -0
- package/src/core/output/AGENTS.md +69 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +704 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +643 -0
- package/src/core/prompt/index.ts +566 -0
- package/src/core/resolve/AGENTS.md +69 -0
- package/src/core/resolve/index.ts +1331 -0
- package/src/core/schema/AGENTS.md +61 -0
- package/src/core/schema/activity.ts +237 -0
- package/src/core/schema/arg.ts +707 -0
- package/src/core/schema/command.ts +1263 -0
- package/src/core/schema/flag.ts +651 -0
- package/src/core/schema/index.ts +82 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +148 -0
- package/src/core/schema/run.ts +187 -0
- package/src/core/testkit/AGENTS.md +55 -0
- package/src/core/testkit/index.ts +365 -0
- package/src/index.ts +164 -0
- package/src/runtime/AGENTS.md +74 -0
- package/src/runtime/adapter.ts +300 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +355 -0
- package/src/runtime/detect.ts +102 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +278 -0
- package/src/runtime/paths.ts +56 -0
- package/src/runtime/support.ts +119 -0
- package/src/runtime/test-helpers.ts +40 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +23 -0
- 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": "
|
|
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
|
-
"
|
|
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 |
|