@kjanat/dreamcli 0.0.0 → 2.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 +706 -0
- package/LICENSE +22 -0
- package/README.md +502 -0
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -0
- package/dist/index.mjs +1 -0
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/runtime/adapter.mjs +1 -0
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +7 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit.d.mts +6 -0
- package/dist/testkit.mjs +1 -0
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +44 -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/docs.ts +11 -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 +307 -0
- package/examples/gh/src/main.ts +40 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +91 -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 +147 -0
- package/package.json +149 -2
- package/src/core/cli/dispatch.ts +286 -0
- package/src/core/cli/index.ts +978 -0
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +117 -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/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +88 -0
- package/src/core/completion/shells/bash.ts +459 -0
- package/src/core/completion/shells/fish.ts +259 -0
- package/src/core/completion/shells/powershell.ts +405 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +381 -0
- package/src/core/config/index.ts +407 -0
- package/src/core/config/package-json.ts +220 -0
- package/src/core/errors/index.ts +193 -0
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +557 -0
- package/src/core/json-schema/index.ts +891 -0
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +669 -0
- package/src/core/output/renderers.ts +125 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +661 -0
- package/src/core/prompt/index.ts +583 -0
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +108 -0
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +240 -0
- package/src/core/schema/arg.ts +719 -0
- package/src/core/schema/command.ts +1490 -0
- package/src/core/schema/flag.ts +756 -0
- package/src/core/schema/index.ts +91 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +156 -0
- package/src/core/schema/run.ts +195 -0
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +123 -0
- package/src/index.ts +170 -0
- package/src/runtime/adapter.ts +303 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +369 -0
- package/src/runtime/detect.ts +105 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +300 -0
- package/src/runtime/paths.ts +62 -0
- package/src/runtime/support.ts +135 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +25 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Mixed machine-readable JSON and human-readable side-channel output.
|
|
4
|
+
*
|
|
5
|
+
* Demonstrates: machine-readable `out.json()` stdout, human-readable stderr
|
|
6
|
+
* side channels, and `--json` for CLI-managed structured errors.
|
|
7
|
+
*
|
|
8
|
+
* Usage:
|
|
9
|
+
* npx tsx examples/json-mode.ts list # JSON stdout + plain stderr side channel
|
|
10
|
+
* npx tsx examples/json-mode.ts list --format table # JSON stdout + table stderr side channel
|
|
11
|
+
* npx tsx examples/json-mode.ts list --json # same success output; CLI-managed errors stay JSON-safe
|
|
12
|
+
* npx tsx examples/json-mode.ts show web-api
|
|
13
|
+
* npx tsx examples/json-mode.ts show nonexistent # structured error
|
|
14
|
+
* npx tsx examples/json-mode.ts show nonexistent --json # JSON error
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { arg, CLIError, cli, command, flag } from '@kjanat/dreamcli';
|
|
18
|
+
|
|
19
|
+
// --- Sample data ---
|
|
20
|
+
|
|
21
|
+
type Service = {
|
|
22
|
+
readonly name: string;
|
|
23
|
+
readonly status: 'healthy' | 'degraded' | 'down';
|
|
24
|
+
readonly uptime: number;
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
const services: readonly Service[] = [
|
|
28
|
+
{ name: 'web-api', status: 'healthy', uptime: 99.9 },
|
|
29
|
+
{ name: 'worker', status: 'degraded', uptime: 95.2 },
|
|
30
|
+
{ name: 'database', status: 'healthy', uptime: 99.99 },
|
|
31
|
+
{ name: 'cache', status: 'down', uptime: 0 },
|
|
32
|
+
];
|
|
33
|
+
|
|
34
|
+
// --- Commands ---
|
|
35
|
+
|
|
36
|
+
const list = command('list')
|
|
37
|
+
.description('List all services')
|
|
38
|
+
.flag(
|
|
39
|
+
'format',
|
|
40
|
+
flag.enum(['table', 'plain']).default('plain').alias('f').describe('Output format'),
|
|
41
|
+
)
|
|
42
|
+
.action(({ flags, out }) => {
|
|
43
|
+
// This example always emits machine-readable JSON to stdout. `--json`
|
|
44
|
+
// still matters for DreamCLI-managed output such as structured errors.
|
|
45
|
+
out.json(services);
|
|
46
|
+
|
|
47
|
+
if (flags.format === 'table') {
|
|
48
|
+
out.table(
|
|
49
|
+
services,
|
|
50
|
+
[
|
|
51
|
+
{ key: 'name', header: 'Service' },
|
|
52
|
+
{ key: 'status', header: 'Status' },
|
|
53
|
+
{ key: 'uptime', header: 'Uptime %' },
|
|
54
|
+
],
|
|
55
|
+
{ format: 'text', stream: 'stderr' },
|
|
56
|
+
);
|
|
57
|
+
} else {
|
|
58
|
+
for (const s of services) {
|
|
59
|
+
out.error(`${s.name}: ${s.status} (${s.uptime}%)`);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
const show = command('show')
|
|
65
|
+
.description('Show details for a service')
|
|
66
|
+
.arg('name', arg.string().describe('Service name'))
|
|
67
|
+
.action(({ args, out }) => {
|
|
68
|
+
const service = services.find((s) => s.name === args.name);
|
|
69
|
+
|
|
70
|
+
if (!service) {
|
|
71
|
+
// CLIError with details serializes cleanly in --json mode.
|
|
72
|
+
throw new CLIError(`Service '${args.name}' not found`, {
|
|
73
|
+
code: 'NOT_FOUND',
|
|
74
|
+
exitCode: 1,
|
|
75
|
+
suggest: `Available: ${services.map((s) => s.name).join(', ')}`,
|
|
76
|
+
details: { requested: args.name, available: services.map((s) => s.name) },
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
out.json(service);
|
|
81
|
+
out.error(`${service.name}: ${service.status} (uptime ${service.uptime}%)`);
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
// --- CLI with --json support ---
|
|
85
|
+
|
|
86
|
+
void cli('services')
|
|
87
|
+
.version('1.0.0')
|
|
88
|
+
.description('Service status dashboard')
|
|
89
|
+
.command(list)
|
|
90
|
+
.command(show)
|
|
91
|
+
.run();
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Middleware patterns: auth guard, request timing, error handling.
|
|
4
|
+
*
|
|
5
|
+
* Demonstrates: typed middleware context, auth guards, short-circuiting, and
|
|
6
|
+
* 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 '@kjanat/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: top-level commands, nested groups, version metadata, and
|
|
6
|
+
* env-backed flags.
|
|
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 '@kjanat/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()`, `spinner.wrap()`, and
|
|
6
|
+
* automatic suppression in non-TTY or `--json` mode.
|
|
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 '@kjanat/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,147 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Testing examples using @kjanat/dreamcli/testkit.
|
|
4
|
+
*
|
|
5
|
+
* Demonstrates: `runCommand()`, prompt answers, env/config injection, output
|
|
6
|
+
* assertions, middleware context, and activity assertions.
|
|
7
|
+
*
|
|
8
|
+
* This file is structured as a Vitest test suite — run with
|
|
9
|
+
* `bun test examples/testing.ts`.
|
|
10
|
+
*
|
|
11
|
+
* Usage:
|
|
12
|
+
* bun test examples/testing.ts
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { arg, command, flag, middleware } from '@kjanat/dreamcli';
|
|
16
|
+
import { createTestPrompter, PROMPT_CANCEL, runCommand } from '@kjanat/dreamcli/testkit';
|
|
17
|
+
import { describe, expect, it } from 'vitest';
|
|
18
|
+
|
|
19
|
+
// --- Command under test ---
|
|
20
|
+
|
|
21
|
+
const deploy = command('deploy')
|
|
22
|
+
.description('Deploy to an environment')
|
|
23
|
+
.arg('target', arg.string().describe('Deploy target'))
|
|
24
|
+
.flag(
|
|
25
|
+
'region',
|
|
26
|
+
flag
|
|
27
|
+
.enum(['us', 'eu', 'ap'])
|
|
28
|
+
.env('DEPLOY_REGION')
|
|
29
|
+
.config('deploy.region')
|
|
30
|
+
.prompt({ kind: 'select', message: 'Which region?' })
|
|
31
|
+
.describe('Target region'),
|
|
32
|
+
)
|
|
33
|
+
.flag('force', flag.boolean().alias('f'))
|
|
34
|
+
.action(({ args, flags, out }) => {
|
|
35
|
+
if (!flags.force) {
|
|
36
|
+
out.warn('Use --force to skip confirmation');
|
|
37
|
+
}
|
|
38
|
+
out.log(`Deploying ${args.target} to ${flags.region}`);
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
// --- Tests ---
|
|
42
|
+
|
|
43
|
+
describe('deploy command', () => {
|
|
44
|
+
it('deploys with explicit flags', async () => {
|
|
45
|
+
const result = await runCommand(deploy, ['production', '--region', 'eu', '--force']);
|
|
46
|
+
|
|
47
|
+
expect(result.exitCode).toBe(0);
|
|
48
|
+
expect(result.stdout).toEqual(['Deploying production to eu\n']);
|
|
49
|
+
expect(result.stderr).toEqual([]);
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
it('resolves region from environment variable', async () => {
|
|
53
|
+
const result = await runCommand(deploy, ['staging', '--force'], {
|
|
54
|
+
env: { DEPLOY_REGION: 'ap' },
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
expect(result.exitCode).toBe(0);
|
|
58
|
+
expect(result.stdout).toEqual(['Deploying staging to ap\n']);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it('resolves region from config file', async () => {
|
|
62
|
+
const result = await runCommand(deploy, ['staging', '--force'], {
|
|
63
|
+
config: { deploy: { region: 'eu' } },
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
expect(result.exitCode).toBe(0);
|
|
67
|
+
expect(result.stdout).toEqual(['Deploying staging to eu\n']);
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
it('prompts for region when not provided', async () => {
|
|
71
|
+
const result = await runCommand(deploy, ['staging', '--force'], {
|
|
72
|
+
answers: ['us'],
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
expect(result.exitCode).toBe(0);
|
|
76
|
+
expect(result.stdout).toEqual(['Deploying staging to us\n']);
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
it('handles prompt cancellation', async () => {
|
|
80
|
+
const result = await runCommand(deploy, ['staging'], {
|
|
81
|
+
prompter: createTestPrompter([PROMPT_CANCEL]),
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
expect(result.exitCode).not.toBe(0);
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
it('shows warning when --force is not set', async () => {
|
|
88
|
+
const result = await runCommand(deploy, ['production', '--region', 'us']);
|
|
89
|
+
|
|
90
|
+
expect(result.exitCode).toBe(0);
|
|
91
|
+
expect(result.stderr).toEqual(['Use --force to skip confirmation\n']);
|
|
92
|
+
expect(result.stdout).toEqual(['Deploying production to us\n']);
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
it('renders help text', async () => {
|
|
96
|
+
const result = await runCommand(deploy, ['--help']);
|
|
97
|
+
|
|
98
|
+
expect(result.exitCode).toBe(0);
|
|
99
|
+
expect(result.stdout.join('')).toContain('Deploy to an environment');
|
|
100
|
+
expect(result.stdout.join('')).toContain('--region');
|
|
101
|
+
});
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
// --- Middleware testing ---
|
|
105
|
+
|
|
106
|
+
const auth = middleware<{ user: string }>(async ({ next }) => {
|
|
107
|
+
return next({ user: 'alice' });
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
const guarded = command('secret')
|
|
111
|
+
.description('Protected command')
|
|
112
|
+
.middleware(auth)
|
|
113
|
+
.action(({ ctx, out }) => {
|
|
114
|
+
out.log(`Hello, ${ctx.user}`);
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
describe('middleware context', () => {
|
|
118
|
+
it('passes context from middleware to action', async () => {
|
|
119
|
+
const result = await runCommand(guarded, []);
|
|
120
|
+
|
|
121
|
+
expect(result.exitCode).toBe(0);
|
|
122
|
+
expect(result.stdout).toEqual(['Hello, alice\n']);
|
|
123
|
+
});
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
// --- Spinner/progress activity events ---
|
|
127
|
+
|
|
128
|
+
const build = command('build')
|
|
129
|
+
.description('Build something')
|
|
130
|
+
.action(({ out }) => {
|
|
131
|
+
const spinner = out.spinner('Building...');
|
|
132
|
+
spinner.succeed('Done');
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
describe('activity events', () => {
|
|
136
|
+
it('captures spinner lifecycle in activity array', async () => {
|
|
137
|
+
const result = await runCommand(build, []);
|
|
138
|
+
|
|
139
|
+
expect(result.exitCode).toBe(0);
|
|
140
|
+
expect(result.activity).toContainEqual(
|
|
141
|
+
expect.objectContaining({ type: 'spinner:start', text: 'Building...' }),
|
|
142
|
+
);
|
|
143
|
+
expect(result.activity).toContainEqual(
|
|
144
|
+
expect.objectContaining({ type: 'spinner:succeed', text: 'Done' }),
|
|
145
|
+
);
|
|
146
|
+
});
|
|
147
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kjanat/dreamcli",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "Schema-first, fully typed TypeScript CLI framework",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cli",
|
|
@@ -10,5 +10,152 @@
|
|
|
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": {
|
|
22
|
+
"name": "Kaj Kowalski",
|
|
23
|
+
"email": "info@kajkowalski.nl",
|
|
24
|
+
"url": "https://github.com/kjanat"
|
|
25
|
+
},
|
|
26
|
+
"type": "module",
|
|
27
|
+
"imports": {
|
|
28
|
+
"#dreamcli": "./src/index.ts",
|
|
29
|
+
"#dreamcli/runtime": "./src/runtime.ts",
|
|
30
|
+
"#dreamcli/testkit": "./src/testkit.ts",
|
|
31
|
+
"#internals/*": "./src/*",
|
|
32
|
+
"#schema": "./dreamcli.schema.json",
|
|
33
|
+
"#package.json": "./package.json"
|
|
34
|
+
},
|
|
35
|
+
"exports": {
|
|
36
|
+
".": {
|
|
37
|
+
"types": "./dist/index.d.mts",
|
|
38
|
+
"bun": "./src/index.ts",
|
|
39
|
+
"deno": "./src/index.ts",
|
|
40
|
+
"default": "./dist/index.mjs"
|
|
41
|
+
},
|
|
42
|
+
"./runtime": {
|
|
43
|
+
"types": "./dist/runtime.d.mts",
|
|
44
|
+
"bun": "./src/runtime.ts",
|
|
45
|
+
"deno": "./src/runtime.ts",
|
|
46
|
+
"default": "./dist/runtime.mjs"
|
|
47
|
+
},
|
|
48
|
+
"./testkit": {
|
|
49
|
+
"types": "./dist/testkit.d.mts",
|
|
50
|
+
"bun": "./src/testkit.ts",
|
|
51
|
+
"deno": "./src/testkit.ts",
|
|
52
|
+
"default": "./dist/testkit.mjs"
|
|
53
|
+
},
|
|
54
|
+
"./schema": "./dreamcli.schema.json",
|
|
55
|
+
"./package.json": "./package.json"
|
|
56
|
+
},
|
|
57
|
+
"files": [
|
|
58
|
+
"CHANGELOG.md",
|
|
59
|
+
"LICENSE",
|
|
60
|
+
"README.md",
|
|
61
|
+
"dist",
|
|
62
|
+
"dreamcli.schema.json",
|
|
63
|
+
"examples",
|
|
64
|
+
"!examples/.cache",
|
|
65
|
+
"package.json",
|
|
66
|
+
"src",
|
|
67
|
+
"!src/**/*.test.ts",
|
|
68
|
+
"!src/**/*test-helpers.ts",
|
|
69
|
+
"!**/AGENTS.md"
|
|
70
|
+
],
|
|
71
|
+
"workspaces": [
|
|
72
|
+
"./examples/*"
|
|
73
|
+
],
|
|
74
|
+
"scripts": {
|
|
75
|
+
"bd": "bunx --bun tsdown",
|
|
76
|
+
"build": "bunx --bun tsdown",
|
|
77
|
+
"build:watch": "bunx --bun tsdown --watch",
|
|
78
|
+
"ci": "bun typecheck && bun lint && bun run format:check && bun run meta-descriptions:check && bun run test && bun run docs:build && bun bd",
|
|
79
|
+
"coverage": "vitest run --coverage",
|
|
80
|
+
"dev": "bunx --bun tsdown --logLevel silent --watch & bunx --bun vitepress@next dev docs --host --port ${PORT:-5173} & wait",
|
|
81
|
+
"docs:build": "bunx --bun vitepress@next build docs",
|
|
82
|
+
"docs:dev": "bunx --bun vitepress@next dev docs",
|
|
83
|
+
"docs:preview": "bunx --bun vitepress@next preview docs",
|
|
84
|
+
"fmt": "dprint fmt",
|
|
85
|
+
"format": "dprint fmt",
|
|
86
|
+
"format:check": "dprint check",
|
|
87
|
+
"gh-project": "bun scripts/gh-project.ts",
|
|
88
|
+
"gh-project:finish": "bun gh-project finish",
|
|
89
|
+
"gh-project:list": "bun gh-project list",
|
|
90
|
+
"gh-project:set": "bun gh-project set",
|
|
91
|
+
"gh-project:start": "bun gh-project start",
|
|
92
|
+
"gh-project:sync": "bun gh-project sync",
|
|
93
|
+
"knip": "knip",
|
|
94
|
+
"lint": "biome lint",
|
|
95
|
+
"lint:fix": "biome lint --fix",
|
|
96
|
+
"meta-descriptions": "bun --bun scripts/build-meta-descriptions.ts",
|
|
97
|
+
"meta-descriptions:check": "bun --bun scripts/build-meta-descriptions.ts --check",
|
|
98
|
+
"prepack": "bunx --bun tsdown --logLevel silent",
|
|
99
|
+
"test": "vitest run",
|
|
100
|
+
"test:watch": "vitest",
|
|
101
|
+
"typecheck": "tsgo --noEmit",
|
|
102
|
+
"typecheck:tsc": "tsc --noEmit",
|
|
103
|
+
"upgrade": "bun update --latest && bun add -D vitepress@next"
|
|
104
|
+
},
|
|
105
|
+
"devDependencies": {
|
|
106
|
+
"@arethetypeswrong/core": "^0.18.2",
|
|
107
|
+
"@biomejs/biome": "^2.4.10",
|
|
108
|
+
"@iarna/toml": "^2.2.5",
|
|
109
|
+
"@shikijs/transformers": "^4.0.2",
|
|
110
|
+
"@shikijs/vitepress-twoslash": "^4.0.2",
|
|
111
|
+
"@types/bun": "^1.3.0",
|
|
112
|
+
"@types/deno": "^2.5.0",
|
|
113
|
+
"@types/node": ">=22.0.0, <23.0.0",
|
|
114
|
+
"@typescript/native-preview": "^7.0.0-dev.20260406.1",
|
|
115
|
+
"@vitest/coverage-v8": "^4.1.2",
|
|
116
|
+
"dprint": "^0.53.2",
|
|
117
|
+
"floating-vue": "^5.2.2",
|
|
118
|
+
"knip": "^6.3.0",
|
|
119
|
+
"mermaid": "^11.14.0",
|
|
120
|
+
"publint": "^0.3.18",
|
|
121
|
+
"tsdown": "^0.21.7",
|
|
122
|
+
"typedoc": "^0.28.18",
|
|
123
|
+
"typescript": "^6.0.2",
|
|
124
|
+
"vitepress": "^2.0.0-alpha.17",
|
|
125
|
+
"vitest": "^4.1.2",
|
|
126
|
+
"wrangler": "^4.80.0",
|
|
127
|
+
"yaml": "^2.8.3"
|
|
128
|
+
},
|
|
129
|
+
"optionalDependencies": {
|
|
130
|
+
"vite": "^8"
|
|
131
|
+
},
|
|
132
|
+
"packageManager": "bun@1.3.11",
|
|
133
|
+
"engines": {
|
|
134
|
+
"bun": ">=1.3.11",
|
|
135
|
+
"deno": ">=2.6.0",
|
|
136
|
+
"node": ">=22.22.2"
|
|
137
|
+
},
|
|
138
|
+
"devEngines": {
|
|
139
|
+
"packageManager": {
|
|
140
|
+
"name": "bun",
|
|
141
|
+
"onFail": "warn"
|
|
142
|
+
},
|
|
143
|
+
"runtime": {
|
|
144
|
+
"name": "bun",
|
|
145
|
+
"onFail": "ignore"
|
|
146
|
+
}
|
|
147
|
+
},
|
|
148
|
+
"volta": {
|
|
149
|
+
"node": "25.8.2",
|
|
150
|
+
"npm": "11.12.1"
|
|
151
|
+
},
|
|
152
|
+
"publishConfig": {
|
|
153
|
+
"access": "public",
|
|
154
|
+
"provenance": true
|
|
155
|
+
},
|
|
156
|
+
"catalog": {
|
|
157
|
+
"@types/bun": "^1.3.0",
|
|
158
|
+
"@types/node": ">=22.0.0, <23.0.0",
|
|
159
|
+
"typescript": "^6.0.2"
|
|
160
|
+
}
|
|
14
161
|
}
|