nymor 1.0.1

package/src/utils/skills.ts

@@ -0,0 +1,152 @@
+import fs from "fs-extra";
+import path from "path";
+import yaml from "yaml";
+
+export interface SkillFrontmatter {
+  name: string;
+  description?: string;
+  globs?: string[];
+  alwaysApply?: boolean;
+}
+
+export interface SkillFile {
+  id: string;
+  dirPath: string;
+  skillPath: string;
+  frontmatter: SkillFrontmatter;
+  body: string;
+  raw: string;
+}
+
+export interface SkillIndexEntry {
+  id: string;
+  name: string;
+  description: string;
+  globs: string[];
+  alwaysApply: boolean;
+}
+
+export async function listSkillDirectories(skillsDir: string): Promise<string[]> {
+  if (!(await fs.pathExists(skillsDir))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+
+export async function loadSkills(skillsDir: string): Promise<SkillFile[]> {
+  const skillDirs = await listSkillDirectories(skillsDir);
+  const skills: SkillFile[] = [];
+
+  for (const dirName of skillDirs) {
+    const skillPath = path.join(skillsDir, dirName, "SKILL.md");
+    if (!(await fs.pathExists(skillPath))) {
+      continue;
+    }
+
+    skills.push(await readSkillFile(dirName, skillPath));
+  }
+
+  return skills.sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name));
+}
+
+export async function readSkillFile(id: string, skillPath: string): Promise<SkillFile> {
+  const raw = await fs.readFile(skillPath, "utf8");
+  const { frontmatter, body } = parseSkillContent(raw, id);
+
+  return {
+    id,
+    dirPath: path.dirname(skillPath),
+    skillPath,
+    frontmatter,
+    body,
+    raw
+  };
+}
+
+export function parseSkillContent(content: string, id: string): { frontmatter: SkillFrontmatter; body: string } {
+  const lines = content.split(/\r?\n/);
+  if (lines.length === 0 || lines[0].trim() !== "---") {
+    throw new Error(`Skill ${id} is missing frontmatter`);
+  }
+
+  const endIndex = lines.slice(1).findIndex((line) => line.trim() === "---");
+  if (endIndex === -1) {
+    throw new Error(`Skill ${id} frontmatter is not closed`);
+  }
+
+  const frontmatterText = lines.slice(1, endIndex + 1).join("\n");
+  const body = lines.slice(endIndex + 2).join("\n").trimStart();
+  const data = yaml.parse(frontmatterText) as SkillFrontmatter;
+
+  if (!data?.name) {
+    throw new Error(`Skill ${id} is missing a name in frontmatter`);
+  }
+
+  const globs = normalizeGlobs(data.globs);
+
+  return {
+    frontmatter: {
+      name: data.name,
+      description: data.description ?? "",
+      globs,
+      alwaysApply: Boolean(data.alwaysApply)
+    },
+    body
+  };
+}
+
+export function buildSkillIndex(skills: SkillFile[]): { markdown: string; json: string } {
+  const entries = skills.map(toIndexEntry);
+
+  const rows = entries.map((entry) => {
+    const globs = entry.globs.length > 0 ? entry.globs.join(", ") : "-";
+    const alwaysApply = entry.alwaysApply ? "yes" : "no";
+    return `| ${entry.name} | ${entry.id} | ${entry.description || "-"} | ${globs} | ${alwaysApply} |`;
+  });
+
+  const markdown = [
+    "# Nymor Skills Index",
+    "",
+    "This index is regenerated by Nymor on every compile.",
+    "",
+    "| Skill | Folder | Description | Globs | Always Apply |",
+    "|---|---|---|---|---|",
+    ...rows,
+    "",
+    "## How to use this index",
+    "1. Review the Description and Globs columns",
+    "2. Load the relevant skill folders from .nymor/skills/",
+    "3. Apply their rules for the current task",
+    ""
+  ].join("\n");
+
+  const json = JSON.stringify({ skills: entries }, null, 2);
+
+  return { markdown, json };
+}
+
+function toIndexEntry(skill: SkillFile): SkillIndexEntry {
+  const globs = normalizeGlobs(skill.frontmatter.globs);
+
+  return {
+    id: skill.id,
+    name: skill.frontmatter.name,
+    description: skill.frontmatter.description ?? "",
+    globs,
+    alwaysApply: Boolean(skill.frontmatter.alwaysApply)
+  };
+}
+
+function normalizeGlobs(globs: SkillFrontmatter["globs"]): string[] {
+  if (!globs) {
+    return [];
+  }
+
+  if (Array.isArray(globs)) {
+    return globs.map((glob) => String(glob)).filter(Boolean);
+  }
+
+  return [String(globs)];
+}

package/tests/compiler/__snapshots__/claude.test.ts.snap

@@ -0,0 +1,65 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`compileClaudeSkills > copies every skill folder 1`] = `
+{
+  "scoped/SKILL.md": "---
+name: Scoped Skill
+description: Applies to TypeScript source files.
+globs:
+  - "src/**/*.ts"
+alwaysApply: false
+---
+
+# Skill: Scoped Skill
+
+## Rule
+Use explicit return types on exported functions.
+
+## Why
+Exported APIs should be clear at the boundary.
+
+## Example
+export function run(): void {}
+",
+  "simple/SKILL.md": "---
+name: Simple Skill
+description: Applies everywhere.
+alwaysApply: true
+---
+
+# Skill: Simple Skill
+
+## Rule
+Always keep the code readable.
+
+## Why
+Readable code is easier to review and maintain.
+
+## Example
+Prefer a named helper over a dense inline expression.
+",
+  "with-examples/SKILL.md": "---
+name: With Examples
+description: Includes extra example files.
+globs:
+  - "src/**/*.ts"
+alwaysApply: false
+---
+
+# Skill: With Examples
+
+## Rule
+Keep examples near the skill.
+
+## Why
+Examples make a convention concrete.
+
+## Example
+See examples/example.md.
+",
+  "with-examples/examples/example.md": "# Example
+
+Use a small fixture alongside the skill.
+",
+}
+`;

package/tests/compiler/__snapshots__/copilot.test.ts.snap

@@ -0,0 +1,54 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`renderCopilotInstructions > renders GitHub instruction content for fixture skills 1`] = `
+{
+  "scoped": "---
+applyTo: "src/**/*.ts"
+---
+
+# Skill: Scoped Skill
+
+## Rule
+Use explicit return types on exported functions.
+
+## Why
+Exported APIs should be clear at the boundary.
+
+## Example
+export function run(): void {}
+
+",
+  "simple": "---
+applyTo: "**/*"
+---
+
+# Skill: Simple Skill
+
+## Rule
+Always keep the code readable.
+
+## Why
+Readable code is easier to review and maintain.
+
+## Example
+Prefer a named helper over a dense inline expression.
+
+",
+  "with-examples": "---
+applyTo: "src/**/*.ts"
+---
+
+# Skill: With Examples
+
+## Rule
+Keep examples near the skill.
+
+## Why
+Examples make a convention concrete.
+
+## Example
+See examples/example.md.
+
+",
+}
+`;

package/tests/compiler/__snapshots__/cursor.test.ts.snap

@@ -0,0 +1,62 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`renderCursorRule > renders .mdc rule content for fixture skills 1`] = `
+{
+  "scoped": "---
+description: "Applies to TypeScript source files."
+globs:
+  - "src/**/*.ts"
+alwaysApply: false
+---
+
+# Skill: Scoped Skill
+
+## Rule
+Use explicit return types on exported functions.
+
+## Why
+Exported APIs should be clear at the boundary.
+
+## Example
+export function run(): void {}
+
+",
+  "simple": "---
+description: "Applies everywhere."
+globs: []
+alwaysApply: true
+---
+
+# Skill: Simple Skill
+
+## Rule
+Always keep the code readable.
+
+## Why
+Readable code is easier to review and maintain.
+
+## Example
+Prefer a named helper over a dense inline expression.
+
+",
+  "with-examples": "---
+description: "Includes extra example files."
+globs:
+  - "src/**/*.ts"
+alwaysApply: false
+---
+
+# Skill: With Examples
+
+## Rule
+Keep examples near the skill.
+
+## Why
+Examples make a convention concrete.
+
+## Example
+See examples/example.md.
+
+",
+}
+`;

package/tests/compiler/__snapshots__/kiro.test.ts.snap

@@ -0,0 +1,54 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`renderKiroSteering > renders Kiro steering content for fixture skills 1`] = `
+{
+  "scoped": "---
+inclusion: manual
+---
+
+# Skill: Scoped Skill
+
+## Rule
+Use explicit return types on exported functions.
+
+## Why
+Exported APIs should be clear at the boundary.
+
+## Example
+export function run(): void {}
+
+",
+  "simple": "---
+inclusion: always
+---
+
+# Skill: Simple Skill
+
+## Rule
+Always keep the code readable.
+
+## Why
+Readable code is easier to review and maintain.
+
+## Example
+Prefer a named helper over a dense inline expression.
+
+",
+  "with-examples": "---
+inclusion: manual
+---
+
+# Skill: With Examples
+
+## Rule
+Keep examples near the skill.
+
+## Why
+Examples make a convention concrete.
+
+## Example
+See examples/example.md.
+
+",
+}
+`;

package/tests/compiler/block.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { upsertManagedBlock } from "../../src/compiler/block";
+
+describe("upsertManagedBlock", () => {
+  it("is idempotent", () => {
+    const once = upsertManagedBlock(null, "generated");
+    expect(upsertManagedBlock(once, "generated")).toBe(once);
+  });
+
+  it("preserves user content outside the managed block", () => {
+    const existing = ["user header", "", "<!-- nymor:start -->", "old", "<!-- nymor:end -->", "", "user footer", ""].join("\n");
+
+    expect(upsertManagedBlock(existing, "new")).toMatchInlineSnapshot(`
+      "user header
+
+      <!-- nymor:start -->
+      new
+      <!-- nymor:end -->
+
+      user footer
+      "
+    `);
+  });
+});

package/tests/compiler/claude.test.ts

@@ -0,0 +1,46 @@
+import os from "os";
+import path from "path";
+import fs from "fs-extra";
+import { describe, expect, it } from "vitest";
+import { compileClaudeSkills } from "../../src/compiler/claude";
+import { loadSkills } from "../../src/utils/skills";
+
+const fixturesDir = path.resolve(__dirname, "..", "fixtures", "skills");
+
+describe("compileClaudeSkills", () => {
+  it("copies every skill folder", async () => {
+    const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "nymor-claude-"));
+    const skills = await loadSkills(fixturesDir);
+
+    await compileClaudeSkills(skills, projectRoot);
+
+    expect(await readTree(path.join(projectRoot, ".claude", "skills"))).toMatchSnapshot();
+  });
+});
+
+async function readTree(root: string): Promise<Record<string, string>> {
+  const files = await listFiles(root);
+  const output: Record<string, string> = {};
+
+  for (const file of files) {
+    output[path.relative(root, file)] = await fs.readFile(file, "utf8");
+  }
+
+  return output;
+}
+
+async function listFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(entryPath)));
+    } else {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort();
+}

package/tests/compiler/copilot.test.ts

@@ -0,0 +1,15 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { renderCopilotInstructions } from "../../src/compiler/copilot";
+import { loadSkills } from "../../src/utils/skills";
+
+const fixturesDir = path.resolve(__dirname, "..", "fixtures", "skills");
+
+describe("renderCopilotInstructions", () => {
+  it("renders GitHub instruction content for fixture skills", async () => {
+    const skills = await loadSkills(fixturesDir);
+    const output = Object.fromEntries(skills.map((skill) => [skill.id, renderCopilotInstructions(skill)]));
+
+    expect(output).toMatchSnapshot();
+  });
+});

package/tests/compiler/cursor.test.ts

@@ -0,0 +1,15 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { renderCursorRule } from "../../src/compiler/cursor";
+import { loadSkills } from "../../src/utils/skills";
+
+const fixturesDir = path.resolve(__dirname, "..", "fixtures", "skills");
+
+describe("renderCursorRule", () => {
+  it("renders .mdc rule content for fixture skills", async () => {
+    const skills = await loadSkills(fixturesDir);
+    const output = Object.fromEntries(skills.map((skill) => [skill.id, renderCursorRule(skill)]));
+
+    expect(output).toMatchSnapshot();
+  });
+});

package/tests/compiler/kiro.test.ts

@@ -0,0 +1,15 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { renderKiroSteering } from "../../src/compiler/kiro";
+import { loadSkills } from "../../src/utils/skills";
+
+const fixturesDir = path.resolve(__dirname, "..", "fixtures", "skills");
+
+describe("renderKiroSteering", () => {
+  it("renders Kiro steering content for fixture skills", async () => {
+    const skills = await loadSkills(fixturesDir);
+    const output = Object.fromEntries(skills.map((skill) => [skill.id, renderKiroSteering(skill)]));
+
+    expect(output).toMatchSnapshot();
+  });
+});

package/tests/detector/agents.test.ts

@@ -0,0 +1,48 @@
+import os from "os";
+import path from "path";
+import fs from "fs-extra";
+import { describe, expect, it } from "vitest";
+import { detectAgents } from "../../src/detector/agents";
+
+describe("detectAgents", () => {
+  it("detects known agent surfaces", async () => {
+    const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "nymor-agents-"));
+    await fs.ensureDir(path.join(projectRoot, ".claude"));
+    await fs.ensureDir(path.join(projectRoot, ".cursor"));
+    await fs.ensureDir(path.join(projectRoot, ".github", "instructions"));
+    await fs.ensureDir(path.join(projectRoot, ".kiro"));
+    await fs.writeFile(path.join(projectRoot, "AGENTS.md"), "agents", "utf8");
+    await fs.writeFile(path.join(projectRoot, "GEMINI.md"), "gemini", "utf8");
+    await fs.ensureDir(path.join(projectRoot, ".windsurf"));
+    await fs.ensureDir(path.join(projectRoot, ".goose"));
+    await fs.ensureDir(path.join(projectRoot, ".opencode"));
+
+    await expect(detectAgents(projectRoot)).resolves.toEqual({
+      claude: true,
+      cursor: true,
+      copilot: true,
+      kiro: true,
+      "agents-md": true,
+      gemini: true,
+      windsurf: true,
+      goose: true,
+      opencode: true
+    });
+  });
+
+  it("returns false for absent agents", async () => {
+    const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "nymor-agents-"));
+
+    await expect(detectAgents(projectRoot)).resolves.toEqual({
+      claude: false,
+      cursor: false,
+      copilot: false,
+      kiro: false,
+      "agents-md": false,
+      gemini: false,
+      windsurf: false,
+      goose: false,
+      opencode: false
+    });
+  });
+});

package/tests/detector/stack.test.ts

@@ -0,0 +1,29 @@
+import path from "path";
+import os from "os";
+import fs from "fs-extra";
+import { describe, expect, it } from "vitest";
+import { detectStack, Stack } from "../../src/detector/stack";
+
+const fixturesRoot = path.resolve(__dirname, "..", "fixtures", "stacks");
+
+describe("detectStack", () => {
+  const cases: Array<[string, Stack]> = [
+    ["nodejs", "nodejs"],
+    ["react", "react"],
+    ["vue", "vue"],
+    ["django", "django"],
+    ["fastapi", "fastapi"],
+    ["rust", "rust"],
+    ["go", "go"]
+  ];
+
+  it.each(cases)("detects %s", async (fixture, expected) => {
+    await expect(detectStack(path.join(fixturesRoot, fixture))).resolves.toBe(expected);
+  });
+
+  it("returns null when no stack signals are present", async () => {
+    const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "nymor-stack-"));
+
+    await expect(detectStack(projectRoot)).resolves.toBeNull();
+  });
+});