@wringer/gunshi 0.0.0-stage → 0.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 (45) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +55 -2
  3. package/dist/build-failure-envelope.d.ts +2 -0
  4. package/dist/build-gunshi-args.d.ts +4 -0
  5. package/dist/build-gunshi-commands.d.ts +22 -0
  6. package/dist/build-positional-args.d.ts +4 -0
  7. package/dist/build-raw-args.d.ts +17 -0
  8. package/dist/collect-boolean-flags-with-value.d.ts +3 -0
  9. package/dist/collect-flags-without-value.d.ts +3 -0
  10. package/dist/find-signed-value-flag.d.ts +6 -0
  11. package/dist/index.d.ts +3 -0
  12. package/dist/keep-flag-text.d.ts +1 -0
  13. package/dist/parse-arg-properties.d.ts +22 -0
  14. package/dist/pick-cli-outcome.d.ts +23 -0
  15. package/dist/pick-command-name.d.ts +1 -0
  16. package/dist/pick-dispatch-plan.d.ts +13 -0
  17. package/dist/pick-output-mode.d.ts +8 -0
  18. package/dist/read-repo-root.d.ts +2 -0
  19. package/dist/render-envelope.d.ts +3 -0
  20. package/dist/render-human-envelope.d.ts +2 -0
  21. package/dist/render-human-event.d.ts +1 -0
  22. package/dist/run-cli.d.ts +19 -0
  23. package/dist/run-verify.d.ts +2 -0
  24. package/package.json +46 -4
  25. package/src/build-failure-envelope.ts +19 -0
  26. package/src/build-gunshi-args.ts +66 -0
  27. package/src/build-gunshi-commands.ts +217 -0
  28. package/src/build-positional-args.ts +83 -0
  29. package/src/build-raw-args.ts +132 -0
  30. package/src/collect-boolean-flags-with-value.ts +22 -0
  31. package/src/collect-flags-without-value.ts +26 -0
  32. package/src/find-signed-value-flag.ts +35 -0
  33. package/src/index.ts +3 -0
  34. package/src/keep-flag-text.ts +6 -0
  35. package/src/parse-arg-properties.ts +117 -0
  36. package/src/pick-cli-outcome.ts +32 -0
  37. package/src/pick-command-name.ts +9 -0
  38. package/src/pick-dispatch-plan.ts +24 -0
  39. package/src/pick-output-mode.ts +31 -0
  40. package/src/read-repo-root.ts +35 -0
  41. package/src/render-envelope.ts +7 -0
  42. package/src/render-human-envelope.ts +29 -0
  43. package/src/render-human-event.ts +8 -0
  44. package/src/run-cli.ts +186 -0
  45. package/src/run-verify.ts +35 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Geoff Whatley
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,56 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
+ <h1>@wringer/gunshi</h1>
2
3
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
4
+ <p>
5
+ <a href="https://www.npmjs.com/package/@wringer/gunshi"><img src="https://img.shields.io/npm/v/@wringer/gunshi" alt="npm version"></a>
6
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
7
+ </p>
8
+ </div>
9
+
10
+ Turns a wringer registry into the repo's verify CLI, with [gunshi](https://gunshi.dev) parsing the
11
+ command line.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ bun add @wringer/core @wringer/gunshi
17
+ ```
18
+
19
+ The package runs on [Bun](https://bun.sh) 1.3 or newer.
20
+
21
+ ## Usage
22
+
23
+ Call `runVerify` from the repo's verify script with the registry that `@wringer/core` builds:
24
+
25
+ ```ts
26
+ import { runVerify } from '@wringer/gunshi';
27
+ import { registry } from './registry.ts';
28
+
29
+ await runVerify(registry);
30
+ ```
31
+
32
+ Run it as `bun verify.ts <command>`, for example `bun verify.ts up` or
33
+ `bun verify.ts action seed --count 3`.
34
+
35
+ ## Behaviour
36
+
37
+ - Each command prints one JSON envelope. A streaming command, such as `doctor`, prints its NDJSON
38
+ events first.
39
+ - The CLI prints text in place of JSON when stdout is a terminal and no coding agent runs it.
40
+ `--human` and `--json` choose the format.
41
+ - An unknown flag, a flag of the wrong type or arguments that fail the command's schema end in a
42
+ `usage` envelope and exit code 2. So does a flag with no value after it; write `--label ''` to
43
+ pass an empty one.
44
+ - Write a negative value with `=`, as in `--degrees=-15`. The parser reads `--degrees -15` as two
45
+ short options, and the usage envelope's hint gives the joined form. Put a negative positional
46
+ after `--`, as in `lean -- -15`.
47
+ - A flag of an object or a list of objects takes JSON text, such as `--address '{"town":"Hollin"}'`.
48
+ - When a command's arguments are a union of objects, each branch's fields are flags, and the
49
+ command's schema picks the branch.
50
+ - Every command takes `--target`, `--feature` and `--timeout-ms`, unless it declares an argument of
51
+ the same name. `use --target` sets the target for later commands, where `status --target` reads
52
+ one target once.
53
+ - `--help` marks each command `[read]` or `[write]`, so a reader sees which commands a read-only
54
+ target refuses. A command whose arguments decide, such as `db query`, shows `[read or write]`.
55
+ - The script starts itself again, detached, as the run's supervisor, so `up` and `attach` need no
56
+ separate daemon.
@@ -0,0 +1,2 @@
1
+ import type { Envelope, WringerError } from '@wringer/core';
2
+ export declare function buildFailureEnvelope(command: string, error: WringerError): Envelope;
@@ -0,0 +1,4 @@
1
+ import type { CommandInfo } from '@wringer/core';
2
+ import type { ArgSchema } from 'gunshi';
3
+ export type GunshiArgs = Readonly<Record<string, ArgSchema>>;
4
+ export declare function buildGunshiArgs(info: CommandInfo): GunshiArgs;
@@ -0,0 +1,22 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { Wringer } from '@wringer/core';
3
+ import type { Command } from 'gunshi';
4
+ interface GlobalFlags {
5
+ readonly target?: string | undefined;
6
+ readonly feature?: string | undefined;
7
+ readonly timeoutMs?: number | undefined;
8
+ }
9
+ export interface Invocation {
10
+ readonly path: readonly string[];
11
+ readonly raw: Readonly<Record<string, unknown>>;
12
+ readonly globals: GlobalFlags;
13
+ }
14
+ export type InvokeResult = {
15
+ readonly kind: 'invoked';
16
+ readonly invocation: Invocation;
17
+ } | {
18
+ readonly kind: 'refused';
19
+ readonly error: WringerError;
20
+ };
21
+ export declare function buildGunshiCommands(wringer: Wringer, onInvoke: (result: InvokeResult) => void): Record<string, Command>;
22
+ export {};
@@ -0,0 +1,4 @@
1
+ import type { CommandInfo } from '@wringer/core';
2
+ import type { GunshiArgs } from './build-gunshi-args.ts';
3
+ export declare const extraWordsArg = "wringer-extra-words";
4
+ export declare function buildPositionalArgs(info: CommandInfo | null): GunshiArgs;
@@ -0,0 +1,17 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { ArgToken } from 'gunshi';
3
+ import type { GunshiArgs } from './build-gunshi-args.ts';
4
+ export interface ParsedCommand {
5
+ readonly tokens: readonly ArgToken[];
6
+ readonly values: Readonly<Record<string, unknown>>;
7
+ readonly explicit: Readonly<Record<string, boolean>>;
8
+ readonly rest: readonly string[];
9
+ }
10
+ export type RawArgsResult = {
11
+ readonly ok: true;
12
+ readonly raw: Record<string, unknown>;
13
+ } | {
14
+ readonly ok: false;
15
+ readonly error: WringerError;
16
+ };
17
+ export declare function buildRawArgs(args: GunshiArgs, parsed: ParsedCommand): RawArgsResult;
@@ -0,0 +1,3 @@
1
+ import type { ArgToken } from 'gunshi';
2
+ import type { GunshiArgs } from './build-gunshi-args.ts';
3
+ export declare function collectBooleanFlagsWithValue(tokens: readonly ArgToken[], args: GunshiArgs): readonly string[];
@@ -0,0 +1,3 @@
1
+ import type { ArgToken } from 'gunshi';
2
+ import type { GunshiArgs } from './build-gunshi-args.ts';
3
+ export declare function collectFlagsWithoutValue(tokens: readonly ArgToken[], args: GunshiArgs): readonly string[];
@@ -0,0 +1,6 @@
1
+ import type { ArgToken } from 'gunshi';
2
+ export interface SignedValueFlag {
3
+ readonly flag: string;
4
+ readonly value: string;
5
+ }
6
+ export declare function findSignedValueFlag(tokens: readonly ArgToken[], argv: readonly string[]): SignedValueFlag | undefined;
@@ -0,0 +1,3 @@
1
+ export { runCLI } from './run-cli.ts';
2
+ export type { CLIPorts } from './run-cli.ts';
3
+ export { runVerify } from './run-verify.ts';
@@ -0,0 +1 @@
1
+ export declare function keepFlagText(value: string): string;
@@ -0,0 +1,22 @@
1
+ import type { CommandInfo } from '@wringer/core';
2
+ import { z } from 'zod';
3
+ export declare const scalarTypeSchema: z.ZodEnum<{
4
+ boolean: "boolean";
5
+ integer: "integer";
6
+ number: "number";
7
+ string: "string";
8
+ }>;
9
+ export type ScalarType = z.infer<typeof scalarTypeSchema>;
10
+ declare const propertyJSONSchema: z.ZodObject<{
11
+ type: z.ZodOptional<z.ZodUnknown>;
12
+ enum: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
13
+ items: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
14
+ type: z.ZodOptional<z.ZodUnknown>;
15
+ }, z.core.$loose>, z.ZodPipe<z.ZodBoolean, z.ZodTransform<{
16
+ type: null;
17
+ }, boolean>>]>>;
18
+ description: z.ZodOptional<z.ZodString>;
19
+ }, z.core.$loose>;
20
+ export type ArgProperty = z.infer<typeof propertyJSONSchema>;
21
+ export declare function parseArgProperties(info: CommandInfo): Readonly<Record<string, ArgProperty>>;
22
+ export {};
@@ -0,0 +1,23 @@
1
+ import type { WringerError } from '@wringer/core';
2
+ import type { Invocation } from './build-gunshi-commands.ts';
3
+ import type { OutputMode } from './pick-output-mode.ts';
4
+ export type ParsedInvocation = {
5
+ readonly kind: 'invoked';
6
+ readonly invocation: Invocation;
7
+ } | {
8
+ readonly kind: 'printed';
9
+ readonly text: string;
10
+ } | {
11
+ readonly kind: 'failed';
12
+ readonly command: string;
13
+ readonly error: WringerError;
14
+ };
15
+ export type CLIOutcome = {
16
+ readonly kind: 'write';
17
+ readonly text: string;
18
+ readonly exitCode: number;
19
+ } | {
20
+ readonly kind: 'dispatch';
21
+ readonly invocation: Invocation;
22
+ };
23
+ export declare function pickCLIOutcome(parsed: ParsedInvocation, mode: OutputMode): CLIOutcome;
@@ -0,0 +1 @@
1
+ export declare function pickCommandName(commandPath: readonly string[], argv: readonly string[]): string;
@@ -0,0 +1,13 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { Envelope } from '@wringer/core';
3
+ import type { Invocation } from './build-gunshi-commands.ts';
4
+ export type DispatchPlan = {
5
+ readonly kind: 'refuse';
6
+ readonly envelope: Envelope;
7
+ readonly exitCode: number;
8
+ } | {
9
+ readonly kind: 'dispatch';
10
+ readonly root: string;
11
+ readonly invocation: Invocation;
12
+ };
13
+ export declare function pickDispatchPlan(invocation: Invocation, root: string | WringerError): DispatchPlan;
@@ -0,0 +1,8 @@
1
+ import type { ArgToken } from 'gunshi';
2
+ export type OutputMode = 'json' | 'human';
3
+ export interface OutputModeInput {
4
+ readonly tokens: readonly ArgToken[];
5
+ readonly isTTY: boolean;
6
+ readonly isAgent: boolean;
7
+ }
8
+ export declare function pickOutputMode(input: OutputModeInput): OutputMode;
@@ -0,0 +1,2 @@
1
+ import { WringerError } from '@wringer/core';
2
+ export declare function readRepoRoot(cwd: string): Promise<string | WringerError>;
@@ -0,0 +1,3 @@
1
+ import type { Envelope } from '@wringer/core';
2
+ import type { OutputMode } from './pick-output-mode.ts';
3
+ export declare function renderEnvelope(envelope: Envelope, mode: OutputMode): string;
@@ -0,0 +1,2 @@
1
+ import type { Envelope } from '@wringer/core';
2
+ export declare function renderHumanEnvelope(envelope: Envelope): string;
@@ -0,0 +1 @@
1
+ export declare function renderHumanEvent(line: string): string;
@@ -0,0 +1,19 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { RepoHost, StatePort, SupervisorPort, Wringer } from '@wringer/core';
3
+ interface RepoPorts {
4
+ readonly state: StatePort;
5
+ readonly repoHost: RepoHost;
6
+ readonly supervisor: SupervisorPort;
7
+ }
8
+ export interface CLIPorts {
9
+ readonly argv: readonly string[];
10
+ readonly cwd: string;
11
+ readonly isTTY: boolean;
12
+ readonly isAgent: boolean;
13
+ readonly writeStdout: (text: string) => void;
14
+ readonly readRepoRoot: (cwd: string) => Promise<string | WringerError>;
15
+ readonly openRepo: (root: string) => RepoPorts;
16
+ readonly runSupervisor: (wringer: Wringer, argv: readonly string[]) => Promise<void>;
17
+ }
18
+ export declare function runCLI(wringer: Wringer, ports: CLIPorts): Promise<number>;
19
+ export {};
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function runVerify(wringer: Wringer): Promise<void>;
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@wringer/gunshi",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.0",
4
+ "description": "The gunshi adapter for wringer: turns a wringer registry into a CLI",
5
+ "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/gunshi#readme",
6
+ "bugs": "https://github.com/zgeoff/wringer/issues",
7
+ "license": "MIT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/zgeoff/wringer.git",
11
+ "directory": "packages/gunshi"
12
+ },
13
+ "files": [
14
+ "src",
15
+ "!src/**/*.test.ts",
16
+ "dist",
17
+ "!src/test-utils"
18
+ ],
19
+ "type": "module",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./dist/index.d.ts",
23
+ "default": "./src/index.ts"
24
+ }
25
+ },
26
+ "publishConfig": {
27
+ "access": "public"
28
+ },
29
+ "scripts": {
30
+ "build": "rm -rf dist && tsrs -p tsconfig.build.json",
31
+ "typecheck": "tsrs --noEmit"
32
+ },
33
+ "dependencies": {
34
+ "gunshi": "0.37.3",
35
+ "zod": "4.6.7"
36
+ },
37
+ "devDependencies": {
38
+ "@wringer/core": "0.1.0",
39
+ "@zgeoff/testing": "0.2.1",
40
+ "tiny-invariant": "1.3.3"
41
+ },
42
+ "peerDependencies": {
43
+ "@wringer/core": "0.1.0"
44
+ },
45
+ "engines": {
46
+ "bun": ">=1.3"
47
+ }
48
+ }
@@ -0,0 +1,19 @@
1
+ import { buildEnvelope } from '@wringer/core';
2
+ import type { Envelope, WringerError } from '@wringer/core';
3
+
4
+ // A failure before dispatch, such as a parse error, belongs to no target, run or feature.
5
+ export function buildFailureEnvelope(command: string, error: WringerError): Envelope {
6
+ return buildEnvelope({
7
+ command,
8
+ target: null,
9
+ instance: null,
10
+ feature: null,
11
+ sha: null,
12
+ durationMs: 0,
13
+ data: null,
14
+ evidence: [],
15
+ cursors: {},
16
+ truncatedPath: null,
17
+ error,
18
+ });
19
+ }
@@ -0,0 +1,66 @@
1
+ import type { CommandInfo } from '@wringer/core';
2
+ import type { ArgSchema } from 'gunshi';
3
+ import { keepFlagText } from './keep-flag-text.ts';
4
+ import { parseArgProperties, scalarTypeSchema } from './parse-arg-properties.ts';
5
+ import type { ArgProperty, ScalarType } from './parse-arg-properties.ts';
6
+
7
+ export type GunshiArgs = Readonly<Record<string, ArgSchema>>;
8
+
9
+ // gunshi only types each flag; the command's zod schema still checks the whole object in dispatch,
10
+ // so a required flag, a range or a refinement fails there, with a usage error and its path. The
11
+ // positionals are left out, for gunshi to take as positionals.
12
+ export function buildGunshiArgs(info: CommandInfo): GunshiArgs {
13
+ const positionals = new Set(info.positionals);
14
+
15
+ return Object.fromEntries(
16
+ Object.entries(parseArgProperties(info))
17
+ .filter(([name]) => !positionals.has(name))
18
+ .map(([name, property]) => [name, pickArgSchema(property)]),
19
+ );
20
+ }
21
+
22
+ // A non-scalar flag takes JSON text, which gunshi parses before the command's schema checks it. A
23
+ // boolean flag also takes `--no-<flag>`. An enum flag keeps its text, empty included, as a string
24
+ // flag does, and the command's schema checks the choice.
25
+ function pickArgSchema(property: ArgProperty): ArgSchema {
26
+ const described = property.description === undefined ? {} : { description: property.description };
27
+ const choices = property.enum?.filter((choice) => typeof choice === 'string') ?? [];
28
+
29
+ if (choices.length > 0 && choices.length === property.enum?.length) {
30
+ return { type: 'enum', choices, parse: keepFlagText, ...described };
31
+ }
32
+
33
+ const parsedType = scalarTypeSchema.safeParse(property.type);
34
+
35
+ if (parsedType.success) {
36
+ return toFlagSchema(parsedType.data, described);
37
+ }
38
+
39
+ const itemType = scalarTypeSchema.safeParse(property.items?.type);
40
+
41
+ if (property.type === 'array' && itemType.success) {
42
+ return { ...toFlagSchema(itemType.data, described), multiple: true };
43
+ }
44
+
45
+ return { type: 'custom', parse: parseJSONFlag, ...described };
46
+ }
47
+
48
+ function toFlagSchema(type: ScalarType, described: Pick<ArgSchema, 'description'>): ArgSchema {
49
+ if (type === 'boolean') {
50
+ return { type: 'boolean', negatable: true, ...described };
51
+ }
52
+
53
+ if (type === 'integer') {
54
+ return { type: 'number', ...described };
55
+ }
56
+
57
+ if (type === 'string') {
58
+ return { type, parse: keepFlagText, ...described };
59
+ }
60
+
61
+ return { type, ...described };
62
+ }
63
+
64
+ function parseJSONFlag(value: string): unknown {
65
+ return JSON.parse(value);
66
+ }
@@ -0,0 +1,217 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import type { CommandInfo, Wringer } from '@wringer/core';
3
+ import type { Command, CommandContext } from 'gunshi';
4
+ import { z } from 'zod';
5
+ import { buildGunshiArgs } from './build-gunshi-args.ts';
6
+ import type { GunshiArgs } from './build-gunshi-args.ts';
7
+ import { buildPositionalArgs } from './build-positional-args.ts';
8
+ import { buildRawArgs } from './build-raw-args.ts';
9
+ import { collectBooleanFlagsWithValue } from './collect-boolean-flags-with-value.ts';
10
+ import { collectFlagsWithoutValue } from './collect-flags-without-value.ts';
11
+ import { keepFlagText } from './keep-flag-text.ts';
12
+
13
+ interface GlobalFlags {
14
+ readonly target?: string | undefined;
15
+ readonly feature?: string | undefined;
16
+ readonly timeoutMs?: number | undefined;
17
+ }
18
+
19
+ export interface Invocation {
20
+ readonly path: readonly string[];
21
+ readonly raw: Readonly<Record<string, unknown>>;
22
+ readonly globals: GlobalFlags;
23
+ }
24
+
25
+ export type InvokeResult =
26
+ | { readonly kind: 'invoked'; readonly invocation: Invocation }
27
+ | { readonly kind: 'refused'; readonly error: WringerError };
28
+
29
+ // gunshi parses the words; the command runs only after gunshi returns, so every failure, from
30
+ // gunshi or from the command, reaches the one place that writes the envelope.
31
+ export function buildGunshiCommands(
32
+ wringer: Wringer,
33
+ onInvoke: (result: InvokeResult) => void,
34
+ ): Record<string, Command> {
35
+ const root = buildTree([...wringer.commands.values()].map((command) => command.info));
36
+
37
+ return Object.fromEntries(
38
+ [...root.children].map(([name, node]) => [name, toGunshiCommand([name], node, onInvoke)]),
39
+ );
40
+ }
41
+
42
+ interface CommandNode {
43
+ readonly info: CommandInfo | null;
44
+ readonly children: Map<string, CommandNode>;
45
+ }
46
+
47
+ function buildTree(infos: readonly CommandInfo[]): CommandNode {
48
+ const root: CommandNode = { info: null, children: new Map<string, CommandNode>() };
49
+
50
+ for (const info of infos) {
51
+ const parent = info.path.slice(0, -1).reduce((node, word) => resolveChild(node, word), root);
52
+ const name = info.path.at(-1) ?? '';
53
+ const children = parent.children.get(name)?.children ?? new Map<string, CommandNode>();
54
+
55
+ parent.children.set(name, { info, children });
56
+ }
57
+
58
+ return root;
59
+ }
60
+
61
+ // The node for a path word that only groups commands, such as `action`, is made on first use.
62
+ function resolveChild(node: CommandNode, name: string): CommandNode {
63
+ const existing = node.children.get(name);
64
+
65
+ if (existing !== undefined) {
66
+ return existing;
67
+ }
68
+
69
+ const created: CommandNode = { info: null, children: new Map<string, CommandNode>() };
70
+
71
+ node.children.set(name, created);
72
+
73
+ return created;
74
+ }
75
+
76
+ const globalArgs: GunshiArgs = {
77
+ target: {
78
+ type: 'string',
79
+ parse: keepFlagText,
80
+ description: 'The target to run on, for this command only',
81
+ },
82
+ feature: {
83
+ type: 'string',
84
+ parse: keepFlagText,
85
+ description: 'The feature to record evidence under',
86
+ },
87
+ timeoutMs: { type: 'number', description: 'The deadline of the command, in milliseconds' },
88
+ human: { type: 'boolean', description: 'Print text for a person' },
89
+ json: { type: 'boolean', description: 'Print the JSON envelope' },
90
+ };
91
+
92
+ function toGunshiCommand(
93
+ path: readonly string[],
94
+ node: CommandNode,
95
+ onInvoke: (result: InvokeResult) => void,
96
+ ): Command {
97
+ const commandArgs: GunshiArgs = {
98
+ ...(node.info === null ? {} : buildGunshiArgs(node.info)),
99
+ ...buildPositionalArgs(node.info),
100
+ };
101
+
102
+ // gunshi assigns positionals in key order, and a spread keeps an overridden key where it first
103
+ // appeared, so a command's own `target` drops the global one rather than taking its place.
104
+ const args: GunshiArgs = {
105
+ ...Object.fromEntries(
106
+ Object.entries(globalArgs).filter(([name]) => !Object.hasOwn(commandArgs, name)),
107
+ ),
108
+ ...commandArgs,
109
+ };
110
+
111
+ const subCommands = Object.fromEntries(
112
+ [...node.children].map(([name, child]) => [
113
+ name,
114
+ toGunshiCommand([...path, name], child, onInvoke),
115
+ ]),
116
+ );
117
+
118
+ return {
119
+ name: path.at(-1) ?? '',
120
+ description: buildDescription(node.info),
121
+ args,
122
+ toKebab: true,
123
+ ...(node.children.size === 0 ? {} : { subCommands }),
124
+ run: (ctx: CommandContext) => {
125
+ onInvoke(pickInvokeResult({ path, args, commandArgs, ctx }));
126
+ },
127
+ };
128
+ }
129
+
130
+ // The help marks each command as a read or a write, so a reader of a read-only target sees which
131
+ // commands it refuses before running one. A command that decides by its arguments may be either.
132
+ function buildDescription(info: CommandInfo | null): string {
133
+ if (info === null) {
134
+ return '';
135
+ }
136
+
137
+ const effect = info.decideEffect === undefined ? (info.effect ?? 'write') : 'read or write';
138
+
139
+ return `${info.summary} [${effect}]`;
140
+ }
141
+
142
+ interface InvokeRequest {
143
+ readonly path: readonly string[];
144
+ readonly args: GunshiArgs;
145
+ readonly commandArgs: GunshiArgs;
146
+ readonly ctx: Pick<CommandContext, 'tokens' | 'values' | 'explicit' | 'rest'>;
147
+ }
148
+
149
+ // Words that gunshi parsed but the command cannot take are a usage failure, not an exception.
150
+ function pickInvokeResult(request: InvokeRequest): InvokeResult {
151
+ const bareFlags = collectFlagsWithoutValue(request.ctx.tokens, request.args);
152
+
153
+ if (bareFlags.length > 0) {
154
+ return {
155
+ kind: 'refused',
156
+ error: new WringerError('usage', {
157
+ message: `Give a value after ${bareFlags.join(', ')}.`,
158
+ hint: "Write `''` after a flag to pass an empty value.",
159
+ }),
160
+ };
161
+ }
162
+
163
+ const valuedBooleans = collectBooleanFlagsWithValue(request.ctx.tokens, request.args);
164
+
165
+ if (valuedBooleans.length > 0) {
166
+ return {
167
+ kind: 'refused',
168
+ error: new WringerError('usage', {
169
+ message: `${valuedBooleans.join(', ')} takes no value.`,
170
+ hint: 'Write the flag alone to turn it on, or `--no-<flag>` to turn it off.',
171
+ }),
172
+ };
173
+ }
174
+
175
+ const built = buildRawArgs(request.commandArgs, request.ctx);
176
+
177
+ if (!built.ok) {
178
+ return { kind: 'refused', error: built.error };
179
+ }
180
+
181
+ const globals = parseGlobalFlags(request.commandArgs, request.ctx);
182
+
183
+ if (globals instanceof WringerError) {
184
+ return { kind: 'refused', error: globals };
185
+ }
186
+
187
+ return { kind: 'invoked', invocation: { path: request.path, raw: built.raw, globals } };
188
+ }
189
+
190
+ const globalFlagsSchema = z.strictObject({
191
+ target: z.string().min(1).optional(),
192
+ feature: z.string().min(1).optional(),
193
+ timeoutMs: z.number().int().positive().optional(),
194
+ });
195
+
196
+ // A command that declares its own `--target` or `--feature`, such as `use`, keeps it as an
197
+ // argument; the global flag applies to every other command.
198
+ function parseGlobalFlags(
199
+ commandArgs: GunshiArgs,
200
+ ctx: Pick<CommandContext, 'values' | 'explicit'>,
201
+ ): GlobalFlags | WringerError {
202
+ const given = Object.fromEntries(
203
+ Object.keys(globalFlagsSchema.shape).flatMap((name) =>
204
+ Object.hasOwn(commandArgs, name) || ctx.explicit[name] !== true
205
+ ? []
206
+ : [[name, ctx.values[name]] as const],
207
+ ),
208
+ );
209
+
210
+ const parsed = globalFlagsSchema.safeParse(given);
211
+
212
+ if (!parsed.success) {
213
+ return new WringerError('usage', { message: z.prettifyError(parsed.error) });
214
+ }
215
+
216
+ return parsed.data;
217
+ }