From 1a349a7496b2a5b071b0e7cf898ca1cd35122577 Mon Sep 17 00:00:00 2001 From: factory-review-fix Date: Fri, 13 Nov 2026 13:27:06 +0200 Subject: [PATCH] feat(skills): skip command generation for reference-only skills (ADR-507) skills add: a skill whose frontmatter carries reference-only: true (or "true") generates no command file and is counted in a visible skip line; unmarked siblings in the same install still generate. skills update: a stale generated command for a reference-only skill is deleted (the pre-marker install artifact); a user-authored file with the same name is left untouched. Implements the adlc-cli half of adlc-workspace ADR-507 (factory-runbook is reference-only - never invoked, no slash command). Both guarded call sites are pinned by tests/reference-only.test.mjs (passes with the change, fails without it). --- src/commands/skills.mjs | 22 ++++ tests/reference-only.test.mjs | 183 ++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 tests/reference-only.test.mjs diff --git a/src/commands/skills.mjs b/src/commands/skills.mjs index 5f704dc..86c379a 100644 --- a/src/commands/skills.mjs +++ b/src/commands/skills.mjs @@ -169,7 +169,12 @@ export async function cmdAdd(args, flags) { mkdirSync(absCommandsDir, { recursive: true }); let generated = 0; + let referenceSkipped = 0; for (const skill of filtered) { + if (skill.frontmatter?.["reference-only"] === true || skill.frontmatter?.["reference-only"] === "true") { + referenceSkipped++; + continue; + } const filename = commandFilename(skill, agent, { prefix }); const content = generateCommand(skill, agent, { mode, prefix, source }); const filepath = join(absCommandsDir, filename); @@ -180,6 +185,12 @@ export async function cmdAdd(args, flags) { glyph: sym.success, color: "green", }); + if (referenceSkipped > 0) { + item(`Skipped ${referenceSkipped} reference-only skill(s) (no command file)`, { + glyph: sym.info, + color: "gray", + }); + } const agentEventConfig = getEventAgentConfig(agentKey); if (agentEventConfig && !noEvents) { @@ -322,6 +333,17 @@ export async function cmdUpdate(args, flags) { let skipped = 0; for (const skill of skills) { + if (skill.frontmatter?.["reference-only"] === true || skill.frontmatter?.["reference-only"] === "true") { + const filename = commandFilename(skill, agent, { prefix }); + const filepath = join(absCommandsDir, filename); + if (existsSync(filepath) && isGenerated(readFileSync(filepath, "utf-8"))) { + rmSync(filepath); + updated++; + } else { + skipped++; + } + continue; + } const filename = commandFilename(skill, agent, { prefix }); const filepath = join(absCommandsDir, filename); diff --git a/tests/reference-only.test.mjs b/tests/reference-only.test.mjs new file mode 100644 index 0000000..5ffdc16 --- /dev/null +++ b/tests/reference-only.test.mjs @@ -0,0 +1,183 @@ +// tests/reference-only.test.mjs — ADR-507: reference-only skills never get a +// command file. +// +// The `reference-only: true` frontmatter marker (adlc-workspace ADR-507, +// "factory-runbook is reference-only — never invoked, no slash command") has +// two CLI obligations, both pinned here: +// 1. `skills add` skips command generation for marked skills and reports the +// skip count; unmarked siblings in the same install still generate. +// 2. `skills update` deletes a stale *generated* command for a marked skill +// (the pre-marker install artifact) while leaving a user-authored file +// with the same name untouched. +// +// The units under test (cmdAdd, cmdUpdate) run for real against temp-dir +// fixtures through the CLI binary, the way team-mcp-chain.test.mjs runs its +// units: one external boundary is stubbed — the `npx skills` installer (a PATH +// stub; cmdAdd's install loop must not hit the network), and `--no-events` +// keeps the events-manifest fetch offline. Frontmatter parsing yields strings +// (`reference-only: true` and `reference-only: "true"` both arrive as `"true"`), +// so both spellings are pinned. + +import { it } from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + readFileSync, + existsSync, + rmSync, + chmodSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname, resolve, delimiter } from "node:path"; +import { fileURLToPath } from "node:url"; +import { findInstalledSkills } from "../src/source.mjs"; +import { generateCommand, commandFilename, isGenerated } from "../src/convert.mjs"; +import { getAgent } from "../src/registry.mjs"; + +const exec = promisify(execFile); +const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +const BIN = join(REPO_ROOT, "bin", "adlc-cli.mjs"); +// execFile resolves without a status and rejects with e.code on non-zero — +// normalise both shapes to { status, stdout, stderr }. +const run = async (args, { cwd, env } = {}) => { + try { + const { stdout, stderr } = await exec(process.execPath, [BIN, ...args], { + cwd, + env: { ...process.env, ...env }, + }); + return { status: 0, stdout, stderr }; + } catch (e) { + return { status: typeof e.code === "number" ? e.code : 1, stdout: e.stdout || "", stderr: e.stderr || "" }; + } +}; + +const SKILLS = { + "plain-skill": `--- +name: plain-skill +description: An ordinary invocable skill with no marker. +--- + +# plain-skill + +Ordinary body.`, + "ref-bool": `--- +name: ref-bool +description: Reference-only skill, bare boolean spelling. +reference-only: true +--- + +# ref-bool + +Read this; never invoke it.`, + "ref-str": `--- +name: ref-str +description: Reference-only skill, quoted spelling. +reference-only: "true" +--- + +# ref-str + +Read this; never invoke it.`, +}; + +// Temp project: the three fixture skills installed under .agents/skills, plus +// a PATH stub for `npx` so cmdAdd's install loop exits 0 without network. +// Two twins of the stub — `npx` (POSIX shebang script) and `npx.cmd` (CRLF +// batch): on Windows spawnNpxSync goes through cmd.exe, which resolves the +// command via PATHEXT and cannot execute an extensionless script. +function project() { + const dir = mkdtempSync(join(tmpdir(), "adlc-reference-only-")); + + for (const [name, content] of Object.entries(SKILLS)) { + mkdirSync(join(dir, ".agents", "skills", name), { recursive: true }); + writeFileSync(join(dir, ".agents", "skills", name, "SKILL.md"), content, "utf-8"); + } + + const bin = join(dir, "bin"); + mkdirSync(bin, { recursive: true }); + const npx = join(bin, "npx"); + writeFileSync(npx, "#!/bin/sh\nexit 0\n", "utf-8"); + chmodSync(npx, 0o755); + writeFileSync(join(bin, "npx.cmd"), "@echo off\r\nexit /b 0\r\n", "utf-8"); + + const pathValue = [bin, process.env.PATH].filter(Boolean).join(delimiter); + const env = process.platform === "win32" + ? { PATH: pathValue, Path: pathValue } + : { PATH: pathValue }; + + return { + dir, + path: (rel) => join(dir, rel), + exists: (rel) => existsSync(join(dir, rel)), + read: (rel) => readFileSync(join(dir, rel), "utf-8"), + env, + cleanup: () => rmSync(dir, { recursive: true, force: true }), + }; +} + +it("skills add: generates commands for plain skills, skips reference-only ones", async () => { + const p = project(); + try { + const r = await run(["skills", "add", "fixture-src", "-a", "opencode", "--no-events"], { + cwd: p.dir, + env: p.env, + }); + assert.equal(r.status, 0, `exit ${r.status}: ${r.stderr || r.stdout}`); + + // The unmarked sibling still generates — the skip is selective, not a stall. + const plain = p.read(".opencode/commands/plain-skill.md"); + assert.ok(isGenerated(plain), "plain-skill command must be generated"); + + // Both marker spellings are skipped: no command file at all. + assert.ok(!p.exists(".opencode/commands/ref-bool.md"), "ref-bool must not get a command"); + assert.ok(!p.exists(".opencode/commands/ref-str.md"), "ref-str must not get a command"); + + // The skip is visible, not silent. + assert.match(r.stdout, /Skipped 2 reference-only skill\(s\)/); + } finally { + p.cleanup(); + } +}); + +it("skills update: deletes a stale generated command, preserves a user-authored one", async () => { + const p = project(); + try { + const agent = getAgent("opencode"); + const skills = await findInstalledSkills(".agents/skills", p.dir); + const byName = Object.fromEntries(skills.map((s) => [s.name, s])); + + // Pre-marker artifact: ref-bool had a command generated before the marker + // existed. Regenerating here is the faithful shape — same code path cmdAdd + // used — so isGenerated() must recognise it as ours to delete. + mkdirSync(p.path(".opencode/commands"), { recursive: true }); + writeFileSync( + p.path(".opencode/commands/ref-bool.md"), + generateCommand(byName["ref-bool"], agent, { source: "pre-marker" }), + "utf-8", + ); + + // A user-authored file sharing the skipped skill's name — not ours, must + // survive the update untouched. + const userContent = "# My own ref-str command\n\nHand-written body.\n"; + writeFileSync(p.path(".opencode/commands/ref-str.md"), userContent, "utf-8"); + + // No --pull: cmdUpdate regenerates from installed skills without npx. + const r = await run(["skills", "update", "-a", "opencode"], { cwd: p.dir, env: p.env }); + assert.equal(r.status, 0, `exit ${r.status}: ${r.stderr || r.stdout}`); + + // Stale generated command for the marked skill is gone. + assert.ok(!p.exists(".opencode/commands/ref-bool.md"), "stale generated command must be deleted"); + // User-authored file survives byte-for-byte. + assert.equal(p.read(".opencode/commands/ref-str.md"), userContent, "user file must be untouched"); + // The plain skill regenerates as usual in the same pass. + assert.ok(isGenerated(p.read(".opencode/commands/plain-skill.md")), "plain-skill regenerates"); + // 2 updates (ref-bool deletion + plain-skill generation), 1 skipped (ref-str). + assert.match(r.stdout, /2 updated, 1 user-modified \(skipped\)/); + } finally { + p.cleanup(); + } +});