macca-method 2.0.0 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/.agents/macca-lock.json +1 -1
  2. package/.agents/skills/_shared/references/brainstorm-session.md +5 -5
  3. package/.agents/skills/_shared/references/fix-mode.md +18 -3
  4. package/.agents/skills/_shared/references/human-loop.md +1 -1
  5. package/.agents/skills/_shared/references/invocation-policy.md +20 -20
  6. package/.agents/skills/_shared/references/language-config.md +7 -5
  7. package/.agents/skills/_shared/references/output-ownership.md +11 -11
  8. package/.agents/skills/_shared/references/scope-rules.md +1 -1
  9. package/.agents/skills/_shared/references/skill-catalog.md +20 -20
  10. package/.agents/skills/_shared/scripts/validate-skills.py +37 -15
  11. package/.agents/skills/add-feature/SKILL.md +11 -3
  12. package/.agents/skills/antislop-copywriting/SKILL.md +372 -0
  13. package/.agents/skills/brainstorm-api/SKILL.md +33 -19
  14. package/.agents/skills/brainstorm-api/assets/api.template.md +35 -15
  15. package/.agents/skills/brainstorm-architecture/SKILL.md +40 -18
  16. package/.agents/skills/brainstorm-architecture/assets/architecture.template.md +44 -25
  17. package/.agents/skills/brainstorm-prd/SKILL.md +52 -20
  18. package/.agents/skills/brainstorm-prd/assets/PRD.template.md +47 -23
  19. package/.agents/skills/brainstorm-rules/SKILL.md +39 -22
  20. package/.agents/skills/brainstorm-rules/assets/rules.template.md +32 -18
  21. package/.agents/skills/brainstorm-schema/SKILL.md +23 -11
  22. package/.agents/skills/brainstorm-schema/assets/schema.template.md +25 -10
  23. package/.agents/skills/brainstorm-styleguide/SKILL.md +40 -22
  24. package/.agents/skills/brainstorm-styleguide/assets/StyleGuide.template.md +78 -60
  25. package/.agents/skills/brainstorm-task/SKILL.md +29 -14
  26. package/.agents/skills/brainstorm-task/assets/Task.template.md +29 -18
  27. package/.agents/skills/bug-fix/SKILL.md +39 -8
  28. package/.agents/skills/code-review/SKILL.md +9 -7
  29. package/.agents/skills/code-review/references/review-checklist.md +21 -10
  30. package/.agents/skills/developer/SKILL.md +10 -0
  31. package/.agents/skills/developer/references/execute-task.md +13 -7
  32. package/.agents/skills/developer/references/onboarding.md +1 -1
  33. package/.agents/skills/help/SKILL.md +39 -23
  34. package/.agents/skills/meet/SKILL.md +11 -4
  35. package/.agents/skills/quick-dev/SKILL.md +29 -22
  36. package/.agents/skills/release-readiness/SKILL.md +19 -13
  37. package/.agents/skills/skill-creator/LICENSE.txt +202 -0
  38. package/.agents/skills/skill-creator/SKILL.md +485 -0
  39. package/.agents/skills/skill-creator/agents/analyzer.md +274 -0
  40. package/.agents/skills/skill-creator/agents/comparator.md +202 -0
  41. package/.agents/skills/skill-creator/agents/grader.md +223 -0
  42. package/.agents/skills/skill-creator/assets/eval_review.html +146 -0
  43. package/.agents/skills/skill-creator/eval-viewer/generate_review.py +471 -0
  44. package/.agents/skills/skill-creator/eval-viewer/viewer.html +1325 -0
  45. package/.agents/skills/skill-creator/references/schemas.md +441 -0
  46. package/.agents/skills/skill-creator/scripts/__init__.py +0 -0
  47. package/.agents/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
  48. package/.agents/skills/skill-creator/scripts/generate_report.py +326 -0
  49. package/.agents/skills/skill-creator/scripts/improve_description.py +247 -0
  50. package/.agents/skills/skill-creator/scripts/package_skill.py +136 -0
  51. package/.agents/skills/skill-creator/scripts/quick_validate.py +103 -0
  52. package/.agents/skills/skill-creator/scripts/run_eval.py +310 -0
  53. package/.agents/skills/skill-creator/scripts/run_loop.py +328 -0
  54. package/.agents/skills/skill-creator/scripts/utils.py +47 -0
  55. package/.agents/skills/spec-audit/SKILL.md +33 -4
  56. package/.agents/skills/spec-compliance/SKILL.md +36 -21
  57. package/.agents/skills/spec-init/SKILL.md +31 -17
  58. package/README.md +165 -129
  59. package/bin/macca-method.js +1378 -1077
  60. package/package.json +40 -40
  61. package/scripts/run-skill-validator.js +27 -9
  62. package/scripts/test-install.js +611 -337
  63. package/scripts/test-upgrade-legacy.js +131 -76
  64. package/scripts/validate-skill-behavior.js +175 -64
@@ -10,7 +10,9 @@ const { execFileSync } = require("node:child_process");
10
10
 
11
11
  const rootDir = path.resolve(__dirname, "..");
12
12
  const mode = process.argv.includes("--published") ? "published" : "local";
13
- const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "macca-test-install-"));
13
+ const tmpDir = fs.mkdtempSync(
14
+ path.join(resolveTempRoot(), "macca-test-install-"),
15
+ );
14
16
  const projectDir = path.join(tmpDir, "project");
15
17
  const collisionDir = path.join(tmpDir, "collision-project");
16
18
  const symlinkDir = path.join(tmpDir, "symlink-project");
@@ -18,381 +20,653 @@ const driftDir = path.join(tmpDir, "drift-project");
18
20
  let packageSpec = "macca-method";
19
21
 
20
22
  function commandName(base) {
21
- return process.platform === "win32" ? `${base}.cmd` : base;
23
+ if (process.platform !== "win32") {
24
+ return base;
25
+ }
26
+
27
+ return base === "npm" || base === "npx" ? `${base}.cmd` : base;
28
+ }
29
+
30
+ function resolveTempRoot() {
31
+ const tempRoot = os.tmpdir();
32
+ try {
33
+ return fs.realpathSync(tempRoot);
34
+ } catch {
35
+ return tempRoot;
36
+ }
37
+ }
38
+
39
+ function runNpm(args, options = {}) {
40
+ const npmExecPath = process.env.npm_execpath;
41
+ if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
42
+ return capture(process.execPath, [npmExecPath, ...args], options);
43
+ }
44
+
45
+ return capture(commandName("npm"), args, options);
46
+ }
47
+
48
+ function runNpmWithInheritedStdio(args, options = {}) {
49
+ const npmExecPath = process.env.npm_execpath;
50
+ if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
51
+ run(process.execPath, [npmExecPath, ...args], options);
52
+ return;
53
+ }
54
+
55
+ run(commandName("npm"), args, options);
22
56
  }
23
57
 
24
58
  function run(command, args, options = {}) {
25
- execFileSync(command, args, {
26
- cwd: rootDir,
27
- stdio: "inherit",
28
- ...options
29
- });
59
+ execFileSync(command, args, {
60
+ cwd: rootDir,
61
+ stdio: "inherit",
62
+ ...options,
63
+ });
30
64
  }
31
65
 
32
66
  function capture(command, args, options = {}) {
33
- return execFileSync(command, args, {
34
- cwd: rootDir,
35
- encoding: "utf8",
36
- ...options
37
- });
67
+ return execFileSync(command, args, {
68
+ cwd: rootDir,
69
+ encoding: "utf8",
70
+ ...options,
71
+ });
38
72
  }
39
73
 
40
74
  function runCli(args) {
41
- if (mode === "published") {
42
- run(commandName("npx"), ["--yes", "macca-method", ...args]);
43
- return;
44
- }
45
-
46
- run(commandName("npx"), ["--yes", "--package", packageSpec, "macca-method", ...args]);
75
+ if (mode === "published") {
76
+ runNpmWithInheritedStdio([
77
+ "exec",
78
+ "--yes",
79
+ "--package",
80
+ "macca-method",
81
+ "--",
82
+ "macca-method",
83
+ ...args,
84
+ ]);
85
+ return;
86
+ }
87
+
88
+ runNpmWithInheritedStdio([
89
+ "exec",
90
+ "--yes",
91
+ "--package",
92
+ packageSpec,
93
+ "--",
94
+ "macca-method",
95
+ ...args,
96
+ ]);
47
97
  }
48
98
 
49
99
  function expectCliFailure(args, expectedText) {
50
- try {
51
- if (mode === "published") {
52
- capture(commandName("npx"), ["--yes", "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
53
- } else {
54
- capture(commandName("npx"), ["--yes", "--package", packageSpec, "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
55
- }
56
- } catch (error) {
57
- const output = `${error.stdout || ""}${error.stderr || ""}`;
58
- if (!output.includes(expectedText)) {
59
- throw new Error(`Expected failed command to include ${expectedText}, got: ${output}`);
60
- }
61
- return;
100
+ try {
101
+ if (mode === "published") {
102
+ runNpm(
103
+ [
104
+ "exec",
105
+ "--yes",
106
+ "--package",
107
+ "macca-method",
108
+ "--",
109
+ "macca-method",
110
+ ...args,
111
+ ],
112
+ { cwd: rootDir, stdio: "pipe" },
113
+ );
114
+ } else {
115
+ runNpm(
116
+ [
117
+ "exec",
118
+ "--yes",
119
+ "--package",
120
+ packageSpec,
121
+ "--",
122
+ "macca-method",
123
+ ...args,
124
+ ],
125
+ { cwd: rootDir, stdio: "pipe" },
126
+ );
127
+ }
128
+ } catch (error) {
129
+ const output = `${error.stdout || ""}${error.stderr || ""}${error.message || ""}`;
130
+ if (!output.includes(expectedText)) {
131
+ throw new Error(
132
+ `Expected failed command to include ${expectedText}, got: ${output}`,
133
+ );
62
134
  }
63
- throw new Error(`Expected command to fail: ${args.join(" ")}`);
135
+ return;
136
+ }
137
+ throw new Error(`Expected command to fail: ${args.join(" ")}`);
64
138
  }
65
139
 
66
140
  function assertPathExists(targetPath) {
67
- if (!fs.existsSync(targetPath)) {
68
- throw new Error(`Missing expected path: ${targetPath}`);
69
- }
141
+ if (!fs.existsSync(targetPath)) {
142
+ throw new Error(`Missing expected path: ${targetPath}`);
143
+ }
70
144
  }
71
145
 
72
146
  function readNonEmptyLines(filePath) {
73
- return fs
74
- .readFileSync(filePath, "utf8")
75
- .split(/\r?\n/)
76
- .map((line) => line.trim())
77
- .filter(Boolean);
147
+ return fs
148
+ .readFileSync(filePath, "utf8")
149
+ .split(/\r?\n/)
150
+ .map((line) => line.trim())
151
+ .filter(Boolean);
78
152
  }
79
153
 
80
154
  function listFiles(directoryPath) {
81
- const files = [];
82
-
83
- function walk(currentPath) {
84
- const entries = fs.readdirSync(currentPath, { withFileTypes: true });
85
- for (const entry of entries) {
86
- const entryPath = path.join(currentPath, entry.name);
87
- if (entry.isDirectory()) {
88
- walk(entryPath);
89
- continue;
90
- }
91
-
92
- files.push(entryPath);
93
- }
155
+ const files = [];
156
+
157
+ function walk(currentPath) {
158
+ const entries = fs.readdirSync(currentPath, { withFileTypes: true });
159
+ for (const entry of entries) {
160
+ const entryPath = path.join(currentPath, entry.name);
161
+ if (entry.isDirectory()) {
162
+ walk(entryPath);
163
+ continue;
164
+ }
165
+
166
+ files.push(entryPath);
94
167
  }
168
+ }
95
169
 
96
- walk(directoryPath);
97
- return files.sort();
170
+ walk(directoryPath);
171
+ return files.sort();
98
172
  }
99
173
 
100
174
  function ensureExpectedTools(filePath) {
101
- const tools = readNonEmptyLines(filePath);
102
- if (!tools.includes("codex")) {
103
- throw new Error("Expected codex in .agents/macca-tools.txt");
104
- }
105
-
106
- if (!tools.includes("copilot")) {
107
- throw new Error("Expected copilot in .agents/macca-tools.txt");
108
- }
175
+ const tools = readNonEmptyLines(filePath);
176
+ if (!tools.includes("codex")) {
177
+ throw new Error("Expected codex in .agents/macca-tools.txt");
178
+ }
179
+
180
+ if (!tools.includes("copilot")) {
181
+ throw new Error("Expected copilot in .agents/macca-tools.txt");
182
+ }
109
183
  }
110
184
 
111
185
  function resolveLocalPackage() {
112
- const packOutput = capture(commandName("npm"), ["pack", "--json", "--pack-destination", tmpDir]);
113
- const packageList = JSON.parse(packOutput);
186
+ const packOutput = runNpm(["pack", "--json", "--pack-destination", tmpDir]);
187
+ const packageList = JSON.parse(packOutput);
188
+
189
+ if (
190
+ !Array.isArray(packageList) ||
191
+ packageList.length === 0 ||
192
+ !packageList[0].filename
193
+ ) {
194
+ throw new Error("npm pack did not return a tarball filename");
195
+ }
196
+
197
+ packageSpec = path.join(tmpDir, packageList[0].filename);
198
+ }
199
+
200
+ function main() {
201
+ process.stdout.write("\n");
202
+ process.stdout.write(" MACCA test-install\n");
203
+ process.stdout.write(` Mode: ${mode}\n`);
114
204
 
115
- if (!Array.isArray(packageList) || packageList.length === 0 || !packageList[0].filename) {
116
- throw new Error("npm pack did not return a tarball filename");
205
+ try {
206
+ if (mode === "local") {
207
+ resolveLocalPackage();
117
208
  }
118
209
 
119
- packageSpec = path.join(tmpDir, packageList[0].filename);
120
- }
210
+ fs.mkdirSync(projectDir, { recursive: true });
211
+ const collisionSkill = path.join(
212
+ collisionDir,
213
+ ".agents",
214
+ "skills",
215
+ "developer",
216
+ "SKILL.md",
217
+ );
218
+ fs.mkdirSync(path.dirname(collisionSkill), { recursive: true });
219
+ fs.writeFileSync(
220
+ collisionSkill,
221
+ "---\nname: developer\ndescription: User-owned collision fixture.\n---\n",
222
+ "utf8",
223
+ );
224
+ expectCliFailure(
225
+ ["install", "--yes", "--tool", "codex", "--directory", collisionDir],
226
+ "Refusing to overwrite or remove unowned skill directory",
227
+ );
228
+ if (
229
+ !fs
230
+ .readFileSync(collisionSkill, "utf8")
231
+ .includes("User-owned collision fixture")
232
+ ) {
233
+ throw new Error("Collision protection modified the user-owned skill");
234
+ }
121
235
 
122
- function main() {
123
- process.stdout.write("\n");
124
- process.stdout.write(" MACCA test-install\n");
125
- process.stdout.write(` Mode: ${mode}\n`);
126
-
127
- try {
128
- if (mode === "local") {
129
- resolveLocalPackage();
130
- }
131
-
132
- fs.mkdirSync(projectDir, { recursive: true });
133
- const collisionSkill = path.join(collisionDir, ".agents", "skills", "developer", "SKILL.md");
134
- fs.mkdirSync(path.dirname(collisionSkill), { recursive: true });
135
- fs.writeFileSync(collisionSkill, "---\nname: developer\ndescription: User-owned collision fixture.\n---\n", "utf8");
236
+ if (process.platform !== "win32") {
237
+ const outsideSkills = path.join(tmpDir, "outside-skills");
238
+ fs.mkdirSync(path.join(symlinkDir, ".agents"), { recursive: true });
239
+ fs.mkdirSync(outsideSkills, { recursive: true });
240
+ fs.symlinkSync(
241
+ outsideSkills,
242
+ path.join(symlinkDir, ".agents", "skills"),
243
+ "dir",
244
+ );
245
+ expectCliFailure(
246
+ ["install", "--yes", "--tool", "codex", "--directory", symlinkDir],
247
+ "Refusing symlinked skill destination component",
248
+ );
249
+ if (fs.readdirSync(outsideSkills).length !== 0) {
250
+ throw new Error(
251
+ "Symlink containment test wrote outside the target project",
252
+ );
253
+ }
254
+
255
+ const outerReal = path.join(tmpDir, "outer-real-project");
256
+ const outerLink = path.join(tmpDir, "outer-link-project");
257
+ fs.mkdirSync(outerReal, { recursive: true });
258
+ fs.symlinkSync(outerReal, outerLink, "dir");
259
+ expectCliFailure(
260
+ ["install", "--yes", "--tool", "codex", "--directory", outerLink],
261
+ "Refusing symlinked target project ancestor",
262
+ );
263
+ if (fs.readdirSync(outerReal).length !== 0) {
264
+ throw new Error(
265
+ "Target directory ancestry symlink test wrote into the real directory",
266
+ );
267
+ }
268
+ } else {
269
+ const outerReal = path.join(tmpDir, "outer-real-project");
270
+ const outerLink = path.join(tmpDir, "outer-link-project");
271
+ fs.mkdirSync(outerReal, { recursive: true });
272
+ try {
273
+ run(commandName("cmd"), ["/c", "mklink", "/J", outerLink, outerReal]);
136
274
  expectCliFailure(
137
- ["install", "--yes", "--tool", "codex", "--directory", collisionDir],
138
- "Refusing to overwrite or remove unowned skill directory"
275
+ ["install", "--yes", "--tool", "codex", "--directory", outerLink],
276
+ "Refusing symlinked target project ancestor",
139
277
  );
140
- if (!fs.readFileSync(collisionSkill, "utf8").includes("User-owned collision fixture")) {
141
- throw new Error("Collision protection modified the user-owned skill");
142
- }
143
-
144
- if (process.platform !== "win32") {
145
- const outsideSkills = path.join(tmpDir, "outside-skills");
146
- fs.mkdirSync(path.join(symlinkDir, ".agents"), { recursive: true });
147
- fs.mkdirSync(outsideSkills, { recursive: true });
148
- fs.symlinkSync(outsideSkills, path.join(symlinkDir, ".agents", "skills"), "dir");
149
- expectCliFailure(
150
- ["install", "--yes", "--tool", "codex", "--directory", symlinkDir],
151
- "Refusing symlinked skill destination component"
152
- );
153
- if (fs.readdirSync(outsideSkills).length !== 0) {
154
- throw new Error("Symlink containment test wrote outside the target project");
155
- }
156
-
157
- const outerReal = path.join(tmpDir, "outer-real-project");
158
- const outerLink = path.join(tmpDir, "outer-link-project");
159
- fs.mkdirSync(outerReal, { recursive: true });
160
- fs.symlinkSync(outerReal, outerLink, "dir");
161
- expectCliFailure(
162
- ["install", "--yes", "--tool", "codex", "--directory", outerLink],
163
- "Refusing symlinked target project ancestor"
164
- );
165
- if (fs.readdirSync(outerReal).length !== 0) {
166
- throw new Error("Target directory ancestry symlink test wrote into the real directory");
167
- }
168
- } else {
169
- const outerReal = path.join(tmpDir, "outer-real-project");
170
- const outerLink = path.join(tmpDir, "outer-link-project");
171
- fs.mkdirSync(outerReal, { recursive: true });
172
- try {
173
- run(commandName("cmd"), ["/c", "mklink", "/J", outerLink, outerReal]);
174
- expectCliFailure(
175
- ["install", "--yes", "--tool", "codex", "--directory", outerLink],
176
- "Refusing symlinked target project ancestor"
177
- );
178
- } catch {
179
- process.stdout.write(" Skipping Windows junction ancestry test (mklink unavailable or not permitted)\n");
180
- }
181
- }
182
-
183
- const customSkill = path.join(projectDir, ".agents", "skills", "custom-skill", "SKILL.md");
184
- fs.mkdirSync(path.dirname(customSkill), { recursive: true });
185
- fs.writeFileSync(customSkill, "---\nname: custom-skill\ndescription: User-owned test skill.\n---\n", "utf8");
186
-
187
- process.stdout.write("\n");
188
- process.stdout.write(` Installing into: ${projectDir}\n`);
189
-
190
- runCli(["install", "--yes", "--tool", "codex", "--tool", "github-copilot", "--directory", projectDir]);
191
-
192
- const configPath = path.join(projectDir, ".agents", "developer-config.json");
193
- const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
194
- config.name = "Preserved Name";
195
- config.project = "Preserved Project";
196
- config.languagePreferences.communication = { raw: "English", normalized: "english" };
197
- config.languagePreferences.documents = { raw: "English", normalized: "english" };
198
- config.customField = { preserved: true };
199
- fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
200
- runCli(["install", "--yes", "--tool", "opencode", "--directory", projectDir]);
201
-
202
- run(commandName("node"), [
203
- path.join(rootDir, "scripts", "run-skill-validator.js"),
204
- path.join(projectDir, ".opencode", "skills", "_shared", "scripts", "validate-skills.py")
205
- ]);
206
-
207
- const managedPath = path.join(projectDir, ".agents", "macca-managed-skills.txt");
208
- const originalManaged = fs.readFileSync(managedPath, "utf8");
209
- fs.writeFileSync(managedPath, `${originalManaged}../../outside\n`, "utf8");
210
- expectCliFailure(["upgrade", "--directory", projectDir], "locally modified MACCA metadata");
211
- fs.writeFileSync(managedPath, originalManaged, "utf8");
212
-
213
- const maliciousSource = path.join(projectDir, "src");
214
- const maliciousTransactionId = "1-1-deadbeef";
215
- const maliciousBackup = path.join(projectDir, `.src.macca-backup-${maliciousTransactionId}`);
216
- const interruptedJournal = path.join(projectDir, ".agents", "macca-transaction.json");
217
- fs.mkdirSync(maliciousSource, { recursive: true });
218
- fs.writeFileSync(path.join(maliciousSource, "sentinel.txt"), "keep", "utf8");
219
- fs.writeFileSync(interruptedJournal, `${JSON.stringify({
220
- version: 1,
221
- phase: "committed",
222
- transactionId: maliciousTransactionId,
223
- entries: [{
224
- targetPath: maliciousSource,
225
- stagingPath: null,
226
- backupPath: maliciousBackup,
227
- kind: "directory",
228
- hadTarget: true
229
- }]
230
- }, null, 2)}\n`, "utf8");
231
- expectCliFailure(["upgrade", "--directory", projectDir], "not a managed MACCA path");
232
- assertPathExists(path.join(maliciousSource, "sentinel.txt"));
233
- fs.rmSync(interruptedJournal, { force: true });
234
-
235
- const forgedTransactionId = "3-3-feedface";
236
- const customSkillDirectory = path.dirname(customSkill);
237
- const forgedBackup = path.join(
238
- path.dirname(customSkillDirectory),
239
- `.${path.basename(customSkillDirectory)}.macca-backup-${forgedTransactionId}`
278
+ } catch {
279
+ process.stdout.write(
280
+ " Skipping Windows junction ancestry test (mklink unavailable or not permitted)\n",
240
281
  );
241
- fs.writeFileSync(interruptedJournal, `${JSON.stringify({
242
- version: 1,
243
- phase: "committing",
244
- transactionId: forgedTransactionId,
245
- entries: [{
246
- targetPath: customSkillDirectory,
247
- stagingPath: null,
248
- backupPath: forgedBackup,
249
- kind: "directory",
250
- hadTarget: false,
251
- stagedHash: null
252
- }]
253
- }, null, 2)}\n`, "utf8");
254
- expectCliFailure(["upgrade", "--directory", projectDir], "matching transaction evidence");
255
- assertPathExists(customSkill);
256
- fs.rmSync(interruptedJournal, { force: true });
257
-
258
- const interruptedConfig = fs.readFileSync(configPath, "utf8");
259
- const interruptedTransactionId = "2-2-cafebabe";
260
- const interruptedBackup = path.join(
261
- projectDir,
262
- ".agents",
263
- `.developer-config.json.macca-backup-${interruptedTransactionId}`
282
+ }
283
+ }
284
+
285
+ const customSkill = path.join(
286
+ projectDir,
287
+ ".agents",
288
+ "skills",
289
+ "custom-skill",
290
+ "SKILL.md",
291
+ );
292
+ fs.mkdirSync(path.dirname(customSkill), { recursive: true });
293
+ fs.writeFileSync(
294
+ customSkill,
295
+ "---\nname: custom-skill\ndescription: User-owned test skill.\n---\n",
296
+ "utf8",
297
+ );
298
+
299
+ process.stdout.write("\n");
300
+ process.stdout.write(` Installing into: ${projectDir}\n`);
301
+
302
+ runCli([
303
+ "install",
304
+ "--yes",
305
+ "--tool",
306
+ "codex",
307
+ "--tool",
308
+ "github-copilot",
309
+ "--directory",
310
+ projectDir,
311
+ ]);
312
+
313
+ const configPath = path.join(
314
+ projectDir,
315
+ ".agents",
316
+ "developer-config.json",
317
+ );
318
+ const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
319
+ config.name = "Preserved Name";
320
+ config.project = "Preserved Project";
321
+ config.languagePreferences.communication = {
322
+ raw: "English",
323
+ normalized: "english",
324
+ };
325
+ config.languagePreferences.documents = {
326
+ raw: "English",
327
+ normalized: "english",
328
+ };
329
+ config.customField = { preserved: true };
330
+ fs.writeFileSync(
331
+ configPath,
332
+ `${JSON.stringify(config, null, 2)}\n`,
333
+ "utf8",
334
+ );
335
+ runCli([
336
+ "install",
337
+ "--yes",
338
+ "--tool",
339
+ "opencode",
340
+ "--directory",
341
+ projectDir,
342
+ ]);
343
+
344
+ run(commandName("node"), [
345
+ path.join(rootDir, "scripts", "run-skill-validator.js"),
346
+ path.join(
347
+ projectDir,
348
+ ".opencode",
349
+ "skills",
350
+ "_shared",
351
+ "scripts",
352
+ "validate-skills.py",
353
+ ),
354
+ ]);
355
+
356
+ const managedPath = path.join(
357
+ projectDir,
358
+ ".agents",
359
+ "macca-managed-skills.txt",
360
+ );
361
+ const originalManaged = fs.readFileSync(managedPath, "utf8");
362
+ fs.writeFileSync(managedPath, `${originalManaged}../../outside\n`, "utf8");
363
+ expectCliFailure(
364
+ ["upgrade", "--directory", projectDir],
365
+ "locally modified MACCA metadata",
366
+ );
367
+ fs.writeFileSync(managedPath, originalManaged, "utf8");
368
+
369
+ const maliciousSource = path.join(projectDir, "src");
370
+ const maliciousTransactionId = "1-1-deadbeef";
371
+ const maliciousBackup = path.join(
372
+ projectDir,
373
+ `.src.macca-backup-${maliciousTransactionId}`,
374
+ );
375
+ const interruptedJournal = path.join(
376
+ projectDir,
377
+ ".agents",
378
+ "macca-transaction.json",
379
+ );
380
+ fs.mkdirSync(maliciousSource, { recursive: true });
381
+ fs.writeFileSync(
382
+ path.join(maliciousSource, "sentinel.txt"),
383
+ "keep",
384
+ "utf8",
385
+ );
386
+ fs.writeFileSync(
387
+ interruptedJournal,
388
+ `${JSON.stringify(
389
+ {
390
+ version: 1,
391
+ phase: "committed",
392
+ transactionId: maliciousTransactionId,
393
+ entries: [
394
+ {
395
+ targetPath: maliciousSource,
396
+ stagingPath: null,
397
+ backupPath: maliciousBackup,
398
+ kind: "directory",
399
+ hadTarget: true,
400
+ },
401
+ ],
402
+ },
403
+ null,
404
+ 2,
405
+ )}\n`,
406
+ "utf8",
407
+ );
408
+ expectCliFailure(
409
+ ["upgrade", "--directory", projectDir],
410
+ "not a managed MACCA path",
411
+ );
412
+ assertPathExists(path.join(maliciousSource, "sentinel.txt"));
413
+ fs.rmSync(interruptedJournal, { force: true });
414
+
415
+ const forgedTransactionId = "3-3-feedface";
416
+ const customSkillDirectory = path.dirname(customSkill);
417
+ const forgedBackup = path.join(
418
+ path.dirname(customSkillDirectory),
419
+ `.${path.basename(customSkillDirectory)}.macca-backup-${forgedTransactionId}`,
420
+ );
421
+ fs.writeFileSync(
422
+ interruptedJournal,
423
+ `${JSON.stringify(
424
+ {
425
+ version: 1,
426
+ phase: "committing",
427
+ transactionId: forgedTransactionId,
428
+ entries: [
429
+ {
430
+ targetPath: customSkillDirectory,
431
+ stagingPath: null,
432
+ backupPath: forgedBackup,
433
+ kind: "directory",
434
+ hadTarget: false,
435
+ stagedHash: null,
436
+ },
437
+ ],
438
+ },
439
+ null,
440
+ 2,
441
+ )}\n`,
442
+ "utf8",
443
+ );
444
+ expectCliFailure(
445
+ ["upgrade", "--directory", projectDir],
446
+ "matching transaction evidence",
447
+ );
448
+ assertPathExists(customSkill);
449
+ fs.rmSync(interruptedJournal, { force: true });
450
+
451
+ const interruptedConfig = fs.readFileSync(configPath, "utf8");
452
+ const interruptedTransactionId = "2-2-cafebabe";
453
+ const interruptedBackup = path.join(
454
+ projectDir,
455
+ ".agents",
456
+ `.developer-config.json.macca-backup-${interruptedTransactionId}`,
457
+ );
458
+ const interruptedTarget = `${JSON.stringify({ interrupted: true }, null, 2)}\n`;
459
+ fs.renameSync(configPath, interruptedBackup);
460
+ fs.writeFileSync(configPath, interruptedTarget, "utf8");
461
+ fs.writeFileSync(
462
+ interruptedJournal,
463
+ `${JSON.stringify(
464
+ {
465
+ version: 1,
466
+ phase: "committing",
467
+ transactionId: interruptedTransactionId,
468
+ entries: [
469
+ {
470
+ targetPath: configPath,
471
+ stagingPath: null,
472
+ backupPath: interruptedBackup,
473
+ kind: "file",
474
+ hadTarget: true,
475
+ stagedHash: crypto
476
+ .createHash("sha256")
477
+ .update(interruptedTarget)
478
+ .digest("hex"),
479
+ },
480
+ ],
481
+ },
482
+ null,
483
+ 2,
484
+ )}\n`,
485
+ "utf8",
486
+ );
487
+ runCli(["upgrade", "--directory", projectDir]);
488
+ if (fs.existsSync(interruptedJournal) || fs.existsSync(interruptedBackup)) {
489
+ throw new Error(
490
+ "Interrupted transaction recovery left journal or backup artifacts",
491
+ );
492
+ }
493
+ if (fs.readFileSync(configPath, "utf8") !== interruptedConfig) {
494
+ throw new Error(
495
+ "Interrupted transaction recovery did not restore developer-config.json",
496
+ );
497
+ }
498
+
499
+ runCli(["install", "--yes", "--tool", "opencode", "--directory", driftDir]);
500
+ const driftSkill = path.join(
501
+ driftDir,
502
+ ".opencode",
503
+ "skills",
504
+ "developer",
505
+ "SKILL.md",
506
+ );
507
+ fs.appendFileSync(driftSkill, "\nlocal edit\n", "utf8");
508
+ expectCliFailure(
509
+ ["upgrade", "--directory", driftDir],
510
+ "locally modified managed skill",
511
+ );
512
+
513
+ assertPathExists(path.join(projectDir, ".agents", "developer-config.json"));
514
+ assertPathExists(
515
+ path.join(projectDir, ".agents", "macca-managed-skills.txt"),
516
+ );
517
+ assertPathExists(path.join(projectDir, ".agents", "macca-tools.txt"));
518
+ assertPathExists(
519
+ path.join(projectDir, ".agents", "skills", "brainstorm-prd", "SKILL.md"),
520
+ );
521
+ assertPathExists(
522
+ path.join(projectDir, ".github", "skills", "brainstorm-prd", "SKILL.md"),
523
+ );
524
+ assertPathExists(
525
+ path.join(
526
+ projectDir,
527
+ ".opencode",
528
+ "skills",
529
+ "brainstorm-prd",
530
+ "SKILL.md",
531
+ ),
532
+ );
533
+ for (const skillsRoot of [
534
+ path.join(projectDir, ".agents", "skills"),
535
+ path.join(projectDir, ".github", "skills"),
536
+ path.join(projectDir, ".opencode", "skills"),
537
+ ]) {
538
+ assertPathExists(path.join(skillsRoot, "meet", "SKILL.md"));
539
+ }
540
+ assertPathExists(customSkill);
541
+ assertPathExists(path.join(projectDir, ".agents", "macca-lock.json"));
542
+
543
+ const allToolsDir = path.join(tmpDir, "all-tools-project");
544
+ runCli([
545
+ "install",
546
+ "--yes",
547
+ "--tool",
548
+ "codex",
549
+ "--tool",
550
+ "github-copilot",
551
+ "--tool",
552
+ "cursor",
553
+ "--tool",
554
+ "claude-code",
555
+ "--tool",
556
+ "windsurf",
557
+ "--tool",
558
+ "gemini-cli",
559
+ "--tool",
560
+ "opencode",
561
+ "--tool",
562
+ "kilo-code",
563
+ "--tool",
564
+ "kimi-cli",
565
+ "--directory",
566
+ allToolsDir,
567
+ ]);
568
+ for (const expectedPath of [
569
+ path.join(allToolsDir, ".agents", "skills", "meet", "SKILL.md"),
570
+ path.join(allToolsDir, ".github", "skills", "meet", "SKILL.md"),
571
+ path.join(allToolsDir, ".cursor", "skills", "meet", "SKILL.md"),
572
+ path.join(allToolsDir, ".claude", "skills", "meet", "SKILL.md"),
573
+ path.join(allToolsDir, ".windsurf", "skills", "meet", "SKILL.md"),
574
+ path.join(allToolsDir, ".gemini", "skills", "meet", "SKILL.md"),
575
+ path.join(allToolsDir, ".opencode", "skills", "meet", "SKILL.md"),
576
+ path.join(allToolsDir, ".kilo", "skills", "meet", "SKILL.md"),
577
+ ]) {
578
+ assertPathExists(expectedPath);
579
+ }
580
+
581
+ if (mode === "local") {
582
+ const downgradeDir = path.join(tmpDir, "downgrade-project");
583
+ runCli([
584
+ "install",
585
+ "--yes",
586
+ "--tool",
587
+ "github-copilot",
588
+ "--tool",
589
+ "opencode",
590
+ "--directory",
591
+ downgradeDir,
592
+ "--name",
593
+ "Downgrade User",
594
+ "--project",
595
+ "Downgrade Project",
596
+ "--communication-language",
597
+ "English",
598
+ "--document-language",
599
+ "English",
600
+ ]);
601
+ const downgradeLockPath = path.join(
602
+ downgradeDir,
603
+ ".agents",
604
+ "macca-lock.json",
605
+ );
606
+ const downgradeLock = JSON.parse(
607
+ fs.readFileSync(downgradeLockPath, "utf8"),
608
+ );
609
+ downgradeLock.version = "99.0.0";
610
+ fs.writeFileSync(
611
+ downgradeLockPath,
612
+ `${JSON.stringify(downgradeLock, null, 2)}\n`,
613
+ "utf8",
614
+ );
615
+ expectCliFailure(
616
+ ["upgrade", "--directory", downgradeDir],
617
+ "Refusing to downgrade MACCA",
618
+ );
619
+ assertPathExists(
620
+ path.join(downgradeDir, ".github", "skills", "meet", "SKILL.md"),
621
+ );
622
+ assertPathExists(
623
+ path.join(downgradeDir, ".opencode", "skills", "meet", "SKILL.md"),
624
+ );
625
+ }
626
+
627
+ const preservedConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
628
+ if (
629
+ !preservedConfig.customField ||
630
+ preservedConfig.customField.preserved !== true
631
+ ) {
632
+ throw new Error(
633
+ "Reinstall did not preserve unknown developer-config.json fields",
634
+ );
635
+ }
636
+ if (
637
+ preservedConfig.name !== "Preserved Name" ||
638
+ preservedConfig.project !== "Preserved Project" ||
639
+ preservedConfig.languagePreferences.communication.normalized !==
640
+ "english" ||
641
+ preservedConfig.languagePreferences.documents.normalized !== "english"
642
+ ) {
643
+ throw new Error("Reinstall reset known developer-config.json values");
644
+ }
645
+
646
+ const tools = readNonEmptyLines(
647
+ path.join(projectDir, ".agents", "macca-tools.txt"),
648
+ );
649
+ for (const expectedTool of ["codex", "copilot", "opencode"]) {
650
+ if (!tools.includes(expectedTool)) {
651
+ throw new Error(
652
+ `Reinstall orphaned previously selected tool: ${expectedTool}`,
264
653
  );
265
- const interruptedTarget = `${JSON.stringify({ interrupted: true }, null, 2)}\n`;
266
- fs.renameSync(configPath, interruptedBackup);
267
- fs.writeFileSync(configPath, interruptedTarget, "utf8");
268
- fs.writeFileSync(interruptedJournal, `${JSON.stringify({
269
- version: 1,
270
- phase: "committing",
271
- transactionId: interruptedTransactionId,
272
- entries: [{
273
- targetPath: configPath,
274
- stagingPath: null,
275
- backupPath: interruptedBackup,
276
- kind: "file",
277
- hadTarget: true,
278
- stagedHash: crypto.createHash("sha256").update(interruptedTarget).digest("hex")
279
- }]
280
- }, null, 2)}\n`, "utf8");
281
- runCli(["upgrade", "--directory", projectDir]);
282
- if (fs.existsSync(interruptedJournal) || fs.existsSync(interruptedBackup)) {
283
- throw new Error("Interrupted transaction recovery left journal or backup artifacts");
284
- }
285
- if (fs.readFileSync(configPath, "utf8") !== interruptedConfig) {
286
- throw new Error("Interrupted transaction recovery did not restore developer-config.json");
287
- }
288
-
289
- runCli(["install", "--yes", "--tool", "opencode", "--directory", driftDir]);
290
- const driftSkill = path.join(driftDir, ".opencode", "skills", "developer", "SKILL.md");
291
- fs.appendFileSync(driftSkill, "\nlocal edit\n", "utf8");
292
- expectCliFailure(["upgrade", "--directory", driftDir], "locally modified managed skill");
293
-
294
- assertPathExists(path.join(projectDir, ".agents", "developer-config.json"));
295
- assertPathExists(path.join(projectDir, ".agents", "macca-managed-skills.txt"));
296
- assertPathExists(path.join(projectDir, ".agents", "macca-tools.txt"));
297
- assertPathExists(path.join(projectDir, ".agents", "skills", "brainstorm-prd", "SKILL.md"));
298
- assertPathExists(path.join(projectDir, ".github", "skills", "brainstorm-prd", "SKILL.md"));
299
- assertPathExists(path.join(projectDir, ".opencode", "skills", "brainstorm-prd", "SKILL.md"));
300
- for (const skillsRoot of [
301
- path.join(projectDir, ".agents", "skills"),
302
- path.join(projectDir, ".github", "skills"),
303
- path.join(projectDir, ".opencode", "skills")
304
- ]) {
305
- assertPathExists(path.join(skillsRoot, "meet", "SKILL.md"));
306
- }
307
- assertPathExists(customSkill);
308
- assertPathExists(path.join(projectDir, ".agents", "macca-lock.json"));
309
-
310
- const allToolsDir = path.join(tmpDir, "all-tools-project");
311
- runCli([
312
- "install",
313
- "--yes",
314
- "--tool", "codex",
315
- "--tool", "github-copilot",
316
- "--tool", "cursor",
317
- "--tool", "claude-code",
318
- "--tool", "windsurf",
319
- "--tool", "gemini-cli",
320
- "--tool", "opencode",
321
- "--tool", "kilo-code",
322
- "--tool", "kimi-cli",
323
- "--directory", allToolsDir
324
- ]);
325
- for (const expectedPath of [
326
- path.join(allToolsDir, ".agents", "skills", "meet", "SKILL.md"),
327
- path.join(allToolsDir, ".github", "skills", "meet", "SKILL.md"),
328
- path.join(allToolsDir, ".cursor", "skills", "meet", "SKILL.md"),
329
- path.join(allToolsDir, ".claude", "skills", "meet", "SKILL.md"),
330
- path.join(allToolsDir, ".windsurf", "skills", "meet", "SKILL.md"),
331
- path.join(allToolsDir, ".gemini", "skills", "meet", "SKILL.md"),
332
- path.join(allToolsDir, ".opencode", "skills", "meet", "SKILL.md"),
333
- path.join(allToolsDir, ".kilo", "skills", "meet", "SKILL.md")
334
- ]) {
335
- assertPathExists(expectedPath);
336
- }
337
-
338
- if (mode === "local") {
339
- const downgradeDir = path.join(tmpDir, "downgrade-project");
340
- runCli([
341
- "install",
342
- "--yes",
343
- "--tool", "github-copilot",
344
- "--tool", "opencode",
345
- "--directory", downgradeDir,
346
- "--name", "Downgrade User",
347
- "--project", "Downgrade Project",
348
- "--communication-language", "English",
349
- "--document-language", "English"
350
- ]);
351
- const downgradeLockPath = path.join(downgradeDir, ".agents", "macca-lock.json");
352
- const downgradeLock = JSON.parse(fs.readFileSync(downgradeLockPath, "utf8"));
353
- downgradeLock.version = "99.0.0";
354
- fs.writeFileSync(downgradeLockPath, `${JSON.stringify(downgradeLock, null, 2)}\n`, "utf8");
355
- expectCliFailure([
356
- "upgrade",
357
- "--directory", downgradeDir
358
- ], "Refusing to downgrade MACCA");
359
- assertPathExists(path.join(downgradeDir, ".github", "skills", "meet", "SKILL.md"));
360
- assertPathExists(path.join(downgradeDir, ".opencode", "skills", "meet", "SKILL.md"));
361
- }
362
-
363
- const preservedConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
364
- if (!preservedConfig.customField || preservedConfig.customField.preserved !== true) {
365
- throw new Error("Reinstall did not preserve unknown developer-config.json fields");
366
- }
367
- if (
368
- preservedConfig.name !== "Preserved Name"
369
- || preservedConfig.project !== "Preserved Project"
370
- || preservedConfig.languagePreferences.communication.normalized !== "english"
371
- || preservedConfig.languagePreferences.documents.normalized !== "english"
372
- ) {
373
- throw new Error("Reinstall reset known developer-config.json values");
374
- }
375
-
376
- const tools = readNonEmptyLines(path.join(projectDir, ".agents", "macca-tools.txt"));
377
- for (const expectedTool of ["codex", "copilot", "opencode"]) {
378
- if (!tools.includes(expectedTool)) {
379
- throw new Error(`Reinstall orphaned previously selected tool: ${expectedTool}`);
380
- }
381
- }
382
-
383
- ensureExpectedTools(path.join(projectDir, ".agents", "macca-tools.txt"));
384
-
385
- process.stdout.write("\n");
386
- process.stdout.write(" Verified files:\n");
387
- for (const filePath of listFiles(projectDir)) {
388
- process.stdout.write(`${filePath}\n`);
389
- }
390
-
391
- process.stdout.write("\n");
392
- process.stdout.write(" ✓ test-install passed\n");
393
- } finally {
394
- fs.rmSync(tmpDir, { recursive: true, force: true });
654
+ }
395
655
  }
656
+
657
+ ensureExpectedTools(path.join(projectDir, ".agents", "macca-tools.txt"));
658
+
659
+ process.stdout.write("\n");
660
+ process.stdout.write(" Verified files:\n");
661
+ for (const filePath of listFiles(projectDir)) {
662
+ process.stdout.write(`${filePath}\n`);
663
+ }
664
+
665
+ process.stdout.write("\n");
666
+ process.stdout.write(" ✓ test-install passed\n");
667
+ } finally {
668
+ fs.rmSync(tmpDir, { recursive: true, force: true });
669
+ }
396
670
  }
397
671
 
398
672
  main();