@gtrabanco/agentic-workflow 0.1.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/README.md +19 -0
- package/bin/agwo.mjs +237 -0
- package/bin/path-guard.mjs +263 -0
- package/bin/turn-contract.mjs +174 -0
- package/package.json +20 -0
- package/src/edit/Budgets.mjs +103 -0
- package/src/edit/Changelog.mjs +92 -0
- package/src/edit/Manifest.mjs +167 -0
- package/src/edit/Roadmap.mjs +143 -0
- package/src/edit/UnitDoc.mjs +331 -0
- package/src/edit/schema.mjs +90 -0
- package/src/path-policy.mjs +570 -0
- package/test/edit.test.mjs +358 -0
- package/test/fixtures.mjs +326 -0
- package/test/path-guard.engine.test.mjs +304 -0
- package/test/turn-contract.engine.test.mjs +103 -0
- package/test/turn-contract.parity.test.mjs +20 -0
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Deterministic verifier for the canonical turn contract's mechanical boxes
|
|
3
|
+
// (branch, pre-edit artifacts, commit, pushed pull request, clean tree).
|
|
4
|
+
// Node standard library only, zero dependencies. The verifier mutates nothing
|
|
5
|
+
// of its own: its one spawned process is the repository's own
|
|
6
|
+
// scripts/phase-lint.mjs (box2, engine-only clause).
|
|
7
|
+
// See skills/orchestration-envelope/references/TURN_CONTRACT.md.
|
|
8
|
+
//
|
|
9
|
+
// usage: turn-contract [--finished|--help]
|
|
10
|
+
// prints exactly one line: TURN-CONTRACT ok
|
|
11
|
+
// or: TURN-CONTRACT fail box<N>: <code>
|
|
12
|
+
|
|
13
|
+
import { execFileSync, spawnSync } from "node:child_process";
|
|
14
|
+
import { existsSync, statSync } from "node:fs";
|
|
15
|
+
import path from "node:path";
|
|
16
|
+
|
|
17
|
+
const USAGE =
|
|
18
|
+
"usage: turn-contract [--finished|--help]\n\n" +
|
|
19
|
+
" --finished also check box4 (pushed branch + open pull request whose head is local HEAD)\n" +
|
|
20
|
+
" --help print this usage and exit 0\n";
|
|
21
|
+
|
|
22
|
+
// Every git call is lock-free: a read that may opportunistically write —
|
|
23
|
+
// `git status` refreshing the index — would rewrite `.git/index` and contradict
|
|
24
|
+
// the read-only claim above (F10, fold cycle 3).
|
|
25
|
+
function git(cwd, args) {
|
|
26
|
+
try {
|
|
27
|
+
const out = execFileSync("git", ["--no-optional-locks", ...args], {
|
|
28
|
+
cwd,
|
|
29
|
+
encoding: "utf8",
|
|
30
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
31
|
+
});
|
|
32
|
+
return { ok: true, out: out.trimEnd() };
|
|
33
|
+
} catch {
|
|
34
|
+
return { ok: false, out: "" };
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function count(cwd, range) {
|
|
39
|
+
const r = git(cwd, ["rev-list", "--count", range]);
|
|
40
|
+
const n = r.ok ? Number.parseInt(r.out, 10) : Number.NaN;
|
|
41
|
+
return Number.isFinite(n) ? n : null;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// box2 applies only when the unit path is a DIRECTORY: a path that exists as a
|
|
45
|
+
// regular file means the unit directory does not exist, so the box is
|
|
46
|
+
// not-applicable — the shim's `[ -d ]` semantics (F5, review cycle 2; SPEC
|
|
47
|
+
// box2 row + ED-52-2).
|
|
48
|
+
function isDir(p) {
|
|
49
|
+
try {
|
|
50
|
+
return statSync(p).isDirectory();
|
|
51
|
+
} catch {
|
|
52
|
+
return false;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// bun-else-node per the repository runtime convention.
|
|
57
|
+
function resolveRuntime() {
|
|
58
|
+
const override = process.env.AGENTIC_WORKFLOW_RUNTIME;
|
|
59
|
+
if (override === "bun" || override === "node") return override;
|
|
60
|
+
if ((process.env.npm_config_user_agent ?? "").startsWith("bun/")) return "bun";
|
|
61
|
+
return spawnSync("bun", ["--version"], { stdio: "ignore" }).status === 0 ? "bun" : "node";
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function main(argv) {
|
|
65
|
+
let finished = false;
|
|
66
|
+
const rest = [...argv];
|
|
67
|
+
while (rest.length > 0) {
|
|
68
|
+
const arg = rest.shift();
|
|
69
|
+
if (arg === "--finished") finished = true;
|
|
70
|
+
else if (arg === "--help") {
|
|
71
|
+
process.stdout.write(USAGE);
|
|
72
|
+
return 0;
|
|
73
|
+
} else {
|
|
74
|
+
process.stderr.write(`turn-contract: unknown argument: ${arg}\n`);
|
|
75
|
+
process.stderr.write(USAGE);
|
|
76
|
+
return 2;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const fail = (box, code) => {
|
|
81
|
+
process.stdout.write(`TURN-CONTRACT fail box${box}: ${code}\n`);
|
|
82
|
+
return 1;
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
// box1 — inside a git repository, and not on its default branch.
|
|
86
|
+
const top = git(process.cwd(), ["rev-parse", "--show-toplevel"]);
|
|
87
|
+
if (!top.ok || top.out === "") return fail(1, "not-a-repo");
|
|
88
|
+
const root = top.out;
|
|
89
|
+
|
|
90
|
+
// Default branch chain: origin/HEAD, else local main, else local master.
|
|
91
|
+
let defaultRef = "";
|
|
92
|
+
const originHead = git(root, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
|
|
93
|
+
if (originHead.ok && originHead.out !== "") defaultRef = originHead.out;
|
|
94
|
+
else if (git(root, ["show-ref", "--verify", "--quiet", "refs/heads/main"]).ok) defaultRef = "main";
|
|
95
|
+
else if (git(root, ["show-ref", "--verify", "--quiet", "refs/heads/master"]).ok) defaultRef = "master";
|
|
96
|
+
const defaultBranch = defaultRef.replace(/^origin\//, "");
|
|
97
|
+
|
|
98
|
+
const current = git(root, ["branch", "--show-current"]);
|
|
99
|
+
const currentBranch = current.ok ? current.out : "";
|
|
100
|
+
if (defaultBranch !== "" && currentBranch === defaultBranch) return fail(1, "branch-default");
|
|
101
|
+
|
|
102
|
+
// box2 — frozen acceptance at HEAD for a unit-shaped branch; when the
|
|
103
|
+
// project ships scripts/phase-lint.mjs and the unit has a TASKS.md, phase
|
|
104
|
+
// lint must be green (engine-only clause — the shim runs no other runtime).
|
|
105
|
+
let unitDir = "";
|
|
106
|
+
if (currentBranch.startsWith("feat/")) unitDir = `docs/features/${currentBranch.slice("feat/".length)}`;
|
|
107
|
+
else if (currentBranch.startsWith("fix/")) unitDir = `docs/fix/${currentBranch.slice("fix/".length)}`;
|
|
108
|
+
if (unitDir !== "" && isDir(path.join(root, unitDir))) {
|
|
109
|
+
// Feature 61: the unit document is the frozen surface (ACCEPTANCE.md is retired).
|
|
110
|
+
if (!git(root, ["cat-file", "-e", `HEAD:${unitDir}/SPEC.md`]).ok) return fail(2, "unit-doc-missing");
|
|
111
|
+
const lint = path.join(root, "scripts", "phase-lint.mjs");
|
|
112
|
+
const tasks = path.join(root, unitDir, "TASKS.md");
|
|
113
|
+
if (existsSync(lint) && existsSync(tasks)) {
|
|
114
|
+
const r = spawnSync(resolveRuntime(), ["scripts/phase-lint.mjs", `${unitDir}/TASKS.md`], {
|
|
115
|
+
cwd: root,
|
|
116
|
+
stdio: ["ignore", "ignore", "ignore"],
|
|
117
|
+
});
|
|
118
|
+
if (r.status !== 0) return fail(2, "phase-lint-failed");
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
// box3 — at least one commit on this branch that is not on the default.
|
|
123
|
+
const ownCommits = defaultRef !== "" ? count(root, `${defaultRef}..HEAD`) : count(root, "HEAD");
|
|
124
|
+
if (ownCommits === null || ownCommits < 1) return fail(3, "no-commits");
|
|
125
|
+
|
|
126
|
+
// box4 — only with --finished: an upstream and an open PR whose head is HEAD.
|
|
127
|
+
if (finished) {
|
|
128
|
+
const upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
|
|
129
|
+
if (!upstream.ok || upstream.out === "") return fail(4, "pr-not-open");
|
|
130
|
+
const head = git(root, ["rev-parse", "HEAD"]);
|
|
131
|
+
const localHead = head.ok ? head.out : "";
|
|
132
|
+
// This branch's own pull requests, scoped by --head: `gh pr view <arg>`
|
|
133
|
+
// reads an all-numeric argument as a PR *number*, so a branch named e.g.
|
|
134
|
+
// `123` would have box4 judge an unrelated PR (F11, fold cycle 3). The list
|
|
135
|
+
// query also answers "is there a PR at all?" with exit 0 plus an empty
|
|
136
|
+
// result, which is what separates a missing PR (pr-not-open) from a gh
|
|
137
|
+
// failure (pr-unreachable) — `gh pr view` exits nonzero for both, so the
|
|
138
|
+
// SPEC's "no PR → pr-not-open" clause was unimplementable (F9).
|
|
139
|
+
const gh = spawnSync(
|
|
140
|
+
"gh",
|
|
141
|
+
["pr", "list", "--head", currentBranch, "--state", "open", "--json", "state,headRefOid"],
|
|
142
|
+
{ cwd: root, encoding: "utf8" },
|
|
143
|
+
);
|
|
144
|
+
if (gh.status !== 0) return fail(4, "pr-unreachable");
|
|
145
|
+
let parsed;
|
|
146
|
+
try {
|
|
147
|
+
parsed = JSON.parse(gh.stdout);
|
|
148
|
+
} catch {
|
|
149
|
+
parsed = null;
|
|
150
|
+
}
|
|
151
|
+
const prs = Array.isArray(parsed) ? parsed : [];
|
|
152
|
+
const pr = prs.find((entry) => entry?.state === "OPEN");
|
|
153
|
+
if (pr === undefined) return fail(4, "pr-not-open");
|
|
154
|
+
if (pr.headRefOid !== localHead) return fail(4, "pr-head-mismatch");
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
// box5 — clean tree, then not ahead of the configured upstream. A status
|
|
158
|
+
// query that cannot be answered (error, or output past the buffer cap) is
|
|
159
|
+
// never proof of a clean tree: it fails closed as dirty-tree.
|
|
160
|
+
// `--untracked-files=all` overrides a repo-local status.showUntrackedFiles=no,
|
|
161
|
+
// which would otherwise hide an untracked file and win a false ok (F8).
|
|
162
|
+
const status = git(root, ["status", "--porcelain", "--untracked-files=all"]);
|
|
163
|
+
if (!status.ok || status.out !== "") return fail(5, "dirty-tree");
|
|
164
|
+
const upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
|
|
165
|
+
if (upstream.ok && upstream.out !== "") {
|
|
166
|
+
const ahead = count(root, `${upstream.out}..HEAD`);
|
|
167
|
+
if (ahead === null || ahead !== 0) return fail(5, "ahead-of-remote");
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
process.stdout.write("TURN-CONTRACT ok\n");
|
|
171
|
+
return 0;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
process.exitCode = main(process.argv.slice(2));
|
package/package.json
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@gtrabanco/agentic-workflow",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Producer crate for the deterministic agentic-workflow scripts; later producers land their scripts as subcommands here.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/gtrabanco/agentic-workflow.git",
|
|
10
|
+
"directory": "packages/agentic-workflow"
|
|
11
|
+
},
|
|
12
|
+
"type": "module",
|
|
13
|
+
"bin": {
|
|
14
|
+
"agwo": "./bin/agwo.mjs"
|
|
15
|
+
},
|
|
16
|
+
"engines": {
|
|
17
|
+
"node": ">=18",
|
|
18
|
+
"bun": ">=1.4"
|
|
19
|
+
}
|
|
20
|
+
}
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Budgets — ceiling rebase for budget tables.
|
|
3
|
+
*
|
|
4
|
+
* Refuses to shrink without a declared growth source.
|
|
5
|
+
* Operations validate post-state and emit receipts.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
9
|
+
import { createHash } from "node:crypto";
|
|
10
|
+
|
|
11
|
+
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
12
|
+
|
|
13
|
+
function sha256(text) {
|
|
14
|
+
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function shaPrefix(hex) {
|
|
18
|
+
return hex.slice(0, 8);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function makeReceipt(service, op, path, schema, before, after, ok) {
|
|
22
|
+
return { service, op, path, schema, before, after, ok };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// ── Public API ───────────────────────────────────────────────────────────
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* ceilingRebase(budgetFile, route, estimateMax, linesMax, growthSource)
|
|
29
|
+
*
|
|
30
|
+
* Rebases the ceiling values for a budget route. If either value would
|
|
31
|
+
* shrink (i.e., the new value is less than the existing value in the file),
|
|
32
|
+
* a non-empty growthSource string is required and must be written into the
|
|
33
|
+
* route's `sources` object.
|
|
34
|
+
*
|
|
35
|
+
* budgetFile is the absolute path to the budget JSON file.
|
|
36
|
+
* route is the route name (e.g. "execute-phase").
|
|
37
|
+
* estimateMax is the new estimate-max value (number).
|
|
38
|
+
* linesMax is the new lines-max value (number).
|
|
39
|
+
* growthSource is the declared reason for shrinkage (required if shrinking).
|
|
40
|
+
*
|
|
41
|
+
* The budget file is a JSON file with a structure like:
|
|
42
|
+
* { "routes": { "<route>": { "estimateMax": N, "linesMax": N, "sources": {} } } }
|
|
43
|
+
*
|
|
44
|
+
* Returns a receipt with ok: false if shrinking without a growth source
|
|
45
|
+
* (refusal — nothing is written). ok: true on success.
|
|
46
|
+
*
|
|
47
|
+
* For SDK callers that want throw semantics on shrink: check receipt.ok === false.
|
|
48
|
+
*/
|
|
49
|
+
export function ceilingRebase(budgetFile, route, estimateMax, linesMax, growthSource) {
|
|
50
|
+
const content = readFileSync(budgetFile, "utf8");
|
|
51
|
+
const beforeHash = sha256(content);
|
|
52
|
+
|
|
53
|
+
const data = JSON.parse(content);
|
|
54
|
+
const routeData = data.routes?.[route];
|
|
55
|
+
|
|
56
|
+
if (!routeData) {
|
|
57
|
+
throw new Error(`Budget route "${route}" not found`);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const estimateRef = routeData.estimateMax ?? Infinity;
|
|
61
|
+
const linesRef = routeData.linesMax ?? Infinity;
|
|
62
|
+
|
|
63
|
+
// Check for shrinkage
|
|
64
|
+
const estimateShrinks = estimateMax !== undefined && estimateMax < estimateRef;
|
|
65
|
+
const linesShrinks = linesMax !== undefined && linesMax < linesRef;
|
|
66
|
+
|
|
67
|
+
if ((estimateShrinks || linesShrinks) && (!growthSource || growthSource.trim() === "")) {
|
|
68
|
+
// Refuse shrinkage without a growth source — return fail receipt
|
|
69
|
+
return makeReceipt(
|
|
70
|
+
"budgets",
|
|
71
|
+
"ceilingRebase",
|
|
72
|
+
budgetFile,
|
|
73
|
+
"budgets-table@1",
|
|
74
|
+
shaPrefix(beforeHash),
|
|
75
|
+
shaPrefix(beforeHash),
|
|
76
|
+
false,
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Apply the rebase
|
|
81
|
+
if (estimateMax !== undefined) routeData.estimateMax = estimateMax;
|
|
82
|
+
if (linesMax !== undefined) routeData.linesMax = linesMax;
|
|
83
|
+
|
|
84
|
+
// Record the growth source if provided
|
|
85
|
+
if (growthSource) {
|
|
86
|
+
routeData.sources = routeData.sources || {};
|
|
87
|
+
routeData.sources.ceilingRebase = growthSource;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const newContent = JSON.stringify(data, null, 2);
|
|
91
|
+
writeFileSync(budgetFile, newContent, "utf8");
|
|
92
|
+
const afterHash = sha256(newContent);
|
|
93
|
+
|
|
94
|
+
return makeReceipt(
|
|
95
|
+
"budgets",
|
|
96
|
+
"ceilingRebase",
|
|
97
|
+
budgetFile,
|
|
98
|
+
"budgets-table@1",
|
|
99
|
+
shaPrefix(beforeHash),
|
|
100
|
+
shaPrefix(afterHash),
|
|
101
|
+
true,
|
|
102
|
+
);
|
|
103
|
+
}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Changelog — versioned row add per named skill section.
|
|
3
|
+
*
|
|
4
|
+
* The changelog file uses headings like:
|
|
5
|
+
* #### `skillName`
|
|
6
|
+
* followed by a Markdown table of version rows.
|
|
7
|
+
*
|
|
8
|
+
* rowAdd inserts a new row below the table header of the named section,
|
|
9
|
+
* respecting the table's column order.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
13
|
+
import { createHash } from "node:crypto";
|
|
14
|
+
|
|
15
|
+
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
16
|
+
|
|
17
|
+
function sha256(text) {
|
|
18
|
+
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function shaPrefix(hex) {
|
|
22
|
+
return hex.slice(0, 8);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function makeReceipt(service, op, path, schema, before, after, ok) {
|
|
26
|
+
return { service, op, path, schema, before, after, ok };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// ── Public API ───────────────────────────────────────────────────────────
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* rowAdd(table, sectionName, { version, date, type, what })
|
|
33
|
+
* Inserts a new row below the table header of the named #### `skillName` section.
|
|
34
|
+
*
|
|
35
|
+
* table is the absolute path to the CHANGELOG.md (or similar).
|
|
36
|
+
* sectionName is the skill name to target (matches #### `skillName`).
|
|
37
|
+
* version, date, type, what are the column values for the new row.
|
|
38
|
+
*
|
|
39
|
+
* Returns a receipt. Throws if the section is not found.
|
|
40
|
+
*/
|
|
41
|
+
export function rowAdd(table, sectionName, { version, date, type, what }) {
|
|
42
|
+
const content = readFileSync(table, "utf8");
|
|
43
|
+
const beforeHash = sha256(content);
|
|
44
|
+
const lines = content.split("\n");
|
|
45
|
+
|
|
46
|
+
// Find the section heading and insert the new row below its table header
|
|
47
|
+
let inserted = false;
|
|
48
|
+
const newLines = [];
|
|
49
|
+
|
|
50
|
+
for (let i = 0; i < lines.length; i++) {
|
|
51
|
+
newLines.push(lines[i]);
|
|
52
|
+
|
|
53
|
+
// Check if this is the target section heading
|
|
54
|
+
const sectionMatch = lines[i].match(/^#### `(.+)`/);
|
|
55
|
+
if (sectionMatch && sectionMatch[1] === sectionName) {
|
|
56
|
+
// We're in the target section — look for the next table header
|
|
57
|
+
let j = i + 1;
|
|
58
|
+
for (; j < lines.length; j++) {
|
|
59
|
+
if (lines[j].includes("|---|")) {
|
|
60
|
+
// Found the table separator — insert the row after it
|
|
61
|
+
const newRow = `| ${version} | ${date} | ${type} | ${what} |`;
|
|
62
|
+
newLines.push(newRow);
|
|
63
|
+
inserted = true;
|
|
64
|
+
break;
|
|
65
|
+
}
|
|
66
|
+
// Stop if we hit a new section before finding the table
|
|
67
|
+
if (lines[j].match(/^#{1,4} /)) {
|
|
68
|
+
break;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
break;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
if (!inserted) {
|
|
76
|
+
throw new Error(`Could not find section "#### \`${sectionName}\`" with a table in ${table}`);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const newContent = newLines.join("\n");
|
|
80
|
+
writeFileSync(table, newContent, "utf8");
|
|
81
|
+
const afterHash = sha256(newContent);
|
|
82
|
+
|
|
83
|
+
return makeReceipt(
|
|
84
|
+
"changelog",
|
|
85
|
+
"rowAdd",
|
|
86
|
+
table,
|
|
87
|
+
"changelog-table@1",
|
|
88
|
+
shaPrefix(beforeHash),
|
|
89
|
+
shaPrefix(afterHash),
|
|
90
|
+
true,
|
|
91
|
+
);
|
|
92
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Manifest — skill add/remove across .claude-plugin/plugin.json and skills.sh.json.
|
|
3
|
+
*
|
|
4
|
+
* Both files are JSON with a "skills" array. skillAdd/skillRemove keep the
|
|
5
|
+
* array alphabetically sorted. skills.sh.json groups skills into sections
|
|
6
|
+
* (e.g., "User-facing", "Internal").
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { readFileSync, writeFileSync, existsSync } from "node:fs";
|
|
10
|
+
import { createHash } from "node:crypto";
|
|
11
|
+
import { join, dirname } from "node:path";
|
|
12
|
+
|
|
13
|
+
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
14
|
+
|
|
15
|
+
function sha256(text) {
|
|
16
|
+
return createHash("sha256").update(text, "utf8").digest("hex");
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function shaPrefix(hex) {
|
|
20
|
+
return hex.slice(0, 8);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function makeReceipt(service, op, path, schema, before, after, ok) {
|
|
24
|
+
return { service, op, path, schema, before, after, ok };
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function atomicWrite(targetPath, content) {
|
|
28
|
+
writeFileSync(targetPath, content, "utf8");
|
|
29
|
+
return targetPath;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
// ── Public API ───────────────────────────────────────────────────────────
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* skillAdd(pluginJson, skillName, { group, description, userInvocable })
|
|
36
|
+
*
|
|
37
|
+
* pluginJson is the absolute path to .claude-plugin/plugin.json.
|
|
38
|
+
* skillName is the name to add.
|
|
39
|
+
* group, description, userInvocable are optional metadata.
|
|
40
|
+
*
|
|
41
|
+
* Adds the skill to the skills array in alphabetical order.
|
|
42
|
+
* Also updates skills.sh.json if it exists (same alphabetical placement).
|
|
43
|
+
*
|
|
44
|
+
* Returns a receipt.
|
|
45
|
+
*/
|
|
46
|
+
export function skillAdd(pluginJson, skillName, { group, description, userInvocable } = {}) {
|
|
47
|
+
const content = readFileSync(pluginJson, "utf8");
|
|
48
|
+
const beforeHashValue = sha256(content);
|
|
49
|
+
|
|
50
|
+
const data = JSON.parse(content);
|
|
51
|
+
const skills = data.skills || [];
|
|
52
|
+
|
|
53
|
+
// Check if already present
|
|
54
|
+
if (skills.some((s) => s.name === skillName)) {
|
|
55
|
+
throw new Error(`Skill "${skillName}" already exists`);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Build the skill entry
|
|
59
|
+
const entry = { name: skillName };
|
|
60
|
+
if (description) entry.description = description;
|
|
61
|
+
if (group) entry.group = group;
|
|
62
|
+
if (userInvocable !== undefined) entry["user-invocable"] = userInvocable;
|
|
63
|
+
|
|
64
|
+
// Insert in alphabetical order by name
|
|
65
|
+
let inserted = false;
|
|
66
|
+
const newSkills = [];
|
|
67
|
+
for (const s of skills) {
|
|
68
|
+
if (!inserted && s.name > skillName) {
|
|
69
|
+
newSkills.push(entry);
|
|
70
|
+
inserted = true;
|
|
71
|
+
}
|
|
72
|
+
newSkills.push(s);
|
|
73
|
+
}
|
|
74
|
+
if (!inserted) {
|
|
75
|
+
newSkills.push(entry);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
data.skills = newSkills;
|
|
79
|
+
const newContent = JSON.stringify(data, null, 2);
|
|
80
|
+
atomicWrite(pluginJson, newContent);
|
|
81
|
+
const afterHashValue = sha256(newContent);
|
|
82
|
+
|
|
83
|
+
// Also update skills.sh.json if it exists
|
|
84
|
+
const shDir = join(dirname(pluginJson), "..");
|
|
85
|
+
const shJsonPath = join(shDir, "skills.sh.json");
|
|
86
|
+
if (existsSync(shJsonPath)) {
|
|
87
|
+
const shContent = readFileSync(shJsonPath, "utf8");
|
|
88
|
+
const shData = JSON.parse(shContent);
|
|
89
|
+
if (shData.skills) {
|
|
90
|
+
// Insert alphabetically in skills.sh.json as well
|
|
91
|
+
const shSkills = shData.skills;
|
|
92
|
+
let shInserted = false;
|
|
93
|
+
const newShSkills = [];
|
|
94
|
+
for (const s of shSkills) {
|
|
95
|
+
if (!shInserted && s > skillName) {
|
|
96
|
+
newShSkills.push(skillName);
|
|
97
|
+
shInserted = true;
|
|
98
|
+
}
|
|
99
|
+
newShSkills.push(s);
|
|
100
|
+
}
|
|
101
|
+
if (!shInserted) {
|
|
102
|
+
newShSkills.push(skillName);
|
|
103
|
+
}
|
|
104
|
+
shData.skills = newShSkills;
|
|
105
|
+
atomicWrite(shJsonPath, JSON.stringify(shData, null, 2));
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
return makeReceipt(
|
|
110
|
+
"manifest",
|
|
111
|
+
"skillAdd",
|
|
112
|
+
pluginJson,
|
|
113
|
+
"manifest-table@1",
|
|
114
|
+
shaPrefix(beforeHashValue),
|
|
115
|
+
shaPrefix(afterHashValue),
|
|
116
|
+
true,
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* skillRemove(pluginJson, skillName)
|
|
122
|
+
*
|
|
123
|
+
* Removes the skill from the skills array in plugin.json (and skills.sh.json).
|
|
124
|
+
* Keeps the array alphabetically sorted.
|
|
125
|
+
*
|
|
126
|
+
* Returns a receipt. Throws if the skill is not found.
|
|
127
|
+
*/
|
|
128
|
+
export function skillRemove(pluginJson, skillName) {
|
|
129
|
+
const content = readFileSync(pluginJson, "utf8");
|
|
130
|
+
const beforeHashValue = sha256(content);
|
|
131
|
+
|
|
132
|
+
const data = JSON.parse(content);
|
|
133
|
+
const skills = data.skills || [];
|
|
134
|
+
const beforeCount = skills.length;
|
|
135
|
+
|
|
136
|
+
const newSkills = skills.filter((s) => s.name !== skillName);
|
|
137
|
+
if (newSkills.length === beforeCount) {
|
|
138
|
+
throw new Error(`Skill "${skillName}" not found`);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
data.skills = newSkills;
|
|
142
|
+
const newContent = JSON.stringify(data, null, 2);
|
|
143
|
+
atomicWrite(pluginJson, newContent);
|
|
144
|
+
const afterHashValue = sha256(newContent);
|
|
145
|
+
|
|
146
|
+
// Also update skills.sh.json if it exists
|
|
147
|
+
const shDir = join(dirname(pluginJson), "..");
|
|
148
|
+
const shJsonPath = join(shDir, "skills.sh.json");
|
|
149
|
+
if (existsSync(shJsonPath)) {
|
|
150
|
+
const shContent = readFileSync(shJsonPath, "utf8");
|
|
151
|
+
const shData = JSON.parse(shContent);
|
|
152
|
+
if (shData.skills) {
|
|
153
|
+
shData.skills = shData.skills.filter((s) => s !== skillName);
|
|
154
|
+
atomicWrite(shJsonPath, JSON.stringify(shData, null, 2));
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return makeReceipt(
|
|
159
|
+
"manifest",
|
|
160
|
+
"skillRemove",
|
|
161
|
+
pluginJson,
|
|
162
|
+
"manifest-table@1",
|
|
163
|
+
shaPrefix(beforeHashValue),
|
|
164
|
+
shaPrefix(afterHashValue),
|
|
165
|
+
true,
|
|
166
|
+
);
|
|
167
|
+
}
|