yadflow 4.7.0 → 4.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +116 -0
- package/README.md +43 -4
- package/bin/commands.mjs +5 -1
- package/bin/yad.mjs +169 -22
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +388 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/build.mjs +1 -1
- package/cli/ci-check.mjs +492 -0
- package/cli/docs.mjs +1 -1
- package/cli/doctor.mjs +148 -7
- package/cli/epic-state.mjs +3 -3
- package/cli/errors.mjs +1 -0
- package/cli/guide.mjs +549 -0
- package/cli/hook.mjs +32 -3
- package/cli/lib.mjs +46 -0
- package/cli/lifecycle/defaults/2.json +124 -0
- package/cli/lifecycle/lifecycle.schema.json +5 -2
- package/cli/lifecycle.mjs +16 -3
- package/cli/machine.mjs +141 -0
- package/cli/manifest.mjs +75 -0
- package/cli/marked-block.mjs +48 -0
- package/cli/members.mjs +19 -5
- package/cli/migrate.mjs +17 -19
- package/cli/next.mjs +1 -1
- package/cli/openpr.mjs +46 -6
- package/cli/plan.mjs +326 -22
- package/cli/preview.mjs +253 -0
- package/cli/protection.mjs +50 -0
- package/cli/reconcile.mjs +187 -26
- package/cli/repo.mjs +64 -3
- package/cli/report.mjs +62 -14
- package/cli/review.mjs +4 -0
- package/cli/setup.mjs +244 -25
- package/cli/signing.mjs +377 -0
- package/cli/story-frames.mjs +296 -0
- package/cli/test-agents-file.mjs +993 -0
- package/cli/test-ci-check.mjs +616 -0
- package/cli/test-guide.mjs +1267 -0
- package/cli/test-machine.mjs +140 -0
- package/cli/test-node.mjs +129 -0
- package/cli/test-preview.mjs +511 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/test-story-frames.mjs +339 -0
- package/cli/toolbox.mjs +35 -1
- package/cli/update-commit.mjs +313 -11
- package/cli/workspace.mjs +37 -12
- package/package.json +6 -4
- package/skills/sdlc/config.yaml +4 -4
- package/skills/sdlc/module-help.csv +1 -0
- package/skills/yad-change/SKILL.md +3 -2
- package/skills/yad-checks/SKILL.md +29 -9
- package/skills/yad-checks/references/check-gates.md +9 -4
- package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
- package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
- package/skills/yad-commit/SKILL.md +4 -3
- package/skills/yad-connect-design/SKILL.md +7 -4
- package/skills/yad-connect-design/references/design-context.md +23 -0
- package/skills/yad-connect-design/references/design-registry.md +3 -3
- package/skills/yad-connect-repos/SKILL.md +13 -3
- package/skills/yad-connect-repos/references/code-context.md +2 -1
- package/skills/yad-connect-repos/references/repos-registry.md +2 -1
- package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
- package/skills/yad-engineer-review/SKILL.md +25 -7
- package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
- package/skills/yad-epic/SKILL.md +2 -1
- package/skills/yad-epic/references/state-schema.md +7 -1
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-implement/SKILL.md +14 -0
- package/skills/yad-open-pr/SKILL.md +5 -2
- package/skills/yad-pair-review/SKILL.md +19 -5
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
- package/skills/yad-product-bridge/SKILL.md +32 -13
- package/skills/yad-product-bridge/references/bridge.md +6 -3
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
- package/skills/yad-report/SKILL.md +15 -0
- package/skills/yad-review-companion/SKILL.md +9 -4
- package/skills/yad-review-gate/SKILL.md +13 -9
- package/skills/yad-review-gate/references/gating.md +1 -1
- package/skills/yad-run/SKILL.md +10 -6
- package/skills/yad-run/references/run-loop.md +2 -1
- package/skills/yad-spec/SKILL.md +21 -0
- package/skills/yad-stories/SKILL.md +22 -0
- package/skills/yad-stories/references/story-schema.md +1 -0
- package/skills/yad-sync-repos/SKILL.md +2 -1
- package/skills/yad-ui/SKILL.md +7 -2
package/cli/lib.mjs
CHANGED
|
@@ -219,6 +219,52 @@ export function copyDir(src, dest) {
|
|
|
219
219
|
fs.rmSync(dest, { recursive: true, force: true });
|
|
220
220
|
fs.cpSync(src, dest, { recursive: true });
|
|
221
221
|
}
|
|
222
|
+
// E161 — which Node line this is. Below 18 yadflow does not run (YAD-ENV-003). 18 and 20 are end of life:
|
|
223
|
+
// yadflow 4 still runs on them, with a warning (YAD-ENV-004), and yadflow 5 needs 22. 22 and later are ok.
|
|
224
|
+
export const NODE_FLOOR = 18;
|
|
225
|
+
export const NODE_SUPPORTED = 22;
|
|
226
|
+
export function nodeSupport(version = process.versions.node) {
|
|
227
|
+
const major = Number(String(version).replace(/^v/, '').split('.')[0]);
|
|
228
|
+
return !(major >= NODE_FLOOR) ? 'unsupported' : major < NODE_SUPPORTED ? 'end-of-life' : 'ok';
|
|
229
|
+
}
|
|
230
|
+
export const nodeEndOfLife = (version) => `Node ${version} is end of life and gets no security fixes. yadflow 4 still runs on it; yadflow 5 will need Node ${NODE_SUPPORTED} or newer. Upgrade: https://nodejs.org`;
|
|
231
|
+
|
|
232
|
+
// Remove a file or a folder tree, read-only folders too: each folder is opened (its owner may write) first,
|
|
233
|
+
// since a folder whose mode forbids writing keeps its files from `rmSync`. A path that is not there is fine.
|
|
234
|
+
export function rmTree(p) {
|
|
235
|
+
let st;
|
|
236
|
+
try { st = fs.lstatSync(p); } catch { return; }
|
|
237
|
+
if (st.isDirectory()) {
|
|
238
|
+
try { fs.chmodSync(p, (st.mode & 0o7777) | 0o700); } catch { /* not ours to open: rmSync says why */ }
|
|
239
|
+
for (const name of fs.readdirSync(p)) rmTree(path.join(p, name));
|
|
240
|
+
}
|
|
241
|
+
fs.rmSync(p, { recursive: true, force: true });
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
// Copy a folder into another, joining folders and never replacing a file: a file that is already there is
|
|
245
|
+
// an EEXIST error. `fs.cpSync(…, { errorOnExist: true, force: false })` did this up to Node 22; Node 24
|
|
246
|
+
// refuses a folder that exists too, even an empty one, so a move into a folder with the user's own files
|
|
247
|
+
// failed. A new folder keeps its source's permissions, and a file its mode (copyFileSync). A link is copied
|
|
248
|
+
// as the link it is (cpSync made a relative link absolute, into the source the move then deletes).
|
|
249
|
+
// Anything else (a named pipe, a device) is refused, as cpSync did. `created`, when given, collects every
|
|
250
|
+
// path this copy made, so a failed move removes those and nothing that was there before.
|
|
251
|
+
export function cpMerge(src, dest, created = null) {
|
|
252
|
+
const st = fs.lstatSync(src);
|
|
253
|
+
let there = true;
|
|
254
|
+
try { fs.lstatSync(dest); } catch { there = false; }
|
|
255
|
+
if (st.isDirectory()) {
|
|
256
|
+
// The source's mode is set after the folder is filled: a read-only folder must still take its files.
|
|
257
|
+
if (!there) { fs.mkdirSync(dest); created?.push(dest); }
|
|
258
|
+
for (const name of fs.readdirSync(src)) cpMerge(path.join(src, name), path.join(dest, name), created);
|
|
259
|
+
if (!there) fs.chmodSync(dest, st.mode & 0o7777);
|
|
260
|
+
return;
|
|
261
|
+
}
|
|
262
|
+
if (there) throw Object.assign(new Error(`EEXIST: ${dest} already exists, and a copy never replaces a file`), { code: 'EEXIST' });
|
|
263
|
+
if (st.isSymbolicLink()) fs.symlinkSync(fs.readlinkSync(src), dest);
|
|
264
|
+
else if (st.isFile()) fs.copyFileSync(src, dest, fs.constants.COPYFILE_EXCL);
|
|
265
|
+
else throw Object.assign(new Error(`${src} is not a file, a folder or a link, so it is not copied`), { code: 'EINVAL' });
|
|
266
|
+
created?.push(dest);
|
|
267
|
+
}
|
|
222
268
|
// Recursive list of file paths relative to `dir`.
|
|
223
269
|
export function listFiles(dir, base = dir) {
|
|
224
270
|
if (!fs.existsSync(dir)) return [];
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 10,
|
|
3
|
+
"extends": "yadflow-default@2",
|
|
4
|
+
"phases": [
|
|
5
|
+
{ "id": "foundation", "name": "Foundation", "level": "product", "runs": "once", "built": true,
|
|
6
|
+
"description": "The Product level, written once: what the product is for and how it will be built. Optional, but every epic reads it when it exists." },
|
|
7
|
+
{ "id": "discover", "name": "Discover", "part": "Shape", "level": "feature", "runs": "once", "built": true,
|
|
8
|
+
"description": "Say what the change is and why: the optional analysis, then the epic." },
|
|
9
|
+
{ "id": "design", "name": "Design", "part": "Shape", "level": "feature", "runs": "once", "built": true,
|
|
10
|
+
"description": "Decide how it is built: the architecture and its locked contract, and the user interface when there is one." },
|
|
11
|
+
{ "id": "plan", "name": "Plan", "part": "Shape", "level": "feature", "runs": "once", "built": true,
|
|
12
|
+
"description": "Split the work into stories, and write the test cases that prove them." },
|
|
13
|
+
{ "id": "build", "name": "Build", "part": "Build", "level": "feature", "runs": "loop", "over": ["story", "repo"], "built": true,
|
|
14
|
+
"description": "Each story is built in each repo it names, one lane at a time: spec, tasks, implement and checks by the agent, then a person's engineer review and merge." },
|
|
15
|
+
{ "id": "release", "name": "Release", "part": "Run", "level": "feature", "runs": "loop", "over": ["release"], "built": false,
|
|
16
|
+
"description": "Not built yet." },
|
|
17
|
+
{ "id": "operate", "name": "Operate", "part": "Run", "level": "feature", "runs": "once", "built": false,
|
|
18
|
+
"description": "Not built yet." }
|
|
19
|
+
],
|
|
20
|
+
"steps": [
|
|
21
|
+
{ "id": "foundation", "name": "Foundation", "phase": "foundation", "kind": "author",
|
|
22
|
+
"description": "Write the Product's foundation once: its purpose, scope, first release (MVP), roadmap, stack and repos, plus its market and risks if wanted. Every epic builds on it.", "driver": "pair",
|
|
23
|
+
"artifact": { "type": "set", "path": "foundation/",
|
|
24
|
+
"files": ["purpose.md", "market.md", "scope.md", "mvp.md", "roadmap.md", "stack.md", "repos.md", "risks.md"],
|
|
25
|
+
"optional": ["market.md", "risks.md"] },
|
|
26
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
27
|
+
"description": "A person reviews the foundation and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-discovery"], "behaviours": ["product-level"],
|
|
28
|
+
"extraPaths": [], "inputs": [], "replaces": "discovery",
|
|
29
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "foundation" } },
|
|
30
|
+
{ "id": "discovery", "name": "Discovery", "phase": "foundation", "kind": "author",
|
|
31
|
+
"description": "The old Product-level step, replaced by Foundation. Kept so a Product that still uses it can be read.", "driver": "pair",
|
|
32
|
+
"artifact": { "type": "set", "path": "discovery/",
|
|
33
|
+
"files": ["market-research.md", "competitor-analysis.md", "current-state.md", "feasibility.md", "requirements.md", "roadmap.md"],
|
|
34
|
+
"optional": [] },
|
|
35
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
36
|
+
"description": "A person reviews the discovery and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-discovery"], "behaviours": ["product-level"],
|
|
37
|
+
"extraPaths": [], "inputs": [], "retired": true,
|
|
38
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "discovery" } },
|
|
39
|
+
{ "id": "analysis", "name": "Analysis", "phase": "discover", "kind": "author",
|
|
40
|
+
"description": "Study the problem before the epic: who it is for, the options, and the evidence. The analysis-first and spike routes start here.", "driver": "pair",
|
|
41
|
+
"artifact": { "type": "file", "path": "analysis.md" },
|
|
42
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
43
|
+
"description": "A person reviews the analysis and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-analysis"], "behaviours": [],
|
|
44
|
+
"extraPaths": [], "inputs": [],
|
|
45
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "analysis" } },
|
|
46
|
+
{ "id": "epic", "name": "Epic", "phase": "discover", "kind": "author",
|
|
47
|
+
"description": "Describe the change: the problem, the goal, what is in and out of scope, and how success is measured. It sets the work-item type the rest of the chain follows.", "driver": "pair",
|
|
48
|
+
"artifact": { "type": "file", "path": "epic.md" },
|
|
49
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
50
|
+
"description": "A person reviews the epic and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-epic"], "behaviours": ["work-item-source"],
|
|
51
|
+
"extraPaths": [], "inputs": ["analysis"],
|
|
52
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "epic" } },
|
|
53
|
+
{ "id": "architecture", "name": "Architecture", "phase": "design", "kind": "author",
|
|
54
|
+
"description": "Decide how the change is built across the repos, and lock the contract between them. A later change to the locked contract needs its own review.", "driver": "pair",
|
|
55
|
+
"artifact": { "type": "file", "path": "architecture.md" },
|
|
56
|
+
"optional": false, "gate": { "riskTags": ["contract"], "advance": "human",
|
|
57
|
+
"description": "A person reviews the architecture and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-architecture"], "behaviours": ["locks-contract"],
|
|
58
|
+
"extraPaths": ["contract.md", ".sdlc/contract-lock.json"], "inputs": ["epic"],
|
|
59
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "architecture" } },
|
|
60
|
+
{ "id": "ui-design", "name": "UI design", "phase": "design", "kind": "author",
|
|
61
|
+
"description": "Design the screens and flows, and link the design files. Optional on the routes that offer it: skip it when the change has no user interface.", "driver": "pair",
|
|
62
|
+
"artifact": { "type": "file", "path": "ui-design.md" },
|
|
63
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
64
|
+
"description": "A person reviews the UI design and approves it: on its review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-ui"], "behaviours": [],
|
|
65
|
+
"extraPaths": ["DESIGN.md", ".sdlc/design-links.json"], "inputs": ["epic", "architecture"],
|
|
66
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "ui-design" } },
|
|
67
|
+
{ "id": "stories", "name": "Stories", "phase": "plan", "kind": "author",
|
|
68
|
+
"description": "Split the epic into stories, each tagged with the repos it touches. Its approval ends Shape, so Build can start.", "driver": "pair",
|
|
69
|
+
"artifact": { "type": "folder", "path": "stories/", "unit": "story" },
|
|
70
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
71
|
+
"description": "A person reviews the stories and approves them: on their review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-stories"], "behaviours": ["ends-shape"],
|
|
72
|
+
"extraPaths": [], "inputs": ["epic", "architecture", "ui-design"],
|
|
73
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "stories" } },
|
|
74
|
+
{ "id": "test-cases", "name": "Test cases", "phase": "plan", "kind": "author",
|
|
75
|
+
"description": "Write the test cases that prove the stories work. It runs beside Build, not before it.", "driver": "pair",
|
|
76
|
+
"artifact": { "type": "file", "path": "test-cases.md" },
|
|
77
|
+
"optional": false, "gate": { "riskTags": [], "advance": "human",
|
|
78
|
+
"description": "A person reviews the test cases and approves them: on their review PR/MR, then merges it, when the Product has a platform; with `yad gate approve` and `yad gate advance` when it has none (in solo mode no approval is counted, so only `yad gate advance`). The step never moves on by itself." }, "skills": ["yad-test-cases"], "behaviours": ["parallel-with-build"],
|
|
79
|
+
"extraPaths": [".sdlc/test-links.json"], "inputs": ["stories"],
|
|
80
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "test-cases" } },
|
|
81
|
+
{ "id": "spec", "name": "Spec", "phase": "build", "kind": "author",
|
|
82
|
+
"description": "For one story in one repo, write the detailed spec the code is built from.", "driver": "agent",
|
|
83
|
+
"artifact": null,
|
|
84
|
+
"optional": false, "gate": null, "skills": ["yad-spec"], "behaviours": ["spec-source"],
|
|
85
|
+
"extraPaths": [], "inputs": ["stories"],
|
|
86
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "spec" } },
|
|
87
|
+
{ "id": "tasks", "name": "Tasks", "phase": "build", "kind": "author",
|
|
88
|
+
"description": "Break the spec into small, ordered tasks, each naming the files it may touch (aim for 3 or fewer).", "driver": "agent",
|
|
89
|
+
"artifact": null,
|
|
90
|
+
"optional": false, "gate": null, "skills": ["yad-spec"], "behaviours": [],
|
|
91
|
+
"extraPaths": [], "inputs": ["spec"],
|
|
92
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "tasks" } },
|
|
93
|
+
{ "id": "implement", "name": "Implement", "phase": "build", "kind": "author",
|
|
94
|
+
"description": "Write the code and its tests for one task, on the task's branch.", "driver": "agent",
|
|
95
|
+
"artifact": null,
|
|
96
|
+
"optional": false, "gate": null, "skills": ["yad-implement"], "behaviours": ["code-change"],
|
|
97
|
+
"extraPaths": [], "inputs": ["tasks"],
|
|
98
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "implement" } },
|
|
99
|
+
{ "id": "checks", "name": "Checks", "phase": "build", "kind": "author",
|
|
100
|
+
"description": "Run the CI gates on this machine (`yad run checks`). Then the task's PR/MR is opened, so CI runs them too; `yad dial open-pr` says whether the agent asks first.", "driver": "agent",
|
|
101
|
+
"artifact": null,
|
|
102
|
+
"optional": false, "gate": null, "skills": ["yad-checks"], "behaviours": ["ci-gates"],
|
|
103
|
+
"extraPaths": [], "inputs": ["implement"],
|
|
104
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "checks" } },
|
|
105
|
+
{ "id": "engineer-review", "name": "Engineer review", "phase": "build", "kind": "review",
|
|
106
|
+
"description": "A person reviews the PR/MR, approves it and merges it. An AI first pass may help, but the merge is always a person's.", "driver": "human",
|
|
107
|
+
"artifact": null,
|
|
108
|
+
"optional": false, "gate": null, "skills": ["yad-engineer-review"], "behaviours": ["merge-gate"],
|
|
109
|
+
"extraPaths": [], "inputs": ["checks"],
|
|
110
|
+
"provider": { "id": "yadflow", "version": 1, "origin": "engineer-review" } }
|
|
111
|
+
],
|
|
112
|
+
"routes": [
|
|
113
|
+
{ "id": "classic", "name": "the 10-step chain",
|
|
114
|
+
"steps": ["epic", "architecture", { "id": "ui-design", "optional": true }, "stories", "test-cases"] },
|
|
115
|
+
{ "id": "analysis-first", "name": "the 12-step chain",
|
|
116
|
+
"steps": ["analysis", "epic", "architecture", { "id": "ui-design", "optional": true }, "stories", "test-cases"] },
|
|
117
|
+
{ "id": "chore", "name": "the upkeep lane", "steps": ["epic", "stories"] },
|
|
118
|
+
{ "id": "spike", "name": "the investigation lane", "steps": ["analysis", "epic", "stories"] },
|
|
119
|
+
{ "id": "discovery", "name": "the product front-zero", "steps": ["discovery"], "retired": true },
|
|
120
|
+
{ "id": "foundation", "name": "the Product Foundation", "steps": ["foundation"] },
|
|
121
|
+
{ "id": "lane", "name": "the Build lane", "steps": ["spec", "tasks", "implement", "checks", "engineer-review"] }
|
|
122
|
+
],
|
|
123
|
+
"plugins": []
|
|
124
|
+
}
|
|
@@ -54,7 +54,9 @@
|
|
|
54
54
|
"type": "object",
|
|
55
55
|
"properties": {
|
|
56
56
|
"riskTags": { "type": "array", "items": { "type": "string" } },
|
|
57
|
-
"skills": { "type": "array", "items": { "type": "string" } }
|
|
57
|
+
"skills": { "type": "array", "items": { "type": "string" } },
|
|
58
|
+
"description": { "type": "string", "description": "What the review is for, in a sentence an AI agent can show the person." },
|
|
59
|
+
"advance": { "const": "human", "description": "Who moves the gate on: always a person." }
|
|
58
60
|
}
|
|
59
61
|
}
|
|
60
62
|
]
|
|
@@ -88,7 +90,8 @@
|
|
|
88
90
|
"inputs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
|
|
89
91
|
"retired": { "type": "boolean", "default": false },
|
|
90
92
|
"replaces": { "type": "string" },
|
|
91
|
-
"provider": { "$ref": "#/$defs/provider" }
|
|
93
|
+
"provider": { "$ref": "#/$defs/provider" },
|
|
94
|
+
"driver": { "enum": ["human", "pair", "agent"], "description": "Who does the step's work by default: only a person, the AI agent and the person together (the agent drafts, the person decides), or the agent. A review step's driver is \"human\"." }
|
|
92
95
|
}
|
|
93
96
|
},
|
|
94
97
|
"route": {
|
package/cli/lifecycle.mjs
CHANGED
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
import fs from 'node:fs';
|
|
26
26
|
|
|
27
27
|
// The newest shipped default — the one every reader uses until a team file exists (E135).
|
|
28
|
-
export const DEFAULT_VERSION =
|
|
28
|
+
export const DEFAULT_VERSION = 2;
|
|
29
29
|
|
|
30
30
|
const DEFAULTS_DIR = new URL('./lifecycle/defaults/', import.meta.url);
|
|
31
31
|
|
|
@@ -92,6 +92,14 @@ export const ARTIFACT_TYPES = ['file', 'folder', 'set'];
|
|
|
92
92
|
export const PHASE_RUNS = ['once', 'loop'];
|
|
93
93
|
export const PHASE_LEVELS = ['feature', 'product'];
|
|
94
94
|
export const PARTS = ['Shape', 'Build', 'Run'];
|
|
95
|
+
// Who does a step's work, by default (E157), in the words of the shape-4 `driver` dial (cli/manifest.mjs):
|
|
96
|
+
// `human` (only a person can), `pair` (the AI agent drafts, the person answers its questions and decides)
|
|
97
|
+
// or `agent` (the agent does it). An epic's own `driver` on a step, when it records one, says what that
|
|
98
|
+
// epic chose. An AI agent reads it through `yad guide --json` to know when to stop and hand the work over.
|
|
99
|
+
// A review step is a person's approval, so its driver is `human`. A gate is moved on only by a person (its
|
|
100
|
+
// `advance` is `human`, rule 1 of the spine: a gate is never automatic), so a file that says otherwise is
|
|
101
|
+
// refused.
|
|
102
|
+
export const DRIVERS = ['human', 'pair', 'agent'];
|
|
95
103
|
|
|
96
104
|
// THE BEHAVIOUR REGISTRY. A behaviour is something the engine does because of a step, not because of a
|
|
97
105
|
// step's name: the epic step is where the work-item type is read, the architecture step locks the
|
|
@@ -137,9 +145,9 @@ export const KNOWN_KEYS = {
|
|
|
137
145
|
file: ['$schema', 'schemaVersion', 'extends', 'phases', 'steps', 'routes', 'plugins'],
|
|
138
146
|
phase: ['id', 'name', 'description', 'part', 'level', 'runs', 'over', 'built'],
|
|
139
147
|
step: ['id', 'name', 'description', 'phase', 'kind', 'artifact', 'optional', 'gate', 'skills', 'behaviours',
|
|
140
|
-
'extraPaths', 'inputs', 'retired', 'replaces', 'provider'],
|
|
148
|
+
'extraPaths', 'inputs', 'retired', 'replaces', 'provider', 'driver'],
|
|
141
149
|
route: ['id', 'name', 'description', 'steps', 'bindings', 'retired', 'provider'],
|
|
142
|
-
gate: ['riskTags', 'skills'],
|
|
150
|
+
gate: ['riskTags', 'skills', 'description', 'advance'],
|
|
143
151
|
artifact: ['type', 'path', 'unit', 'files', 'optional', 'in'],
|
|
144
152
|
provider: ['id', 'version', 'origin'],
|
|
145
153
|
routeStep: ['id', 'optional'],
|
|
@@ -335,6 +343,9 @@ export function lifecycleProblems(raw) {
|
|
|
335
343
|
}
|
|
336
344
|
if (s.replaces !== undefined && typeof s.replaces !== 'string') add('error', where, '"replaces" must be a step id');
|
|
337
345
|
if (s.description !== undefined && typeof s.description !== 'string') add('error', where, '"description" must be text');
|
|
346
|
+
if (s.driver !== undefined && typeof s.driver !== 'string') add('error', where, `"driver" must be one word: ${DRIVERS.join(', ')}`);
|
|
347
|
+
else if (s.driver !== undefined && !DRIVERS.includes(s.driver)) add('unusable', where, `"driver" is "${s.driver}", which this yadflow does not know; the step cannot be used for new epics`);
|
|
348
|
+
if (s.kind === 'review' && s.driver !== undefined && s.driver !== 'human') add('error', where, 'a review step is a person\'s approval, so its "driver" is "human"');
|
|
338
349
|
if (s.provider !== undefined && !providerOk(s.provider)) add('error', where, PROVIDER_SHAPE);
|
|
339
350
|
if (!phaseIds.has(s.phase)) add('error', where, `its phase "${s.phase}" does not exist`);
|
|
340
351
|
else if (unknownRuns.has(s.phase)) add('unusable', where, `its phase "${s.phase}" uses a "runs" value this yadflow does not know`);
|
|
@@ -351,6 +362,8 @@ export function lifecycleProblems(raw) {
|
|
|
351
362
|
|| (s.gate.skills !== undefined && !isStrings(s.gate.skills)))) {
|
|
352
363
|
add('error', where, '"gate" must be null or { "riskTags": [ … ], "skills": [ … ] }');
|
|
353
364
|
}
|
|
365
|
+
if (isObj(s.gate) && s.gate.description !== undefined && typeof s.gate.description !== 'string') add('error', where, 'the gate\'s "description" must be text');
|
|
366
|
+
if (isObj(s.gate) && s.gate.advance !== undefined && s.gate.advance !== 'human') add('error', where, 'a gate is moved on only by a person, so the gate\'s "advance" is "human"');
|
|
354
367
|
|
|
355
368
|
if (n.artifact !== null) {
|
|
356
369
|
const a = n.artifact;
|
package/cli/machine.mjs
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
// #352 — the machine setup local work depends on, for `yad doctor`. Three checks, each from what is on disk
|
|
2
|
+
// here (no network):
|
|
3
|
+
// node the Node running yad (the active one, e.g. nvm's default) against the version each repo pins:
|
|
4
|
+
// .nvmrc, .node-version, .tool-versions (nodejs), package.json `engines.node` and `volta.node`.
|
|
5
|
+
// A pin yad cannot read as a version (`lts/*`, a URL) is left out, never guessed.
|
|
6
|
+
// docker Docker running, only where a repo itself asks for it: a compose file, a Dockerfile, a `docker`
|
|
7
|
+
// call in its package.json scripts, or a docker hook in its pre-commit config. yad's own gates
|
|
8
|
+
// need no Docker, so a repo that names none is never asked about.
|
|
9
|
+
// glab more than one glab config file. glab then reads only one and ignores the other (a login saved
|
|
10
|
+
// there is not used), and warns on every run, which breaks JSON for a tool that reads its output
|
|
11
|
+
// and its errors together.
|
|
12
|
+
import fs from 'node:fs';
|
|
13
|
+
import os from 'node:os';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
import { run, readJSON, isPlainObject, forTerminal } from './lib.mjs';
|
|
16
|
+
|
|
17
|
+
const read = (file) => { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } };
|
|
18
|
+
|
|
19
|
+
// The Node versions a folder pins, each { source, want }.
|
|
20
|
+
export function nodePins(dir) {
|
|
21
|
+
const pins = [];
|
|
22
|
+
for (const f of ['.nvmrc', '.node-version']) {
|
|
23
|
+
const t = read(path.join(dir, f));
|
|
24
|
+
const v = t?.split('\n').map((l) => l.replace(/#.*/, '').trim()).find(Boolean);
|
|
25
|
+
if (v) pins.push({ source: f, want: v });
|
|
26
|
+
}
|
|
27
|
+
const tv = read(path.join(dir, '.tool-versions'));
|
|
28
|
+
// A line may list fallbacks (`nodejs 24.2.0 22.0.0`): the first is the one in use, and the one read.
|
|
29
|
+
const line = tv?.split('\n').map((l) => l.replace(/#.*/, '').trim()).find((l) => /^(nodejs|node)\s/.test(l));
|
|
30
|
+
if (line) pins.push({ source: '.tool-versions', want: line.split(/\s+/)[1] });
|
|
31
|
+
const pkg = readJSON(path.join(dir, 'package.json'), null);
|
|
32
|
+
if (isPlainObject(pkg)) {
|
|
33
|
+
if (typeof pkg.engines?.node === 'string' && pkg.engines.node.trim()) pins.push({ source: 'package.json engines.node', want: pkg.engines.node.trim() });
|
|
34
|
+
if (typeof pkg.volta?.node === 'string' && pkg.volta.node.trim()) pins.push({ source: 'package.json volta.node', want: pkg.volta.node.trim() });
|
|
35
|
+
}
|
|
36
|
+
return pins;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const parts = (v) => {
|
|
40
|
+
const m = /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/i.exec(String(v).trim());
|
|
41
|
+
if (!m) return null;
|
|
42
|
+
const n = (x) => (x === undefined || /^[x*]$/i.test(x) ? null : Number(x));
|
|
43
|
+
return [Number(m[1]), n(m[2]), n(m[3])];
|
|
44
|
+
};
|
|
45
|
+
const cmp = (a, b) => { for (let i = 0; i < 3; i++) { const d = (a[i] ?? 0) - (b[i] ?? 0); if (d) return d; } return 0; };
|
|
46
|
+
|
|
47
|
+
// Does `version` (x.y.z) meet `spec`? true / false, or null when the spec is not one yad reads (a name such
|
|
48
|
+
// as `lts/*`, a URL): never guessed. Reads exact and partial versions (`24`, `22.8`), `x` and `*`, the
|
|
49
|
+
// operators >= > <= < = (with or without a space before the version), ^ and ~, `a - b`, spaces (all must
|
|
50
|
+
// hold) and `||` (any may). A pre-release (`24.0.0-rc.1`), in the spec or the running Node, is not read.
|
|
51
|
+
export function satisfies(version, spec) {
|
|
52
|
+
const have = parts(version);
|
|
53
|
+
if (!have) return null;
|
|
54
|
+
const alts = String(spec).split('||').map((s) => s.trim());
|
|
55
|
+
let unknown = false;
|
|
56
|
+
for (const alt of alts) {
|
|
57
|
+
if (alt === '' || alt === '*' || /^x$/i.test(alt)) return true;
|
|
58
|
+
const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(alt);
|
|
59
|
+
// `>= 22` is `>=22`: an operator is joined to its version before the spaces split the terms.
|
|
60
|
+
const joined = alt.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1');
|
|
61
|
+
const terms = hyphen ? [`>=${hyphen[1]}`, `<=${hyphen[2]}`] : joined.split(/\s+/).filter(Boolean);
|
|
62
|
+
let all = true;
|
|
63
|
+
for (const term of terms) {
|
|
64
|
+
const m = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(term);
|
|
65
|
+
const want = m && parts(m[2]);
|
|
66
|
+
if (!want) { unknown = true; all = false; break; }
|
|
67
|
+
const op = m[1] || '';
|
|
68
|
+
const c = cmp(have, want);
|
|
69
|
+
const lead = want.findIndex((x) => x === null);
|
|
70
|
+
let ok;
|
|
71
|
+
if (op === '>=') ok = c >= 0;
|
|
72
|
+
// `>24` is above every 24.x.y (npm reads it as >=25.0.0): only the parts it names are compared.
|
|
73
|
+
else if (op === '>') ok = lead >= 0 ? cmp(have.slice(0, lead), want.slice(0, lead)) > 0 : c > 0;
|
|
74
|
+
else if (op === '<=') ok = c <= 0 || (lead >= 0 && have.slice(0, lead).every((x, i) => x === want[i]));
|
|
75
|
+
else if (op === '<') ok = c < 0;
|
|
76
|
+
else if (op === '^') {
|
|
77
|
+
ok = c >= 0 && (want[0] > 0 ? have[0] === want[0]
|
|
78
|
+
: want[1] === null || want[1] > 0 ? have[0] === 0 && (want[1] === null || have[1] === want[1])
|
|
79
|
+
: have[0] === 0 && have[1] === 0 && (want[2] === null || have[2] === want[2]));
|
|
80
|
+
}
|
|
81
|
+
else if (op === '~') ok = c >= 0 && have[0] === want[0] && (want[1] === null || have[1] === want[1]);
|
|
82
|
+
// A bare or `=` version: the parts it names must match (`24` is any 24.x.y).
|
|
83
|
+
else ok = want.every((x, i) => x === null || x === have[i]);
|
|
84
|
+
if (!ok) { all = false; break; }
|
|
85
|
+
}
|
|
86
|
+
if (all) return true;
|
|
87
|
+
}
|
|
88
|
+
return unknown ? null : false;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// What the person runs to fix a Node mismatch: nvm's commands when nvm is here, else plain words.
|
|
92
|
+
export function nodeFix(rawWant, { env = process.env, home = os.homedir() } = {}) {
|
|
93
|
+
const want = forTerminal(rawWant);
|
|
94
|
+
const exact = /^v?\d+(\.\d+){0,2}$/.test(want) ? want.replace(/^v/, '') : null;
|
|
95
|
+
const nvm = !!env.NVM_DIR || fs.existsSync(path.join(home, '.nvm'));
|
|
96
|
+
if (nvm && exact) return `nvm install ${exact} && nvm use ${exact} (and \`nvm alias default ${exact}\` to make it the default in new shells)`;
|
|
97
|
+
if (nvm) return `nvm install <a version that meets ${want}> && nvm use <that version>`;
|
|
98
|
+
return `install Node ${want} (or switch to it with your version manager)`;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// Why a folder needs Docker: the files and lines that ask for it ([] when none). Script names come from the
|
|
102
|
+
// repo, so they are cleaned for the terminal here.
|
|
103
|
+
export function dockerReasons(dir) {
|
|
104
|
+
const why = [];
|
|
105
|
+
let names = [];
|
|
106
|
+
try { names = fs.readdirSync(dir); } catch { /* not readable: no reasons */ }
|
|
107
|
+
for (const f of names) {
|
|
108
|
+
if (/^(docker-)?compose\.ya?ml$/i.test(f) || /^dockerfile(\..+)?$/i.test(f) || /\.dockerfile$/i.test(f)) why.push(forTerminal(f));
|
|
109
|
+
}
|
|
110
|
+
const pkg = readJSON(path.join(dir, 'package.json'), null);
|
|
111
|
+
const scripts = isPlainObject(pkg?.scripts) ? pkg.scripts : {};
|
|
112
|
+
// docker run as a command: at the start, after `&&` `||` `;` `|` `(`, after `npx`, or by its path —
|
|
113
|
+
// not the word inside another command (`--ignore-pattern docker`, `echo docker`).
|
|
114
|
+
const cmd = /(^|[;&|(]\s*|\bnpx\s+(-y\s+)?)(\S*\/)?docker(-compose)?(\s|$)/;
|
|
115
|
+
const named = Object.entries(scripts).filter(([, v]) => typeof v === 'string' && cmd.test(v)).map(([k]) => forTerminal(k));
|
|
116
|
+
if (named.length) why.push(`package.json scripts: ${named.join(', ')}`);
|
|
117
|
+
const pre = read(path.join(dir, '.pre-commit-config.yaml'));
|
|
118
|
+
if (pre && /^\s*language:\s*["']?(docker|docker_image)["']?\s*(#.*)?$/m.test(pre)) why.push('.pre-commit-config.yaml (a docker hook)');
|
|
119
|
+
return why;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// Is Docker here and running? 'running' | 'stopped' (the CLI is here, the daemon does not answer) |
|
|
123
|
+
// 'missing' (no docker command).
|
|
124
|
+
export function dockerState({ runner = run } = {}) {
|
|
125
|
+
if (!runner(process.platform === 'win32' ? 'where' : 'which', ['docker']).ok) return 'missing';
|
|
126
|
+
return runner('docker', ['info', '--format', '{{.ServerVersion}}'], { timeout: 8000 }).ok ? 'running' : 'stopped';
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// The glab config files that exist on this machine, in the places glab looks. GLAB_CONFIG_DIR, or else
|
|
130
|
+
// XDG_CONFIG_HOME, names the one place glab reads (it then warns about no other); without them glab looks
|
|
131
|
+
// in ~/.config and the system's own folder, and warns when both hold a config.
|
|
132
|
+
export function glabConfigs({ env = process.env, home = os.homedir(), platform = process.platform } = {}) {
|
|
133
|
+
const places = env.GLAB_CONFIG_DIR ? [path.join(env.GLAB_CONFIG_DIR, 'config.yml')]
|
|
134
|
+
: env.XDG_CONFIG_HOME ? [path.join(env.XDG_CONFIG_HOME, 'glab-cli', 'config.yml')]
|
|
135
|
+
: [
|
|
136
|
+
path.join(home, '.config', 'glab-cli', 'config.yml'),
|
|
137
|
+
platform === 'darwin' && path.join(home, 'Library', 'Application Support', 'glab-cli', 'config.yml'),
|
|
138
|
+
platform === 'win32' && env.APPDATA && path.join(env.APPDATA, 'glab-cli', 'config.yml'),
|
|
139
|
+
].filter(Boolean);
|
|
140
|
+
return [...new Set(places)].filter((f) => fs.existsSync(f));
|
|
141
|
+
}
|
package/cli/manifest.mjs
CHANGED
|
@@ -56,6 +56,8 @@ export const SKILLS = [
|
|
|
56
56
|
'yad-pair-review',
|
|
57
57
|
'yad-status',
|
|
58
58
|
'yad-report',
|
|
59
|
+
// E158: the rules and the step loop for an AI agent, loaded before any yadflow work.
|
|
60
|
+
'yad-guide',
|
|
59
61
|
'yad-change',
|
|
60
62
|
'yad-timeline',
|
|
61
63
|
'yad-defects',
|
|
@@ -568,6 +570,26 @@ export const PRODUCT_WIRING = {
|
|
|
568
570
|
// The branch-protection setup guide (E48), linked from `yad doctor`'s `protection` section. A URL, not a
|
|
569
571
|
// path: the reader is in their own repo, where `docs/` is not yadflow's.
|
|
570
572
|
export const PROTECTION_GUIDE_URL = 'https://github.com/abdelrahmannasr/yadflow/blob/main/docs/branch-protection.md';
|
|
573
|
+
// E160b — the checks a team requires before a merge, by the name the platform gives each one: on GitHub a
|
|
574
|
+
// check is named after its job (the jobs set no `name:`), on GitLab a job is the job's key. `yad ci check`
|
|
575
|
+
// reads the GitHub list against the branch's required checks; on GitLab "Pipelines must succeed" covers
|
|
576
|
+
// every job, so the list there is for the docs only. `productVerified` is the Product's verified-commits
|
|
577
|
+
// workflow, required when that file is there. Tests hold this equal to the templates' jobs and to the table
|
|
578
|
+
// in docs/branch-protection.md.
|
|
579
|
+
export const REQUIRED_CHECKS = Object.freeze({
|
|
580
|
+
github: Object.freeze({
|
|
581
|
+
product: Object.freeze(['commit-message', 'pr-title', 'pr-template', 'ledger-guard', 'member-check']),
|
|
582
|
+
productVerified: Object.freeze(['verified-commits']),
|
|
583
|
+
code: Object.freeze(['spec-link', 'contract-check', 'risk-map', 'build-test-lint', 'lineage-check', 'epic-open', 'reconcile-debt',
|
|
584
|
+
'commit-message', 'pr-title', 'pr-template', 'verified-commits']),
|
|
585
|
+
}),
|
|
586
|
+
gitlab: Object.freeze({
|
|
587
|
+
product: Object.freeze(['yad-product-commit-message', 'yad-product-pr-title', 'yad-product-pr-template', 'yad-product-ledger-guard', 'yad-product-member-check']),
|
|
588
|
+
productVerified: Object.freeze(['yad-product-verified-commits']),
|
|
589
|
+
code: Object.freeze(['yad-spec-link', 'yad-contract-check', 'yad-risk-map', 'yad-build-test-lint', 'yad-lineage-check', 'yad-epic-open',
|
|
590
|
+
'yad-reconcile-debt', 'yad-commit-message', 'yad-pr-title', 'yad-pr-template', 'yad-verified-commits']),
|
|
591
|
+
}),
|
|
592
|
+
});
|
|
571
593
|
// The hub -> Product hand-change guide (E124), linked from `yad migrate`'s last line while `.sdlc/hub.json` is on
|
|
572
594
|
// disk. A URL for the same reason.
|
|
573
595
|
export const PRODUCT_RENAME_GUIDE_URL = 'https://github.com/abdelrahmannasr/yadflow/blob/main/docs/migrations/hub-to-product.md';
|
|
@@ -748,6 +770,59 @@ export const CAPTURE_ADAPTERS = Object.freeze({
|
|
|
748
770
|
}),
|
|
749
771
|
});
|
|
750
772
|
|
|
773
|
+
// The agent guard (E158): BEFORE an agent's shell command runs, `hooks/agent-guard.mjs` asks
|
|
774
|
+
// `yad hook agent-guard` whether it is a yad command only the person may run (an approval, a gate comment,
|
|
775
|
+
// advance or reopen, `commit --manual`), a PR/MR approval or merge, skipping the git hooks, or a force push,
|
|
776
|
+
// and refuses it with what to do instead. Wired on every Product and every connected code repo cloned here
|
|
777
|
+
// (E158b), in both ledger modes: it is about the agent's rules, not about who owns the ledger. A speed bump,
|
|
778
|
+
// not proof (cli/agent-guard.mjs). Codex has no hooks: there, only the rules in AGENTS.md apply.
|
|
779
|
+
//
|
|
780
|
+
// ONE script for both harnesses. It reads the payload and answers in the protocol the payload names:
|
|
781
|
+
// Cursor's `beforeShellExecution` is a permission hook (a JSON verdict on stdout, always), Claude Code's
|
|
782
|
+
// `PreToolUse` reads the exit code. So both entries are a program and one path, the form Cursor documents.
|
|
783
|
+
export const AGENT_GUARD_WIRING = [
|
|
784
|
+
{ src: 'skills/yad-checks/templates/hooks/agent-guard.mjs', dest: 'hooks/agent-guard.mjs' },
|
|
785
|
+
];
|
|
786
|
+
// In a connected code repo the script goes in `checks/`, the folder yad already owns there (E158b): a root
|
|
787
|
+
// `hooks/` folder is often the app's own. The script finds yad from its grandparent, the repo's root, either way.
|
|
788
|
+
export const REPO_AGENT_GUARD_DEST = 'checks/agent-guard.mjs';
|
|
789
|
+
// The Claude and Cursor entries that run the script at `dest` (a path from the project's root).
|
|
790
|
+
export const agentGuardAdapters = (dest) => Object.freeze({
|
|
791
|
+
'.claude': Object.freeze({
|
|
792
|
+
target: '.claude',
|
|
793
|
+
label: 'agent guard',
|
|
794
|
+
settings: '.claude/settings.json',
|
|
795
|
+
event: 'PreToolUse',
|
|
796
|
+
nested: true,
|
|
797
|
+
preamble: null,
|
|
798
|
+
// The shell tool: the one way an agent runs a yad command or a git push.
|
|
799
|
+
matcher: 'Bash',
|
|
800
|
+
projectDirEnv: CLAUDE_PROJECT_DIR_ENV,
|
|
801
|
+
// Quoted and anchored on the project root, for the reason the ledger guard's entry is (see above).
|
|
802
|
+
command: `node "$${CLAUDE_PROJECT_DIR_ENV}/${dest}"`,
|
|
803
|
+
wiring: Object.freeze([]),
|
|
804
|
+
legacyCommands: Object.freeze([]),
|
|
805
|
+
}),
|
|
806
|
+
'.cursor': Object.freeze({
|
|
807
|
+
target: '.cursor',
|
|
808
|
+
label: 'agent guard',
|
|
809
|
+
settings: '.cursor/hooks.json',
|
|
810
|
+
// Fires before every shell command the agent runs, and takes no matcher.
|
|
811
|
+
event: 'beforeShellExecution',
|
|
812
|
+
nested: false,
|
|
813
|
+
preamble: Object.freeze({ version: 1 }),
|
|
814
|
+
matcher: null,
|
|
815
|
+
projectDirEnv: CURSOR_PROJECT_DIR_ENV,
|
|
816
|
+
// Relative and unquoted, for the reason the ledger guard's Cursor entry is (see above).
|
|
817
|
+
command: `node ${dest}`,
|
|
818
|
+
// A permission hook: an empty or off-schema answer BLOCKS, so the script always prints a verdict.
|
|
819
|
+
requiresJsonVerdict: true,
|
|
820
|
+
wiring: Object.freeze([]),
|
|
821
|
+
legacyCommands: Object.freeze([]),
|
|
822
|
+
}),
|
|
823
|
+
});
|
|
824
|
+
export const AGENT_GUARD_ADAPTERS = agentGuardAdapters(AGENT_GUARD_WIRING[0].dest);
|
|
825
|
+
|
|
751
826
|
// The Claude adapter's fields under their original names. Kept because they are what the shipped
|
|
752
827
|
// error text and the existing tests name, and renaming a constant buys nothing; new code should read
|
|
753
828
|
// the adapter, since these three describe ONE harness and the engine now supports two.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// A block yad owns inside a file the team owns (E158): AGENTS.md and CLAUDE.md. Only the lines between the
|
|
2
|
+
// two markers are ever written; everything outside them is the team's and is kept byte for byte.
|
|
3
|
+
//
|
|
4
|
+
// The markers bound the block, so nothing has to guess where it ends (the lesson of E87: never infer the end
|
|
5
|
+
// of a generated block from headings). The rules follow `applyConfigRegions` (cli/lifecycle.mjs): exactly one
|
|
6
|
+
// begin marker followed by exactly one end marker, or the file is refused and left as it is; a file checked
|
|
7
|
+
// out with Windows line endings (CRLF) is compared without them and written back with them.
|
|
8
|
+
//
|
|
9
|
+
// Unlike a config region, a block that is not there yet is ADDED: the file is the team's, and yad's block is
|
|
10
|
+
// appended after their text, with one blank line between.
|
|
11
|
+
|
|
12
|
+
// The text of a file with yad's block in place, and what that changed.
|
|
13
|
+
// status 'new' the file had no block (or did not exist): it is appended
|
|
14
|
+
// 'outdated' the block is there with other lines
|
|
15
|
+
// 'ok' the block is there and right
|
|
16
|
+
// refused why the markers could not be trusted (a begin with no end, two of either, an end first). The
|
|
17
|
+
// text is then returned unchanged.
|
|
18
|
+
// `text` is null for a file that does not exist.
|
|
19
|
+
// `beginKey` is the start every begin line shares, so a later release can reword the note after it.
|
|
20
|
+
export function applyMarkedBlock(text, { begin, beginKey = begin, end, lines }) {
|
|
21
|
+
const source = text ?? '';
|
|
22
|
+
// Each line with its own ending, so the text outside the block is kept byte for byte, mixed endings too.
|
|
23
|
+
const rows = source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
|
|
24
|
+
const bare = rows.map((r) => r.replace(/\r?\n$/, ''));
|
|
25
|
+
const begins = bare.flatMap((l, i) => (l.trim().startsWith(beginKey) ? [i] : []));
|
|
26
|
+
const ends = bare.flatMap((l, i) => (l.trim() === end ? [i] : []));
|
|
27
|
+
const want = [begin, ...lines, end];
|
|
28
|
+
if (!begins.length && !ends.length) {
|
|
29
|
+
// Appended after the team's text, in the file's own line ending: a newline is added only when it has none
|
|
30
|
+
// at the end, and a blank line only when it does not already end with one.
|
|
31
|
+
const eol = source.includes('\r\n') ? '\r\n' : '\n';
|
|
32
|
+
let head = source;
|
|
33
|
+
if (head && !/\n$/.test(head)) head += eol;
|
|
34
|
+
if (head && !/\n\r?\n$/.test(head)) head += eol;
|
|
35
|
+
return { text: `${head}${want.join(eol)}${eol}`, status: 'new', refused: null };
|
|
36
|
+
}
|
|
37
|
+
if (begins.length !== 1 || ends.length !== 1 || ends[0] < begins[0]) {
|
|
38
|
+
return { text: source, status: null, refused: `the yadflow block needs exactly one line starting "${beginKey}" followed by one line "${end}"` };
|
|
39
|
+
}
|
|
40
|
+
const [b, e] = [begins[0], ends[0]];
|
|
41
|
+
if (bare.slice(b, e + 1).join('\n') === want.join('\n')) return { text: source, status: 'ok', refused: null };
|
|
42
|
+
// The block is written in the ending its begin line had; the end line keeps whatever followed it (none at
|
|
43
|
+
// the very end of a file).
|
|
44
|
+
const eol = /\r\n$/.test(rows[b]) ? '\r\n' : '\n';
|
|
45
|
+
const tail = (rows[e].match(/\r?\n$/) ?? [''])[0];
|
|
46
|
+
const block = `${want.join(eol)}${tail}`;
|
|
47
|
+
return { text: rows.slice(0, b).join('') + block + rows.slice(e + 1).join(''), status: 'outdated', refused: null };
|
|
48
|
+
}
|
package/cli/members.mjs
CHANGED
|
@@ -43,7 +43,7 @@ import path from 'node:path';
|
|
|
43
43
|
import { createHash } from 'node:crypto';
|
|
44
44
|
import { spawnSync } from 'node:child_process';
|
|
45
45
|
|
|
46
|
-
import { c, log, ok, info, warn, fail, hand, run, readJSON, forTerminal, isPlainObject, asset } from './lib.mjs';
|
|
46
|
+
import { c, log, ok, info, warn, fail, hand, run, readJSON, forTerminal, isPlainObject, asset, inJSON, refuse as refuseJSON } from './lib.mjs';
|
|
47
47
|
import { productConfigPath, isVerifiedLedger, SCHEMA_VERSION } from './manifest.mjs';
|
|
48
48
|
import { LOGIN_RE, hostFromGitUrl, plainHost } from './platform.mjs';
|
|
49
49
|
import { repoPathFromGitUrl, httpStatus } from './protection.mjs';
|
|
@@ -670,18 +670,31 @@ export async function runMemberAdd(root, { soft = false, noPush = false, runner
|
|
|
670
670
|
return accounts;
|
|
671
671
|
};
|
|
672
672
|
let accounts = discover();
|
|
673
|
+
// E159: under --json (an agent's run) no login is started — the person runs it, and this says how.
|
|
674
|
+
const startLogin = interactive(env) && !noLogin && !inJSON();
|
|
675
|
+
const loginStep = (cmd) => ({
|
|
676
|
+
act: 'login',
|
|
677
|
+
why: `a member file needs an account the platform can prove, and logging in to ${identity.platform === 'github' ? 'GitHub' : 'GitLab'} is the person's (a secret)`,
|
|
678
|
+
commands: [cmd],
|
|
679
|
+
verify: 'yad member add --json',
|
|
680
|
+
});
|
|
681
|
+
const noLoginYet = (msg, cmd) => {
|
|
682
|
+
if (!inJSON()) return refuse(msg, `run \`${cmd}\`, then \`yad member add\``);
|
|
683
|
+
if (soft) { warn(msg); hand(`run \`${cmd}\`, then \`yad member add\``); return { written: false, person: loginStep(cmd) }; }
|
|
684
|
+
return refuseJSON(msg, `the person runs \`${cmd}\` (\`!\` in front in Claude Code), then \`yad member add\``, { person: loginStep(cmd) });
|
|
685
|
+
};
|
|
673
686
|
const onProduct = () => accounts.some((a) => a.platform === identity.platform && a.host === identity.host && (a.platform === 'gitlab' || validLogin(a.login)));
|
|
674
687
|
if (identity.platform === 'github' && !onProduct()) {
|
|
675
|
-
if (
|
|
688
|
+
if (startLogin) {
|
|
676
689
|
info(`not logged in to GitHub on ${identity.host} — starting \`gh auth login\``);
|
|
677
690
|
spawnSync('gh', ['auth', 'login', '--hostname', identity.host, '--scopes', 'user:email'], { stdio: 'inherit' });
|
|
678
691
|
accounts = discover();
|
|
679
692
|
}
|
|
680
|
-
if (!onProduct()) return
|
|
693
|
+
if (!onProduct()) return noLoginYet(`not logged in to GitHub on ${identity.host}`, `gh auth login --hostname ${identity.host} --scopes user:email`);
|
|
681
694
|
}
|
|
682
695
|
let proofs = accounts.map((a) => accountProof(a, { runner, env }));
|
|
683
696
|
if (identity.platform === 'gitlab' && !proofs.some((p) => p.account.platform === 'gitlab' && p.account.host === identity.host && validLogin(p.account.login))) {
|
|
684
|
-
if (
|
|
697
|
+
if (startLogin) {
|
|
685
698
|
info(`not logged in to GitLab on ${identity.host} — starting \`glab auth login\``);
|
|
686
699
|
spawnSync('glab', ['auth', 'login', '--hostname', identity.host], { stdio: 'inherit' });
|
|
687
700
|
proofs = discover().map((a) => accountProof(a, { runner, env }));
|
|
@@ -706,7 +719,8 @@ export async function runMemberAdd(root, { soft = false, noPush = false, runner
|
|
|
706
719
|
const existingAll = membersAt(root, baseRef, identity);
|
|
707
720
|
const mine = existingAll.members.find((m) => proofs.some((p) => p.account.platform === identity.platform && p.account.host === identity.host && p.account.login.toLowerCase() === m.primary.login.toLowerCase()));
|
|
708
721
|
const built = buildRecord({ identity, proofs, git, today, existing: mine || null, proved: now.replace(/\.\d+Z$/, 'Z') });
|
|
709
|
-
if (built.problem) return
|
|
722
|
+
if (built.problem && built.login) return noLoginYet(built.problem, `${cli} auth login --hostname ${identity.host}`);
|
|
723
|
+
if (built.problem) return refuse(built.problem, built.hint || null);
|
|
710
724
|
const { record, primary, plainByHash } = built;
|
|
711
725
|
if (!Number.isSafeInteger(primary.id)) return refuse(`the platform did not give the numeric id of ${accountLabel(primary)} — the member-check gate needs it`, 'run `yad member add` again; if it keeps failing, report it with `yad report`');
|
|
712
726
|
// A login renamed away and registered again by someone else is another account: the old file is not theirs.
|