@tinkered/cli 0.0.0-stage → 0.27.2

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/README.md CHANGED
@@ -1,3 +1,334 @@
1
- # Temporary Holding Version
1
+ # @tinkered/cli
2
2
 
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.
3
+ The `tinker` command (ADR 0156).
4
+ It is made for an agent that writes the code.
5
+ `tinker check` runs every fast gate.
6
+ Each finding prints its fix.
7
+ The fix text comes from the skill.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ bun add -d @tinkered/cli
13
+ ```
14
+
15
+ Each release also attaches tarballs to its
16
+ GitHub release; the
17
+ [changelog](../../CHANGELOG.md) lists them.
18
+
19
+ ## Commands
20
+
21
+ ```text
22
+ tinker check [root] [--json]
23
+ tinker skill list
24
+ tinker skill load <skill>
25
+ ```
26
+
27
+ Where only Bun may run, call it with `--bun`:
28
+
29
+ ```bash
30
+ bun --bun tinker check
31
+ ```
32
+
33
+ ## The check loop
34
+
35
+ `tinker check` runs two stages in order.
36
+
37
+ 1. **types:** the app's `tsc`, the kind gate and
38
+ the cast gate.
39
+ 2. **rules:** Tinker's rules, then the app's
40
+ other lint.
41
+
42
+ - Only the first stage that fails prints.
43
+ - At most 5 findings print.
44
+ - One fault prints once.
45
+ - A finding is one line, then its fix.
46
+ - The last line is the next step.
47
+
48
+ ```text
49
+ src/a.tsx:64 tinker/kind kind "locked" has no case
50
+ Right: a `switch` on `kind`, with a case for
51
+ each kind the check names. Do not add
52
+ `default:`. Do not cast.
53
+ more: tinker skill load @tinkered/react#react
54
+
55
+ tinker check: types failed.
56
+ Next: fix each finding, then run `tinker check`
57
+ again. The rules stage runs once types pass.
58
+ ```
59
+
60
+ Only this says the work is done:
61
+
62
+ ```text
63
+ ran: tsc, lint, rules (66 files)
64
+ tinker check: OK
65
+ ```
66
+
67
+ `--json` prints the same report as data:
68
+ `kind` is `ok` or `failed`.
69
+
70
+ Exit codes:
71
+
72
+ - `0`: done.
73
+ - `1`: one finding or more.
74
+ - `2`: a wrong call, a config it cannot read, a
75
+ tool it cannot run, or a tool with no config.
76
+
77
+ The check has no lint or type config of its own.
78
+ It runs the app's own tools:
79
+
80
+ - `tsc --noEmit`, when the app has a
81
+ `tsconfig.json`;
82
+ - `vp lint`, when the app has a `vite.config`.
83
+
84
+ A tool with no config is skipped, and the
85
+ `skipped:` line says so. Then the answer is
86
+ `tinker check: not done`, with exit 2: only a
87
+ run of every stage can say OK.
88
+
89
+ ## Where the fix comes from
90
+
91
+ A skill has a section per mistake. Its heading
92
+ holds the rule id:
93
+
94
+ ```md
95
+ ### HIGH: a cast [tinker/cast]
96
+
97
+ Right: narrow or parse. Do not cast:
98
+ ```
99
+
100
+ The check prints the `Right:` part of that
101
+ section. It reads the skills the app has
102
+ installed, through Intent. So the fix has the
103
+ version of the code you have.
104
+
105
+ A lint rule with no section prints the lint's own
106
+ `help:` line.
107
+
108
+ ## The gates
109
+
110
+ The package exports one base config. The app
111
+ extends it, and says where it applies:
112
+
113
+ ```json
114
+ { "extends": "@tinkered/cli/tsconfig.json" }
115
+ ```
116
+
117
+ ```ts
118
+ import { gates } from "@tinkered/cli/config";
119
+
120
+ lint: {
121
+ overrides: [{ files: ["src/**"], rules: gates }],
122
+ },
123
+ ```
124
+
125
+ - **The kind gate, `tinker/kind`.** A `switch` on
126
+ a call's answer has a case for each kind, and
127
+ no `default`. `noImplicitReturns` makes `tsc`
128
+ fail on a kind with no case; the lint rule names
129
+ the kind.
130
+ - **The cast gate, `tinker/cast`.** No `as` but
131
+ `as const`. No `!`. No `any`.
132
+
133
+ ## Skills
134
+
135
+ ```bash
136
+ tinker skill list
137
+ tinker skill load @tinkered/react#react
138
+ ```
139
+
140
+ `list` names each skill the app has, with when
141
+ to load it. `load` prints the skill's text.
142
+ Intent finds them (ADR 0143).
143
+
144
+ ## Tinker's rules
145
+
146
+ - `tinker/plain` — a named function in `src/`,
147
+ `cmds/` or `tinker/` is an operation.
148
+ A function that passes is not called by name,
149
+ and a flow function passes: see below.
150
+ - `tinker/one-wire` — a page file calls no
151
+ `fetch`, `WebSocket`, `EventSource`,
152
+ `XMLHttpRequest` or `sendBeacon`.
153
+ The rpc client is the one wire.
154
+ - `tinker/react-state` — a page file calls no
155
+ `useState`, `useReducer`, `useEffect` or
156
+ `useLayoutEffect`.
157
+ State lives in a Core cell.
158
+ - `tinker/gap` — a gap marker sits on an open
159
+ row: see below.
160
+
161
+ A page file is a file in `src/` with no `.server`
162
+ in its name.
163
+
164
+ ## A call by name
165
+
166
+ A function passes `tinker/plain` when something
167
+ else calls it: Core, a library, React. So app
168
+ code does not call it by name (ADR 0149).
169
+
170
+ ```ts
171
+ const add = useCallback(
172
+ (a: number, b: number) => a + b,
173
+ [],
174
+ );
175
+ add(1, 2);
176
+ ```
177
+
178
+ ```text
179
+ src/page.tsx:1 tinker/plain a helper, called
180
+ by name at src/page.tsx:5
181
+ ```
182
+
183
+ App code may call by name:
184
+
185
+ - an operation, through the scope;
186
+ - a closure: a function that reads a name of a
187
+ function around it, so it holds that unit's
188
+ state;
189
+ - an entry in `tinker.json`.
190
+
191
+ ```ts
192
+ factory: () => {
193
+ let n = 0;
194
+ const bump = () => ++n;
195
+ return { bump, twice: () => [bump(), bump()] };
196
+ },
197
+ ```
198
+
199
+ `bump` reads `n`, so it is a closure. It passes.
200
+
201
+ The check reads syntax only. It does not see a
202
+ function that comes through `depends`, or one a
203
+ library hands back. Review looks at those.
204
+
205
+ ## Flow files: the Workflow SDK
206
+
207
+ The [Workflow SDK](https://workflow-sdk.dev) finds
208
+ a workflow and a step by a directive. So they
209
+ cannot be operations (ADR 0148).
210
+
211
+ A flow file is a file whose name ends in
212
+ `.flow.ts` or `.flow.server.ts`. In it, a
213
+ function passes `tinker/plain` when its body
214
+ starts with `"use workflow"` or `"use step"`:
215
+
216
+ ```ts
217
+ export async function nameFlow() {
218
+ "use workflow";
219
+ return await suggest();
220
+ }
221
+
222
+ async function suggest() {
223
+ "use step";
224
+ return callOperation("naming.suggest");
225
+ }
226
+ ```
227
+
228
+ - The directive is first in the body. Only other
229
+ directives, such as `"use strict"`, may come
230
+ before it.
231
+ - In any other file, the same function fails.
232
+ - A helper in a flow file still fails.
233
+ - Only a flow function calls a flow function by
234
+ name. A call from other code is a finding.
235
+ `start(nameFlow, [...])` is no call by name.
236
+ - Name it `.flow.server.ts` to keep it out of the
237
+ page rules.
238
+
239
+ ## The app's own exceptions
240
+
241
+ `tinker.json`, at the app root.
242
+ Each exception carries its reason as text.
243
+
244
+ ```json
245
+ {
246
+ "plain": {
247
+ "entries": {
248
+ "tinker/base/main-host.ts": {
249
+ "runMain": "Owns the exit code."
250
+ }
251
+ }
252
+ },
253
+ "page": {
254
+ "files": ["src/frontend/**"],
255
+ "skip": {
256
+ "src/bench/**": "Other libraries."
257
+ }
258
+ }
259
+ }
260
+ ```
261
+
262
+ - `gaps`: the path of a gaps doc. A finding
263
+ is allowed when the line above it is
264
+ `// tinker-gap: G3` and row `G3` is open.
265
+ See below.
266
+ - `plain.entries`: functions that stay plain, by
267
+ file and name. An entry runs before a scope
268
+ exists, so it cannot be an operation.
269
+ - `page.files`: where the page's files are.
270
+ Default: `src/**`.
271
+ - `page.skip`: globs to leave out of the page.
272
+
273
+ ## Gaps: a finding you cannot fix yet
274
+
275
+ A gap is a finding that waits on a Tinker
276
+ change. Mark it, and give it a row in the
277
+ gaps doc.
278
+
279
+ ```ts
280
+ // tinker-gap: G3
281
+ const answer = await fetch("/api/auth");
282
+ ```
283
+
284
+ ```md
285
+ ## G3: the auth library's own HTTP
286
+
287
+ - Status: open
288
+ - Lines: 5
289
+ ```
290
+
291
+ - The marker is on the line directly above.
292
+ - The row must be open.
293
+ - A row allows at most `Lines` marked lines,
294
+ so the count can only go down.
295
+ - A marker with no finding below it breaks
296
+ `tinker/gap`.
297
+
298
+ Each run prints the counts:
299
+ `gaps: G1 3/3, G3 5/5`.
300
+
301
+ ## Lint rules
302
+
303
+ `@tinkered/cli/lint` is an Oxlint plugin.
304
+
305
+ ```ts
306
+ jsPlugins: [
307
+ {
308
+ name: "tinker",
309
+ specifier: "@tinkered/cli/lint",
310
+ },
311
+ ],
312
+ rules: {
313
+ "tinker/blank-lines": "error",
314
+ "tinker/body-steps": "error",
315
+ "tinker/cell-write": "warn",
316
+ },
317
+ ```
318
+
319
+ - `tinker/cell-write` — warns on a write to a cell
320
+ that another capsule owns (ADR 0123).
321
+ - `tinker/blank-lines`, `tinker/body-steps` — a
322
+ body reads as steps (ADR 0111).
323
+
324
+ ## From code
325
+
326
+ ```ts
327
+ import { check } from "@tinkered/cli";
328
+
329
+ const report = check(process.cwd());
330
+ ```
331
+
332
+ `check` runs Tinker's rules only.
333
+ `report.findings` holds each finding:
334
+ `path`, `line`, `rule`, `what`.
@@ -0,0 +1,7 @@
1
+ {
2
+ "compilerOptions": {
3
+ "strict": true,
4
+ "noUncheckedIndexedAccess": true,
5
+ "noImplicitReturns": true
6
+ }
7
+ }
package/dist/cli.d.mts ADDED
@@ -0,0 +1 @@
1
+ export {}
package/dist/cli.mjs ADDED
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ import { t as main } from "./main-DQK2xJ_R.mjs";
3
+ //#region src/cli.ts
4
+ if (import.meta.main) {
5
+ const { code, out, err } = main(process.argv.slice(2), process.cwd());
6
+ process.stdout.write(out);
7
+ process.stderr.write(err);
8
+ process.exitCode = code;
9
+ }
10
+ //#endregion
11
+ export {};
@@ -0,0 +1,13 @@
1
+ //#region src/config.d.ts
2
+ /** A lint rule's setting, in the shape the app's lint config takes. */
3
+ type Setting = "error" | ["error", Readonly<Record<string, boolean | string>>];
4
+ /**
5
+ * Tinker's gates (ADR 0156 decisions 5 and 6), for the app's lint `overrides`. The app places
6
+ * them on the files they guard, such as `src/**`.
7
+ *
8
+ * - The kind gate: a `switch` on a call's answer has a case for each kind, and no `default`.
9
+ * A `default` does not stand in for a kind, so a new kind still fails.
10
+ * - The cast gate: no `as` but `as const`, no `!`, no `any`.
11
+ */
12
+ export declare const gates: Readonly<Record<string, Setting>>;
13
+ //#endregion
@@ -0,0 +1,20 @@
1
+ //#region src/config.ts
2
+ /**
3
+ * Tinker's gates (ADR 0156 decisions 5 and 6), for the app's lint `overrides`. The app places
4
+ * them on the files they guard, such as `src/**`.
5
+ *
6
+ * - The kind gate: a `switch` on a call's answer has a case for each kind, and no `default`.
7
+ * A `default` does not stand in for a kind, so a new kind still fails.
8
+ * - The cast gate: no `as` but `as const`, no `!`, no `any`.
9
+ */
10
+ const gates = {
11
+ "typescript/switch-exhaustiveness-check": ["error", {
12
+ considerDefaultExhaustiveForUnions: false,
13
+ allowDefaultCaseForExhaustiveSwitch: false
14
+ }],
15
+ "typescript/consistent-type-assertions": ["error", { assertionStyle: "never" }],
16
+ "typescript/no-non-null-assertion": "error",
17
+ "typescript/no-explicit-any": "error"
18
+ };
19
+ //#endregion
20
+ export { gates };
@@ -0,0 +1,163 @@
1
+ //#region src/rules.d.ts
2
+ /** Tinker's own rules: `check` finds them in the app's files. */
3
+ declare const own: readonly ["tinker/plain", "tinker/one-wire", "tinker/react-state", "tinker/gap"];
4
+ //#endregion
5
+ //#region src/check.d.ts
6
+ declare namespace Check {
7
+ /** A rule id, as the skills name it (ADR 0143 decision 4). */
8
+ type Rule = (typeof own)[number];
9
+ /** One file of the app: its path from the app root, with `/`, and its text. */
10
+ type Source = {
11
+ path: string;
12
+ text: string;
13
+ };
14
+ /** One broken rule at one line. `what` names the thing found there. */
15
+ type Finding = {
16
+ path: string;
17
+ line: number;
18
+ rule: Rule;
19
+ what: string;
20
+ };
21
+ /**
22
+ * Functions that may stay plain, by file and then by name. Each value is the reason: an
23
+ * entry contract runs before any scope exists, so it cannot be an operation.
24
+ */
25
+ type Entries = Readonly<Record<string, Readonly<Record<string, string>>>>;
26
+ /** The app's `tinker.json`. Every key may be absent. */
27
+ type Config = {
28
+ plain?: {
29
+ entries?: Entries;
30
+ };
31
+ /**
32
+ * `files` are the globs of the page's files (default: all of `src/`, less `.server.`
33
+ * files). `skip` takes files out again: a glob, and the reason as its value.
34
+ */
35
+ page?: {
36
+ files?: readonly string[];
37
+ skip?: Readonly<Record<string, string>>;
38
+ };
39
+ /**
40
+ * The app's gaps doc, from the root. A finding marked `// tinker-gap: G<n>` on the line
41
+ * above is allowed while row `G<n>` of that doc is open and within its count.
42
+ */
43
+ gaps?: string;
44
+ };
45
+ /** One row of the gaps doc: its id, whether it is open, its count, and its marked lines. */
46
+ type Gap = {
47
+ gap: string;
48
+ open: boolean;
49
+ lines: number;
50
+ marked: number;
51
+ };
52
+ /** `files` counts every file read. Findings are in path order, then line order. */
53
+ type Report = {
54
+ files: number;
55
+ findings: Finding[];
56
+ gaps: Gap[];
57
+ };
58
+ }
59
+ /**
60
+ * Read the app at `root` and answer every broken rule. It reads files and nothing else: it
61
+ * runs no app code. A `tinker.json` at the root holds the app's own exceptions.
62
+ *
63
+ * @throws `BadConfig` when that file is not the shape `Check.Config` names.
64
+ */
65
+ export declare function check(root: string): Check.Report;
66
+ //#endregion
67
+ //#region src/errors.d.ts
68
+ /** The registry: the command makes no error of its own outside it. */
69
+ type Payloads = {
70
+ /** The app's `tinker.json` does not have the shape `Check.Config` names. */
71
+ BadConfig: {
72
+ path: string;
73
+ reason: string;
74
+ };
75
+ /** The app has a tool's config, but not the tool. */
76
+ MissingTool: {
77
+ tool: string;
78
+ reason: string;
79
+ };
80
+ /** A tool failed and printed no finding: its own output says why. */
81
+ ToolFailed: {
82
+ tool: string;
83
+ output: string;
84
+ };
85
+ };
86
+ declare namespace Errors {
87
+ type Name = keyof Payloads;
88
+ type Payload<N extends Name> = Payloads[N];
89
+ type Of<N extends Name = Name> = Error & {
90
+ readonly kind: N;
91
+ readonly payload: Payloads[N];
92
+ };
93
+ }
94
+ /** Narrow an unknown error to one registry entry; callers rethrow on mismatch. */
95
+ export declare function isError<N extends Errors.Name>(value: unknown, kind: N): value is Errors.Of<N>;
96
+ //#endregion
97
+ //#region src/tools.d.ts
98
+ declare namespace Tools {
99
+ /** A stage of `tinker check`: `types` runs first, and `rules` only once it is clean. */
100
+ type Stage = "types" | "rules";
101
+ /**
102
+ * One error from the app's own tools. `rule` is a Tinker rule id, a `TS` code, or a lint
103
+ * rule as `<plugin>/<rule>`. `help` is the tool's own hint, when it gives one.
104
+ */
105
+ type Found = {
106
+ path: string;
107
+ line: number;
108
+ rule: string;
109
+ what: string;
110
+ help?: string;
111
+ };
112
+ /** What each stage got from the tools, and the tools that ran or were skipped. */
113
+ type Report = {
114
+ types: Found[];
115
+ rules: Found[];
116
+ ran: string[];
117
+ skipped: string[];
118
+ };
119
+ }
120
+ //#endregion
121
+ //#region src/main.d.ts
122
+ declare namespace Main {
123
+ /** What the command would print and exit with. Nothing is printed here. */
124
+ type Result = {
125
+ code: number;
126
+ out: string;
127
+ err: string;
128
+ };
129
+ /** A finding as it prints: the skill's `Right:` lines, or the tool's own hint. */
130
+ type Finding = Omit<Tools.Found, "help"> & {
131
+ fix: string[];
132
+ skill?: string;
133
+ };
134
+ /**
135
+ * The answer of `tinker check`. `ok` is the only answer that means done: every stage ran
136
+ * and is clean. `failed` names the first stage that failed, its first findings, and how many
137
+ * it has in all. `incomplete` is clean, but a tool did not run for want of its config.
138
+ */
139
+ type Report = {
140
+ kind: "ok";
141
+ ran: string[];
142
+ gaps: Check.Gap[];
143
+ } | {
144
+ kind: "incomplete";
145
+ ran: string[];
146
+ skipped: string[];
147
+ gaps: Check.Gap[];
148
+ } | {
149
+ kind: "failed";
150
+ stage: Tools.Stage;
151
+ total: number;
152
+ findings: Finding[];
153
+ gaps: Check.Gap[];
154
+ };
155
+ }
156
+ /**
157
+ * The command, without the process: `argv` is what follows the program name, and `cwd` is
158
+ * the folder a relative root starts from. Exit 0 is done, 1 is a finding, 2 is a call, a
159
+ * config or a tool the command cannot use.
160
+ */
161
+ export declare function main(argv: readonly string[], cwd: string): Main.Result;
162
+ //#endregion
163
+ export type { Check, Errors, Main };
package/dist/index.mjs ADDED
@@ -0,0 +1,2 @@
1
+ import { n as check, r as isError, t as main } from "./main-DQK2xJ_R.mjs";
2
+ export { check, isError, main };