nymor 1.0.1

package/dist/templates/bootstrap.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderBootstrap = renderBootstrap;
+exports.renderLearnCommand = renderLearnCommand;
+exports.renderLearnSkill = renderLearnSkill;
+const LEARN_TRIGGER = "/nymor-learn";
+function getLearnArgumentsPlaceholder(target) {
+    return target.id === "copilot" ? "{{input}}" : "$ARGUMENTS";
+}
+function renderBootstrap(target, skills = [], wrap = true) {
+    const body = [
+        "# Nymor",
+        "",
+        "Nymor teaches this repo what AI agents keep forgetting.",
+        "",
+        "Source skills live in `.nymor/skills/`. Apply any matching skill during the task, using `globs` and `alwaysApply` to decide relevance.",
+        "",
+        "If the user states a durable repo rule, says things like \"always\", \"never\", \"in this repo\", \"we use\", \"remember this\", or corrects the same behavior more than once, gently suggest:",
+        "",
+        "`This looks like a reusable repo rule. Want me to capture it with /nymor-learn?`",
+        "",
+        `Only create a skill after the user explicitly invokes ${LEARN_TRIGGER}.`,
+        "",
+        `When the user invokes ${LEARN_TRIGGER} "<rule>":`,
+        "",
+        "1. Infer the durable rule from the conversation.",
+        "2. Choose a stable lowercase folder id with hyphens.",
+        "3. Read `nymor.json` and `.nymor/skills/`.",
+        "4. Write `.nymor/skills/<id>/SKILL.md` directly.",
+        "5. Include complete frontmatter: `name`, `description`, `globs`, and `alwaysApply`.",
+        "6. Include complete sections: `## Rule`, `## Why`, and `## Example`.",
+        "7. Keep `globs` narrow unless the rule is genuinely global.",
+        "8. Add `<id>` to `nymor.json.local` if missing.",
+        "9. Run `nymor compile`.",
+        "10. Run `nymor validate`.",
+        "11. Report the captured rule and skill path.",
+        "",
+        "Never create placeholders. Write directly to the active skill path. Create only the requested skill; do not seed unrelated skills or use external installs.",
+        "",
+        renderAlwaysApplySection(skills)
+    ].join("\n");
+    return wrap ? wrapBootstrap(target, body) : body;
+}
+function renderLearnCommand(target) {
+    const inputPlaceholder = getLearnArgumentsPlaceholder(target);
+    return [
+        "---",
+        "description: Capture a durable repo rule as a Nymor skill.",
+        "---",
+        "",
+        `# ${target.label} Nymor Learn`,
+        "",
+        "User input:",
+        "",
+        "```text",
+        inputPlaceholder,
+        "```",
+        "",
+        renderBootstrap(target, [], false)
+    ].join("\n");
+}
+function renderLearnSkill(target) {
+    return [
+        "---",
+        "name: Nymor Learn",
+        "description: Capture durable repo rules as active Nymor skills.",
+        "globs:",
+        "  - \"**/*\"",
+        "alwaysApply: true",
+        "---",
+        "",
+        renderBootstrap(target, [], false)
+    ].join("\n");
+}
+function wrapBootstrap(target, body) {
+    if (target.id === "cursor") {
+        return ["---", "description: Nymor repo-memory capture and skill guidance.", "globs:", "  - \"**/*\"", "alwaysApply: true", "---", "", body].join("\n");
+    }
+    if (target.id === "copilot") {
+        return ["---", "applyTo: \"**/*\"", "---", "", body].join("\n");
+    }
+    if (target.id === "kiro") {
+        return ["---", "inclusion: always", "---", "", body].join("\n");
+    }
+    return body;
+}
+function renderAlwaysApplySection(skills) {
+    const alwaysApply = skills.filter((skill) => skill.frontmatter.alwaysApply);
+    if (alwaysApply.length === 0) {
+        return "No always-apply Nymor skills are currently configured.";
+    }
+    return [
+        "## Always-Apply Nymor Skills",
+        "",
+        ...alwaysApply.map((skill) => [`### ${skill.frontmatter.name}`, "", skill.body.trim()].join("\n")).join("\n\n---\n\n").split("\n")
+    ].join("\n");
+}

package/dist/templates/cicada-json.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultManifest = createDefaultManifest;
+function createDefaultManifest() {
+    return {
+        version: "1",
+        agents: ["claude", "cursor", "copilot", "kiro", "agents-md"],
+        skills: {},
+        local: []
+    };
+}

package/dist/templates/nymor-json.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultManifest = createDefaultManifest;
+const targets_1 = require("../agents/targets");
+function createDefaultManifest() {
+    return {
+        version: "1",
+        agents: [...targets_1.DEFAULT_AGENT_TARGETS],
+        local: []
+    };
+}

package/dist/utils/manifest.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readManifest = readManifest;
+exports.writeManifest = writeManifest;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const targets_1 = require("../agents/targets");
+const nymor_json_1 = require("../templates/nymor-json");
+const paths_1 = require("./paths");
+async function readManifest(projectRoot) {
+    const manifestPath = (0, paths_1.getManifestPath)(projectRoot);
+    if (!(await fs_extra_1.default.pathExists(manifestPath))) {
+        return (0, nymor_json_1.createDefaultManifest)();
+    }
+    const manifest = await fs_extra_1.default.readJson(manifestPath);
+    return normalizeManifest(manifest);
+}
+async function writeManifest(projectRoot, manifest) {
+    const manifestPath = (0, paths_1.getManifestPath)(projectRoot);
+    await fs_extra_1.default.writeJson(manifestPath, manifest, { spaces: 2 });
+}
+function normalizeManifest(raw) {
+    const defaultManifest = (0, nymor_json_1.createDefaultManifest)();
+    const agents = (raw.agents ?? defaultManifest.agents).filter((agent) => (0, targets_1.isAgentTarget)(String(agent)));
+    return {
+        version: raw.version ?? defaultManifest.version,
+        agents,
+        local: raw.local ?? []
+    };
+}

package/dist/utils/paths.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRepoRoot = getRepoRoot;
+exports.getNymorDir = getNymorDir;
+exports.getSkillsDir = getSkillsDir;
+exports.getIndexMarkdownPath = getIndexMarkdownPath;
+exports.getIndexJsonPath = getIndexJsonPath;
+exports.getManifestPath = getManifestPath;
+const path_1 = __importDefault(require("path"));
+function getRepoRoot(cwd = process.cwd()) {
+    return cwd;
+}
+function getNymorDir(root) {
+    return path_1.default.join(root, ".nymor");
+}
+function getSkillsDir(root) {
+    return path_1.default.join(getNymorDir(root), "skills");
+}
+function getIndexMarkdownPath(root) {
+    return path_1.default.join(getNymorDir(root), "index.md");
+}
+function getIndexJsonPath(root) {
+    return path_1.default.join(getNymorDir(root), "index.json");
+}
+function getManifestPath(root) {
+    return path_1.default.join(root, "nymor.json");
+}

package/dist/utils/skills.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSkillDirectories = listSkillDirectories;
+exports.loadSkills = loadSkills;
+exports.readSkillFile = readSkillFile;
+exports.parseSkillContent = parseSkillContent;
+exports.buildSkillIndex = buildSkillIndex;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+async function listSkillDirectories(skillsDir) {
+    if (!(await fs_extra_1.default.pathExists(skillsDir))) {
+        return [];
+    }
+    const entries = await fs_extra_1.default.readdir(skillsDir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+async function loadSkills(skillsDir) {
+    const skillDirs = await listSkillDirectories(skillsDir);
+    const skills = [];
+    for (const dirName of skillDirs) {
+        const skillPath = path_1.default.join(skillsDir, dirName, "SKILL.md");
+        if (!(await fs_extra_1.default.pathExists(skillPath))) {
+            continue;
+        }
+        skills.push(await readSkillFile(dirName, skillPath));
+    }
+    return skills.sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name));
+}
+async function readSkillFile(id, skillPath) {
+    const raw = await fs_extra_1.default.readFile(skillPath, "utf8");
+    const { frontmatter, body } = parseSkillContent(raw, id);
+    return {
+        id,
+        dirPath: path_1.default.dirname(skillPath),
+        skillPath,
+        frontmatter,
+        body,
+        raw
+    };
+}
+function parseSkillContent(content, id) {
+    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_1.default.parse(frontmatterText);
+    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
+    };
+}
+function buildSkillIndex(skills) {
+    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) {
+    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) {
+    if (!globs) {
+        return [];
+    }
+    if (Array.isArray(globs)) {
+        return globs.map((glob) => String(glob)).filter(Boolean);
+    }
+    return [String(globs)];
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "nymor",
+  "version": "1.0.1",
+  "description": "Teach your repo what your AI agents keep forgetting",
+  "license": "MIT",
+  "bin": {
+    "nymor": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "fs-extra": "^11.0.0",
+    "glob": "^10.0.0",
+    "inquirer": "^9.0.0",
+    "picocolors": "^1.0.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/inquirer": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.6.1"
+  }
+}

package/src/agents/targets.ts

@@ -0,0 +1,141 @@
+import path from "path";
+
+export type AgentTarget =
+  | "claude"
+  | "cursor"
+  | "copilot"
+  | "kiro"
+  | "agents-md"
+  | "gemini"
+  | "windsurf"
+  | "goose"
+  | "opencode";
+
+export type AgentOutputKind =
+  | "claude"
+  | "cursor"
+  | "copilot"
+  | "kiro"
+  | "shared-md"
+  | "gemini"
+  | "windsurf"
+  | "native-skills";
+
+export interface AgentTargetDefinition {
+  id: AgentTarget;
+  label: string;
+  short: string;
+  description: string;
+  detectPaths: string[];
+  kind: AgentOutputKind;
+  bootstrapFile?: string;
+  commandFile?: string;
+  nativeSkillDir?: string;
+  sharedConsumers?: string[];
+}
+
+export const AGENT_TARGETS: AgentTargetDefinition[] = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    short: "Claude",
+    description: "Claude skills, CLAUDE.md bootstrap, and /nymor-learn command",
+    detectPaths: [".claude", "CLAUDE.md"],
+    kind: "claude",
+    bootstrapFile: "CLAUDE.md",
+    commandFile: path.join(".claude", "commands", "nymor-learn.md")
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    short: "Cursor",
+    description: "Cursor rules and /nymor-learn command",
+    detectPaths: [".cursor"],
+    kind: "cursor",
+    bootstrapFile: path.join(".cursor", "rules", "nymor.mdc"),
+    commandFile: path.join(".cursor", "commands", "nymor-learn.md")
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    short: "Copilot",
+    description: "GitHub Copilot instructions and /nymor-learn prompt",
+    detectPaths: [
+      path.join(".github", "copilot-instructions.md"),
+      path.join(".github", "instructions"),
+      path.join(".github", "prompts")
+    ],
+    kind: "copilot",
+    bootstrapFile: path.join(".github", "instructions", "nymor-bootstrap.instructions.md"),
+    commandFile: path.join(".github", "prompts", "nymor-learn.prompt.md")
+  },
+  {
+    id: "kiro",
+    label: "Kiro",
+    short: "Kiro",
+    description: "Kiro steering files",
+    detectPaths: [".kiro"],
+    kind: "kiro",
+    bootstrapFile: path.join(".kiro", "steering", "nymor.md")
+  },
+  {
+    id: "agents-md",
+    label: "AGENTS.md",
+    short: "AGENTS.md",
+    description: "Shared AGENTS.md for Codex, OpenCode, Aider, Goose, Zed, Warp, Devin, and Junie",
+    detectPaths: ["AGENTS.md", ".codex", ".aider.conf.yml", ".zed", ".warp", ".junie", ".goose", ".opencode"],
+    kind: "shared-md",
+    bootstrapFile: "AGENTS.md",
+    sharedConsumers: ["Codex", "OpenCode", "Aider", "Goose", "Zed", "Warp", "Devin", "Junie"]
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI",
+    short: "Gemini",
+    description: "GEMINI.md managed block",
+    detectPaths: ["GEMINI.md", ".gemini"],
+    kind: "gemini",
+    bootstrapFile: "GEMINI.md"
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    short: "Windsurf",
+    description: "Windsurf project rule file",
+    detectPaths: [".windsurf", ".windsurfrules"],
+    kind: "windsurf",
+    bootstrapFile: path.join(".windsurf", "rules", "nymor.md")
+  },
+  {
+    id: "goose",
+    label: "Goose",
+    short: "Goose",
+    description: "Goose native skills",
+    detectPaths: [".goose"],
+    kind: "native-skills",
+    nativeSkillDir: path.join(".goose", "skills")
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    short: "OpenCode",
+    description: "OpenCode native skills",
+    detectPaths: [".opencode", "opencode.json"],
+    kind: "native-skills",
+    nativeSkillDir: path.join(".opencode", "skill")
+  }
+];
+
+export const DEFAULT_AGENT_TARGETS: AgentTarget[] = AGENT_TARGETS.map((target) => target.id);
+
+export function getAgentTargetDefinition(id: AgentTarget): AgentTargetDefinition {
+  const target = AGENT_TARGETS.find((item) => item.id === id);
+  if (!target) {
+    throw new Error(`Unknown agent target: ${id}`);
+  }
+  return target;
+}
+
+export function isAgentTarget(value: string): value is AgentTarget {
+  return AGENT_TARGETS.some((target) => target.id === value);
+}

package/src/commands/compile.ts

@@ -0,0 +1,202 @@
+import fs from "fs-extra";
+import path from "path";
+import { AGENT_TARGETS, AgentTargetDefinition } from "../agents/targets";
+import { renderCopilotInstructions } from "../compiler/copilot";
+import { renderCursorRule } from "../compiler/cursor";
+import { renderKiroSteering } from "../compiler/kiro";
+import { upsertManagedBlock } from "../compiler/block";
+import { renderBootstrap, renderLearnCommand, renderLearnSkill } from "../templates/bootstrap";
+import { buildSkillIndex, loadSkills, SkillFile } from "../utils/skills";
+import { readManifest } from "../utils/manifest";
+import { getIndexJsonPath, getIndexMarkdownPath, getNymorDir, getSkillsDir } from "../utils/paths";
+
+export interface PlannedCompileFile {
+  path: string;
+  content: Buffer;
+}
+
+export async function compileCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const skillsDir = getSkillsDir(projectRoot);
+
+  if (!(await fs.pathExists(skillsDir))) {
+    console.log("No skills found. Run nymor init first.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const skills = await loadSkills(skillsDir);
+  const { markdown, json } = buildSkillIndex(skills);
+
+  await fs.ensureDir(getNymorDir(projectRoot));
+  await fs.writeFile(getIndexMarkdownPath(projectRoot), markdown, "utf8");
+  await fs.writeFile(getIndexJsonPath(projectRoot), json, "utf8");
+
+  const manifest = await readManifest(projectRoot);
+  const agentSet = new Set(manifest.agents);
+
+  for (const target of AGENT_TARGETS) {
+    if (agentSet.has(target.id)) {
+      await writeTargetOutputs(projectRoot, target, skills);
+    }
+  }
+
+  console.log(`Compiled ${skills.length} skills.`);
+}
+
+export async function planCompileOutputs(projectRoot: string): Promise<PlannedCompileFile[]> {
+  const skillsDir = getSkillsDir(projectRoot);
+  const skills = await loadSkills(skillsDir);
+  const { markdown, json } = buildSkillIndex(skills);
+  const manifest = await readManifest(projectRoot);
+  const agentSet = new Set(manifest.agents);
+  const files: PlannedCompileFile[] = [
+    textFile(getIndexMarkdownPath(projectRoot), markdown),
+    textFile(getIndexJsonPath(projectRoot), json)
+  ];
+
+  for (const target of AGENT_TARGETS) {
+    if (agentSet.has(target.id)) {
+      files.push(...(await planTargetOutputs(projectRoot, target, skills)));
+    }
+  }
+
+  return files;
+}
+
+async function writeTargetOutputs(projectRoot: string, target: AgentTargetDefinition, skills: SkillFile[]): Promise<void> {
+  for (const file of await planTargetOutputs(projectRoot, target, skills)) {
+    await fs.ensureDir(path.dirname(file.path));
+    await fs.writeFile(file.path, file.content);
+  }
+}
+
+async function planTargetOutputs(
+  projectRoot: string,
+  target: AgentTargetDefinition,
+  skills: SkillFile[]
+): Promise<PlannedCompileFile[]> {
+  const files: PlannedCompileFile[] = [];
+
+  if (target.bootstrapFile) {
+    files.push(await planBootstrap(projectRoot, target, skills));
+  }
+
+  if (target.commandFile) {
+    files.push(textFile(path.join(projectRoot, target.commandFile), `${renderLearnCommand(target)}\n`));
+  }
+
+  switch (target.kind) {
+    case "claude":
+      files.push(...(await planClaudeOutputs(skills, projectRoot)));
+      break;
+    case "cursor":
+      for (const skill of skills) {
+        files.push(textFile(path.join(projectRoot, ".cursor", "rules", `nymor-${skill.id}.mdc`), renderCursorRule(skill)));
+      }
+      break;
+    case "copilot":
+      for (const skill of skills) {
+        files.push(
+          textFile(
+            path.join(projectRoot, ".github", "instructions", `nymor-${skill.id}.instructions.md`),
+            renderCopilotInstructions(skill)
+          )
+        );
+      }
+      break;
+    case "kiro":
+      for (const skill of skills) {
+        files.push(textFile(path.join(projectRoot, ".kiro", "steering", `nymor-${skill.id}.md`), renderKiroSteering(skill)));
+      }
+      break;
+    case "native-skills":
+      if (target.nativeSkillDir) {
+        files.push(...(await planNativeSkillOutputs(projectRoot, target, skills)));
+      }
+      break;
+    case "shared-md":
+    case "gemini":
+    case "windsurf":
+      break;
+  }
+
+  return files;
+}
+
+async function planBootstrap(
+  projectRoot: string,
+  target: AgentTargetDefinition,
+  skills: SkillFile[]
+): Promise<PlannedCompileFile> {
+  const targetPath = path.join(projectRoot, target.bootstrapFile!);
+  const content = renderBootstrap(target, skills);
+
+  if (target.id === "claude" || target.id === "agents-md" || target.id === "gemini") {
+    const existing = (await fs.pathExists(targetPath)) ? await fs.readFile(targetPath, "utf8") : null;
+    return textFile(targetPath, upsertManagedBlock(existing, content));
+  }
+
+  return textFile(targetPath, `${content.trimEnd()}\n`);
+}
+
+async function planClaudeOutputs(skills: SkillFile[], projectRoot: string): Promise<PlannedCompileFile[]> {
+  const outputRoot = path.join(projectRoot, ".claude", "skills");
+  const files: PlannedCompileFile[] = [];
+
+  for (const skill of skills) {
+    const sourceFiles = await listFilesRecursive(skill.dirPath);
+    for (const sourcePath of sourceFiles) {
+      const relative = path.relative(skill.dirPath, sourcePath);
+      files.push({
+        path: path.join(outputRoot, skill.id, relative),
+        content: await fs.readFile(sourcePath)
+      });
+    }
+  }
+
+  return files;
+}
+
+async function planNativeSkillOutputs(
+  projectRoot: string,
+  target: AgentTargetDefinition,
+  skills: SkillFile[]
+): Promise<PlannedCompileFile[]> {
+  const files: PlannedCompileFile[] = [
+    textFile(path.join(projectRoot, target.nativeSkillDir!, "nymor-learn", "SKILL.md"), `${renderLearnSkill(target)}\n`)
+  ];
+
+  for (const skill of skills) {
+    const sourceFiles = await listFilesRecursive(skill.dirPath);
+    for (const sourcePath of sourceFiles) {
+      const relative = path.relative(skill.dirPath, sourcePath);
+      files.push({
+        path: path.join(projectRoot, target.nativeSkillDir!, skill.id, relative),
+        content: await fs.readFile(sourcePath)
+      });
+    }
+  }
+
+  return files;
+}
+
+async function listFilesRecursive(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 listFilesRecursive(entryPath)));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+
+  return files.sort();
+}
+
+function textFile(filePath: string, content: string): PlannedCompileFile {
+  return { path: filePath, content: Buffer.from(content, "utf8") };
+}