@wringer/gunshi 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +55 -2
- package/dist/build-failure-envelope.d.ts +2 -0
- package/dist/build-gunshi-args.d.ts +4 -0
- package/dist/build-gunshi-commands.d.ts +22 -0
- package/dist/build-positional-args.d.ts +4 -0
- package/dist/build-raw-args.d.ts +17 -0
- package/dist/collect-boolean-flags-with-value.d.ts +3 -0
- package/dist/collect-flags-without-value.d.ts +3 -0
- package/dist/find-signed-value-flag.d.ts +6 -0
- package/dist/index.d.ts +3 -0
- package/dist/keep-flag-text.d.ts +1 -0
- package/dist/parse-arg-properties.d.ts +22 -0
- package/dist/pick-cli-outcome.d.ts +23 -0
- package/dist/pick-command-name.d.ts +1 -0
- package/dist/pick-dispatch-plan.d.ts +13 -0
- package/dist/pick-output-mode.d.ts +8 -0
- package/dist/read-repo-root.d.ts +2 -0
- package/dist/render-envelope.d.ts +3 -0
- package/dist/render-human-envelope.d.ts +2 -0
- package/dist/render-human-event.d.ts +1 -0
- package/dist/run-cli.d.ts +19 -0
- package/dist/run-verify.d.ts +2 -0
- package/package.json +46 -4
- package/src/build-failure-envelope.ts +19 -0
- package/src/build-gunshi-args.ts +66 -0
- package/src/build-gunshi-commands.ts +217 -0
- package/src/build-positional-args.ts +83 -0
- package/src/build-raw-args.ts +132 -0
- package/src/collect-boolean-flags-with-value.ts +22 -0
- package/src/collect-flags-without-value.ts +26 -0
- package/src/find-signed-value-flag.ts +35 -0
- package/src/index.ts +3 -0
- package/src/keep-flag-text.ts +6 -0
- package/src/parse-arg-properties.ts +117 -0
- package/src/pick-cli-outcome.ts +32 -0
- package/src/pick-command-name.ts +9 -0
- package/src/pick-dispatch-plan.ts +24 -0
- package/src/pick-output-mode.ts +31 -0
- package/src/read-repo-root.ts +35 -0
- package/src/render-envelope.ts +7 -0
- package/src/render-human-envelope.ts +29 -0
- package/src/render-human-event.ts +8 -0
- package/src/run-cli.ts +186 -0
- 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
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>@wringer/gunshi</h1>
|
|
2
3
|
|
|
3
|
-
|
|
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,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,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;
|
package/dist/index.d.ts
ADDED
|
@@ -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 @@
|
|
|
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 {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wringer/gunshi",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.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.1",
|
|
39
|
+
"@zgeoff/testing": "0.2.1",
|
|
40
|
+
"tiny-invariant": "1.3.3"
|
|
41
|
+
},
|
|
42
|
+
"peerDependencies": {
|
|
43
|
+
"@wringer/core": "0.1.1"
|
|
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
|
+
}
|