magus-cli 7.3.1 → 7.4.1

package/src/__tests__/blind/c12-skill-frontmatter.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Blind tests — contract C12 (requirement R9.5): a skill's frontmatter is read
+ * as YAML, with a line-by-line reading as the fallback when the block is not
+ * valid YAML.
+ *
+ * Written from requirements.md and architecture.md only. No implementation
+ * file was read. The module is loaded with a dynamic import inside each test,
+ * so a missing export fails its own tests one by one instead of failing the
+ * whole file at load time.
+ *
+ * readLocalSkillFrontmatter takes an absolute SKILL.md path, so every test
+ * writes its own SKILL.md into a fresh temp dir and passes that path. Nothing
+ * depends on HOME.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const load = () => import("../../services/skills-manager.js");
+
+const FALLBACK = "fallback-skill-name";
+
+const dirs: string[] = [];
+afterEach(() => {
+	while (dirs.length > 0) {
+		const dir = dirs.pop();
+		if (dir) rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+function tempDir(): string {
+	const dir = mkdtempSync(path.join(os.tmpdir(), "magus-c12-"));
+	dirs.push(dir);
+	return dir;
+}
+
+/** Writes `lines` joined by "\n" (plus a trailing newline) as SKILL.md; returns its absolute path. */
+function writeSkill(lines: string[]): string {
+	const dir = tempDir();
+	const file = path.join(dir, "SKILL.md");
+	writeFileSync(file, `${lines.join("\n")}\n`, "utf8");
+	return file;
+}
+
+/** Collapses every whitespace run to one space and trims — compares text independent of line breaks. */
+const squash = (s: string): string => s.replace(/\s+/g, " ").trim();
+
+async function read(file: string, fallback = FALLBACK) {
+	const { readLocalSkillFrontmatter } = await load();
+	return readLocalSkillFrontmatter(file, fallback);
+}
+
+describe("C12 — block-scalar descriptions yield the text", () => {
+	test("R9.5 folded `>-` over three indented lines yields the lines joined by single spaces", async () => {
+		const file = writeSkill([
+			"---",
+			"name: folded-skill",
+			"description: >-",
+			"  Reviews pull requests for style.",
+			"  Use when the user asks for a review,",
+			"  or mentions lint.",
+			"---",
+			"",
+			"# Body",
+		]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("folded-skill");
+		expect(fm?.description).toBe(
+			"Reviews pull requests for style. Use when the user asks for a review, or mentions lint.",
+		);
+		expect(fm?.description.startsWith(">")).toBe(false);
+	});
+
+	test("R9.5 folded `>-` over two indented lines yields the joined text, never the literal `>-`", async () => {
+		const file = writeSkill([
+			"---",
+			"name: two-line",
+			"description: >-",
+			"  First half of the text",
+			"  second half of the text",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.description).toBe(
+			"First half of the text second half of the text",
+		);
+		expect(fm?.description).not.toContain(">-");
+	});
+
+	test("R9.5 folded `>` (clip) yields the text, never a leading `>`", async () => {
+		const file = writeSkill([
+			"---",
+			"name: clip-folded",
+			"description: >",
+			"  Alpha beta",
+			"  gamma delta",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.description.startsWith(">")).toBe(false);
+		expect(squash(fm?.description ?? "")).toBe("Alpha beta gamma delta");
+	});
+
+	test("R9.5 literal `|` yields the text (line breaks allowed), never the literal `|`", async () => {
+		const file = writeSkill([
+			"---",
+			"name: literal-skill",
+			"description: |",
+			"  First line of the description.",
+			"  Second line of the description.",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("literal-skill");
+		expect(fm?.description.startsWith("|")).toBe(false);
+		expect(fm?.description).not.toBe("|");
+		expect(squash(fm?.description ?? "")).toBe(
+			"First line of the description. Second line of the description.",
+		);
+	});
+
+	test("R9.5 literal `|-` yields the text, never the literal `|-`", async () => {
+		const file = writeSkill([
+			"---",
+			"name: literal-strip",
+			"description: |-",
+			"  One",
+			"  Two",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.description).not.toContain("|-");
+		expect(squash(fm?.description ?? "")).toBe("One Two");
+	});
+
+	test("R9.5 a block scalar ends at the next key — the following key's text is not in the description", async () => {
+		const file = writeSkill([
+			"---",
+			"description: >-",
+			"  Text of the description",
+			"  continues here",
+			"name: key-after-block",
+			"version: 1.2.3",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe("key-after-block");
+		expect(fm?.description).toBe("Text of the description continues here");
+		expect(fm?.description).not.toContain("key-after-block");
+		expect(fm?.description).not.toContain("1.2.3");
+	});
+});
+
+describe("C12 — plain and quoted descriptions", () => {
+	test("R9.5 a plain one-line description is returned as written", async () => {
+		const file = writeSkill([
+			"---",
+			"name: plain-skill",
+			"description: foo bar",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("plain-skill");
+		expect(fm?.description).toBe("foo bar");
+	});
+
+	test("R9.5 a double-quoted description containing `: ` yields the unquoted text", async () => {
+		const file = writeSkill([
+			"---",
+			"name: dq-skill",
+			'description: "Use when: the user asks for help"',
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe("dq-skill");
+		expect(fm?.description).toBe("Use when: the user asks for help");
+	});
+
+	test("R9.5 a single-quoted description containing `: ` yields the unquoted text", async () => {
+		const file = writeSkill([
+			"---",
+			"name: sq-skill",
+			"description: 'Triggers: review, lint'",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe("sq-skill");
+		expect(fm?.description).toBe("Triggers: review, lint");
+	});
+});
+
+describe("C12 — frontmatter that is not valid YAML falls back to a line-by-line reading", () => {
+	test("R9.5 an unquoted `: ` inside the description still yields the description and the name", async () => {
+		const file = writeSkill([
+			"---",
+			"name: colon-skill",
+			"description: Use when: the user asks",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("colon-skill");
+		expect(fm?.description).toContain("Use when");
+		expect(fm?.description).toContain("the user asks");
+	});
+
+	test("R9.5 invalid YAML with the name AFTER the description still yields both", async () => {
+		const file = writeSkill([
+			"---",
+			"description: Reviews code. Use when: the user asks for a review",
+			"name: name-after-bad-line",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe("name-after-bad-line");
+		expect(fm?.description).toContain("Reviews code. Use when");
+		expect(fm?.description).toContain("the user asks for a review");
+	});
+
+	test("R9.5 invalid YAML with no name falls back to the caller's name and keeps the description", async () => {
+		const file = writeSkill([
+			"---",
+			"description: Use when: the user asks",
+			"---",
+		]);
+		const fm = await read(file, "caller-name");
+		expect(fm?.name).toBe("caller-name");
+		expect(fm?.description).toContain("Use when");
+		expect(fm?.description).toContain("the user asks");
+	});
+});
+
+describe("C12 — missing fields", () => {
+	test("R9.5 a missing name falls back to the caller's name", async () => {
+		const file = writeSkill(["---", "description: has no name", "---"]);
+		const fm = await read(file, "from-the-caller");
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("from-the-caller");
+		expect(fm?.description).toBe("has no name");
+	});
+
+	test("R9.5 a missing description yields the empty string", async () => {
+		const file = writeSkill(["---", "name: no-description", "---"]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe("no-description");
+		expect(fm?.description).toBe("");
+	});
+
+	test("R9.5 a missing name and description yields the fallback name and the empty string", async () => {
+		const file = writeSkill(["---", "version: 1.0.0", "---"]);
+		const fm = await read(file);
+		expect(fm?.name).toBe(FALLBACK);
+		expect(fm?.description).toBe("");
+	});
+});
+
+describe("C12 — no frontmatter", () => {
+	test("R9.5 a file with no frontmatter yields the fallback name and the empty string", async () => {
+		const file = writeSkill(["# A skill", "", "Just a body, no frontmatter."]);
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe(FALLBACK);
+		expect(fm?.description).toBe("");
+	});
+
+	test("R9.5 an empty file yields the fallback name and the empty string", async () => {
+		const dir = tempDir();
+		const file = path.join(dir, "SKILL.md");
+		writeFileSync(file, "", "utf8");
+		const fm = await read(file);
+		expect(fm).not.toBeNull();
+		expect(fm?.name).toBe(FALLBACK);
+		expect(fm?.description).toBe("");
+	});
+
+	test("R9.5 `name:`/`description:` lines in the body, outside the frontmatter, are not read", async () => {
+		const file = writeSkill([
+			"---",
+			"version: 2.0.0",
+			"---",
+			"",
+			"name: body-name",
+			"description: body description",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe(FALLBACK);
+		expect(fm?.description).toBe("");
+	});
+
+	test("R9.5 a `---` block that does not start the file is not frontmatter", async () => {
+		const file = writeSkill([
+			"# Title first",
+			"---",
+			"name: not-leading",
+			"description: not leading",
+			"---",
+		]);
+		const fm = await read(file);
+		expect(fm?.name).toBe(FALLBACK);
+		expect(fm?.description).toBe("");
+	});
+});
+
+describe("C12 — unreadable path", () => {
+	test("R9.5 a path that does not exist yields null", async () => {
+		const dir = tempDir();
+		const fm = await read(path.join(dir, "missing", "SKILL.md"));
+		expect(fm).toBeNull();
+	});
+
+	test("R9.5 a path that is a directory (cannot be read as a file) yields null", async () => {
+		const dir = tempDir();
+		const asDir = path.join(dir, "SKILL.md");
+		mkdirSync(asDir);
+		const fm = await read(asDir);
+		expect(fm).toBeNull();
+	});
+});