yadflow 4.7.0 → 4.8.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 +89 -0
- package/README.md +43 -4
- package/bin/commands.mjs +4 -1
- package/bin/yad.mjs +147 -20
- package/cli/agent-guard.mjs +511 -0
- package/cli/agent-guide.mjs +83 -0
- package/cli/agent-rules.mjs +381 -0
- package/cli/argv-flags.mjs +7 -0
- package/cli/ci-check.mjs +492 -0
- package/cli/docs.mjs +1 -1
- package/cli/doctor.mjs +43 -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/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/plan.mjs +326 -22
- package/cli/protection.mjs +50 -0
- package/cli/reconcile.mjs +187 -26
- package/cli/report.mjs +62 -14
- package/cli/setup.mjs +244 -25
- package/cli/signing.mjs +377 -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-node.mjs +129 -0
- package/cli/test-setup-agent.mjs +352 -0
- package/cli/test-signing.mjs +524 -0
- package/cli/toolbox.mjs +1 -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-repos/SKILL.md +5 -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 +12 -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 +1 -1
- package/skills/yad-guide/SKILL.md +192 -0
- package/skills/yad-open-pr/SKILL.md +1 -1
- package/skills/yad-pair-review/SKILL.md +14 -5
- 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 +5 -3
- 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-sync-repos/SKILL.md +2 -1
- package/skills/yad-ui/SKILL.md +2 -2
|
@@ -0,0 +1,511 @@
|
|
|
1
|
+
// The agent guard (E158): a hook that runs before an AI agent's shell command, in Claude Code (`PreToolUse`,
|
|
2
|
+
// matcher `Bash`) and Cursor (`beforeShellExecution`), and refuses four kinds of command:
|
|
3
|
+
// - a yad command only the person may run (`classify` in cli/agent-rules.mjs says `human-only`: an
|
|
4
|
+
// approval, a gate comment or advance or reopen, a commit past the ledger guard);
|
|
5
|
+
// - approving or merging a PR/MR on the platform (`gh pr review --approve`, `gh pr merge`, `glab mr approve`,
|
|
6
|
+
// `glab mr merge` or `accept`, or the same through `gh api`/`glab api` and GraphQL): the person's, even
|
|
7
|
+
// when the agent's login could;
|
|
8
|
+
// - a force push (`git push --force`, `-f`, `--force-with-lease`, `--force-if-includes`, `--mirror`, a `+`
|
|
9
|
+
// refspec);
|
|
10
|
+
// - skipping the git hooks, the ledger guard's door (`git commit --no-verify` or `-n`, `YAD_HOOK_DISABLE=…`,
|
|
11
|
+
// `git -c core.hooksPath=…`, `git config core.hooksPath <path>`): the person's, through `yad commit --manual`.
|
|
12
|
+
// The refusal says what to do instead: ask the person to run it themselves (`! <command>` in Claude Code).
|
|
13
|
+
//
|
|
14
|
+
// A SPEED BUMP, NOT PROOF. It reads the command line the agent sends, so a command hidden in a script, an
|
|
15
|
+
// alias or `eval` is not seen; Codex has no hooks at all. What proves an approval is the platform (and CI's
|
|
16
|
+
// ledger guard). The rules in AGENTS.md are what the agent follows; this catches the plain mistake.
|
|
17
|
+
//
|
|
18
|
+
// FAIL-OPEN, like the ledger guard: a payload it cannot read, or no command in it, is allowed.
|
|
19
|
+
import { classify } from './agent-rules.mjs';
|
|
20
|
+
import { VALUE_FLAGS, LIST_FLAGS } from './argv-flags.mjs';
|
|
21
|
+
|
|
22
|
+
// A heredoc's `<<` and its end word: bare (`EOF`), quoted (`'EOF'`, `"EOF"`, `E"OF"`) or escaped (`\EOF`). Any
|
|
23
|
+
// quote or `\` in the word makes the text plain text, as bash reads it: nothing in it runs.
|
|
24
|
+
const HEREDOC = /^<<(-?)[ \t]*((?:\\.|'[^'\n]*'|"[^"\n]*"|[A-Za-z0-9_.-])+)/;
|
|
25
|
+
const heredocOf = (m) => ({ word: m[2].replace(/\\(.)|['"]/g, '$1'), tabs: m[1] === '-', quoted: /['"\\]/.test(m[2]) });
|
|
26
|
+
|
|
27
|
+
// One command line split into its simple commands: on `;`, `&`, `&&`, `||`, `|` and newlines, outside
|
|
28
|
+
// quotes. Each part is a list of words, with quotes removed and `\` escapes applied. Read as the shell reads it
|
|
29
|
+
// in the ways an agent's commands use most: a `\` at the end of a line joins the next line on, a `#` that
|
|
30
|
+
// starts a word begins a comment, and the body of a heredoc (`cat > notes.md <<EOF` … `EOF`) is text fed to a
|
|
31
|
+
// command, never commands. A `<<` whose end line never comes (an arithmetic shift, `$((1<<2))`) is not a
|
|
32
|
+
// heredoc: nothing after it is skipped. `<<<` is a here-string, one word of text. A command substitution
|
|
33
|
+
// (`$(…)` or backticks, outside single quotes) stays inside its word, and its text is also kept in
|
|
34
|
+
// `parts.subs`, so the caller judges the command it runs: `r=$(yad gate approve …)` runs an approval. Quotes
|
|
35
|
+
// inside it are its own (`"$(cat <<'EOF' … EOF)"` holds any `"` in the heredoc's text).
|
|
36
|
+
export function shellParts(line) {
|
|
37
|
+
const parts = [];
|
|
38
|
+
// Not enumerable: `parts` reads as the plain list of parts it always was.
|
|
39
|
+
Object.defineProperty(parts, 'subs', { value: [] });
|
|
40
|
+
let words = [];
|
|
41
|
+
let word = '';
|
|
42
|
+
let inWord = false;
|
|
43
|
+
let quote = null;
|
|
44
|
+
const heredocs = [];
|
|
45
|
+
const endWord = () => { if (inWord) words.push(word); word = ''; inWord = false; };
|
|
46
|
+
const endPart = () => { endWord(); if (words.length) parts.push(words); words = []; };
|
|
47
|
+
// Where the heredocs opened on this line end: the index just past the last one's end line, or -1 when an end
|
|
48
|
+
// line never comes. The text of one whose end word is not quoted (`<<EOF`, not `<<'EOF'`) still runs its
|
|
49
|
+
// `$(…)` and backticks, so those go to `parts.subs`.
|
|
50
|
+
const heredocsEnd = (from) => {
|
|
51
|
+
let at = from;
|
|
52
|
+
const bodies = [];
|
|
53
|
+
for (const h of heredocs) {
|
|
54
|
+
const start = at;
|
|
55
|
+
for (;;) {
|
|
56
|
+
if (at > line.length) return -1;
|
|
57
|
+
const eol = line.indexOf('\n', at);
|
|
58
|
+
const text = line.slice(at, eol < 0 ? line.length : eol).replace(/\r$/, '');
|
|
59
|
+
const lineStart = at;
|
|
60
|
+
at = eol < 0 ? line.length + 1 : eol + 1;
|
|
61
|
+
if ((h.tabs ? text.replace(/^\t+/, '') : text) === h.word) { if (!h.quoted) bodies.push(line.slice(start, lineStart)); break; }
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
for (const body of bodies) parts.subs.push(...substitutionsIn(body));
|
|
65
|
+
return at;
|
|
66
|
+
};
|
|
67
|
+
for (let i = 0; i < line.length; i++) {
|
|
68
|
+
const ch = line[i];
|
|
69
|
+
// A command substitution, unquoted or in double quotes (single quotes keep it as text).
|
|
70
|
+
if (quote !== '\'' && ((ch === '$' && line[i + 1] === '(') || ch === '`')) {
|
|
71
|
+
const end = ch === '`' ? backtickEnd(line, i + 1) : substitutionEnd(line, i + 2);
|
|
72
|
+
parts.subs.push(ch === '`' ? line.slice(i + 1, end).replace(/\\`/g, '`') : line.slice(i + 2, end));
|
|
73
|
+
word += line.slice(i, end + 1); inWord = true;
|
|
74
|
+
i = end;
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
if (quote) {
|
|
78
|
+
if (ch === quote) quote = null;
|
|
79
|
+
else if (ch === '\\' && quote === '"' && line[i + 1] === '\n') i++;
|
|
80
|
+
else if (ch === '\\' && quote === '"' && i + 1 < line.length) word += line[++i];
|
|
81
|
+
else word += ch;
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
84
|
+
if (ch === '\'' || ch === '"') { quote = ch; inWord = true; continue; }
|
|
85
|
+
if (ch === '\\' && line[i + 1] === '\n') { i++; continue; }
|
|
86
|
+
if (ch === '\\' && line[i + 1] === '\r' && line[i + 2] === '\n') { i += 2; continue; }
|
|
87
|
+
if (ch === '\\' && i + 1 < line.length) { word += line[++i]; inWord = true; continue; }
|
|
88
|
+
if (ch === '#' && !inWord) { while (i + 1 < line.length && line[i + 1] !== '\n') i++; continue; }
|
|
89
|
+
if (ch === '<' && line[i + 1] === '<' && line[i + 2] === '<') { endWord(); i += 2; continue; }
|
|
90
|
+
if (ch === '<' && line[i + 1] === '<') {
|
|
91
|
+
// A heredoc: its delimiter, bare or quoted, with `<<-` stripping leading tabs from the lines.
|
|
92
|
+
const m = HEREDOC.exec(line.slice(i));
|
|
93
|
+
if (m) { heredocs.push(heredocOf(m)); endWord(); i += m[0].length - 1; continue; }
|
|
94
|
+
}
|
|
95
|
+
if (ch === '\n' && heredocs.length) {
|
|
96
|
+
endPart();
|
|
97
|
+
const at = heredocsEnd(i + 1);
|
|
98
|
+
heredocs.length = 0;
|
|
99
|
+
// No end line: not a heredoc after all, so the next lines are read as commands.
|
|
100
|
+
if (at >= 0) i = at - 1 - 1;
|
|
101
|
+
continue;
|
|
102
|
+
}
|
|
103
|
+
if (ch === '\n' || ch === ';' || ch === '&' || ch === '|') { endPart(); continue; }
|
|
104
|
+
if (ch === ' ' || ch === '\t' || ch === '\r') { endWord(); continue; }
|
|
105
|
+
word += ch; inWord = true;
|
|
106
|
+
}
|
|
107
|
+
endPart();
|
|
108
|
+
return parts;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// Where the `$(` whose text starts at `from` closes: the index of its `)`, or the end of the line when it never
|
|
112
|
+
// closes. Quotes, nested `(…)` and a heredoc's text inside it are its own, so a `)` in them does not close it.
|
|
113
|
+
function substitutionEnd(line, from) {
|
|
114
|
+
let depth = 1;
|
|
115
|
+
let quote = null;
|
|
116
|
+
const heredocs = [];
|
|
117
|
+
for (let i = from; i < line.length; i++) {
|
|
118
|
+
const ch = line[i];
|
|
119
|
+
if (quote) {
|
|
120
|
+
if (ch === quote) quote = null;
|
|
121
|
+
else if (ch === '\\' && quote === '"') i++;
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
if (ch === '\\') { i++; continue; }
|
|
125
|
+
if (ch === '\'' || ch === '"') { quote = ch; continue; }
|
|
126
|
+
if (ch === '<' && line[i + 1] === '<' && line[i + 2] !== '<') {
|
|
127
|
+
const m = HEREDOC.exec(line.slice(i));
|
|
128
|
+
if (m) { heredocs.push(heredocOf(m)); i += m[0].length - 1; continue; }
|
|
129
|
+
}
|
|
130
|
+
if (ch === '\n' && heredocs.length) {
|
|
131
|
+
// Skip each heredoc's text to its end line; one that never ends is not a heredoc.
|
|
132
|
+
let at = i + 1;
|
|
133
|
+
let found = true;
|
|
134
|
+
for (const h of heredocs) {
|
|
135
|
+
for (;;) {
|
|
136
|
+
if (at > line.length) { found = false; break; }
|
|
137
|
+
const eol = line.indexOf('\n', at);
|
|
138
|
+
const text = line.slice(at, eol < 0 ? line.length : eol).replace(/\r$/, '');
|
|
139
|
+
at = eol < 0 ? line.length + 1 : eol + 1;
|
|
140
|
+
if ((h.tabs ? text.replace(/^\t+/, '') : text) === h.word) break;
|
|
141
|
+
}
|
|
142
|
+
if (!found) break;
|
|
143
|
+
}
|
|
144
|
+
heredocs.length = 0;
|
|
145
|
+
if (found) i = at - 2;
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
if (ch === '(') depth++;
|
|
149
|
+
else if (ch === ')' && --depth === 0) return i;
|
|
150
|
+
}
|
|
151
|
+
return line.length;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// The commands of every `$(…)` and backticks in a heredoc's text, where quotes are plain characters and `\`
|
|
155
|
+
// keeps the next one as text.
|
|
156
|
+
function substitutionsIn(text) {
|
|
157
|
+
const out = [];
|
|
158
|
+
for (let i = 0; i < text.length; i++) {
|
|
159
|
+
const ch = text[i];
|
|
160
|
+
if (ch === '\\') { i++; continue; }
|
|
161
|
+
if ((ch === '$' && text[i + 1] === '(') || ch === '`') {
|
|
162
|
+
const end = ch === '`' ? backtickEnd(text, i + 1) : substitutionEnd(text, i + 2);
|
|
163
|
+
out.push(ch === '`' ? text.slice(i + 1, end).replace(/\\`/g, '`') : text.slice(i + 2, end));
|
|
164
|
+
i = end;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
return out;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// Where the backtick whose text starts at `from` closes, or the end of the line.
|
|
171
|
+
function backtickEnd(line, from) {
|
|
172
|
+
for (let i = from; i < line.length; i++) {
|
|
173
|
+
if (line[i] === '\\') i++;
|
|
174
|
+
else if (line[i] === '`') return i;
|
|
175
|
+
}
|
|
176
|
+
return line.length;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
// Words that only set up how a command runs, skipped to find the command itself: `env`, `VAR=value`, `sudo`,
|
|
180
|
+
// `command`, `exec`, `time`, `nohup`, `nice`, `timeout` with its duration, the shell's own words (`then`, `do`,
|
|
181
|
+
// `else`, `{`, `!`), `xargs`, `stdbuf`, `watch`, and a `(` stuck to the front of the first word. The options of a prefix are skipped with
|
|
182
|
+
// it, and the value of one that takes a value (`sudo -u <user>`, `nice -n <n>`, `env -u <name>`).
|
|
183
|
+
const PREFIXES = new Set(['env', 'sudo', 'command', 'exec', 'time', 'nohup', 'nice', 'xargs', 'stdbuf', 'watch', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', '{', '!']);
|
|
184
|
+
const PREFIX_VALUE_OPTIONS = new Set(['-u', '-g', '-n', '-C', '-h', '-U', '-r', '-t', '-s', '-k', '-o', '--user', '--group', '--signal',
|
|
185
|
+
'--kill-after', '--unset', '--chdir', '--adjustment', '--output']);
|
|
186
|
+
// A prefix whose letters mean something else (`xargs -r` and `-t` take no value, `sudo -E` none either) reads
|
|
187
|
+
// only its own options that take a value, never the shared list.
|
|
188
|
+
const PREFIX_OWN_VALUE_OPTIONS = {
|
|
189
|
+
// `-J`, `-R` and `-S` are the BSD (macOS) xargs's.
|
|
190
|
+
xargs: new Set(['-n', '-s', '-I', '-L', '-P', '-d', '-E', '-a', '-J', '-R', '-S', '--replace', '--max-lines', '--max-args', '--max-chars',
|
|
191
|
+
'--max-procs', '--delimiter', '--arg-file', '--eof']),
|
|
192
|
+
stdbuf: new Set(['-i', '-o', '-e', '--input', '--output', '--error']),
|
|
193
|
+
watch: new Set(['-n', '--interval']),
|
|
194
|
+
};
|
|
195
|
+
const stripPrefix = (words) => {
|
|
196
|
+
const w = words.slice();
|
|
197
|
+
if (w.length && w[0].startsWith('(')) w[0] = w[0].replace(/^\(+/, '');
|
|
198
|
+
let i = 0;
|
|
199
|
+
for (;;) {
|
|
200
|
+
while (i < w.length && w[i] === '') i++;
|
|
201
|
+
if (i < w.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[i])) { i++; continue; }
|
|
202
|
+
if (i < w.length && (PREFIXES.has(w[i]) || w[i] === 'timeout')) {
|
|
203
|
+
const isTimeout = w[i] === 'timeout';
|
|
204
|
+
const own = PREFIX_OWN_VALUE_OPTIONS[w[i]];
|
|
205
|
+
i++;
|
|
206
|
+
const valued = own || PREFIX_VALUE_OPTIONS;
|
|
207
|
+
while (i < w.length && w[i].startsWith('-')) i += valued.has(w[i]) ? 2 : 1;
|
|
208
|
+
if (isTimeout) i++; // the duration
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
return w.slice(i);
|
|
212
|
+
}
|
|
213
|
+
};
|
|
214
|
+
const programOf = (word) => word.split(/[\\/]/).pop().replace(/\.(exe|cmd)$/i, '');
|
|
215
|
+
|
|
216
|
+
// How package runners start a program. `npx [-y] yadflow[@v] …` or `npx yad …` (and pnpx, bunx), `npx -p
|
|
217
|
+
// yadflow yad …`, `npm [opts] exec|x yadflow|yad -- …`, `pnpm [opts] exec|dlx …`, `pnpm yad …`, `yarn [opts]
|
|
218
|
+
// [workspace <name>] [exec|dlx|run] yad …`, `bun x|run yad …`. `yad` is the program the yadflow package
|
|
219
|
+
// installs, so a local install runs it as `npx yad`.
|
|
220
|
+
const NODE_VALUE_OPTIONS = new Set(['-r', '--require', '--import', '--loader', '--experimental-loader', '-e', '--eval', '-p', '--print', '--input-type', '--conditions', '-C',
|
|
221
|
+
'--env-file', '--env-file-if-exists', '--watch-path']);
|
|
222
|
+
const NPX_VALUE_OPTIONS = new Set(['-p', '--package', '-c', '--call', '--cache', '--registry', '--userconfig', '--prefix']);
|
|
223
|
+
// The options that take a value and may come before the subcommand or the program (`pnpm -C x yad …`,
|
|
224
|
+
// `npm -w web exec …`). pnpm's `-c` is `--shell-mode` and its `-w` is `--workspace-root`: neither takes one.
|
|
225
|
+
const RUNNER_VALUE_OPTIONS = new Set([...NPX_VALUE_OPTIONS, '-C', '--dir', '--cwd', '--filter', '-F', '--workspace', '-w',
|
|
226
|
+
'--filter-prod', '--loglevel', '--reporter', '--workspace-concurrency', '--include', '--exclude', '--from', '-j', '--jobs']);
|
|
227
|
+
const PNPM_VALUE_OPTIONS = new Set([...RUNNER_VALUE_OPTIONS].filter((o) => o !== '-c' && o !== '-w'));
|
|
228
|
+
// bun's own options that take a value (`bun --env-file .env run …`).
|
|
229
|
+
const BUN_VALUE_OPTIONS = new Set([...RUNNER_VALUE_OPTIONS, '--env-file', '--preload', '-r', '--config', '-e', '--eval', '--tsconfig-override']);
|
|
230
|
+
const isYadflow = (x) => /^yadflow(@.*)?$/.test(x);
|
|
231
|
+
const dropDashDash = (args) => (args[0] === '--' ? args.slice(1) : args);
|
|
232
|
+
// The first plain word of `w` at or after `from`, past options and the value of an option that takes one.
|
|
233
|
+
const plainAfter = (w, from, valued) => {
|
|
234
|
+
let i = from;
|
|
235
|
+
while (i < w.length && w[i].startsWith('-')) i += valued.has(w[i]) ? 2 : 1;
|
|
236
|
+
return i;
|
|
237
|
+
};
|
|
238
|
+
|
|
239
|
+
// A package runner's parts: `{prog, start, valued}`, where `start` is the index its options before the program
|
|
240
|
+
// begin at (just past `exec`, `dlx`, `run`, `x` or `workspace <name>`), or null when `w` is not a runner that
|
|
241
|
+
// starts a program.
|
|
242
|
+
function runnerOf(w) {
|
|
243
|
+
if (!w.length) return null;
|
|
244
|
+
const prog = programOf(w[0]);
|
|
245
|
+
const valued = prog === 'pnpm' ? PNPM_VALUE_OPTIONS : prog === 'bun' ? BUN_VALUE_OPTIONS : RUNNER_VALUE_OPTIONS;
|
|
246
|
+
if (prog === 'npx' || prog === 'pnpx' || prog === 'bunx') return { prog, start: 1, valued };
|
|
247
|
+
if (prog === 'bun') {
|
|
248
|
+
// bun's own options may come first: `bun --filter web run …`, `bun --bun x …`.
|
|
249
|
+
const k = plainAfter(w, 1, valued);
|
|
250
|
+
return w[k] === 'x' || w[k] === 'run' ? { prog, start: k + 1, valued, sub: w[k] } : null;
|
|
251
|
+
}
|
|
252
|
+
if (prog === 'npm') {
|
|
253
|
+
const k = plainAfter(w, 1, valued);
|
|
254
|
+
return w[k] === 'exec' || w[k] === 'x' ? { prog, start: k + 1, valued, sub: w[k] } : null;
|
|
255
|
+
}
|
|
256
|
+
if (prog === 'pnpm' || prog === 'yarn') {
|
|
257
|
+
let k = plainAfter(w, 1, valued);
|
|
258
|
+
// `yarn workspace <name> <program> …` runs the program in that workspace; `yarn workspaces foreach [opts]
|
|
259
|
+
// run|exec …` runs it in each one.
|
|
260
|
+
if (prog === 'yarn' && w[k] === 'workspace') k = plainAfter(w, k + 2, valued);
|
|
261
|
+
else if (prog === 'yarn' && w[k] === 'workspaces' && w[k + 1] === 'foreach') k = plainAfter(w, k + 2, valued);
|
|
262
|
+
const subs = prog === 'yarn' ? ['exec', 'dlx', 'run'] : ['exec', 'dlx'];
|
|
263
|
+
return subs.includes(w[k]) ? { prog, start: k + 1, valued, sub: w[k] } : { prog, start: k, valued };
|
|
264
|
+
}
|
|
265
|
+
return null;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// The command line a shell runs from its `-c` argument (`bash -c "yad gate approve …"`), or null. A package
|
|
269
|
+
// runner's `-c`/`--call` before its program is one too (`npx -c '<line>'`, `npm exec -c '<line>'`), and
|
|
270
|
+
// `pnpm exec|dlx -c` runs the rest of its words as a shell line. A program's own `-c` (`vitest -c x`) is not.
|
|
271
|
+
function shellC(words) {
|
|
272
|
+
const w = stripPrefix(words);
|
|
273
|
+
if (!w.length) return null;
|
|
274
|
+
const prog = programOf(w[0]);
|
|
275
|
+
if (['bash', 'sh', 'zsh', 'dash', 'ksh'].includes(prog)) {
|
|
276
|
+
const c = w.findIndex((x, n) => n > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(x));
|
|
277
|
+
return c > 0 && c + 1 < w.length ? w[c + 1] : null;
|
|
278
|
+
}
|
|
279
|
+
const r = runnerOf(w);
|
|
280
|
+
if (!r) return null;
|
|
281
|
+
if (r.prog === 'pnpm') {
|
|
282
|
+
if (r.sub !== 'exec' && r.sub !== 'dlx') return null;
|
|
283
|
+
// pnpm reads `-c` before or after `exec`: every option up to the program.
|
|
284
|
+
for (let i = 1; i < w.length; i++) {
|
|
285
|
+
if (w[i] === r.sub && i === r.start - 1) continue;
|
|
286
|
+
if (!w[i].startsWith('-')) return null;
|
|
287
|
+
if (w[i] === '-c' || w[i] === '--shell-mode') return i + 1 < w.length ? w.slice(i + 1).join(' ') : null;
|
|
288
|
+
if (r.valued.has(w[i])) i++;
|
|
289
|
+
}
|
|
290
|
+
return null;
|
|
291
|
+
}
|
|
292
|
+
if (!['npx', 'pnpx', 'npm'].includes(r.prog)) return null;
|
|
293
|
+
for (let i = r.start; i < w.length && w[i].startsWith('-'); i++) {
|
|
294
|
+
if (w[i] === '-c' || w[i] === '--call') return i + 1 < w.length ? w[i + 1] : null;
|
|
295
|
+
if (/^(--call|-c)=/.test(w[i])) return w[i].slice(w[i].indexOf('=') + 1);
|
|
296
|
+
if (r.valued.has(w[i])) i++;
|
|
297
|
+
}
|
|
298
|
+
return null;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
// The yad argv after the program, or null when the part does not run yad: `yad …` (any path, `yad.mjs` too),
|
|
302
|
+
// yadflow's `yad` through a package runner (`runnerOf`), or `node [options] …/yad.mjs …`.
|
|
303
|
+
function yadArgs(words) {
|
|
304
|
+
const w = stripPrefix(words);
|
|
305
|
+
if (!w.length) return null;
|
|
306
|
+
const prog = programOf(w[0]);
|
|
307
|
+
if (prog === 'yad' || prog === 'yad.mjs') return w.slice(1);
|
|
308
|
+
const r = runnerOf(w);
|
|
309
|
+
if (r) {
|
|
310
|
+
const i = plainAfter(w, r.start, r.valued);
|
|
311
|
+
return i < w.length && (isYadflow(w[i]) || programOf(w[i]) === 'yad') ? dropDashDash(w.slice(i + 1)) : null;
|
|
312
|
+
}
|
|
313
|
+
if (prog === 'node') {
|
|
314
|
+
const i = plainAfter(w, 1, NODE_VALUE_OPTIONS);
|
|
315
|
+
return i < w.length && programOf(w[i]) === 'yad.mjs' ? w.slice(i + 1) : null;
|
|
316
|
+
}
|
|
317
|
+
return null;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
// The command words and flag names of yad's argv, read as bin/yad.mjs reads it: flags may come anywhere, a
|
|
321
|
+
// flag that takes a value (`--dir <path>`, `-m <text>`) takes the word after it, and `--` is a word like any
|
|
322
|
+
// other (yad has no end-of-flags marker). `help` is set for `--help`/`-h`: that run only prints the help.
|
|
323
|
+
function yadWords(args) {
|
|
324
|
+
const words = [];
|
|
325
|
+
const flags = [];
|
|
326
|
+
let help = false;
|
|
327
|
+
for (let i = 0; i < args.length; i++) {
|
|
328
|
+
const a = args[i];
|
|
329
|
+
if (a === '-h' || a === '--help') { help = true; continue; }
|
|
330
|
+
if (a.startsWith('--') && a !== '--') {
|
|
331
|
+
const name = a.split('=')[0];
|
|
332
|
+
flags.push(name.slice(2));
|
|
333
|
+
if (!a.includes('=') && (VALUE_FLAGS.has(name) || LIST_FLAGS.has(name))) i++;
|
|
334
|
+
} else if (a === '-m') i++;
|
|
335
|
+
else if (a.startsWith('-') && a !== '--') continue;
|
|
336
|
+
else if (words.length < 2) words.push(a);
|
|
337
|
+
}
|
|
338
|
+
return { words, flags, help };
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
// The git subcommand and its arguments, past git's own options (`-C <dir>`, `-c <k=v>`, `--git-dir <dir>`, …).
|
|
342
|
+
const GIT_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env']);
|
|
343
|
+
function gitArgs(words) {
|
|
344
|
+
const w = stripPrefix(words);
|
|
345
|
+
if (!w.length || programOf(w[0]) !== 'git') return null;
|
|
346
|
+
let i = 1;
|
|
347
|
+
while (i < w.length && w[i].startsWith('-')) i += GIT_VALUE_OPTIONS.has(w[i]) ? 2 : 1;
|
|
348
|
+
return w.slice(i);
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
// Is this part a force push? `git push … --force | -f | --force-with-lease[=…] | --force-if-includes | a refspec
|
|
352
|
+
// starting with `+`` | --mirror. The value of an option that takes one (`-o <text>`) is text, never a refspec.
|
|
353
|
+
const PUSH_VALUE_OPTIONS = new Set(['-o', '--push-option', '--repo', '--receive-pack', '--exec']);
|
|
354
|
+
function forcePush(words) {
|
|
355
|
+
const g = gitArgs(words);
|
|
356
|
+
if (!g || g[0] !== 'push' || g.includes('--help') || g.includes('-h')) return false;
|
|
357
|
+
for (let i = 1; i < g.length; i++) {
|
|
358
|
+
const a = g[i];
|
|
359
|
+
if (PUSH_VALUE_OPTIONS.has(a)) { i++; continue; }
|
|
360
|
+
// `--mirror` makes the remote match this clone: it overwrites and deletes refs there, as a force push does.
|
|
361
|
+
if (a === '--force' || a === '--mirror' || a === '--force-if-includes' || /^--force-with-lease(=|$)/.test(a)
|
|
362
|
+
|| (/^-[A-Za-z]+$/.test(a) && a.includes('f')) || /^\+/.test(a)) return true;
|
|
363
|
+
}
|
|
364
|
+
return false;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
// Does this part skip the git hooks, the ledger guard's door? `git commit --no-verify` or `-n` (alone or in a
|
|
368
|
+
// cluster such as `-nm`), `git -c core.hooksPath=… <any>`, `git config [scope] core.hooksPath <path>`, or `YAD_HOOK_DISABLE=…` set for the command or
|
|
369
|
+
// exported. That is what `yad commit --manual` does, with the reason recorded: the person's.
|
|
370
|
+
const COMMIT_VALUE_OPTIONS = new Set(['-m', '--message', '-F', '--file', '-t', '--template', '-c', '--reedit-message', '-C',
|
|
371
|
+
'--reuse-message', '--author', '--date', '--fixup', '--squash', '--trailer', '--cleanup']);
|
|
372
|
+
function hookSkip(words) {
|
|
373
|
+
const w = stripPrefix(words);
|
|
374
|
+
const lead = words.slice(0, words.length - w.length);
|
|
375
|
+
const disables = (x) => /^YAD_HOOK_DISABLE=./.test(x);
|
|
376
|
+
if (lead.some(disables)) return true;
|
|
377
|
+
if (w.length && ['export', 'declare', 'typeset'].includes(w[0]) && w.slice(1).some(disables)) return true;
|
|
378
|
+
if (!w.length || programOf(w[0]) !== 'git') return false;
|
|
379
|
+
for (let i = 1; i < w.length && w[i].startsWith('-'); i++) {
|
|
380
|
+
if (w[i] === '-c' && /^core\.hookspath=/i.test(w[i + 1] || '')) return true;
|
|
381
|
+
if (GIT_VALUE_OPTIONS.has(w[i])) i++;
|
|
382
|
+
}
|
|
383
|
+
const g = gitArgs(words);
|
|
384
|
+
if (!g || g.includes('--help') || g.includes('-h')) return false;
|
|
385
|
+
// Setting it, not reading it: a value follows the key (`git config --unset core.hooksPath` puts it back).
|
|
386
|
+
if (g[0] === 'config') {
|
|
387
|
+
const k = g.findIndex((x) => /^core\.hookspath$/i.test(x));
|
|
388
|
+
return k > 0 && k + 1 < g.length && !g.slice(1, k).some((x) => /^--(unset|unset-all|get|get-all|get-regexp)$/.test(x));
|
|
389
|
+
}
|
|
390
|
+
if (g[0] !== 'commit') return false;
|
|
391
|
+
for (let i = 1; i < g.length; i++) {
|
|
392
|
+
const a = g[i];
|
|
393
|
+
if (a === '--') break;
|
|
394
|
+
if (COMMIT_VALUE_OPTIONS.has(a)) { i++; continue; }
|
|
395
|
+
if (a === '--no-verify') return true;
|
|
396
|
+
if (/^-[A-Za-z]+$/.test(a)) {
|
|
397
|
+
// A short cluster: the letters up to the first one that takes a value (`-mn` is `-m n`, `-uno` is `-u no`).
|
|
398
|
+
for (const c of a.slice(1)) {
|
|
399
|
+
if (c === 'n') return true;
|
|
400
|
+
if ('mFtcCuS'.includes(c)) break;
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
}
|
|
404
|
+
return false;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
// Is this part an approval or a merge of a PR/MR on the platform? `gh pr review … --approve|-a`, `gh pr merge`,
|
|
408
|
+
// `glab mr approve`, `glab mr merge` (or `accept`), and the same through the API: a PUT to `gh api …/pulls/<n>/merge`
|
|
409
|
+
// (a plain GET there only asks whether it was merged), an approving review (`…/pulls/<n>/reviews` with
|
|
410
|
+
// `event=APPROVE`), a PUT to `glab api …/merge_requests/<n>/merge` or a POST to `…/approve`, and the GraphQL merge
|
|
411
|
+
// and approve mutations. The person's, even when the agent's login could do it. The options
|
|
412
|
+
// that take a value (`-R <repo>`) are skipped with it, so `gh -R o/r pr merge 5` is read as `pr merge`.
|
|
413
|
+
const PLATFORM_VALUE_OPTIONS = new Set(['-R', '--repo', '-b', '--body', '-F', '--body-file', '-t', '--subject', '-m', '--message', '--match-head-commit', '--author-email', '--sha',
|
|
414
|
+
'-f', '--field', '--raw-field', '-X', '--method', '-H', '--header', '--input', '-q', '--jq', '--template', '--hostname', '--cache']);
|
|
415
|
+
// The HTTP method of a `gh api`/`glab api` call: `-X PUT`, `-XPUT`, `--method PUT` or `--method=PUT`; else POST
|
|
416
|
+
// when fields are sent, as both tools do; else GET.
|
|
417
|
+
function apiMethod(w) {
|
|
418
|
+
for (let i = 1; i < w.length; i++) {
|
|
419
|
+
if ((w[i] === '-X' || w[i] === '--method') && i + 1 < w.length) return w[i + 1].toUpperCase();
|
|
420
|
+
const m = /^(?:-X=?|--method=)(.+)$/.exec(w[i]);
|
|
421
|
+
if (m) return m[1].toUpperCase();
|
|
422
|
+
}
|
|
423
|
+
return w.some((x) => /^(-f|-F|--field|--raw-field|--input)$/.test(x) || /^(--(raw-)?field=|-[fF].)/.test(x)) ? 'POST' : 'GET';
|
|
424
|
+
}
|
|
425
|
+
function apiApproval(prog, w, rest) {
|
|
426
|
+
if (rest[0] !== 'api') return false;
|
|
427
|
+
const path = rest[1] || '';
|
|
428
|
+
if (path === 'graphql') {
|
|
429
|
+
return w.some((x) => /\b(mergePullRequest|enablePullRequestAutoMerge|mergeRequestAccept|mergeRequestApprove)\b/.test(x)
|
|
430
|
+
|| /\b(addPullRequestReview|submitPullRequestReview)\b[\s\S]*\bAPPROVE\b/.test(x));
|
|
431
|
+
}
|
|
432
|
+
const method = apiMethod(w);
|
|
433
|
+
if (prog === 'glab') {
|
|
434
|
+
return (method === 'PUT' && /merge_requests\/\d+\/merge(\?|$)/.test(path))
|
|
435
|
+
|| (method === 'POST' && /merge_requests\/\d+\/approve(\?|$)/.test(path));
|
|
436
|
+
}
|
|
437
|
+
if (method === 'PUT' && /\/pulls\/\d+\/merge(\?|$)/.test(path)) return true;
|
|
438
|
+
return /\/pulls\/\d+\/reviews(\/\d+\/events)?(\?|$)/.test(path) && w.some((x) => /^(?:--(?:raw-)?field=|-[fF]=?)?event=APPROVE$/i.test(x));
|
|
439
|
+
}
|
|
440
|
+
function platformApproval(words) {
|
|
441
|
+
const w = stripPrefix(words);
|
|
442
|
+
if (!w.length || w.includes('--help') || w.includes('-h')) return false;
|
|
443
|
+
const prog = programOf(w[0]);
|
|
444
|
+
if (prog !== 'gh' && prog !== 'glab') return false;
|
|
445
|
+
const rest = [];
|
|
446
|
+
const options = [];
|
|
447
|
+
for (let i = 1; i < w.length; i++) {
|
|
448
|
+
if (w[i].startsWith('-')) { options.push(w[i]); if (PLATFORM_VALUE_OPTIONS.has(w[i])) i++; continue; }
|
|
449
|
+
rest.push(w[i]);
|
|
450
|
+
}
|
|
451
|
+
if (apiApproval(prog, w, rest)) return true;
|
|
452
|
+
if (prog === 'gh') {
|
|
453
|
+
if (rest[0] !== 'pr') return false;
|
|
454
|
+
// `--disable-auto` only turns auto-merge off: it merges nothing.
|
|
455
|
+
if (rest[1] === 'merge') return !options.includes('--disable-auto');
|
|
456
|
+
// An option, never an option's value (`--body "-a"` is text).
|
|
457
|
+
return rest[1] === 'review' && options.some((x) => /^--approve(=|$)/.test(x) || x === '-a');
|
|
458
|
+
}
|
|
459
|
+
// `glab mr accept` is `glab mr merge` by another name.
|
|
460
|
+
return rest[0] === 'mr' && ['approve', 'merge', 'accept'].includes(rest[1]);
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
// The verdict for one shell command line: `{allow: true}` or `{allow: false, message}`.
|
|
464
|
+
export function agentGuardDecision(line, depth = 0) {
|
|
465
|
+
if (typeof line !== 'string' || !line.trim()) return { allow: true };
|
|
466
|
+
const parts = shellParts(line);
|
|
467
|
+
// The commands a `$(…)` or backticks run are judged too (a few levels deep at most).
|
|
468
|
+
if (depth < 3) {
|
|
469
|
+
for (const sub of parts.subs) {
|
|
470
|
+
const v = agentGuardDecision(sub, depth + 1);
|
|
471
|
+
if (!v.allow) return v;
|
|
472
|
+
}
|
|
473
|
+
}
|
|
474
|
+
for (const part of parts) {
|
|
475
|
+
// `bash -c "<line>"`: the line it runs is judged too (a few levels deep at most).
|
|
476
|
+
const inner = shellC(part);
|
|
477
|
+
if (inner !== null && depth < 3) {
|
|
478
|
+
const v = agentGuardDecision(inner, depth + 1);
|
|
479
|
+
if (!v.allow) return v;
|
|
480
|
+
}
|
|
481
|
+
const args = yadArgs(part);
|
|
482
|
+
if (args) {
|
|
483
|
+
const { words, flags, help } = yadWords(args);
|
|
484
|
+
if (!help && classify(words, flags) === 'human-only') {
|
|
485
|
+
return { allow: false, message: `yad agent guard: \`yad ${words.join(' ')}${flags.includes('manual') ? ' --manual' : ''}\` is the person's to run, never the agent's (an approval, a gate comment or advance or reopen, or a commit past the ledger guard). Ask the person to run it themselves — in Claude Code they type it with \`!\` in front — then confirm by reading (\`yad gate status\` / \`yad guide --json\`).` };
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
if (platformApproval(part)) {
|
|
489
|
+
return { allow: false, message: 'yad agent guard: approving or merging a PR/MR is the person\'s, never the agent\'s (the yadflow rules), even when your login could. Give the person the link and the exact steps, wait, then confirm by reading (`yad gate status` / `yad guide --json`).' };
|
|
490
|
+
}
|
|
491
|
+
if (hookSkip(part)) {
|
|
492
|
+
return { allow: false, message: 'yad agent guard: skipping the git hooks (`--no-verify`, `-n`, `YAD_HOOK_DISABLE`, `core.hooksPath`) is the person\'s, never the agent\'s (the yadflow rules): it is the door past the ledger guard. When a hook refuses a commit, follow its message; if the commit must go through, the person runs `yad commit --manual --reason "<why>"` themselves (`!` in front in Claude Code).' };
|
|
493
|
+
}
|
|
494
|
+
if (forcePush(part)) {
|
|
495
|
+
return { allow: false, message: 'yad agent guard: a force push is never the agent\'s (the yadflow rules). Tell the person why the push was refused and what a force push would overwrite; if it is needed, they run it themselves.' };
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
return { allow: true };
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
// The shell command in a harness's payload: Claude Code's `tool_input.command` (tool `Bash`), Cursor's
|
|
502
|
+
// `command` (`beforeShellExecution`). Anything else is not a shell call: null.
|
|
503
|
+
export function payloadCommand(payload) {
|
|
504
|
+
if (!payload || typeof payload !== 'object') return null;
|
|
505
|
+
if (typeof payload.tool_input?.command === 'string') return payload.tool_input.command;
|
|
506
|
+
if (typeof payload.command === 'string') return payload.command;
|
|
507
|
+
return null;
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
// Cursor's payload names its event; Claude Code's says `PreToolUse`.
|
|
511
|
+
export const isCursorPayload = (payload) => payload?.hook_event_name === 'beforeShellExecution' || typeof payload?.cursor_version === 'string';
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// The generated sections of the `yad-guide` skill (E158), written from cli/agent-rules.mjs so the skill and
|
|
2
|
+
// the rules `yad guide --json` hands out cannot drift apart. Each section sits between two marker lines the
|
|
3
|
+
// skill holds; only the lines between them are ever replaced (`applyMarkedBlock`, the AGENTS.md block's
|
|
4
|
+
// rules). A test runs `scripts/agent-guide.mjs --check`, and fails when the skill and the rules disagree.
|
|
5
|
+
import fs from 'node:fs';
|
|
6
|
+
import { applyMarkedBlock } from './marked-block.mjs';
|
|
7
|
+
import { CLASSES, ASK, COMMAND_CLASS, RULES, NEVER, HUMAN_ONLY_ACTS, humanOnlyCommands } from './agent-rules.mjs';
|
|
8
|
+
|
|
9
|
+
export const GUIDE_SECTIONS = ['human-only', 'classes', 'never', 'rules'];
|
|
10
|
+
const begin = (name) => `<!-- generated: ${name} — from cli/agent-rules.mjs by scripts/agent-guide.mjs; do not edit by hand -->`;
|
|
11
|
+
const end = (name) => `<!-- end: ${name} -->`;
|
|
12
|
+
|
|
13
|
+
// What each "ask" answer means for the agent, in the words the skill uses.
|
|
14
|
+
const ASK_WORDS = {
|
|
15
|
+
never: 'run it without asking',
|
|
16
|
+
'each-time': 'ask the person every time, naming what it will do; run it only on a yes',
|
|
17
|
+
'per-dial': 'ask first, unless `yad dial open-pr` is `auto`',
|
|
18
|
+
'person-runs': 'never run it: give the person the exact command, wait, then confirm by reading',
|
|
19
|
+
'only-when-asked': 'run it only when the person asked for exactly this, or gave you what it records',
|
|
20
|
+
'not-by-agent': 'do not run it',
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
// Every command line of a class, as finished Markdown: the commands whose own class it is, and
|
|
24
|
+
// `<command> --<flag>` for each flag that raises a command to it.
|
|
25
|
+
function commandsOf(cls) {
|
|
26
|
+
const out = [];
|
|
27
|
+
for (const [key, e] of Object.entries(COMMAND_CLASS)) {
|
|
28
|
+
// A command whose flags raise it says which, so `yad dial` reads as "not with --to".
|
|
29
|
+
const raised = Object.entries(e.flags ?? {}).filter(([, c]) => c !== cls).map(([f]) => `\`--${f}\``);
|
|
30
|
+
if (e.class === cls) out.push(raised.length ? `\`yad ${key}\` (not with ${raised.join(', ')})` : `\`yad ${key}\``);
|
|
31
|
+
for (const [flag, c] of Object.entries(e.flags ?? {})) if (c === cls) out.push(`\`yad ${key} --${flag}\``);
|
|
32
|
+
}
|
|
33
|
+
return out;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function guideSections() {
|
|
37
|
+
return {
|
|
38
|
+
'human-only': [
|
|
39
|
+
'',
|
|
40
|
+
'Only the person does these:',
|
|
41
|
+
'',
|
|
42
|
+
...humanOnlyCommands().map((c) => `- \`${c}\``),
|
|
43
|
+
...HUMAN_ONLY_ACTS.map((a) => `- ${a.text}`),
|
|
44
|
+
'',
|
|
45
|
+
],
|
|
46
|
+
classes: [
|
|
47
|
+
'',
|
|
48
|
+
'`yad guide --json` gives each command its `class` and `ask`. In short:',
|
|
49
|
+
'',
|
|
50
|
+
...CLASSES.filter((cls) => !['internal', 'removed'].includes(cls)).flatMap((cls) => [
|
|
51
|
+
`- **${cls}** — ${ASK_WORDS[ASK[cls]]}. ${commandsOf(cls).join(', ')}.`,
|
|
52
|
+
]),
|
|
53
|
+
'',
|
|
54
|
+
'A command not listed: read `yad <command> --help`, and treat it as a write until you know better.',
|
|
55
|
+
'',
|
|
56
|
+
],
|
|
57
|
+
never: ['', ...NEVER.map((n) => `- ${n.text}`), ''],
|
|
58
|
+
rules: ['', ...RULES.map((r) => `- ${r.text}`), ''],
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// Bring one skill file in line. Returns `{stale: [names], refused: [reasons], text}`; writes only when
|
|
63
|
+
// `check` is false and nothing is refused. A section whose markers are missing is refused, never added: the
|
|
64
|
+
// skill's prose decides where it goes.
|
|
65
|
+
export function syncGuideSkill(file, { check = false } = {}) {
|
|
66
|
+
let text = fs.readFileSync(file, 'utf8');
|
|
67
|
+
const stale = [];
|
|
68
|
+
const refused = [];
|
|
69
|
+
const sections = guideSections();
|
|
70
|
+
for (const name of GUIDE_SECTIONS) {
|
|
71
|
+
const lines = text.split(/\r?\n/);
|
|
72
|
+
if (!lines.some((l) => l.trim().startsWith(`<!-- generated: ${name} `)) || !lines.some((l) => l.trim() === end(name))) {
|
|
73
|
+
refused.push(`the "${name}" section's markers are missing ("${begin(name)}" … "${end(name)}")`);
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
const r = applyMarkedBlock(text, { begin: begin(name), beginKey: `<!-- generated: ${name} `, end: end(name), lines: sections[name] });
|
|
77
|
+
if (r.refused) { refused.push(`"${name}": ${r.refused}`); continue; }
|
|
78
|
+
if (r.status !== 'ok') stale.push(name);
|
|
79
|
+
text = r.text;
|
|
80
|
+
}
|
|
81
|
+
if (!check && !refused.length && stale.length) fs.writeFileSync(file, text);
|
|
82
|
+
return { stale, refused, text };
|
|
83
|
+
}
|