@givolt/i3-composer-agent 2.2.2 → 2.2.3

package/scripts/validate-artifact-paths-test.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { afterEach, test } = require('node:test');
+
+const VALIDATOR = path.join(__dirname, 'validate-artifact-paths.js');
+const sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-validate-artifact-paths-test-'));
+  const scriptsDir = path.join(root, 'scripts');
+  fs.mkdirSync(scriptsDir, { recursive: true });
+  fs.copyFileSync(VALIDATOR, path.join(scriptsDir, 'validate-artifact-paths.js'));
+  sandboxes.push(root);
+  return root;
+}
+
+function writeFile(root, relativePath, content) {
+  const file = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function run(root) {
+  return spawnSync(process.execPath, [path.join(root, 'scripts', 'validate-artifact-paths.js')], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+}
+
+afterEach(() => {
+  for (const root of sandboxes.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('passes when producers and consumers use the canonical artifact paths', () => {
+  const root = makeSandbox();
+  writeFile(root, '.claude/commands/spec.md', 'Save the spec as `SPEC.md` in the project root.\n');
+  writeFile(root, '.claude/commands/plan.md', 'Save the plan to `tasks/plan.md` and task list to `tasks/todo.md`.\n');
+  writeFile(root, '.claude/commands/build.md', 'Look for a spec at `SPEC.md`, `docs/SPEC.md`, or under `spec/`. Require `tasks/plan.md`.\n');
+  writeFile(root, 'skills/i3-spec-driven-development/SKILL.md', 'Save the plan to `tasks/plan.md` and the task list to `tasks/todo.md`.\n');
+  writeFile(root, 'skills/i3-planning-and-task-breakdown/SKILL.md', 'Save to `tasks/plan.md` and `tasks/todo.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /5 files checked — 0 error\(s\) — PASSED/);
+});
+
+test('fails when a producer drifts to an unapproved artifact path (the #93 regression)', () => {
+  const root = makeSandbox();
+  // Only the producers are changed to the per-feature layout; consumers stay on the old paths.
+  writeFile(root, '.claude/commands/spec.md', 'Save the spec to `docs/features/[feature-name]/spec.md`.\n');
+  writeFile(root, '.claude/commands/plan.md', 'Save the plan to `docs/features/[feature-name]/plan.md`.\n');
+  writeFile(root, '.claude/commands/build.md', 'Require a spec at `SPEC.md` and a plan at `tasks/plan.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /docs\/features\/\[feature-name\]\/spec\.md/);
+  assert.match(result.stdout, /docs\/features\/\[feature-name\]\/plan\.md/);
+  assert.match(result.stdout, /error\(s\) — FAILED/);
+});
+
+test('reports the offending file and line number', () => {
+  const root = makeSandbox();
+  writeFile(root, '.claude/commands/plan.md', 'Intro line.\nSave the plan to `plan.md` in the root.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /\.claude\/commands\/plan\.md/);
+  assert.match(result.stdout, /L2:/);
+});
+
+test('accepts the docs/SPEC.md alternate spec location', () => {
+  const root = makeSandbox();
+  writeFile(root, '.claude/commands/build.md', 'Look for the spec at `docs/SPEC.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 files checked — 0 error\(s\) — PASSED/);
+});
+
+test('ignores non-artifact markdown references (no false positives)', () => {
+  const root = makeSandbox();
+  writeFile(
+    root,
+    'skills/i3-spec-driven-development/SKILL.md',
+    'See `SKILL.md` and `references/testing-patterns.md`. Save the plan to `tasks/plan.md`.\n',
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 files checked — 0 error\(s\) — PASSED/);
+});
+
+test('skips guarded files that do not exist', () => {
+  const root = makeSandbox();
+  writeFile(root, '.claude/commands/spec.md', 'Save the spec as `SPEC.md`.\n');
+  // No other guarded files present.
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 files checked — 0 error\(s\) — PASSED/);
+});
+
+// ─── Every command surface is guarded, not only the Claude Code copy ────────
+//
+// The Gemini and root TOML command sets carry their own prompt bodies, which
+// validate-commands.js deliberately does not compare. A producer can therefore
+// drift on one surface while `.claude/commands/` stays correct, and before
+// these files were guarded that drift merged silently.
+
+test('fails when a Gemini command drifts while the Claude Code copy stays canonical', () => {
+  const root = makeSandbox();
+  writeFile(root, '.claude/commands/spec.md', 'Save the spec as `SPEC.md` in the project root.\n');
+  writeFile(
+    root,
+    '.gemini/commands/spec.toml',
+    'description = "Start spec-driven development"\n\nprompt = """\nSave the spec to `docs/features/[feature-name]/spec.md`.\n"""\n',
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /\.gemini\/commands\/spec\.toml/);
+  assert.match(result.stdout, /L4: docs\/features\/\[feature-name\]\/spec\.md/);
+  assert.match(result.stdout, /1 error\(s\) — FAILED/);
+});
+
+test('fails when a root TOML consumer drifts away from the producers', () => {
+  const root = makeSandbox();
+  writeFile(root, 'commands/planning.toml', 'prompt = """\nSave the plan to `tasks/plan.md` and the task list to `tasks/todo.md`.\n"""\n');
+  writeFile(root, 'commands/build.toml', 'prompt = """\nRead the plan from `planning/plan.md` before starting.\n"""\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /commands\/build\.toml/);
+  assert.match(result.stdout, /planning\/plan\.md/);
+});
+
+test('passes when all three command surfaces agree on the canonical paths', () => {
+  const root = makeSandbox();
+  for (const dir of ['.claude/commands', '.gemini/commands', 'commands']) {
+    const ext = dir === '.claude/commands' ? 'md' : 'toml';
+    const planStem = dir === '.claude/commands' ? 'plan' : 'planning';
+    writeFile(root, `${dir}/spec.${ext}`, 'Save the spec as `SPEC.md`.\n');
+    writeFile(root, `${dir}/${planStem}.${ext}`, 'Save to `tasks/plan.md` and `tasks/todo.md`.\n');
+    writeFile(root, `${dir}/build.${ext}`, 'Require `SPEC.md` or `docs/SPEC.md`, and `tasks/plan.md`.\n');
+  }
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /9 files checked — 0 error\(s\) — PASSED/);
+});
+
+test('guards the Copilot setup doc, whose prompt-file aliases name the artifacts', () => {
+  const root = makeSandbox();
+  writeFile(root, 'docs/copilot-setup.md', 'Read `tasks/plan.md`, then write the spec to `specs/[name]/spec.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /docs\/copilot-setup\.md/);
+  assert.match(result.stdout, /specs\/\[name\]\/spec\.md/);
+});

package/scripts/validate-commands-test.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { afterEach, test } = require('node:test');
+
+const VALIDATOR = path.join(__dirname, 'validate-commands.js');
+// The validator shares the frontmatter-validity rules with validate-skills, so
+// the sandbox needs the lib alongside it, not just the script.
+const SKILL_LINT = path.join(__dirname, 'lib', 'skill-lint.js');
+const sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-validate-commands-test-'));
+  const scriptsDir = path.join(root, 'scripts');
+  fs.mkdirSync(scriptsDir, { recursive: true });
+  fs.copyFileSync(VALIDATOR, path.join(scriptsDir, 'validate-commands.js'));
+  fs.mkdirSync(path.join(scriptsDir, 'lib'), { recursive: true });
+  fs.copyFileSync(SKILL_LINT, path.join(scriptsDir, 'lib', 'skill-lint.js'));
+  sandboxes.push(root);
+  return root;
+}
+
+function writeFile(root, relativePath, content) {
+  const file = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function writeClaudeCommand(root, stem, descriptionLine) {
+  writeFile(
+    root,
+    path.join('.claude', 'commands', `${stem}.md`),
+    `---\n${descriptionLine}\n---\n\n# Command\n`,
+  );
+}
+
+function writeTomlCommand(root, directory, stem, descriptionLine) {
+  writeFile(root, path.join(directory, `${stem}.toml`), `${descriptionLine}\nprompt = "Run command"\n`);
+}
+
+function writeMatchingCommands(root, stem, description) {
+  writeClaudeCommand(root, stem, `description: ${description}`);
+  writeTomlCommand(root, path.join('.gemini', 'commands'), stem, `description = "${description}"`);
+  writeTomlCommand(root, 'commands', stem, `description = "${description}"`);
+}
+
+function run(root) {
+  return spawnSync(process.execPath, [path.join(root, 'scripts', 'validate-commands.js')], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+}
+
+afterEach(() => {
+  for (const root of sandboxes.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('passes matching command twins and maps plan to planning', () => {
+  const root = makeSandbox();
+  const description = 'Break work into ordered tasks';
+  writeClaudeCommand(root, 'plan', `description: ${description}`);
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'planning', `description = '${description}'`);
+  writeTomlCommand(root, 'commands', 'planning', `description = '${description}'`);
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /✓  plan \(planning in toml dirs\)/);
+  assert.match(result.stdout, /1 commands checked — 0 error\(s\) — PASSED/);
+});
+
+test('fails when a Claude command is missing a TOML twin', () => {
+  const root = makeSandbox();
+  const description = 'Review a change';
+  writeClaudeCommand(root, 'review', `description: ${description}`);
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'review', `description = "${description}"`);
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /review — missing in: commands/);
+  assert.match(result.stdout, /1 commands checked — 1 error\(s\) — FAILED/);
+});
+
+test('fails when a TOML command has no Claude twin', () => {
+  const root = makeSandbox();
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'deploy', 'description = "Deploy a change"');
+  writeTomlCommand(root, 'commands', 'deploy', 'description = "Deploy a change"');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /deploy — present in toml dirs but missing in \.claude\/commands/);
+  assert.match(result.stdout, /1 commands checked — 1 error\(s\) — FAILED/);
+});
+
+test('reports all descriptions when command twins drift', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'review', 'description: Review a change');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'review', 'description = "Inspect a change"');
+  writeTomlCommand(root, 'commands', 'review', 'description = "Audit a change"');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /\.claude:\s+Review a change/);
+  assert.match(result.stdout, /\.gemini:\s+Inspect a change/);
+  assert.match(result.stdout, /commands\/:\s+Audit a change/);
+});
+
+test('fails with an actionable error for a malformed description', () => {
+  const root = makeSandbox();
+  writeMatchingCommands(root, 'review', 'Review a change');
+  writeFile(
+    root,
+    path.join('.gemini', 'commands', 'review.toml'),
+    'prompt = "Missing description"\n',
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /\.gemini\/commands\/review — missing or malformed description/);
+  assert.match(result.stdout, /1 commands checked — 1 error\(s\) — FAILED/);
+});
+
+test('parses escaped quotes in double-quoted TOML descriptions', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'review', 'description: Review "important" changes');
+  writeTomlCommand(
+    root,
+    path.join('.gemini', 'commands'),
+    'review',
+    'description = "Review \\"important\\" changes"',
+  );
+  writeTomlCommand(
+    root,
+    'commands',
+    'review',
+    'description = "Review \\"important\\" changes"',
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 commands checked — 0 error\(s\) — PASSED/);
+});
+
+// Claude parses a command's frontmatter as YAML when the command is loaded, and
+// `descriptionFromMd` splits each line on its first colon — so a command whose
+// frontmatter is not valid YAML passed every check here. Same class as the
+// SKILL.md gap, on the other set of files the #494 thread checked by hand.
+
+test('a command whose frontmatter is valid YAML passes', () => {
+  const root = makeSandbox();
+  writeMatchingCommands(root, 'build', 'Build the thing');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout);
+  assert.match(result.stdout, /Checking Claude command frontmatter/);
+});
+
+test('an unquoted colon in a command description is rejected', () => {
+  const root = makeSandbox();
+  // Valid to the splitter, rejected by a real YAML parser: it reads a nested
+  // mapping. The TOML siblings keep the same text so only the .md is at fault.
+  writeClaudeCommand(root, 'build', 'description: Build the thing: quickly');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'build', 'description = "Build the thing: quickly"');
+  writeTomlCommand(root, 'commands', 'build', 'description = "Build the thing: quickly"');
+
+  const result = run(root);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stdout, /unquoted value containing/);
+});
+
+test('quoting the same description makes it pass', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'build', 'description: "Build the thing: quickly"');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'build', 'description = "Build the thing: quickly"');
+  writeTomlCommand(root, 'commands', 'build', 'description = "Build the thing: quickly"');
+
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout);
+});
+
+test('a tab-indented command frontmatter is rejected', () => {
+  const root = makeSandbox();
+  writeFile(
+    root,
+    path.join('.claude', 'commands', 'build.md'),
+    '---\ndescription: Build the thing\nmeta:\n\tlevel: core\n---\n\n# Command\n',
+  );
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'build', 'description = "Build the thing"');
+  writeTomlCommand(root, 'commands', 'build', 'description = "Build the thing"');
+
+  const result = run(root);
+  assert.equal(result.status, 1, result.stdout);
+  assert.match(result.stdout, /indents with a tab/);
+});
+
+test('the TOML directories are not put through the YAML rules', () => {
+  const root = makeSandbox();
+  // A TOML description legitimately carries a colon. Running the YAML rules over
+  // these files would fail every command that has one.
+  writeMatchingCommands(root, 'build', 'Build the thing quickly');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout);
+  assert.doesNotMatch(result.stdout, /\.gemini.*unquoted value/);
+});