@autotelic/jig-cli 0.0.0-stage → 0.1.1

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 (81) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +169 -2
  3. package/bin/jig.js +23 -0
  4. package/dist/baseline.d.ts +8 -0
  5. package/dist/baseline.d.ts.map +1 -0
  6. package/dist/baseline.js +30 -0
  7. package/dist/baseline.js.map +1 -0
  8. package/dist/cli.d.ts +2 -0
  9. package/dist/cli.d.ts.map +1 -0
  10. package/dist/cli.js +342 -0
  11. package/dist/cli.js.map +1 -0
  12. package/dist/commands.d.ts +50 -0
  13. package/dist/commands.d.ts.map +1 -0
  14. package/dist/commands.js +145 -0
  15. package/dist/commands.js.map +1 -0
  16. package/dist/config.d.ts +32 -0
  17. package/dist/config.d.ts.map +1 -0
  18. package/dist/config.js +59 -0
  19. package/dist/config.js.map +1 -0
  20. package/dist/engines.d.ts +85 -0
  21. package/dist/engines.d.ts.map +1 -0
  22. package/dist/engines.js +575 -0
  23. package/dist/engines.js.map +1 -0
  24. package/dist/exec.d.ts +16 -0
  25. package/dist/exec.d.ts.map +1 -0
  26. package/dist/exec.js +13 -0
  27. package/dist/exec.js.map +1 -0
  28. package/dist/gate.d.ts +46 -0
  29. package/dist/gate.d.ts.map +1 -0
  30. package/dist/gate.js +82 -0
  31. package/dist/gate.js.map +1 -0
  32. package/dist/git.d.ts +5 -0
  33. package/dist/git.d.ts.map +1 -0
  34. package/dist/git.js +39 -0
  35. package/dist/git.js.map +1 -0
  36. package/dist/gitattributes.d.ts +27 -0
  37. package/dist/gitattributes.d.ts.map +1 -0
  38. package/dist/gitattributes.js +63 -0
  39. package/dist/gitattributes.js.map +1 -0
  40. package/dist/index.d.ts +12 -0
  41. package/dist/index.d.ts.map +1 -0
  42. package/dist/index.js +12 -0
  43. package/dist/index.js.map +1 -0
  44. package/dist/init.d.ts +163 -0
  45. package/dist/init.d.ts.map +1 -0
  46. package/dist/init.js +1855 -0
  47. package/dist/init.js.map +1 -0
  48. package/dist/menu.d.ts +82 -0
  49. package/dist/menu.d.ts.map +1 -0
  50. package/dist/menu.js +388 -0
  51. package/dist/menu.js.map +1 -0
  52. package/dist/opencode.d.ts +66 -0
  53. package/dist/opencode.d.ts.map +1 -0
  54. package/dist/opencode.js +392 -0
  55. package/dist/opencode.js.map +1 -0
  56. package/dist/package-json.d.ts +13 -0
  57. package/dist/package-json.d.ts.map +1 -0
  58. package/dist/package-json.js +33 -0
  59. package/dist/package-json.js.map +1 -0
  60. package/dist/projections.d.ts +140 -0
  61. package/dist/projections.d.ts.map +1 -0
  62. package/dist/projections.js +186 -0
  63. package/dist/projections.js.map +1 -0
  64. package/dist/render.d.ts +21 -0
  65. package/dist/render.d.ts.map +1 -0
  66. package/dist/render.js +131 -0
  67. package/dist/render.js.map +1 -0
  68. package/dist/room.d.ts +16 -0
  69. package/dist/room.d.ts.map +1 -0
  70. package/dist/room.js +56 -0
  71. package/dist/room.js.map +1 -0
  72. package/dist/run.d.ts +10 -0
  73. package/dist/run.d.ts.map +1 -0
  74. package/dist/run.js +18 -0
  75. package/dist/run.js.map +1 -0
  76. package/extensions/jig.ts +465 -0
  77. package/package.json +78 -3
  78. package/skills/feedback-loop/SKILL.md +14 -0
  79. package/skills/intercom-setup/SKILL.md +20 -0
  80. package/skills/project-run/SKILL.md +18 -0
  81. package/skills/room/SKILL.md +17 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 autotelic
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,170 @@
1
- # Temporary Holding Version
1
+ # @autotelic/jig-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 harness.** The command is `jig`; the package is `jig-cli` only because `jig` was
4
+ already taken (an unrelated sibling repo, and the npm name). It owns no analysis. It runs the other engines, merges their output
5
+ into one report, and holds the ratchet.
6
+
7
+ A jig is the fixture that holds a workpiece while several tools work on it: it does not
8
+ cut, it holds the piece so the cuts line up. That is the whole job here — run `plumb`,
9
+ `joggle`, `cutlist`, and whatever else the repo declares, collect their findings into
10
+ one stream, and fail a run only on what is genuinely new.
11
+
12
+ ## It shells out; it does not link
13
+
14
+ `jig` depends on `@autotelic/protocol` and nothing else in this workspace. It drives
15
+ `oxlint` (which carries `plumb`), `joggle`, and `cutlist` **as processes**. That is
16
+ deliberate: the cohesion of `tackle` is a shared _format_, not a shared runtime, so the
17
+ conductor must not be a fifth thing everything links against.
18
+
19
+ ## One report
20
+
21
+ Every engine already reduces to the same shape — a place, a sentence, a severity — and
22
+ oxlint decided what that looks like. `jig` reads the structured encodings and normalizes
23
+ them all:
24
+
25
+ | Engine kind | Invocation | Encoded as |
26
+ | --------------- | ---------------------------- | --------------------------------------------------- |
27
+ | `oxlint-plugin` | `oxlint --format json` | oxlint's JSON (line/column in `labels[0].span`) |
28
+ | `process` | `joggle check --format json` | a report document, or JSONL |
29
+ | `cutlist` | `cutlist build --check` | a non-zero exit becomes one `stale-catalog` finding |
30
+
31
+ `jig` asks oxlint for JSON, but it may be handed an engine it did not configure, so it also
32
+ accepts the shapes a finding is published in: **SARIF 2.1.0**, the **Code Climate / GitLab**
33
+ array (the same shape `jig` projects outward — the read/write loop closes), and **GitHub
34
+ Actions annotations**. JSONL is read too. XML (`checkstyle`, `junit`) and human text are
35
+ deliberately **not** parsed: guessing at them would be a lie dressed as coverage.
36
+
37
+ `fixtures/oxlint/` holds all ten of oxlint 1.88's output varieties, and
38
+ `src/oxlint-conformance.test.ts` proves which are read and that the rest become findings
39
+ rather than silence.
40
+
41
+ oxlint names a rule `plugin(rule)`, so the report must not repeat the engine: on engine
42
+ `plumb`, `plumb(no-raw-html-layout)` is ruleId `no-raw-html-layout`
43
+ (`plumb/no-raw-html-layout`, not `plumb/plumb(...)`), while a sub-plugin keeps its namespace
44
+ (`plumb/plumb-ui/no-raw-interactive`).
45
+
46
+ An engine that speaks none of these is **not** silently treated as clean: it produces one
47
+ `<id>/unparsed-output` info finding, because "no findings" and "not understood" must never
48
+ look the same.
49
+
50
+ The same rule runs one level up. A report distinguishes what an engine **found** from what
51
+ it **did**: an engine that replayed a cache, skipped a rule, or left candidates unjudged is
52
+ marked `replayed`, `skipped`, or `<n> candidate(s) not judged` in the census, so `0 finding(s)`
53
+ never stands in for "clean". A finding carries its judged provenance when it has one — the
54
+ entropy `move`, a `score`, and whether an engine actually judged it — and that provenance
55
+ rides out through every projection below.
56
+
57
+ ## Reading the vocabulary
58
+
59
+ `jig check` enforces the tree; `jig menu` reads the cutlist artifact without importing
60
+ cutlist. No query prints the stable shape and the files; `jig menu dialog` ranks the parts,
61
+ features, and recipes that answer a concept and returns the import and next shape. The pi
62
+ extension exposes the same command as `jig_menu`, the OpenCode plugin as `jig.menu`, and both
63
+ expose the setup prompt as `jig_onboard` / `jig.onboard` and the applying step as
64
+ `jig_init` / `jig.init`. This is
65
+ how the menu reaches an agent without turning the agent into a second renderer: cutlist writes
66
+ the artifact, jig reads it at the seam.
67
+
68
+ ## Outward projections
69
+
70
+ A finding does not leave the workspace in the report's shape; it leaves in the shape the host
71
+ ingests. Each is a pure projection of the one report, specified in
72
+ `protocol/docs/projections.md` and frozen against worked examples. The text form is the one
73
+ human renderer — the pi extension and the OpenCode plugin hand a model that same text rather
74
+ than re-rendering it.
75
+
76
+ | `--format` | Target |
77
+ | ------------- | ------------------------------------------- |
78
+ | `text` | the human report (default) |
79
+ | `json` | the report document, verbatim |
80
+ | `jsonl` | one finding per line, the streaming form |
81
+ | `github` | GitHub Actions workflow annotations |
82
+ | `sarif` | SARIF 2.1.0 for code scanning and IDEs |
83
+ | `lsp` | LSP 3.17 diagnostics (0-based), for editors |
84
+ | `codeclimate` | Code Climate / GitLab Code Quality issues |
85
+
86
+ ## The ratchet
87
+
88
+ The gate is `protocol`'s baseline: findings are accepted **by identity**, never by line.
89
+ A run fails on new identities only. `warn` repo-wide and `error` on what you touched is
90
+ the same file, not a second configuration.
91
+
92
+ ```sh
93
+ jig check # run every engine; fail on errors and new findings
94
+ jig check --format sarif # SARIF 2.1.0 for code scanning
95
+ jig check --limit 20 # the census, then the first 20 findings
96
+ jig baseline # accept the current findings into the baseline
97
+ jig engines # what is configured, and whether it is on PATH
98
+ jig menu # the cutlist stable shape and artifact files
99
+ jig menu dialog # the parts, features, and recipes that answer a concept
100
+ jig init # inspect the repo, then write the harness it can run
101
+ jig init --gate all # the same, enforcing every finding from the first run
102
+ jig init --print # the same plan and agent prompt, writing nothing
103
+ jig init --hooks # .git/hooks/pre-commit, running the scoped gate
104
+ jig init # also writes .agents/skills: room, intercom-setup, feedback-loop, project-run
105
+ jig onboard # just the setup prompt for an agent
106
+ jig onboard --gate all # the prompt, planning a repo-wide gate
107
+ ```
108
+
109
+ From this workspace, `pnpm install` links the package into the root `.bin`, so
110
+ `node_modules/.bin/jig` is the built CLI; `pnpm jig` runs the source instead.
111
+
112
+ ## `jig init` reads before it writes
113
+
114
+ A scaffold that writes the same four files everywhere is a template, not an
115
+ onboarding. `init` inspects the repository first:
116
+
117
+ - the package manager, from `packageManager` or the lockfile;
118
+ - the oxlint gate the repo already runs, preferring a script that names a config
119
+ and a strict name (`lint:errors` over a broad advisory `lint`);
120
+ - whether that config actually loads `@autotelic/plumb`, so the `plumb` engine
121
+ is not a misnamed oxlint;
122
+ - whether `joggle` and `cutlist` are installed, and whether the repo has a
123
+ tsconfig or a `cutlist.config.json`;
124
+ - the agent docs already present, which are left untouched.
125
+
126
+ It enables only engines that can run, writes a starter `joggle.config.json` with
127
+ `unavailable: "count"` when joggle is enabled, and defaults the gate to
128
+ `touched-files`: existing debt is reported, not enforced, until someone touches
129
+ it. `--gate all` opts into the repo-wide ratchet. The generated `JIG.md` and
130
+ `ONBOARD.md` are specific to the profile, and the summary names what was kept,
131
+ what was written, and the next two commands.
132
+
133
+ `ONBOARD.md` is one paste-able prompt, not a reference: it opens with the global
134
+ install of the CLI (the checkout when this tree builds jig, npm otherwise, and
135
+ the manager's own verb), reads the config it just wrote, installs what the census
136
+ says is missing, runs `init`, wires the agent host (`pi install … --local`; for OpenCode, a `"plugin"` array entry
137
+ on opencode2 or a file in `.opencode/plugins/` on opencode 1.x — 1.x reads files, not the array)
138
+ and, in a repo that runs one, plans the room. `JIG.md` stays the reference; the prompt is the door.
139
+
140
+ `touched-files` is the adoption default, but it is the wrong gate for validating a
141
+ clean checkout: the working-tree diff is empty, so the touched set is empty, and a
142
+ run can exit 0 while the report lists findings. For a first run, a workshop, or CI
143
+ on a clean PR checkout, pass `--gate all` — or `gate: "all"` to `jig_onboard` /
144
+ `jig.onboard` and `jig_init` / `jig.init`. The plan's next command carries the gate
145
+ it chose, so the applied config matches what was approved.
146
+
147
+ `jig init --print` and `jig onboard` are the agent door: they run the same
148
+ inspection but write nothing, and print that same prompt with the plan's engines,
149
+ notes, and stop-and-ask points. `--format json` returns the same plan as data,
150
+ and `--gate` / `--force` choose the plan's gate and whether existing files would
151
+ be rewritten. The pi tool `jig_onboard` and the OpenCode tool `jig.onboard` are
152
+ the same command, and `jig_init` / `jig.init` apply the plan after a human
153
+ approves it — with the same `gate` and `force` options.
154
+
155
+ Cutlist is opt-in because its config is the repository's vocabulary, not a
156
+ generic default. When the tree looks like a UI, `init` says so and nothing more.
157
+ `jig init --cutlist` drafts `cutlist.config.json` from the detected roots
158
+ (components, routes, tailwind/theme source, tsconfig path aliases), then asks the
159
+ operator to review it, run `cutlist build`, commit the catalog, and re-run
160
+ `init --force` to enable the engine. A draft is never enabled before someone has
161
+ looked at the vocabulary it inferred.
162
+
163
+ Re-running is safe. It keeps existing files; `--force` rewrites the config and
164
+ the two docs, but never the accepted baseline.
165
+
166
+ ## Where it sits
167
+
168
+ `cutlist` **produces** the vocabulary; `plumb` and `joggle` **consume** it; `jig` runs
169
+ all three and keeps the ledger. It is also the surface pi and OpenCode call, so an agent
170
+ gets the same findings a human's terminal does.
package/bin/jig.js ADDED
@@ -0,0 +1,23 @@
1
+ #!/usr/bin/env node
2
+ // The installed entry point. It runs the build, never the source: Node refuses to strip
3
+ // types for files under node_modules, which is where this file lands once the package is
4
+ // installed. `pnpm jig` runs the source via the development condition.
5
+ //
6
+ // A linked checkout that was never built is the one case the build is absent. Name the
7
+ // command that fixes it instead of throwing ERR_MODULE_NOT_FOUND from the import below --
8
+ // otherwise an adopter's first five minutes go on reading that stack.
9
+ import { existsSync } from "node:fs"
10
+ import { dirname, join } from "node:path"
11
+ import { fileURLToPath } from "node:url"
12
+
13
+ const root = join(dirname(fileURLToPath(import.meta.url)), "..")
14
+ const built = join(root, "dist", "cli.js")
15
+
16
+ if (!existsSync(built)) {
17
+ process.stderr.write(
18
+ "jig: " + root + " has no dist/ -- run `pnpm build` in that checkout, then try again\n",
19
+ )
20
+ process.exit(1)
21
+ }
22
+
23
+ await import(built)
@@ -0,0 +1,8 @@
1
+ import { Effect, FileSystem, Path } from "effect";
2
+ import { type Baseline } from "@autotelic/protocol";
3
+ export declare const emptyBaseline: Baseline;
4
+ /** Read the committed baseline; a missing or malformed file is an empty one. */
5
+ export declare const readBaseline: (file: string) => Effect.Effect<Baseline, never, FileSystem.FileSystem>;
6
+ /** Write the baseline, creating its directory if needed. */
7
+ export declare const writeBaseline: (file: string, baseline: Baseline) => Effect.Effect<void, never, FileSystem.FileSystem | Path.Path>;
8
+ //# sourceMappingURL=baseline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAyC,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAa1F,eAAO,MAAM,aAAa,EAAE,QAA8D,CAAA;AAE1F,gFAAgF;AAChF,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAO5F,CAAA;AAEJ,4DAA4D;AAC5D,eAAO,MAAM,aAAa,SAClB,MAAM,YACF,QAAQ,KACjB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAY3D,CAAA"}
@@ -0,0 +1,30 @@
1
+ import { Effect, FileSystem, Path } from "effect";
2
+ import { decodeBaseline, lexiconRef, parseJson } from "@autotelic/protocol";
3
+ /*
4
+ * The baseline file, in the protocol's shape.
5
+ *
6
+ * It is committed to the repository, so the ratchet is a property of the code rather
7
+ * than a cache somebody can clear. Read defensively — a corrupt baseline means "not
8
+ * accepted yet", which fails safe — and write strictly, in one exact shape.
9
+ *
10
+ * The decode is protocol's, not a schema re-spelled here: the format owns its reader, and
11
+ * two decoders would be two chances to drift.
12
+ */
13
+ export const emptyBaseline = { lexicon: lexiconRef("baseline"), identities: [] };
14
+ /** Read the committed baseline; a missing or malformed file is an empty one. */
15
+ export const readBaseline = (file) => Effect.gen(function* () {
16
+ const fs = yield* FileSystem.FileSystem;
17
+ const exists = yield* Effect.orElseSucceed(fs.exists(file), () => false);
18
+ if (!exists)
19
+ return emptyBaseline;
20
+ const text = yield* Effect.orElseSucceed(fs.readFileString(file), () => "");
21
+ return decodeBaseline(parseJson(text)) ?? emptyBaseline;
22
+ });
23
+ /** Write the baseline, creating its directory if needed. */
24
+ export const writeBaseline = (file, baseline) => Effect.gen(function* () {
25
+ const fs = yield* FileSystem.FileSystem;
26
+ const path = yield* Path.Path;
27
+ yield* Effect.orElseSucceed(fs.makeDirectory(path.dirname(file), { recursive: true }), () => undefined);
28
+ yield* Effect.orElseSucceed(fs.writeFileString(file, `${JSON.stringify(baseline, null, 2)}\n`), () => undefined);
29
+ });
30
+ //# sourceMappingURL=baseline.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAiB,MAAM,qBAAqB,CAAA;AAE1F;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAa,EAAE,OAAO,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAA;AAE1F,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAyD,EAAE,CAClG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IACxE,IAAI,CAAC,MAAM;QAAE,OAAO,aAAa,CAAA;IACjC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3E,OAAO,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,aAAa,CAAA;AACzD,CAAC,CAAC,CAAA;AAEJ,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAY,EACZ,QAAkB,EAC6C,EAAE,CACjE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAA;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAA;IAC7B,KAAK,CAAC,CAAC,MAAM,CAAC,aAAa,CACzB,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EACzD,GAAG,EAAE,CAAC,SAAS,CAChB,CAAA;IACD,KAAK,CAAC,CAAC,MAAM,CAAC,aAAa,CACzB,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAClE,GAAG,EAAE,CAAC,SAAS,CAChB,CAAA;AACH,CAAC,CAAC,CAAA"}
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,342 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { existsSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+ import { Console, Effect, FileSystem, Option, Path, Runtime } from "effect";
6
+ import { Argument, CliError, Command, Flag } from "effect/cli";
7
+ import { NodeRuntime, NodeServices } from "@effect/platform-node";
8
+ import { accept, REPORT_FORMATS } from "@autotelic/protocol";
9
+ import { emptyBaseline, readBaseline, writeBaseline } from "./baseline.js";
10
+ import { explainRule, lesson, promotion, renderLesson, renderPromotion } from "./commands.js";
11
+ import { loadConfig } from "./config.js";
12
+ import { resolveEngineCommand } from "./engines.js";
13
+ import { EXIT, gateVerdict } from "./gate.js";
14
+ import { touchedFiles } from "./git.js";
15
+ import { answerGraph, findMatches, readArtifact, renderGraphAnswer, renderMatches, renderMenuJson, renderSummary, } from "./menu.js";
16
+ import { renderCodeClimate, renderJsonl, renderLsp, renderSarif } from "./projections.js";
17
+ import { renderGithub, renderJson, renderText } from "./render.js";
18
+ import { harnessRun } from "./run.js";
19
+ import { isRoomInvocation, runRoom } from "./room.js";
20
+ import { initialise, initJson, onboardingFor, summaryFor } from "./init.js";
21
+ /**
22
+ * The version a `--version` prints.
23
+ *
24
+ * Every member of the family is `0.0.0` until it is published, so after a rebuild the number
25
+ * cannot answer "is my link current?". When jig runs from a checkout the commit is the answer,
26
+ * and it rides along as semver build metadata: `0.0.0+1a2b3c4`.
27
+ */
28
+ const versionOf = () => {
29
+ try {
30
+ const sha = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
31
+ cwd: fileURLToPath(new URL("..", import.meta.url)),
32
+ stdio: ["ignore", "pipe", "ignore"],
33
+ })
34
+ .toString()
35
+ .trim();
36
+ return sha === "" ? "0.0.0" : `0.0.0+${sha}`;
37
+ }
38
+ catch {
39
+ return "0.0.0";
40
+ }
41
+ };
42
+ /** One line through Effect's Console, newline-normalized. */
43
+ const write = (text) => Console.log(text.endsWith("\n") ? text.slice(0, -1) : text);
44
+ const cwdFlag = Flag.String("cwd").pipe(Flag.withDescription("Project root (default: the current directory)."), Flag.optional);
45
+ const configFlag = Flag.String("config").pipe(Flag.withDescription("Config file, relative to the root (default jig.config.json)."), Flag.optional);
46
+ /** Said by `jig engines` when there is no config: these rows are jig's defaults, not the repo's. */
47
+ const DEFAULTS_NOTICE = "no jig.config.json here: these are jig's defaults, not this repository's config -- run `jig init`";
48
+ /** Resolve the root and its config the same way in every command. */
49
+ const context = ({ cwd, config, }) => Effect.gen(function* () {
50
+ const path = yield* Path.Path;
51
+ const root = path.resolve(Option.getOrUndefined(cwd) ?? process.cwd());
52
+ const file = path.resolve(root, Option.getOrUndefined(config) ?? "jig.config.json");
53
+ const fs = yield* FileSystem.FileSystem;
54
+ // A default config is not this repo's config: a command that prints engines must be able
55
+ // to say so instead of presenting jig's defaults as something someone configured.
56
+ const configured = yield* Effect.orElseSucceed(fs.exists(file), () => false);
57
+ const settings = yield* loadConfig(file);
58
+ return { path, root, settings, configured };
59
+ });
60
+ const checkCommand = Command.make("check", {
61
+ cwd: cwdFlag,
62
+ config: configFlag,
63
+ format: Flag.Literals("format", REPORT_FORMATS).pipe(Flag.withDescription("How to render the report (default: the repo's `report.format`, else text)."), Flag.optional),
64
+ limit: Flag.Int("limit").pipe(Flag.withDescription("Maximum findings to print in the text report. 0 prints all."), Flag.withDefault(20)),
65
+ }, (options) => Effect.gen(function* () {
66
+ const { path, root, settings } = yield* context({ cwd: options.cwd, config: options.config });
67
+ const baseline = yield* readBaseline(path.resolve(root, settings.gate.baseline));
68
+ const run = yield* harnessRun(root, settings, baseline);
69
+ // The accepted identities, so a projection can say novel from known. An empty
70
+ // baseline still counts as "given": everything is novel until it is accepted.
71
+ const known = new Set(baseline.identities);
72
+ const limit = options.limit;
73
+ // The flag wins, then the repo's configured default, then the human form.
74
+ const format = Option.getOrUndefined(options.format) ?? settings.report?.format ?? "text";
75
+ // The gate reads the scope git reports; when git cannot say, it widens to everything
76
+ // rather than narrowing to nothing — an empty scope would pass every finding.
77
+ const touched = settings.gate.mode === "touched-files" ? yield* touchedFiles(root) : undefined;
78
+ const verdict = gateVerdict(run, {
79
+ mode: touched === undefined ? "all" : "touched-files",
80
+ failOn: settings.gate.failOn ?? "any-new",
81
+ maxWarnings: settings.report?.maxWarnings ?? -1,
82
+ touched: touched ?? new Set(),
83
+ advisory: new Set(settings.engines.filter((engine) => engine.advisory === true).map((engine) => engine.id)),
84
+ });
85
+ switch (format) {
86
+ case "json":
87
+ yield* write(renderJson(run.report));
88
+ break;
89
+ case "jsonl":
90
+ yield* write(renderJsonl(run.report));
91
+ break;
92
+ case "github":
93
+ yield* write(renderGithub(run.report));
94
+ break;
95
+ case "sarif":
96
+ yield* write(renderSarif(run.report, known));
97
+ break;
98
+ case "lsp":
99
+ yield* write(renderLsp(run.report));
100
+ break;
101
+ case "codeclimate":
102
+ yield* write(renderCodeClimate(run.report));
103
+ break;
104
+ default:
105
+ yield* write(renderText(run, { limit, gate: verdict }));
106
+ break;
107
+ }
108
+ if (verdict.exitCode !== EXIT.clean) {
109
+ yield* Effect.sync(() => {
110
+ process.exitCode = verdict.exitCode;
111
+ });
112
+ }
113
+ })).pipe(Command.withDescription("Run every engine and fail on errors and new findings."), Command.withShortDescription("Run every engine; hold the ratchet."), Command.withExamples([
114
+ { command: "jig check", description: "Run everything and print the census." },
115
+ { command: "jig check --format github", description: "Emit GitHub Actions annotations." },
116
+ { command: "jig check --format sarif", description: "Emit SARIF 2.1.0 for code scanning." },
117
+ { command: "jig check --limit 20", description: "Print the census and the first 20 findings." },
118
+ ]));
119
+ const baselineCommand = Command.make("baseline", { cwd: cwdFlag, config: configFlag }, (options) => Effect.gen(function* () {
120
+ const { path, root, settings } = yield* context({ cwd: options.cwd, config: options.config });
121
+ const run = yield* harnessRun(root, settings, emptyBaseline);
122
+ const baseline = accept(run.report.diagnostics);
123
+ yield* writeBaseline(path.resolve(root, settings.gate.baseline), baseline);
124
+ yield* write(`jig: accepted ${baseline.identities.length} finding(s) into ${settings.gate.baseline}`);
125
+ })).pipe(Command.withDescription("Accept the current findings into the baseline."), Command.withShortDescription("Accept the current findings."));
126
+ const enginesCommand = Command.make("engines", { cwd: cwdFlag, config: configFlag }, (options) => Effect.gen(function* () {
127
+ const { root, settings, configured } = yield* context({
128
+ cwd: options.cwd,
129
+ config: options.config,
130
+ });
131
+ const onPath = (name) => (process.env.PATH ?? "").split(":").some((dir) => dir !== "" && existsSync(join(dir, name)));
132
+ const header = "engine kind command source";
133
+ const lines = configured ? [header] : [header, DEFAULTS_NOTICE];
134
+ for (const engine of settings.engines) {
135
+ const command = engine.command ?? engine.id;
136
+ const enabled = (engine.enabled === false ? " (disabled)" : "") +
137
+ (engine.advisory === true ? " (advisory)" : "");
138
+ // The column reports where the run WILL draw the command from, so it asks the
139
+ // resolver rather than scanning PATH on its own: project install, PATH, or neither.
140
+ const resolved = resolveEngineCommand({ root, command });
141
+ const source = resolved !== command ? "project" : onPath(command) ? "PATH" : "no";
142
+ lines.push(`${engine.id.padEnd(19)} ${engine.kind.padEnd(15)} ${command.padEnd(14)} ${source}${enabled}`);
143
+ }
144
+ if (lines.some((line) => line.endsWith(" no"))) {
145
+ // `no` is the whole local-dev story on a fresh clone, and it used to say nothing about
146
+ // what to do: an unpublished member of the family is linked from a checkout, not fetched.
147
+ lines.push("", "`no` means the command is neither in this project nor on PATH. Members of the family", "that are not published yet are linked from a checkout and built there:", " pnpm add -D -w link:/path/to/checkout # in this repo", " pnpm build # in the checkout, and again after a change");
148
+ }
149
+ yield* write(lines.join("\n"));
150
+ })).pipe(Command.withDescription("List configured engines and where their command resolves from."), Command.withShortDescription("List configured engines."));
151
+ const initCommand = Command.make("init", {
152
+ cwd: cwdFlag,
153
+ gate: Flag.Literals("gate", ["touched-files", "all"]).pipe(Flag.withDescription("What fails a run: only the change in front of you (default), or every finding in the repo."), Flag.optional),
154
+ force: Flag.Boolean("force").pipe(Flag.withDescription("Rewrite jig.config.json, JIG.md and ONBOARD.md; never the baseline."), Flag.withDefault(false)),
155
+ cutlist: Flag.Boolean("cutlist").pipe(Flag.withDescription("Draft cutlist.config.json from detected UI roots. Review it, run `cutlist build`, then re-run init --force to enable the engine."), Flag.withDefault(false)),
156
+ print: Flag.Boolean("print").pipe(Flag.withDescription("Print the plan and the agent prompt without writing anything."), Flag.withDefault(false)),
157
+ hooks: Flag.Boolean("hooks").pipe(Flag.withDescription("Write .git/hooks/pre-commit running the scoped gate. It steps aside loudly when the CLI is not on the machine, and never replaces a hook that is not jig's."), Flag.withDefault(false)),
158
+ unignore: Flag.Boolean("unignore").pipe(Flag.withDescription("Remove the .gitignore lines that hide this harness. A pattern that hides one is reported, never edited."), Flag.withDefault(false)),
159
+ format: Flag.Literals("format", ["text", "json"]).pipe(Flag.withDescription("How to render the plan. JSON is for a host that reads it."), Flag.withDefault("text")),
160
+ }, (options) => Effect.gen(function* () {
161
+ const path = yield* Path.Path;
162
+ const root = path.resolve(Option.getOrUndefined(options.cwd) ?? process.cwd());
163
+ const result = yield* initialise(root, {
164
+ force: options.force,
165
+ gateMode: Option.getOrUndefined(options.gate),
166
+ cutlist: options.cutlist,
167
+ dryRun: options.print,
168
+ hooks: options.hooks,
169
+ unignore: options.unignore,
170
+ });
171
+ const prompt = options.print ? onboardingFor(result.profile) : undefined;
172
+ if (options.format === "json") {
173
+ yield* write(initJson(result, prompt));
174
+ return;
175
+ }
176
+ yield* write(summaryFor(result));
177
+ if (prompt !== undefined) {
178
+ yield* write(`\n--- agent prompt begins ---\n${prompt}\n--- agent prompt ends ---`);
179
+ }
180
+ })).pipe(Command.withDescription("Inspect the repository and write the harness it should have: the engines it can run, a touched-files gate, a baseline, the cookbook, and the agent prompt."), Command.withShortDescription("Scaffold the harness for this repo."));
181
+ const onboardCommand = Command.make("onboard", {
182
+ cwd: cwdFlag,
183
+ gate: Flag.Literals("gate", ["touched-files", "all"]).pipe(Flag.withDescription("What the plan should gate on: only the change in front of you (default), or every finding in the repo."), Flag.optional),
184
+ force: Flag.Boolean("force").pipe(Flag.withDescription("Plan a rewrite of jig.config.json, JIG.md and ONBOARD.md; never the baseline."), Flag.withDefault(false)),
185
+ format: Flag.Literals("format", ["text", "json"]).pipe(Flag.withDescription("The prompt alone, or the prompt with the plan as JSON."), Flag.withDefault("text")),
186
+ }, (options) => Effect.gen(function* () {
187
+ const path = yield* Path.Path;
188
+ const root = path.resolve(Option.getOrUndefined(options.cwd) ?? process.cwd());
189
+ const result = yield* initialise(root, {
190
+ dryRun: true,
191
+ force: options.force,
192
+ gateMode: Option.getOrUndefined(options.gate),
193
+ });
194
+ const prompt = onboardingFor(result.profile);
195
+ yield* write(options.format === "json" ? initJson(result, prompt) : prompt);
196
+ })).pipe(Command.withDescription("Print the agent prompt that sets jig up here, without writing anything. The prompt names the first command and where to stop and ask."), Command.withShortDescription("Print the setup prompt for an agent."));
197
+ const writeFlag = Flag.Boolean("write").pipe(Flag.withDescription("Apply the change instead of printing it."), Flag.withDefault(false));
198
+ const explainCommand = Command.make("explain", { rule: Argument.String("rule"), cwd: cwdFlag, config: configFlag }, (options) => Effect.gen(function* () {
199
+ const { path, root, settings } = yield* context({ cwd: options.cwd, config: options.config });
200
+ const baseline = yield* readBaseline(path.resolve(root, settings.gate.baseline));
201
+ const run = yield* harnessRun(root, settings, baseline);
202
+ const configured = settings.engines.map((engine) => engine.id);
203
+ yield* write(explainRule(run.report, options.rule, configured));
204
+ })).pipe(Command.withDescription("Everything jig knows about one rule in this repo, right now."), Command.withShortDescription("Explain one rule."), Command.withExamples([
205
+ {
206
+ command: "jig explain plumb/no-raw-html-layout",
207
+ description: "The rule's findings, with the fix.",
208
+ },
209
+ ]));
210
+ const promoteCommand = Command.make("promote", { cwd: cwdFlag, config: configFlag, write: writeFlag }, (options) => Effect.gen(function* () {
211
+ const { path, root, settings } = yield* context({ cwd: options.cwd, config: options.config });
212
+ const baseline = yield* readBaseline(path.resolve(root, settings.gate.baseline));
213
+ const run = yield* harnessRun(root, settings, baseline);
214
+ const plan = promotion(run.diff);
215
+ // `promote` only ever shrinks the ledger. Dropping the identities that no longer fire
216
+ // is the ratchet moving down; accepting a new one is `jig baseline`, a human's call.
217
+ if (options.write && plan.stale.length > 0) {
218
+ yield* writeBaseline(path.resolve(root, settings.gate.baseline), accept(run.diff.known));
219
+ yield* write(renderPromotion({ plan, applied: true }));
220
+ }
221
+ else {
222
+ yield* write(renderPromotion({ plan, applied: false }));
223
+ }
224
+ })).pipe(Command.withDescription("Show the ratchet's next rung: accepted findings that no longer fire. Only ever shrinks."), Command.withShortDescription("Advance the ratchet."));
225
+ const learnCommand = Command.make("learn", { cwd: cwdFlag, config: configFlag, write: writeFlag }, (options) => Effect.gen(function* () {
226
+ const { path, root, settings } = yield* context({ cwd: options.cwd, config: options.config });
227
+ const baseline = yield* readBaseline(path.resolve(root, settings.gate.baseline));
228
+ const run = yield* harnessRun(root, settings, baseline);
229
+ const text = renderLesson(lesson(settings.engines.map((engine) => engine.id), run.diff));
230
+ const name = settings.agent?.cookbook ?? "JIG.md";
231
+ if (options.write) {
232
+ const fs = yield* FileSystem.FileSystem;
233
+ yield* fs.writeFileString(path.resolve(root, name), `${text}\n`);
234
+ yield* write(`jig: wrote ${name}`);
235
+ }
236
+ else {
237
+ yield* write(text);
238
+ }
239
+ })).pipe(Command.withDescription("Write the agent cookbook, scaffolded from the rules this repo already accepts."), Command.withShortDescription("Rewrite the cookbook."));
240
+ const menuCommand = Command.make("menu", {
241
+ cwd: cwdFlag,
242
+ query: Argument.String("query").pipe(Argument.withDescription('A part, feature, or concept to find, for example "dialog" or "wizard".'), Argument.optional),
243
+ format: Flag.Literals("format", ["text", "json"]).pipe(Flag.withDescription("Human text or the same view as JSON."), Flag.withDefault("text")),
244
+ limit: Flag.Int("limit").pipe(Flag.withDescription("Maximum matches to print. Default 12."), Flag.withDefault(12)),
245
+ page: Flag.String("page").pipe(Flag.withDescription("What does this page render? A route name, id, or path."), Flag.optional),
246
+ part: Flag.String("part").pipe(Flag.withDescription("Which pages mount this part? A component name, id, or path."), Flag.optional),
247
+ similar: Flag.String("similar").pipe(Flag.withDescription("What already exists like this? A name, whether the part exists or not."), Flag.optional),
248
+ }, (options) => Effect.gen(function* () {
249
+ const path = yield* Path.Path;
250
+ const root = path.resolve(Option.getOrUndefined(options.cwd) ?? process.cwd());
251
+ const artifact = readArtifact(root);
252
+ const query = Option.getOrUndefined(options.query);
253
+ const page = Option.getOrUndefined(options.page);
254
+ const part = Option.getOrUndefined(options.part);
255
+ const similar = Option.getOrUndefined(options.similar);
256
+ const graph = [
257
+ page === undefined ? undefined : { kind: "page", ref: page },
258
+ part === undefined ? undefined : { kind: "part", ref: part },
259
+ similar === undefined ? undefined : { kind: "similar", ref: similar },
260
+ ].filter((question) => question !== undefined);
261
+ if (graph.length > 1) {
262
+ yield* write("jig menu: ask one of --page, --part, --similar");
263
+ yield* Effect.sync(() => {
264
+ process.exitCode = 1;
265
+ });
266
+ return;
267
+ }
268
+ const question = graph[0];
269
+ if (question !== undefined) {
270
+ const answer = answerGraph(artifact, question);
271
+ if (options.format === "json") {
272
+ yield* write(`${JSON.stringify({ artifact: artifact.paths, question, ...answer }, null, 2)}\n`);
273
+ }
274
+ else {
275
+ yield* write(renderGraphAnswer(answer));
276
+ }
277
+ if (!answer.ok) {
278
+ yield* Effect.sync(() => {
279
+ process.exitCode = 1;
280
+ });
281
+ }
282
+ return;
283
+ }
284
+ const missing = artifact.menu === undefined &&
285
+ artifact.patterns === undefined &&
286
+ artifact.recipes === undefined;
287
+ if (missing) {
288
+ yield* write(renderSummary(artifact, options.limit));
289
+ yield* Effect.sync(() => {
290
+ process.exitCode = 1;
291
+ });
292
+ return;
293
+ }
294
+ const matches = findMatches(artifact, query, options.limit);
295
+ if (options.format === "json") {
296
+ yield* write(renderMenuJson(artifact, matches, query ?? ""));
297
+ return;
298
+ }
299
+ yield* write(query === undefined
300
+ ? renderSummary(artifact, options.limit)
301
+ : renderMatches(artifact, matches, query));
302
+ })).pipe(Command.withDescription("Read the cutlist artifact: the stable shape, the parts and recipes that answer a query, or the graph questions — what a page renders, where a part appears, what a name resembles. This is the agent door to the menu; it does not re-analyse the tree."), Command.withShortDescription("Find a part in the cutlist menu."), Command.withExamples([
303
+ { command: "jig menu", description: "Show the stable shape and the artifact files." },
304
+ {
305
+ command: "jig menu dialog",
306
+ description: "Find parts, features, and recipes matching a word.",
307
+ },
308
+ {
309
+ command: "jig menu --page dashboard_.$id",
310
+ description: "What a route renders today, direct and through its children.",
311
+ },
312
+ {
313
+ command: "jig menu --similar TablePanel",
314
+ description: "What already exists before a new part is invented.",
315
+ },
316
+ { command: "jig menu wizard --format json", description: "Return the same view for a tool." },
317
+ ]));
318
+ // `jig room` is a passthrough, not a subcommand: the room owns its flags and its help, and
319
+ // jig must not learn them. The seam stays a command line, like the engines.
320
+ if (isRoomInvocation(process.argv)) {
321
+ process.exit(runRoom(process.argv));
322
+ }
323
+ const cli = Command.make("jig").pipe(Command.withDescription("The harness: run every conformance engine in one pass, merge them into one report, and hold the ratchet. `jig room` opens the project room."), Command.withSubcommands([
324
+ checkCommand,
325
+ baselineCommand,
326
+ enginesCommand,
327
+ menuCommand,
328
+ initCommand,
329
+ onboardCommand,
330
+ explainCommand,
331
+ promoteCommand,
332
+ learnCommand,
333
+ ]));
334
+ // The run's own codes (0/1/3) are set on `process.exitCode` inside the handlers, and survive
335
+ // the clean teardown the runner uses for them. A parse error instead FAILS the effect with a
336
+ // `CliError`, which the runner would exit 1 for; catching it here maps it to the contract's 2,
337
+ // while `--help` — a request, not a mistake — stays 0.
338
+ const program = Command.run(cli, { version: versionOf() }).pipe(Effect.catchIf(CliError.isCliError, (error) => Effect.sync(() => {
339
+ process.exitCode = Runtime.getErrorExitCode(error) === 0 ? EXIT.clean : EXIT.usage;
340
+ })), Effect.provide(NodeServices.layer));
341
+ NodeRuntime.runMain(program, { disableErrorReporting: true });
342
+ //# sourceMappingURL=cli.js.map