yadflow 4.10.0 → 4.12.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 +152 -0
- package/README.md +14 -3
- package/bin/commands.mjs +7 -1
- package/bin/yad.mjs +163 -16
- package/cli/agent-guard-worker.mjs +13 -0
- package/cli/agent-guard.mjs +1053 -57
- package/cli/agent-rules.mjs +59 -3
- package/cli/argv-flags.mjs +2 -2
- package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
- package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
- package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
- package/cli/brain/vendor/graphology-library.min.js +2 -0
- package/cli/brain/vendor/graphology.umd.min.js +2 -0
- package/cli/brain/vendor/sigma.min.js +1369 -0
- package/cli/brain/view/app.js +382 -0
- package/cli/brain/view/index.html +63 -0
- package/cli/brain/view/live.css +228 -0
- package/cli/brain/view/live.html +110 -0
- package/cli/brain/view/live.js +884 -0
- package/cli/brain/view/style.css +141 -0
- package/cli/brain-about.mjs +206 -0
- package/cli/brain-activity.mjs +285 -0
- package/cli/brain-skills.mjs +118 -0
- package/cli/brain-vendor.mjs +71 -0
- package/cli/brain-view.mjs +345 -0
- package/cli/brain.mjs +810 -0
- package/cli/brand-cmd.mjs +326 -0
- package/cli/brand.mjs +327 -0
- package/cli/ci-check.mjs +3 -3
- package/cli/doctor.mjs +145 -14
- package/cli/epic-state.mjs +93 -1
- package/cli/epic.mjs +15 -3
- package/cli/errors.mjs +2 -1
- package/cli/find-product.mjs +69 -15
- package/cli/foundation-publish.mjs +256 -0
- package/cli/gate.mjs +29 -3
- package/cli/git-read.mjs +38 -0
- package/cli/guard-stream.mjs +409 -0
- package/cli/guide.mjs +26 -3
- package/cli/hook.mjs +59 -9
- package/cli/issues-act.mjs +57 -13
- package/cli/issues-write.mjs +19 -6
- package/cli/issues.mjs +69 -24
- package/cli/lib.mjs +37 -2
- package/cli/local-page.mjs +138 -0
- package/cli/local-setup-record.mjs +71 -0
- package/cli/local-setup-steps.mjs +186 -0
- package/cli/local-setup.mjs +611 -0
- package/cli/machine.mjs +1 -1
- package/cli/manifest.mjs +55 -0
- package/cli/map/view/app.js +712 -0
- package/cli/map/view/index.html +50 -0
- package/cli/map/view/style.css +142 -0
- package/cli/map-view.mjs +190 -0
- package/cli/map.mjs +637 -0
- package/cli/members.mjs +9 -15
- package/cli/next.mjs +1 -1
- package/cli/openpr.mjs +2 -2
- package/cli/plain-text.mjs +22 -0
- package/cli/plan.mjs +310 -36
- package/cli/platform.mjs +5 -5
- package/cli/product-index.mjs +1 -1
- package/cli/protection.mjs +32 -0
- package/cli/reconcile.mjs +61 -13
- package/cli/report.mjs +9 -3
- package/cli/reports-dir.mjs +393 -0
- package/cli/reports.mjs +65 -0
- package/cli/run-checks.mjs +5 -2
- package/cli/scan.mjs +4 -6
- package/cli/secret-text.mjs +66 -0
- package/cli/setup.mjs +54 -8
- package/cli/standup.mjs +94 -72
- package/cli/status.mjs +6 -5
- package/cli/test-agents-file.mjs +614 -8
- package/cli/test-brain-activity.mjs +753 -0
- package/cli/test-brain-view.mjs +381 -0
- package/cli/test-brain.mjs +795 -0
- package/cli/test-brand.mjs +558 -0
- package/cli/test-guide.mjs +438 -0
- package/cli/test-local-setup.mjs +1188 -0
- package/cli/test-machine.mjs +59 -0
- package/cli/test-map.mjs +615 -0
- package/cli/test-reports.mjs +382 -0
- package/cli/test-run-checks.mjs +4 -0
- package/cli/test-worktree.mjs +24 -3
- package/cli/toolbox-connect.mjs +21 -6
- package/cli/toolbox.mjs +74 -5
- package/cli/update-commit.mjs +118 -9
- package/cli/usage.mjs +17 -7
- package/cli/workspace.mjs +11 -2
- package/package.json +8 -4
- package/skills/sdlc/module-help.csv +1 -0
- package/skills/yad-architecture/SKILL.md +22 -4
- package/skills/yad-brand/SKILL.md +69 -0
- package/skills/yad-change/SKILL.md +3 -1
- package/skills/yad-change/references/triage.md +2 -0
- package/skills/yad-checks/SKILL.md +2 -0
- package/skills/yad-checks/references/check-gates.md +8 -5
- package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
- package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
- package/skills/yad-checks/templates/github/yad-checks.yml +3 -2
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +3 -2
- package/skills/yad-checks/templates/hooks/local-setup-notice.mjs +96 -0
- package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
- package/skills/yad-connect-repos/SKILL.md +14 -0
- package/skills/yad-discovery/SKILL.md +11 -0
- package/skills/yad-discovery/references/foundation-schema.md +11 -0
- package/skills/yad-docs/templates/app/package-lock.json +18 -10
- package/skills/yad-docs/templates/app/package.json +6 -1
- package/skills/yad-epic/SKILL.md +3 -0
- package/skills/yad-epic/references/state-schema.md +35 -1
- package/skills/yad-guide/SKILL.md +10 -7
- package/skills/yad-implement/SKILL.md +76 -15
- package/skills/yad-issues/SKILL.md +2 -1
- package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +8 -4
- package/skills/yad-spec/SKILL.md +19 -0
- package/skills/yad-stories/SKILL.md +22 -4
- package/skills/yad-stories/references/story-schema.md +1 -1
|
@@ -0,0 +1,611 @@
|
|
|
1
|
+
// E185 — `yad local-setup`: the script a team member's agent follows on that person's machine.
|
|
2
|
+
//
|
|
3
|
+
// .sdlc/local-setup.json (committed, the Product) the source of truth:
|
|
4
|
+
// { localSetupVersion, catalogueVersion, yadflow: [steps], team: [steps] }
|
|
5
|
+
// `yadflow[]` is rewritten by every `yad setup`, `yad update` and `yad check --fix` (cli/local-setup-steps.mjs).
|
|
6
|
+
// `team[]` is the team's (`yad local-setup add`): an update never touches it.
|
|
7
|
+
// LOCAL-SETUP.md (committed, the Product root) the same steps as text, between yad's markers, so an agent
|
|
8
|
+
// can follow them even with a yad too old to know this command. The team writes freely outside the markers.
|
|
9
|
+
//
|
|
10
|
+
// yad RUNS NO STEP. It shows each step and runs only the built-in checks (cli/local-setup-steps.mjs). The agent
|
|
11
|
+
// runs a step's commands only after the person said yes to it (the `local-setup` rule, cli/agent-rules.mjs).
|
|
12
|
+
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
import { spawnSync } from 'node:child_process';
|
|
16
|
+
import { c, emitJSON, forTerminal, info, log, ok, refuse, warn, writeJSON, isPlainObject } from './lib.mjs';
|
|
17
|
+
import { markedBlockAction } from './plan.mjs';
|
|
18
|
+
import { productConfigPath, SCHEMA_VERSION, VERSION } from './manifest.mjs';
|
|
19
|
+
import {
|
|
20
|
+
LOCAL_SETUP_CATALOGUE_VERSION, LOCAL_SETUP_VERSION, LOCAL_SETUP_FILE, LOCAL_SETUP_DOC, STEP_ID, WHEN, BUILTIN_CHECKS,
|
|
21
|
+
yadflowSteps, cliMinimum, fileCliMin, stepHash, runBuiltinCheck, localSetupPath,
|
|
22
|
+
} from './local-setup-steps.mjs';
|
|
23
|
+
import { detectInstalled } from './detect.mjs';
|
|
24
|
+
import { readLocalSetupRecord, answerFor, writeLocalSetupAnswers } from './local-setup-record.mjs';
|
|
25
|
+
import { looksSecret } from './secret-text.mjs';
|
|
26
|
+
import { isText, plainLine, plainProse, STEP_LIMITS } from './plain-text.mjs';
|
|
27
|
+
export { STEP_LIMITS };
|
|
28
|
+
|
|
29
|
+
export const LOCAL_SETUP_MARKERS = Object.freeze({
|
|
30
|
+
begin: '<!-- yadflow:local-setup:begin — written by yad from .sdlc/local-setup.json; edit outside these lines, `yad update` rewrites them -->',
|
|
31
|
+
beginKey: '<!-- yadflow:local-setup:begin',
|
|
32
|
+
end: '<!-- yadflow:local-setup:end -->',
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
// ---- reading and checking the file ------------------------------------------------------------------
|
|
36
|
+
|
|
37
|
+
const isTextList = (v) => Array.isArray(v) && v.length > 0 && v.every(isText);
|
|
38
|
+
|
|
39
|
+
// What is wrong with one step, as words (empty when it is sound). Used for both lists: a yadflow step in a
|
|
40
|
+
// committed file was written by yad, but the file is the team's to edit, so it is read with the same care.
|
|
41
|
+
// A comment marker anywhere in a step could become one of yad's marker lines in LOCAL-SETUP.md, and no amount of
|
|
42
|
+
// removing text makes that safe (taking out one `<!--` can join the letters around it into another). So a step
|
|
43
|
+
// holding one is refused, and every command is shown exactly as written.
|
|
44
|
+
// `--!>` too: browsers end a comment there as well.
|
|
45
|
+
const MARKER = /<!--|--!?>/;
|
|
46
|
+
// One plain line: nothing `forTerminal` would change — no control character, and none of the invisible or
|
|
47
|
+
// direction-changing ones (U+202E and its kind), which would let LOCAL-SETUP.md show a reviewer one command while
|
|
48
|
+
// the agent runs another.
|
|
49
|
+
// Also every format and separator character (zero-width spaces, soft hyphens, tag characters): `exa\u200bmple.com`
|
|
50
|
+
// reads as `example.com`.
|
|
51
|
+
// And every space but the plain one: a no-break space looks like a space and is not one to the shell.
|
|
52
|
+
// HIDDEN, plainLine and plainProse live in cli/plain-text.mjs (the toolbox's own tools take them too).
|
|
53
|
+
const oneLine = plainLine;
|
|
54
|
+
|
|
55
|
+
const prose = plainProse;
|
|
56
|
+
|
|
57
|
+
export function stepProblems(s, source) {
|
|
58
|
+
const p = [];
|
|
59
|
+
if (!isPlainObject(s)) return ['it is not an object'];
|
|
60
|
+
if (typeof s.id !== 'string' || !STEP_ID.test(s.id)) p.push('its id should be lowercase letters, digits and dashes');
|
|
61
|
+
for (const k of ['title', 'purpose', 'impact']) if (!isText(s[k])) p.push(`it has no ${k}`);
|
|
62
|
+
if (isText(s.title) && (!oneLine(s.title) || s.title.length > STEP_LIMITS.title)) p.push(`its title should be one plain line of at most ${STEP_LIMITS.title} characters`);
|
|
63
|
+
for (const k of ['purpose', 'impact']) {
|
|
64
|
+
if (isText(s[k]) && (!prose(s[k]) || s[k].length > STEP_LIMITS.text)) p.push(`its ${k} should be plain text of at most ${STEP_LIMITS.text} characters (nothing hidden: no emoji joiner, variation selector or invisible character)`);
|
|
65
|
+
}
|
|
66
|
+
if (!isTextList(s.commands)) p.push('it has no commands');
|
|
67
|
+
else if (!s.commands.every(oneLine)) p.push('each command should be one line');
|
|
68
|
+
else if (s.commands.length > STEP_LIMITS.commands || s.commands.some((x) => x.length > STEP_LIMITS.command)) p.push(`it may hold at most ${STEP_LIMITS.commands} commands of at most ${STEP_LIMITS.command} characters each`);
|
|
69
|
+
if (s.person !== undefined && typeof s.person !== 'boolean') p.push('its `person` should be true or false');
|
|
70
|
+
if (s.addedBy != null && (!oneLine(s.addedBy) || s.addedBy.length > 80)) p.push('its `addedBy` should be a name on one plain line');
|
|
71
|
+
if (!WHEN.includes(s.when)) p.push('its `when` should be "required" or "optional"');
|
|
72
|
+
if (s.verify != null && (!oneLine(s.verify) || s.verify.length > STEP_LIMITS.command)) p.push(`its verify should be one line of at most ${STEP_LIMITS.command} characters`);
|
|
73
|
+
if (s.check != null) {
|
|
74
|
+
if (!isPlainObject(s.check)) p.push('its check should be an object');
|
|
75
|
+
else if (source === 'yadflow' && !BUILTIN_CHECKS.includes(s.check.builtin)) p.push('its check is not one yad knows');
|
|
76
|
+
// A team's check is a command and nothing else: a `builtin` beside it would hide the command in the view.
|
|
77
|
+
else if (source === 'team' && (!oneLine(s.check.run) || s.check.run.length > STEP_LIMITS.command || Object.keys(s.check).length !== 1)) p.push('its check should be `{ "run": "<one command>" }`');
|
|
78
|
+
}
|
|
79
|
+
const words = [s.title, s.purpose, s.impact, s.verify, s.addedBy, ...(Array.isArray(s.commands) ? s.commands : []), s.check?.run];
|
|
80
|
+
if (words.some((w) => typeof w === 'string' && MARKER.test(w))) p.push('it holds `<!--`, `-->` or `--!>`, which LOCAL-SETUP.md cannot show safely');
|
|
81
|
+
return p;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// A file's text as JSON, a byte-order mark (some Windows editors add one) read past.
|
|
85
|
+
export const parseJSON = (text) => JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
|
|
86
|
+
|
|
87
|
+
// The two lists, each step checked. `problems` names every step left out and why; the file still answers.
|
|
88
|
+
//
|
|
89
|
+
// VETTED IS NEVER READ FROM THE FILE. Anyone who can merge to the Product can write a step under `yadflow`. A
|
|
90
|
+
// yadflow step counts as yadflow's own (`known`, and `vetted` unless it is a team's tool) only when its id and hash
|
|
91
|
+
// are what this yadflow writes for this Product (`ours`: id → { hash, vetted }). Any other one is shown as not
|
|
92
|
+
// vetted, and `yad update` rewrites it.
|
|
93
|
+
export function readSteps(doc, { ours = null } = {}) {
|
|
94
|
+
// A file another catalogue wrote: its yadflow steps that differ are that release's, not a forgery.
|
|
95
|
+
const otherRelease = doc?.catalogueVersion !== LOCAL_SETUP_CATALOGUE_VERSION;
|
|
96
|
+
const problems = [];
|
|
97
|
+
const steps = [];
|
|
98
|
+
const seen = new Set();
|
|
99
|
+
for (const source of ['yadflow', 'team']) {
|
|
100
|
+
const list = doc?.[source];
|
|
101
|
+
if (list === undefined) continue;
|
|
102
|
+
if (!Array.isArray(list)) { problems.push(`${LOCAL_SETUP_FILE}: \`${source}\` should be a list — ignored`); continue; }
|
|
103
|
+
for (const [i, s] of list.entries()) {
|
|
104
|
+
const label = isPlainObject(s) && typeof s.id === 'string' ? `\`${forTerminal(s.id)}\`` : `number ${i + 1}`;
|
|
105
|
+
const p = stepProblems(s, source);
|
|
106
|
+
if (p.length) { problems.push(`${LOCAL_SETUP_FILE}: ${source} step ${label} is ignored — ${p.join('; ')}`); continue; }
|
|
107
|
+
if (seen.has(s.id)) { problems.push(`${LOCAL_SETUP_FILE}: step ${label} is listed twice — the first one is used`); continue; }
|
|
108
|
+
seen.add(s.id);
|
|
109
|
+
const hash = stepHash(s);
|
|
110
|
+
const mine = source === 'yadflow' ? ours?.get(s.id) : null;
|
|
111
|
+
const known = !!mine && mine.hash === hash;
|
|
112
|
+
steps.push({ ...s, source, known: source === 'yadflow' ? known : false, otherRelease: source === 'yadflow' && !known && otherRelease, vetted: known && mine.vetted !== false, hash });
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
return { steps, problems };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// The file as git has it at HEAD, else as it is on disk (a setup not committed yet). `{ doc, committed, error }`.
|
|
119
|
+
export function readCommittedLocalSetup(root) {
|
|
120
|
+
const r = spawnSync('git', ['show', `HEAD:./${LOCAL_SETUP_FILE}`], { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true });
|
|
121
|
+
let text = r.status === 0 ? r.stdout : null;
|
|
122
|
+
const committed = text !== null;
|
|
123
|
+
if (text === null) {
|
|
124
|
+
try { text = fs.readFileSync(localSetupPath(root), 'utf8'); } catch { return { doc: null, committed: false, error: null }; }
|
|
125
|
+
}
|
|
126
|
+
try {
|
|
127
|
+
const doc = parseJSON(text);
|
|
128
|
+
if (!isPlainObject(doc)) return { doc: null, committed, error: 'is not a JSON object' };
|
|
129
|
+
return { doc, committed, error: null };
|
|
130
|
+
} catch { return { doc: null, committed, error: 'does not parse' }; }
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
// ---- writing it (setup, update, check --fix) --------------------------------------------------------
|
|
134
|
+
|
|
135
|
+
// yad's part of the file merged into what is there: `yadflow[]` and the two version numbers replaced, every
|
|
136
|
+
// other key (the team's list first of all) kept as it is. The shape `reconcile` asks of a shared JSON file.
|
|
137
|
+
// What this yadflow writes for this Product, given the file there now: id → { hash, vetted } (readSteps).
|
|
138
|
+
//
|
|
139
|
+
// Built with the file's OWN CLI version: a member whose yad is newer (or older) than the one that wrote the file
|
|
140
|
+
// still sees yad's own CLI step as yad's. Only a plain release number is taken from the file (PLAIN_VERSION).
|
|
141
|
+
export const oursFor = (doc, root) => new Map(yadflowSteps(root, { cliMin: fileCliMin(doc) ?? VERSION }).map((s) => [s.id, { hash: stepHash(s), vetted: s.vetted }]));
|
|
142
|
+
|
|
143
|
+
// yad's own steps that its own reader would refuse — a team's toolbox tool whose words hold a marker or a
|
|
144
|
+
// two-line install command — are left out when yad writes them, and said once.
|
|
145
|
+
const droppedSaid = new Set();
|
|
146
|
+
function soundSteps(steps) {
|
|
147
|
+
return steps.filter((s) => {
|
|
148
|
+
const p = stepProblems(s, 'yadflow');
|
|
149
|
+
if (!p.length) return true;
|
|
150
|
+
const key = `${s.id}\0${p.join()}`;
|
|
151
|
+
if (!droppedSaid.has(key)) { droppedSaid.add(key); warn(`local setup: the step for \`${forTerminal(s.id)}\` is left out — ${p.join('; ')} (fix the tool in .sdlc/toolbox.json)`); }
|
|
152
|
+
return false;
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export function mergeLocalSetup(current, root) {
|
|
157
|
+
if (!isPlainObject(current)) return { unreadable: 'it is not a JSON object' };
|
|
158
|
+
if (current.team !== undefined && !Array.isArray(current.team)) return { unreadable: '`team` is not a list' };
|
|
159
|
+
// The shape stamp first, as writeJSON writes it: a copy yad builds from nothing then equals the one on disk, so
|
|
160
|
+
// `--open-pr` can tell the file is yad's alone (reconcile's shared-file rows).
|
|
161
|
+
const settings = {
|
|
162
|
+
schemaVersion: current.schemaVersion ?? SCHEMA_VERSION,
|
|
163
|
+
...current,
|
|
164
|
+
localSetupVersion: LOCAL_SETUP_VERSION,
|
|
165
|
+
catalogueVersion: LOCAL_SETUP_CATALOGUE_VERSION,
|
|
166
|
+
yadflow: soundSteps(yadflowSteps(root, { cliMin: cliMinimum(fileCliMin(current)) })),
|
|
167
|
+
team: current.team ?? [],
|
|
168
|
+
};
|
|
169
|
+
return { settings, changed: JSON.stringify(settings) !== JSON.stringify(current) };
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
const said = new Set();
|
|
173
|
+
function localSetupJsonAction(root) {
|
|
174
|
+
const dest = localSetupPath(root);
|
|
175
|
+
const base = { scope: 'product', item: LOCAL_SETUP_FILE, root, paths: [], shared: LOCAL_SETUP_FILE, what: 'its yadflow steps', mergeShared: (o) => mergeLocalSetup(o, root) };
|
|
176
|
+
let raw = null;
|
|
177
|
+
try { raw = fs.readFileSync(dest, 'utf8'); } catch { /* missing */ }
|
|
178
|
+
let parsed = null;
|
|
179
|
+
if (raw !== null) { try { parsed = parseJSON(raw); } catch { parsed = undefined; } }
|
|
180
|
+
const merged = raw === null ? mergeLocalSetup({}, root) : parsed === undefined ? { unreadable: 'it does not parse' } : mergeLocalSetup(parsed, root);
|
|
181
|
+
// Never rebuilt from nothing: that would delete every step the team wrote (memory: read strictly before a write).
|
|
182
|
+
if (merged.unreadable) {
|
|
183
|
+
if (!said.has(dest)) { said.add(dest); warn(`${LOCAL_SETUP_FILE}: ${merged.unreadable} — the local setup script was left as it is; fix it (or restore it from git), then re-run \`yad check --fix\``); }
|
|
184
|
+
return { ...base, status: 'modified', writesNothing: true, apply: () => {} };
|
|
185
|
+
}
|
|
186
|
+
return {
|
|
187
|
+
...base,
|
|
188
|
+
status: raw === null ? 'new' : merged.changed ? 'outdated' : 'ok',
|
|
189
|
+
// Re-read at apply time: setup and reconcile build every action before applying any.
|
|
190
|
+
apply: () => {
|
|
191
|
+
let now = {};
|
|
192
|
+
if (fs.existsSync(dest)) {
|
|
193
|
+
try { now = parseJSON(fs.readFileSync(dest, 'utf8')); } catch { warn(`${LOCAL_SETUP_FILE} does not parse — left untouched`); return; }
|
|
194
|
+
}
|
|
195
|
+
const next = mergeLocalSetup(now, root);
|
|
196
|
+
if (next.unreadable) { warn(`${LOCAL_SETUP_FILE}: ${next.unreadable} — left untouched`); return; }
|
|
197
|
+
if (!next.changed && Object.keys(now).length) return;
|
|
198
|
+
writeJSON(dest, next.settings);
|
|
199
|
+
},
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// The view's words. Every step that reaches here passed stepProblems: it holds no comment marker, and its commands
|
|
204
|
+
// are single lines. Prose is put on one line; code is shown exactly as written, in a span or fence longer than any
|
|
205
|
+
// run of backticks inside it, so an agent that copies from LOCAL-SETUP.md runs what the JSON says.
|
|
206
|
+
// HTML is written as text (review: an unclosed `<details>` would fold every later step out of sight).
|
|
207
|
+
// Every `<`, `>` and `&`, code spans too: telling markdown's code spans apart is exactly what let HTML through
|
|
208
|
+
// (review 3), so `make <target>` in prose shows its escaped form there — a small cost for a view that is safe.
|
|
209
|
+
const md = (s) => forTerminal(String(s ?? '')).replace(/\s+/g, ' ').trim().replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
|
|
210
|
+
const longestTicks = (s) => Math.max(0, ...[...String(s).matchAll(/`+/g)].map((m) => m[0].length));
|
|
211
|
+
const code = (s) => {
|
|
212
|
+
const t = String(s);
|
|
213
|
+
const fence = '`'.repeat(longestTicks(t) + 1);
|
|
214
|
+
const pad = t.startsWith('`') || t.endsWith('`') ? ' ' : '';
|
|
215
|
+
return `${fence}${pad}${t}${pad}${fence}`;
|
|
216
|
+
};
|
|
217
|
+
const CHECK_WORDS = {
|
|
218
|
+
'cli-version': (k) => `${code('yad --version')} is ${md(k.min)} or later`,
|
|
219
|
+
'platform-login': () => 'the platform CLI is signed in to the Product\'s host',
|
|
220
|
+
'ledger-hook': () => `${code('yad doctor')} shows the pre-commit hook as installed`,
|
|
221
|
+
'commit-signing': () => `${code('yad signing check')} finds nothing to set up`,
|
|
222
|
+
tool: (k) => `${code('yad toolbox check')} finds ${md(k.tool)}`,
|
|
223
|
+
};
|
|
224
|
+
const checkWords = (s) => (s.source === 'team'
|
|
225
|
+
? (s.check?.run ? `this command succeeds (ask the person before running it): ${code(s.check.run)}` : null)
|
|
226
|
+
: s.check?.builtin ? (CHECK_WORDS[s.check.builtin]?.(s.check) ?? 'yad checks it') : null);
|
|
227
|
+
|
|
228
|
+
function stepLines(s) {
|
|
229
|
+
const who = s.source === 'team' ? ` · added by your team${s.addedBy ? ` (${md(s.addedBy)})` : ''}, not vetted by yadflow`
|
|
230
|
+
: !s.known ? ` · **not what this yadflow writes — not vetted${s.otherRelease ? ' (possibly from another yadflow version)' : ''}; \`yad update\` rewrites it**`
|
|
231
|
+
: !s.vetted ? ' · a tool your team added, not vetted by yadflow' : '';
|
|
232
|
+
const fence = '`'.repeat(Math.max(3, ...s.commands.map((cmd) => longestTicks(cmd) + 1)));
|
|
233
|
+
const lines = [`### ${md(s.title)}`, '', `- **Id:** ${code(s.id)} · **${s.when}**${who}${s.person ? ' · **the person does this step, not the agent**' : ''}`];
|
|
234
|
+
lines.push(`- **Why:** ${md(s.purpose)}`, `- **What it changes for you:** ${md(s.impact)}`, '- **Run:**', '', ` ${fence}sh`, ...s.commands.map((cmd) => ` ${cmd}`), ` ${fence}`, '');
|
|
235
|
+
const done = checkWords(s);
|
|
236
|
+
if (done) lines.push(`- **Already done when:** ${done}`);
|
|
237
|
+
if (s.verify) lines.push(`- **Confirm with:** ${code(s.verify)}`);
|
|
238
|
+
lines.push('');
|
|
239
|
+
return lines;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// The block yad writes into LOCAL-SETUP.md, from a file yad has just merged (so its yadflow steps are yad's own).
|
|
243
|
+
export function localSetupDocLines(doc) {
|
|
244
|
+
const ours = new Map((doc?.yadflow ?? []).filter(isPlainObject).map((s) => [s.id, { hash: stepHash(s), vetted: s.vetted }]));
|
|
245
|
+
const { steps } = readSteps(doc, { ours });
|
|
246
|
+
const mine = steps.filter((s) => s.source === 'yadflow');
|
|
247
|
+
const theirs = steps.filter((s) => s.source === 'team');
|
|
248
|
+
return [
|
|
249
|
+
'# Local setup',
|
|
250
|
+
'',
|
|
251
|
+
'This is the script that gets a team member\'s machine ready for this project, and keeps it ready after each update.',
|
|
252
|
+
'Each step says why it is needed and what it changes for you, so you decide whether to do it.',
|
|
253
|
+
'',
|
|
254
|
+
`**For the agent:** run ${code('yad local-setup list --json')} to see which steps this machine still needs.`,
|
|
255
|
+
'For each one, tell the person its "Why" and "What it changes for you", and run its commands only after they say yes.',
|
|
256
|
+
'A step marked "the person does this step" is theirs: give them the command and wait.',
|
|
257
|
+
`If ${code('yad local-setup')} is not a command your yad knows, do the "Install the yadflow CLI" step first.`,
|
|
258
|
+
'',
|
|
259
|
+
'## Steps from yadflow',
|
|
260
|
+
'',
|
|
261
|
+
...(mine.length ? mine.flatMap(stepLines) : ['None.', '']),
|
|
262
|
+
'## Steps from your team',
|
|
263
|
+
'',
|
|
264
|
+
...(theirs.length ? theirs.flatMap(stepLines) : ['None yet.', '']),
|
|
265
|
+
].map((l) => l.replace(/\s+$/, ''));
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// The team's list as committed, or undefined when HEAD has no readable file.
|
|
269
|
+
// `{ team }` as committed: `[]` when HEAD has no file (an update PR then commits yad's own, with no team step), or
|
|
270
|
+
// `{ broken: true }` when HEAD's file cannot be read (an update PR never carries the JSON then: reconcile).
|
|
271
|
+
function committedTeam(root) {
|
|
272
|
+
const r = spawnSync('git', ['show', `HEAD:./${LOCAL_SETUP_FILE}`], { cwd: root, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true });
|
|
273
|
+
if (r.status !== 0) return { team: [] };
|
|
274
|
+
try {
|
|
275
|
+
const d = parseJSON(r.stdout);
|
|
276
|
+
return isPlainObject(d) && (d.team === undefined || Array.isArray(d.team)) ? { team: d.team ?? [] } : { broken: true };
|
|
277
|
+
} catch { return { broken: true }; }
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
// The two actions setup, update and check --fix apply: the JSON, then its Markdown view built from what the
|
|
281
|
+
// JSON will hold. Both are shared files (`paths` empty, `shared` named), like AGENTS.md: `--open-pr` carries them.
|
|
282
|
+
export function localSetupActions(root) {
|
|
283
|
+
// A Product's script: a folder with no Product config gets none (its steps would describe nothing).
|
|
284
|
+
if (!fs.existsSync(productConfigPath(root))) return [];
|
|
285
|
+
const json = localSetupJsonAction(root);
|
|
286
|
+
let doc = null;
|
|
287
|
+
let now = {};
|
|
288
|
+
if (!json.writesNothing) {
|
|
289
|
+
try { now = parseJSON(fs.readFileSync(localSetupPath(root), 'utf8')); } catch { /* new */ }
|
|
290
|
+
doc = mergeLocalSetup(isPlainObject(now) ? now : {}, root).settings;
|
|
291
|
+
}
|
|
292
|
+
const actions = [json];
|
|
293
|
+
if (doc) {
|
|
294
|
+
const view = markedBlockAction(root, LOCAL_SETUP_DOC, localSetupDocLines(doc), { markers: LOCAL_SETUP_MARKERS, what: 'the local setup steps' });
|
|
295
|
+
// The view shows the team steps on disk. While those differ from the committed ones (a person's own edit, not
|
|
296
|
+
// committed), the view is theirs too: `--open-pr` must not carry it, or the PR's LOCAL-SETUP.md would list a
|
|
297
|
+
// step its JSON lacks. It goes with the person's own commit of the JSON, which the JSON row asks for.
|
|
298
|
+
// The JSON rides only when its team list is the committed one, so the view does too.
|
|
299
|
+
const head = committedTeam(root);
|
|
300
|
+
const ownEdit = !!head.broken || JSON.stringify(head.team) !== JSON.stringify(isPlainObject(now) ? (now.team ?? []) : []);
|
|
301
|
+
actions.push(ownEdit ? { ...view, shared: undefined, mergeShared: undefined } : view);
|
|
302
|
+
}
|
|
303
|
+
// A file with no block is `missing`; this one is yad's to add on every Product, so it is `new` for an update.
|
|
304
|
+
return actions.map((a) => (a.status === 'missing' ? { ...a, status: 'new' } : a));
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// ---- this machine -----------------------------------------------------------------------------------
|
|
308
|
+
|
|
309
|
+
// Every step with its state here, from yad's own checks and this machine's record (cli/local-setup-record.mjs):
|
|
310
|
+
// skipped the person said no to the step as it is now (the record), whatever a check says
|
|
311
|
+
// ok yad's own check passed pending it failed
|
|
312
|
+
// done the person did a step yad cannot check (a team step, one with no check, one yad did not write)
|
|
313
|
+
// ask such a step, not answered for as it is now: yad runs no team command, so the agent asks the person
|
|
314
|
+
// `recorded`: the record has an answer for the step as it is now. `changed`: it has one for an older form only.
|
|
315
|
+
// `seen`: nothing is left to ask about it.
|
|
316
|
+
// `noProgram` (yad guide, doctor): never start gh or glab, nor reach the network. The checks run are local (git
|
|
317
|
+
// config, files, \`which\`); `platform-login` (gh or glab, which may reach the network) is judged by the record,
|
|
318
|
+
// like a step with no check. `noChecks` (done, skip): run none; the caller checks what it needs.
|
|
319
|
+
export const NO_PROGRAM_CHECKS = Object.freeze(['cli-version', 'ledger-hook', 'commit-signing', 'tool']);
|
|
320
|
+
export function localSetupState(root, { items = null, noProgram = false, noChecks = false } = {}) {
|
|
321
|
+
const read = readCommittedLocalSetup(root);
|
|
322
|
+
const record = readLocalSetupRecord(root);
|
|
323
|
+
const base = { committed: read.committed, record: { path: record.path, error: record.error } };
|
|
324
|
+
if (!read.doc) return { ...base, exists: read.error !== null, error: read.error, steps: [], problems: [] };
|
|
325
|
+
const { steps, problems } = readSteps(read.doc, { ours: oursFor(read.doc, root) });
|
|
326
|
+
// The file says which catalogue wrote it, and whoever writes the file can say anything: the reason is only a
|
|
327
|
+
// possibility, and never softens "not vetted".
|
|
328
|
+
const unknown = steps.filter((s) => s.source === 'yadflow' && !s.known);
|
|
329
|
+
if (unknown.length) problems.push(`${LOCAL_SETUP_FILE}: ${unknown.length} yadflow step(s) are not what this yadflow writes (${unknown.map((s) => s.id).join(', ')}) — not vetted${unknown.some((s) => s.otherRelease) ? '; the file says another yadflow version wrote it' : ''}; \`yad update\` rewrites them`);
|
|
330
|
+
let found = items;
|
|
331
|
+
const out = steps.map((s) => {
|
|
332
|
+
const answer = answerFor(record.entries, s);
|
|
333
|
+
const changed = !answer && Object.hasOwn(record.entries, s.id);
|
|
334
|
+
const mark = (state, why, more = {}) => ({ ...s, state, why, recorded: !!answer, changed: changed && state !== 'ok', seen: ['ok', 'done', 'skipped'].includes(state), ...more });
|
|
335
|
+
if (answer?.state === 'skipped') return mark('skipped', `you said no${answer.reason ? `: ${answer.reason}` : ''}`, { reason: answer.reason ?? null, at: answer.at ?? null });
|
|
336
|
+
const checked = !noChecks && s.source === 'yadflow' && s.known && s.check?.builtin && (!noProgram || NO_PROGRAM_CHECKS.includes(s.check.builtin));
|
|
337
|
+
if (!checked) {
|
|
338
|
+
if (answer?.state === 'done') return mark('done', 'you did it on this machine', { at: answer.at ?? null });
|
|
339
|
+
// A step yad did not write: its check is the file's too, so it never decides what the agent is told.
|
|
340
|
+
const why = s.source === 'yadflow' && !s.known ? 'it is not what this yadflow writes, so the person decides'
|
|
341
|
+
: s.check?.run ? 'yad does not run a team\'s check'
|
|
342
|
+
: s.check?.builtin ? 'not checked here — `yad local-setup` checks it' : 'it has no check';
|
|
343
|
+
return mark('ask', why);
|
|
344
|
+
}
|
|
345
|
+
if (s.check.builtin === 'tool' && !found) found = detectInstalled(root).items;
|
|
346
|
+
const r = runBuiltinCheck(s.check, root, { items: found });
|
|
347
|
+
return mark(r.ok ? 'ok' : 'pending', r.why);
|
|
348
|
+
});
|
|
349
|
+
return { ...base, exists: true, error: null, steps: out, problems };
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
const MARK = { ok: () => c.green('✓'), done: () => c.green('✓'), skipped: () => c.dim('–'), pending: () => c.yellow('•'), ask: () => c.cyan('?') };
|
|
353
|
+
const counts = (steps) => ({ pending: steps.filter((s) => s.state === 'pending').length, ask: steps.filter((s) => s.state === 'ask').length, skipped: steps.filter((s) => s.state === 'skipped').length });
|
|
354
|
+
|
|
355
|
+
// `yad local-setup [list] [--json]`. Reads only: runs yad's own checks, never a step.
|
|
356
|
+
export function runLocalSetupList(root, { json = false } = {}) {
|
|
357
|
+
const st = localSetupState(root);
|
|
358
|
+
const where = { product: root, file: LOCAL_SETUP_FILE };
|
|
359
|
+
if (!st.steps.length && (st.error || !st.exists)) {
|
|
360
|
+
const why = st.error ? `${LOCAL_SETUP_FILE} ${st.error}` : `this Product has no ${LOCAL_SETUP_FILE} yet`;
|
|
361
|
+
const hint = st.error ? 'fix the file, or restore it from git' : 'run `yad update` (it writes the script), then commit it through review';
|
|
362
|
+
if (json) return emitJSON({ ok: true, ...where, exists: st.exists, committed: st.committed, error: st.error, steps: [], pending: 0, ask: 0, skipped: 0, record: st.record, problems: st.error ? [why] : [], hint });
|
|
363
|
+
(st.error ? warn : info)(why);
|
|
364
|
+
info(hint);
|
|
365
|
+
return undefined;
|
|
366
|
+
}
|
|
367
|
+
const n = counts(st.steps);
|
|
368
|
+
if (json) {
|
|
369
|
+
return emitJSON({
|
|
370
|
+
ok: true, ...where, exists: true, committed: st.committed, error: null,
|
|
371
|
+
steps: st.steps.map(({ id, source, title, purpose, impact, when, commands, check, verify, person = false, known, otherRelease = false, vetted, addedBy = null, hash, state, why, recorded, changed, seen, reason = null, at = null }) => ({ id, source, title, purpose, impact, when, commands, check: check ?? null, verify: verify ?? null, person, known, otherRelease, vetted, addedBy, hash, state, why, recorded, changed, seen, reason, at })),
|
|
372
|
+
...n, record: st.record, problems: st.problems,
|
|
373
|
+
});
|
|
374
|
+
}
|
|
375
|
+
for (const p of st.problems) warn(p);
|
|
376
|
+
if (st.record.error) warn(recordWarning(st.record));
|
|
377
|
+
log(c.bold(`\nyad local-setup — ${st.steps.length} step(s): ${n.pending} not done here, ${n.ask} to check with you${n.skipped ? `, ${n.skipped} you said no to` : ''}`));
|
|
378
|
+
if (!st.committed) warn(`${LOCAL_SETUP_FILE} is not committed yet — this is the copy on disk`);
|
|
379
|
+
for (const s of st.steps) {
|
|
380
|
+
log(` ${MARK[s.state]()} ${c.bold(forTerminal(s.title))} ${c.dim(`(${s.id}, ${s.when}${s.source === 'team' ? ', from your team' : !s.known ? `, not vetted${s.otherRelease ? ' — possibly from another yadflow version' : ''}` : ''})`)}`);
|
|
381
|
+
if (s.state === 'ok' || s.state === 'done') continue;
|
|
382
|
+
if (s.state === 'skipped') { log(` ${c.dim(`you said no${s.reason ? `: ${forTerminal(s.reason)}` : ''} — \`yad local-setup done ${s.id}\` once you do it`)}`); continue; }
|
|
383
|
+
if (s.changed) log(` ${c.yellow('changed since this machine last answered for it')}`);
|
|
384
|
+
log(` ${c.dim(`why: ${forTerminal(s.purpose)}`)}`);
|
|
385
|
+
log(` ${c.dim(`changes for you: ${forTerminal(s.impact)}`)}`);
|
|
386
|
+
for (const cmd of s.commands) log(` ${c.dim(`run: ${forTerminal(cmd)}`)}`);
|
|
387
|
+
if (s.state === 'ask' && s.check?.run) log(` ${c.dim(`already done if this succeeds: ${forTerminal(s.check.run)}`)}`);
|
|
388
|
+
}
|
|
389
|
+
info(`the steps, with what each changes, are in ${LOCAL_SETUP_DOC}; \`yad local-setup list --json\` gives them to an agent`);
|
|
390
|
+
if (n.pending || n.ask) info('after each step: `yad local-setup done <id>`; to say no: `yad local-setup skip <id> --reason "<why>"`');
|
|
391
|
+
return undefined;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
// What `yad guide` and `yad doctor` say about this machine: the steps not yet answered for (`pending` and `ask`),
|
|
395
|
+
// or null when there are none. Cheap: no gh or glab, no network (NO_PROGRAM_CHECKS). Never
|
|
396
|
+
// throws: a script or record that cannot be read is an `error`, for the caller to show.
|
|
397
|
+
export function localSetupWaiting(root) {
|
|
398
|
+
let st;
|
|
399
|
+
try { st = localSetupState(root, { noProgram: true }); } catch (e) { return { pending: [], ask: [], changed: [], error: `could not read the steps (${e?.message ?? String(e)})`, recordError: null }; }
|
|
400
|
+
if (st.error) return { pending: [], ask: [], changed: [], error: `${LOCAL_SETUP_FILE} ${st.error}`, recordError: null };
|
|
401
|
+
const ids = (state) => st.steps.filter((s) => s.state === state).map((s) => s.id);
|
|
402
|
+
const w = { pending: ids('pending'), ask: ids('ask'), changed: st.steps.filter((s) => s.changed).map((s) => s.id), error: null, recordError: st.record.error };
|
|
403
|
+
return w.pending.length || w.ask.length || w.recordError ? w : null;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
// ---- answering for this machine: `yad local-setup done` and `skip` ------------------------------------
|
|
407
|
+
|
|
408
|
+
export const DONE_USAGE = 'usage: yad local-setup done <id>… [--json] | yad local-setup skip <id> --reason "<why>" [--json]';
|
|
409
|
+
const REASON_MAX = 500;
|
|
410
|
+
|
|
411
|
+
// The steps named, from the committed script, or a refusal (returned) — shared by `done` and `skip`. Read with no
|
|
412
|
+
// check run: `skip` needs none, and `done` runs only the named steps' own checks.
|
|
413
|
+
function stepsNamed(root, ids, verb, json) {
|
|
414
|
+
if (!ids.length) return { refused: refuse(`yad local-setup ${verb} needs a step id`, `${DONE_USAGE} — \`yad local-setup list\` shows the ids`, { json }) };
|
|
415
|
+
const st = localSetupState(root, { noChecks: true });
|
|
416
|
+
if (st.error) return { refused: refuse(`${LOCAL_SETUP_FILE} ${st.error}`, 'fix it, or restore it from git', { json }) };
|
|
417
|
+
if (!st.steps.length) return { refused: refuse(`this Product has no local setup steps (${LOCAL_SETUP_FILE})`, 'run `yad update` (it writes the script), then commit it through review', { json }) };
|
|
418
|
+
if (!st.record.path) return { refused: refuse(`${root} is not in a git clone, so this machine's answers have nowhere to go`, 'run it from your clone of the Product', { json }) };
|
|
419
|
+
if (st.record.error) return { refused: refuse(recordWarning(st.record), 'delete the file, then run this again', { json }) };
|
|
420
|
+
const byId = new Map(st.steps.map((x) => [x.id, x]));
|
|
421
|
+
const unknown = [...new Set(ids)].filter((id) => !byId.has(id));
|
|
422
|
+
if (unknown.length) return { refused: refuse(`not a step in ${LOCAL_SETUP_FILE}: ${unknown.map((id) => forTerminal(id)).join(', ')}`, '`yad local-setup list` shows the ids', { json }) };
|
|
423
|
+
return { steps: [...new Set(ids)].map((id) => byId.get(id)), st };
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
// `yad local-setup done <id>…`: the person did these steps on this machine. A step yad can check must pass its
|
|
427
|
+
// check first (the check, not the word, says it is done); every id passes or nothing is written.
|
|
428
|
+
export function runLocalSetupDone(root, { ids = [], json = false, now } = {}) {
|
|
429
|
+
const got = stepsNamed(root, ids, 'done', json);
|
|
430
|
+
if (got.refused !== undefined || !got.steps) return got.refused;
|
|
431
|
+
let found = null;
|
|
432
|
+
// Every named step yad can check is checked now, whatever the record says: a no given earlier never lets `done`
|
|
433
|
+
// stand in for a check that fails.
|
|
434
|
+
const failing = got.steps.filter((x) => x.source === 'yadflow' && x.known && x.check?.builtin)
|
|
435
|
+
.map((x) => ({ x, r: runBuiltinCheck(x.check, root, { items: x.check.builtin === 'tool' ? (found ??= detectInstalled(root).items) : null }) })).filter(({ r }) => !r.ok).map(({ x, r }) => ({ ...x, why: r.why }));
|
|
436
|
+
if (failing.length) {
|
|
437
|
+
return refuse(`not done on this machine yet: ${failing.map((x) => `${x.id} (${forTerminal(x.why)})`).join('; ')} — nothing was recorded`,
|
|
438
|
+
'finish the step, run its verify command, then run this again', { json, failing: failing.map((x) => ({ id: x.id, why: x.why })) });
|
|
439
|
+
}
|
|
440
|
+
const file = writeLocalSetupAnswers(root, got.steps.map((x) => ({ id: x.id, hash: x.hash, state: 'done' })), { now });
|
|
441
|
+
const done = got.steps.map((x) => x.id);
|
|
442
|
+
if (json) return emitJSON({ ok: true, product: root, done, record: file });
|
|
443
|
+
ok(`recorded on this machine: ${done.join(', ')} done`);
|
|
444
|
+
return { done, record: file };
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
// `yad local-setup skip <id> --reason "<why>"`: the person said no. It holds until the step changes.
|
|
448
|
+
export function runLocalSetupSkip(root, { ids = [], reason, json = false, now } = {}) {
|
|
449
|
+
if (ids.length > 1) return refuse('yad local-setup skip takes one step id: the reason is the person\'s, for that step', DONE_USAGE, { json });
|
|
450
|
+
const why = typeof reason === 'string' ? reason.replace(/\s+/g, ' ').trim() : '';
|
|
451
|
+
if (!why) return refuse('yad local-setup skip needs --reason "<why>": the person\'s own words, so the team can see why later', DONE_USAGE, { json });
|
|
452
|
+
if (why.length > REASON_MAX || forTerminal(why) !== why) return refuse(`the reason must be one plain line of at most ${REASON_MAX} characters`, DONE_USAGE, { json });
|
|
453
|
+
const got = stepsNamed(root, ids, 'skip', json);
|
|
454
|
+
if (got.refused !== undefined || !got.steps) return got.refused;
|
|
455
|
+
const [x] = got.steps;
|
|
456
|
+
const file = writeLocalSetupAnswers(root, [{ id: x.id, hash: x.hash, state: 'skipped', reason: why }], { now });
|
|
457
|
+
const required = x.when === 'required';
|
|
458
|
+
if (json) return emitJSON({ ok: true, product: root, skipped: x.id, reason: why, required, record: file });
|
|
459
|
+
ok(`recorded on this machine: ${x.id} skipped — it is asked again only when the step changes`);
|
|
460
|
+
if (required) warn(`${x.id} is marked required: ${forTerminal(x.purpose)}`);
|
|
461
|
+
info(`changed your mind? do the step, then \`yad local-setup done ${x.id}\``);
|
|
462
|
+
return { skipped: x.id, reason: why, required, record: file };
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
// ---- the team's steps (E185 part 3) -------------------------------------------------------------------
|
|
466
|
+
|
|
467
|
+
export const TEAM_USAGE = 'usage: yad local-setup add --from <step.json> [--json] · yad local-setup remove <id> [--json]';
|
|
468
|
+
// What a step file may hold. `source`, `vetted` and `addedBy` are yad's to set, never the file's.
|
|
469
|
+
const STEP_KEYS = Object.freeze(['id', 'title', 'purpose', 'impact', 'when', 'commands', 'check', 'verify', 'person']);
|
|
470
|
+
|
|
471
|
+
// The script as it is on disk, read strictly: a file that does not parse, or a `team` that is not a list, is
|
|
472
|
+
// refused, never replaced (read strictly before a write). A missing file is refused too: setup and update write
|
|
473
|
+
// it, with yadflow's steps, and add never writes yadflow's part (review 1). → { doc } | { error }
|
|
474
|
+
function workingScript(root) {
|
|
475
|
+
let text;
|
|
476
|
+
try { text = fs.readFileSync(localSetupPath(root), 'utf8'); } catch (e) { return { error: e.code === 'ENOENT' ? 'is not here yet — `yad check --fix` (or `yad update`) writes it' : 'cannot be read' }; }
|
|
477
|
+
let doc;
|
|
478
|
+
try { doc = parseJSON(text); } catch { return { error: 'does not parse' }; }
|
|
479
|
+
if (!isPlainObject(doc) || (doc.team !== undefined && !Array.isArray(doc.team)) || (doc.yadflow !== undefined && !Array.isArray(doc.yadflow))) return { error: 'is not the shape yad writes' };
|
|
480
|
+
return { doc };
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
// Write the team's list and nothing else: yadflow's part stays as it is on disk (an older or newer yad here must
|
|
484
|
+
// not rewrite it in a team's commit), and the view is made from that same file. Both are checked before either is
|
|
485
|
+
// written: a LOCAL-SETUP.md whose markers yad cannot trust refuses the change, so the JSON and the view never
|
|
486
|
+
// disagree (review 1). → null, or the reason nothing was written.
|
|
487
|
+
function writeTeam(root, doc, team) {
|
|
488
|
+
const next = { ...doc, team };
|
|
489
|
+
const view = markedBlockAction(root, LOCAL_SETUP_DOC, localSetupDocLines(next), { markers: LOCAL_SETUP_MARKERS, what: 'the local setup steps' });
|
|
490
|
+
if (view.writesNothing) return `${LOCAL_SETUP_DOC} cannot be updated (said above) — fix its markers (or delete both of them), then run this again`;
|
|
491
|
+
writeJSON(localSetupPath(root), next);
|
|
492
|
+
view.apply();
|
|
493
|
+
return null;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
// Ids yadflow keeps for its own steps, whatever this Product records today: a team step by one of these names
|
|
497
|
+
// would vanish the day yadflow writes its own (a platform set, a tool added) — so they are refused (review 1).
|
|
498
|
+
const YADFLOW_IDS = Object.freeze(['yadflow-cli', 'platform-login', 'ledger-hook', 'commit-signing']);
|
|
499
|
+
const yadflowsId = (id) => YADFLOW_IDS.includes(id) || id.startsWith('tool-');
|
|
500
|
+
|
|
501
|
+
const gitName = (root) => {
|
|
502
|
+
const r = spawnSync('git', ['config', 'user.name'], { cwd: root, encoding: 'utf8', windowsHide: true });
|
|
503
|
+
// Cut to 80 as stepProblems counts (string length), never inside a character pair.
|
|
504
|
+
let name = r.status === 0 ? r.stdout.replace(/\s+/g, ' ').trim() : '';
|
|
505
|
+
if (name.length > 80) { const chars = Array.from(name); while (chars.join('').length > 80) chars.pop(); name = chars.join(''); }
|
|
506
|
+
return name && plainLine(name) && !/<!--|--!?>/.test(name) ? name : null;
|
|
507
|
+
};
|
|
508
|
+
const scriptRefused = (error, json) => refuse(`${LOCAL_SETUP_FILE} ${error}, so it was not changed`, 'fix it, or restore it from git (`git checkout -- .sdlc/local-setup.json`), then run this again', { json });
|
|
509
|
+
|
|
510
|
+
export function runLocalSetupAdd(root, { from = null, json = false } = {}) {
|
|
511
|
+
if (typeof from !== 'string' || !from) return refuse('yad local-setup add needs --from <step.json>: one step, written as a JSON object', TEAM_USAGE, { json });
|
|
512
|
+
let raw;
|
|
513
|
+
// Relative to where yad was run. Only a plain file: a pipe or a device would wait forever.
|
|
514
|
+
const file = path.resolve(from);
|
|
515
|
+
try { if (!fs.statSync(file).isFile()) throw new Error('not a file'); raw = fs.readFileSync(file, 'utf8'); } catch { return refuse(`cannot read ${forTerminal(from)} as a file`, TEAM_USAGE, { json }); }
|
|
516
|
+
let given;
|
|
517
|
+
try { given = parseJSON(raw); } catch { return refuse(`${forTerminal(from)} does not parse as JSON`, TEAM_USAGE, { json }); }
|
|
518
|
+
if (!isPlainObject(given)) return refuse(`${forTerminal(from)} should hold one step: a JSON object`, TEAM_USAGE, { json });
|
|
519
|
+
const extra = Object.keys(given).filter((k) => !STEP_KEYS.includes(k));
|
|
520
|
+
if (extra.length) return refuse(`the step holds ${extra.map((k) => `\`${forTerminal(k)}\``).join(', ')}, which a step does not take — only ${STEP_KEYS.join(', ')} (source, vetted and addedBy are yad's to set)`, TEAM_USAGE, { json });
|
|
521
|
+
const step = { ...Object.fromEntries(STEP_KEYS.filter((k) => given[k] !== undefined).map((k) => [k, given[k]])), addedBy: gitName(root) };
|
|
522
|
+
const problems = stepProblems(step, 'team');
|
|
523
|
+
if (problems.length) return refuse(`the step cannot be added: ${problems.join('; ')}`, TEAM_USAGE, { json });
|
|
524
|
+
const words = [['title', step.title], ['purpose', step.purpose], ['impact', step.impact], ['verify', step.verify], ['check', step.check?.run], ...step.commands.map((x, i) => [`command ${i + 1}`, x])];
|
|
525
|
+
const secret = words.filter(([, w]) => looksSecret(w)).map(([k]) => k);
|
|
526
|
+
if (secret.length) return refuse(`the step's ${secret.join(', ')} looks like it holds a secret — a step is committed and shown to every member`, 'name where the value comes from instead (an environment variable such as $API_KEY, or the vault the team uses)', { json });
|
|
527
|
+
const w = workingScript(root);
|
|
528
|
+
if (w.error) return scriptRefused(w.error, json);
|
|
529
|
+
const team = Array.isArray(w.doc.team) ? w.doc.team : [];
|
|
530
|
+
const yadIds = new Set([...yadflowSteps(root).map((x) => x.id), ...(Array.isArray(w.doc.yadflow) ? w.doc.yadflow.map((x) => x?.id) : [])]);
|
|
531
|
+
if (yadIds.has(step.id) || yadflowsId(step.id)) return refuse(`\`${step.id}\` is kept for yadflow's own steps (${YADFLOW_IDS.join(', ')} and every tool-…) — pick another id`, null, { json });
|
|
532
|
+
const taken = team.find((x) => x?.id === step.id);
|
|
533
|
+
if (taken) {
|
|
534
|
+
const ignored = stepProblems(taken, 'team').length > 0;
|
|
535
|
+
return refuse(`\`${step.id}\` is already one of your team's steps${ignored ? ' (one yad ignores now — `yad local-setup list` says why)' : ''} — \`yad local-setup remove ${step.id}\` first to replace it`, null, { json });
|
|
536
|
+
}
|
|
537
|
+
const blocked = writeTeam(root, w.doc, [...team, step]);
|
|
538
|
+
if (blocked) return refuse(`nothing was written: ${blocked}`, null, { json });
|
|
539
|
+
const files = [LOCAL_SETUP_FILE, LOCAL_SETUP_DOC];
|
|
540
|
+
if (json) return emitJSON({ ok: true, product: root, added: step.id, step, files });
|
|
541
|
+
ok(`added your team's step ${step.id} to ${LOCAL_SETUP_FILE} and ${LOCAL_SETUP_DOC}`);
|
|
542
|
+
info(`commit both so every member's agent offers it; until then \`yad local-setup list\` (which reads what is committed) does not show it — undo with \`yad local-setup remove ${step.id}\``);
|
|
543
|
+
return { added: step.id, step, files };
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
export function runLocalSetupRemove(root, { ids = [], json = false } = {}) {
|
|
547
|
+
if (ids.length !== 1) return refuse('yad local-setup remove takes one step id', TEAM_USAGE, { json });
|
|
548
|
+
const [id] = ids;
|
|
549
|
+
const w = workingScript(root);
|
|
550
|
+
if (w.error) return scriptRefused(w.error, json);
|
|
551
|
+
const team = Array.isArray(w.doc.team) ? w.doc.team : [];
|
|
552
|
+
if (!team.some((x) => x?.id === id)) {
|
|
553
|
+
const yad = yadflowSteps(root).some((x) => x.id === id);
|
|
554
|
+
return refuse(yad ? `\`${forTerminal(id)}\` is one of yadflow's steps, which come with each release — to say no to it on this machine, \`yad local-setup skip ${forTerminal(id)} --reason "<why>"\``
|
|
555
|
+
: `no team step \`${forTerminal(id)}\` in ${LOCAL_SETUP_FILE}`, null, { json });
|
|
556
|
+
}
|
|
557
|
+
const blocked = writeTeam(root, w.doc, team.filter((x) => x?.id !== id));
|
|
558
|
+
if (blocked) return refuse(`nothing was written: ${blocked}`, null, { json });
|
|
559
|
+
const files = [LOCAL_SETUP_FILE, LOCAL_SETUP_DOC];
|
|
560
|
+
if (json) return emitJSON({ ok: true, product: root, removed: id, files });
|
|
561
|
+
ok(`removed your team's step ${id} from ${LOCAL_SETUP_FILE} and ${LOCAL_SETUP_DOC}`);
|
|
562
|
+
info('commit both so every member\'s agent stops offering it');
|
|
563
|
+
return { removed: id, files };
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
// The warning for a record that cannot be read: it is read as empty, so every answer would be asked again.
|
|
567
|
+
const recordWarning = (r) => `local setup: this machine's record (${forTerminal(r.path)}) ${r.error} — read as empty, so every step is asked again; delete it, it only remembers your answers`;
|
|
568
|
+
|
|
569
|
+
// Whether the committed script holds any step of the team's own (valid or not), for setup's hint to the agent.
|
|
570
|
+
export const hasTeamSteps = (root) => { const d = readCommittedLocalSetup(root).doc; return Array.isArray(d?.team) && d.team.length > 0; };
|
|
571
|
+
|
|
572
|
+
// The few lines setup, update, check and join print about this machine. Never fails the command it is part of.
|
|
573
|
+
// Returns the part of that command's --json answer it adds: `{ pending, ask, unvetted, skipped, changed, error }`
|
|
574
|
+
// (step ids, and why the committed script could not be read, or null).
|
|
575
|
+
const EMPTY = Object.freeze({ pending: [], ask: [], unvetted: [], skipped: [], changed: [] });
|
|
576
|
+
export function localSetupSection(root, { invite = false } = {}) {
|
|
577
|
+
let st;
|
|
578
|
+
try { st = localSetupState(root); } catch (e) { warn(`local setup: could not read the steps (${forTerminal(e?.message ?? String(e))})`); return { ...EMPTY, error: 'could not read' }; }
|
|
579
|
+
if (st.error) { warn(`local setup: ${st.committed ? 'the committed ' : ''}${LOCAL_SETUP_FILE} ${st.error} — fix it (or restore it from git); \`yad local-setup\` says more`); return { ...EMPTY, error: st.error }; }
|
|
580
|
+
// A step the script holds but yad left out (it breaks a rule, or the list is not a list) is said here too, not
|
|
581
|
+
// only in `list` — even when it leaves no step at all (reviews 1, 2).
|
|
582
|
+
const ignored = st.problems.filter((p) => / is ignored — | is listed twice|should be a list — ignored/.test(p));
|
|
583
|
+
if (!st.steps.length) {
|
|
584
|
+
if (ignored.length) warn(`local setup: ${ignored.length} part(s) of ${LOCAL_SETUP_FILE} are left out because they break a rule — \`yad local-setup list\` says which and why`);
|
|
585
|
+
return { ...EMPTY, error: null };
|
|
586
|
+
}
|
|
587
|
+
if (st.record.error) warn(recordWarning(st.record));
|
|
588
|
+
const pending = st.steps.filter((s) => s.state === 'pending');
|
|
589
|
+
const ask = st.steps.filter((s) => s.state === 'ask');
|
|
590
|
+
const skipped = st.steps.filter((s) => s.state === 'skipped');
|
|
591
|
+
const changed = st.steps.filter((s) => s.changed);
|
|
592
|
+
// The `ask` steps under `yadflow` that yad did not write: printed apart, and `unvetted` in --json.
|
|
593
|
+
const strange = ask.filter((s) => s.source === 'yadflow' && !s.known);
|
|
594
|
+
log(c.bold('\nLocal setup (this machine)'));
|
|
595
|
+
if (!pending.length && !ask.length) log(skipped.length === st.steps.length ? ` ${c.dim('–')} you said no to every step` : ` ${c.green('✓')} all ${st.steps.length - skipped.length} step(s) you said yes to are done here`);
|
|
596
|
+
else {
|
|
597
|
+
if (pending.length) log(` ${c.yellow('•')} ${pending.length} step(s) are not done here: ${pending.map((s) => s.id).join(', ')}`);
|
|
598
|
+
const theirs = ask.filter((s) => s.source !== 'yadflow');
|
|
599
|
+
const unchecked = ask.filter((s) => s.source === 'yadflow' && s.known);
|
|
600
|
+
if (theirs.length) log(` ${c.cyan('?')} ${theirs.length} step(s) from your team, to check with you: ${theirs.map((s) => s.id).join(', ')}`);
|
|
601
|
+
if (unchecked.length) log(` ${c.cyan('?')} ${unchecked.length} step(s) yad cannot check, to check with you: ${unchecked.map((s) => s.id).join(', ')}`);
|
|
602
|
+
if (strange.length) log(` ${c.yellow('!')} ${strange.length} yadflow step(s) that are not what this yadflow writes — not vetted, to check with you: ${strange.map((s) => s.id).join(', ')}`);
|
|
603
|
+
if (changed.length) info(`${changed.length} of them changed since this machine last answered: ${changed.map((s) => s.id).join(', ')}`);
|
|
604
|
+
info(`see them with \`yad local-setup\` — each says why it is needed and what it changes for you (${LOCAL_SETUP_DOC})`);
|
|
605
|
+
}
|
|
606
|
+
if (skipped.length) info(c.dim(`${skipped.length} step(s) you said no to: ${skipped.map((s) => s.id).join(', ')}`));
|
|
607
|
+
if (ignored.length) warn(`local setup: ${ignored.length} part(s) of ${LOCAL_SETUP_FILE} are left out because they break a rule — \`yad local-setup list\` says which and why`);
|
|
608
|
+
// E185 part 3: on setup and update only, a team with no step of its own yet (and none left out) is told how.
|
|
609
|
+
if (invite && !ignored.length && !st.steps.some((s) => s.source === 'team')) info(c.dim('no steps from your team yet — add this project\'s own with `yad local-setup add --from <step.json>`, or ask the agent to propose them'));
|
|
610
|
+
return { pending: pending.map((s) => s.id), ask: ask.map((s) => s.id), unvetted: strange.map((s) => s.id), skipped: skipped.map((s) => s.id), changed: changed.map((s) => s.id), error: null };
|
|
611
|
+
}
|
package/cli/machine.mjs
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
// need no Docker, so a repo that names none is never asked about.
|
|
9
9
|
// glab more than one glab config file. glab then reads only one and ignores the other (a login saved
|
|
10
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.
|
|
11
|
+
// and its errors together. yad's own glab calls drop that warning (`run` in cli/lib.mjs, #509).
|
|
12
12
|
import fs from 'node:fs';
|
|
13
13
|
import os from 'node:os';
|
|
14
14
|
import path from 'node:path';
|