@open-domain-specification/skill 0.1.10

package/src/bundle.test.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { Workspace } from "@open-domain-specification/core";
+import { describe, expect, it } from "vitest";
+import {
+	generateReferences,
+	readBundle,
+	skillRoot,
+} from "../scripts/generate.mts";
+
+const file = (path: string) => readFileSync(join(skillRoot, path), "utf8");
+
+describe("SKILL.md", () => {
+	const skill = file("SKILL.md");
+	const frontmatter = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(skill);
+
+	it("has a name and a description in its frontmatter", () => {
+		expect(frontmatter).not.toBeNull();
+		expect(frontmatter![1]).toMatch(/^name: ods-authoring$/m);
+		expect(frontmatter![1]).toMatch(/^description: >/m);
+	});
+
+	it("stays short enough to load unconditionally", () => {
+		expect(frontmatter![2].split("\n").length).toBeLessThan(300);
+	});
+
+	it("only points at references and examples that exist", () => {
+		const paths = new Set(readBundle().map((f) => f.path));
+		for (const [, ref] of skill.matchAll(
+			/`((?:references|examples)\/[\w./-]+)`/g,
+		))
+			expect(paths, ref).toContain(ref);
+	});
+});
+
+describe("generated references", () => {
+	it("are committed up to date with core", () => {
+		for (const generated of generateReferences())
+			expect(file(generated.path), generated.path).toBe(generated.content);
+	});
+});
+
+describe("dsl-api.md", () => {
+	it("names only methods that exist on the core classes", () => {
+		const require = createRequire(import.meta.url);
+		const corePkg = dirname(
+			require.resolve("@open-domain-specification/core/package.json"),
+		);
+		const source = readFileSync(join(corePkg, "src/workspace.ts"), "utf8");
+		const doc = file("references/dsl-api.md");
+		const methods = [...doc.matchAll(/\| `\.?(?:new )?(\w+)\(/g)].map(
+			(m) => m[1],
+		);
+		expect(methods.length).toBeGreaterThan(20);
+		for (const method of methods) {
+			if (method === "Workspace") continue;
+			expect(source, method).toMatch(new RegExp(`\\b${method}\\(`));
+		}
+	});
+});
+
+describe("examples", () => {
+	it("minimal.ods.json loads and validates clean", () => {
+		const json = JSON.parse(file("examples/minimal.ods.json"));
+		const ws = Workspace.fromSchema(json);
+		expect(ws.validate()).toEqual([]);
+	});
+
+	it("minimal.workspace.ts builds the same model as minimal.ods.json", async () => {
+		const { workspace } = await import(
+			"../skill/examples/minimal.workspace.ts"
+		);
+		expect(workspace.validate()).toEqual([]);
+		const { $schema: _s, ...json } = JSON.parse(
+			file("examples/minimal.ods.json"),
+		);
+		expect(workspace.toSchema()).toEqual(json);
+	});
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./install";
+export * from "./targets";

package/src/install.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import {
+	installSkill,
+	isInstalled,
+	rulesSnippet,
+	SKILL_VERSION,
+	skillFiles,
+} from "./install";
+import { SKILL_NAME, skillDir, TARGETS } from "./targets";
+
+describe("skillFiles", () => {
+	it("contains the skill entry point, references and examples", () => {
+		const paths = skillFiles().map((f) => f.path);
+		expect(paths).toContain("SKILL.md");
+		expect(paths).toContain("references/model-reference.md");
+		expect(paths).toContain("references/validation-rules.md");
+		expect(paths).toContain("examples/minimal.ods.json");
+	});
+
+	it("stamps SKILL.md with the package version", () => {
+		const skill = skillFiles().find((f) => f.path === "SKILL.md")!;
+		expect(skill.content).toContain(
+			`<!-- ods-skill-version: ${SKILL_VERSION} -->`,
+		);
+	});
+});
+
+describe("installSkill", () => {
+	it.each(TARGETS.map((t) => t.id))(
+		"writes under %s's skills folder",
+		async (target) => {
+			const written = new Map<string, string>();
+			const paths = await installSkill({
+				root: "/proj",
+				target,
+				write: async (p, c) => {
+					written.set(p, c);
+				},
+			});
+			expect(
+				paths.every((p) => p.startsWith(`/proj/${skillDir(target)}/`)),
+			).toBe(true);
+			expect(written.has(`/proj/${skillDir(target)}/SKILL.md`)).toBe(true);
+			expect(skillDir(target).endsWith(`/skills/${SKILL_NAME}`)).toBe(true);
+		},
+	);
+});
+
+describe("isInstalled", () => {
+	const at = (content?: string) => async () => content;
+
+	it("is missing without a SKILL.md", async () => {
+		expect(await isInstalled("/p", "claude", at(undefined))).toBe("missing");
+	});
+
+	it("is stale when the stamp differs", async () => {
+		expect(
+			await isInstalled(
+				"/p",
+				"claude",
+				at("x\n<!-- ods-skill-version: 0.0.0 -->\n"),
+			),
+		).toBe("stale");
+	});
+
+	it("is current after installing", async () => {
+		const files = new Map<string, string>();
+		await installSkill({
+			root: "/p",
+			target: "codex",
+			write: async (p, c) => {
+				files.set(p, c);
+			},
+		});
+		expect(await isInstalled("/p", "codex", async (p) => files.get(p))).toBe(
+			"current",
+		);
+	});
+});
+
+describe("rulesSnippet", () => {
+	it("points at the installed SKILL.md for the target", () => {
+		expect(rulesSnippet("claude")).toContain(
+			".claude/skills/ods-authoring/SKILL.md",
+		);
+		expect(rulesSnippet()).toContain(".agents/skills/ods-authoring/SKILL.md");
+	});
+});

package/src/install.ts

@@ -0,0 +1,64 @@
+import { BUNDLE, SKILL_VERSION } from "./bundle.generated";
+import { SKILL_NAME, type SkillTarget, skillDir } from "./targets";
+
+export type SkillFile = { path: string; content: string };
+
+const STAMP = /<!-- ods-skill-version: ([^\s]+) -->/;
+
+function stamp(content: string): string {
+	return `${content.trimEnd()}\n\n<!-- ods-skill-version: ${SKILL_VERSION} -->\n`;
+}
+
+/** Every file of the skill bundle, paths relative to the skill folder. */
+export function skillFiles(): SkillFile[] {
+	return BUNDLE.map((f) =>
+		f.path === "SKILL.md" ? { ...f, content: stamp(f.content) } : { ...f },
+	);
+}
+
+export type InstallOptions = {
+	/** The project or home folder the skill is installed into. */
+	root: string;
+	target: SkillTarget;
+	/** Writes one file; receives an absolute-ish path built from `root`. */
+	write: (path: string, content: string) => Promise<void>;
+	/** Override the files to install; defaults to the bundle. */
+	files?: SkillFile[];
+};
+
+/** Writes the bundle into `<root>/<target skills dir>/ods-authoring/` and returns the paths written. */
+export async function installSkill(options: InstallOptions): Promise<string[]> {
+	const base = `${options.root}/${skillDir(options.target)}`;
+	const written: string[] = [];
+	for (const file of options.files ?? skillFiles()) {
+		const path = `${base}/${file.path}`;
+		await options.write(path, file.content);
+		written.push(path);
+	}
+	return written;
+}
+
+export type InstallState = "missing" | "stale" | "current";
+
+/** Compares the version stamp of an installed SKILL.md with this package's. */
+export async function isInstalled(
+	root: string,
+	target: SkillTarget,
+	read: (path: string) => Promise<string | undefined>,
+): Promise<InstallState> {
+	const content = await read(`${root}/${skillDir(target)}/SKILL.md`);
+	if (content === undefined) return "missing";
+	return STAMP.exec(content)?.[1] === SKILL_VERSION ? "current" : "stale";
+}
+
+/** A paragraph for AGENTS.md or copilot-instructions.md pointing agents at the installed skill. */
+export function rulesSnippet(target: SkillTarget = "agents"): string {
+	return [
+		"## Domain model (Open Domain Specification)",
+		"",
+		`This project keeps its domain model as an Open Domain Specification workspace. Before creating or editing anything under \`.ods/\` or a TypeScript file that builds a \`Workspace\` from \`@open-domain-specification/core\`, read \`${skillDir(target)}/SKILL.md\` and follow it: detect whether the model is authored as JSON or via the TypeScript DSL, interview the user in plain language before modelling, and validate after every change.`,
+		"",
+	].join("\n");
+}
+
+export { SKILL_NAME, SKILL_VERSION };

package/src/targets.ts

@@ -0,0 +1,25 @@
+/** Where each agent looks for skills, relative to a project or home folder. */
+export type SkillTarget = "claude" | "agents" | "codex";
+
+/** The folder name of the skill under every `skills/` directory. */
+export const SKILL_NAME = "ods-authoring";
+
+export const TARGETS: ReadonlyArray<{
+	id: SkillTarget;
+	label: string;
+	/** The skills directory, relative to the root the skill is installed into. */
+	dir: string;
+}> = [
+	{ id: "claude", label: "Claude Code", dir: ".claude/skills" },
+	{ id: "agents", label: "Agent Skills (.agents)", dir: ".agents/skills" },
+	{ id: "codex", label: "OpenAI Codex (.codex)", dir: ".codex/skills" },
+];
+
+export const TARGET_DIRS: Record<SkillTarget, string> = Object.fromEntries(
+	TARGETS.map((t) => [t.id, t.dir]),
+) as Record<SkillTarget, string>;
+
+/** The directory the skill lands in for a target, relative to `root`. */
+export function skillDir(target: SkillTarget): string {
+	return `${TARGET_DIRS[target]}/${SKILL_NAME}`;
+}