@ebay-dt/bonfire-context 0.1.0-alpha.4

package/dist/render.js

@@ -0,0 +1,64 @@
+import { lstat, readFile } from "node:fs/promises";
+import { assertSafeContextPaths, assertSafePrototypeContextPaths, } from "./paths.js";
+const ROOT_SOURCE_LABEL = "context/ROOT.md";
+const PROTOTYPE_SOURCE_LABEL = "context/PROTOTYPE.md";
+export const GENERATED_CLAUDE_CONTENT = `<!--
+  This file is generated. Do not edit it directly.
+-->
+
+@AGENTS.md
+`;
+export class ContextRenderError extends Error {
+    source;
+    constructor(source, message) {
+        super(`Unable to render ${source}: ${message}`);
+        this.name = "ContextRenderError";
+        this.source = source;
+    }
+}
+function generatedNotice(source) {
+    return `<!--
+  This file is generated from ${source}.
+  Do not edit it directly. Run \`bonfire context sync\` after changing the source.
+-->
+
+`;
+}
+function ensureFinalNewline(source) {
+    return source.endsWith("\n") ? source : `${source}\n`;
+}
+export function renderMarkdownSource(source, sourceLabel) {
+    return `${generatedNotice(sourceLabel)}${ensureFinalNewline(source)}`;
+}
+export function renderClaudeBridge() {
+    return GENERATED_CLAUDE_CONTENT;
+}
+async function readRequiredMarkdown(path, sourceLabel) {
+    try {
+        const stats = await lstat(path);
+        if (!stats.isFile() || stats.isSymbolicLink()) {
+            throw new Error("not a regular file");
+        }
+        return await readFile(path, "utf8");
+    }
+    catch {
+        throw new ContextRenderError(sourceLabel, "the required source is missing or unreadable");
+    }
+}
+export async function renderRootMarkdown(paths) {
+    assertSafeContextPaths(paths);
+    const source = await readRequiredMarkdown(paths.sources.rootInstructions, ROOT_SOURCE_LABEL);
+    return {
+        agents: renderMarkdownSource(source, ROOT_SOURCE_LABEL),
+        claude: renderClaudeBridge(),
+    };
+}
+export async function renderPrototypeMarkdown(paths) {
+    assertSafePrototypeContextPaths(paths);
+    const source = await readRequiredMarkdown(paths.sources.prototypeInstructions, PROTOTYPE_SOURCE_LABEL);
+    return {
+        agents: renderMarkdownSource(source, PROTOTYPE_SOURCE_LABEL),
+        claude: renderClaudeBridge(),
+    };
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,sBAAsB,EACtB,+BAA+B,GAGhC,MAAM,YAAY,CAAC;AAEpB,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAC5C,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAEtD,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;CAKvC,CAAC;AAOF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,oBAAoB,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO;gCACuB,MAAM;;;;CAIrC,CAAC;AACF,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,WAAmB;IACtE,OAAO,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,IAAY,EAAE,WAAmB;IACnE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kBAAkB,CAC1B,WAAW,EACX,8CAA8C,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA2B;IAE3B,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,MAAM,oBAAoB,CACvC,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAC9B,iBAAiB,CAClB,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,CAAC;QACvD,MAAM,EAAE,kBAAkB,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAoC;IAEpC,+BAA+B,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CACvC,KAAK,CAAC,OAAO,CAAC,qBAAqB,EACnC,sBAAsB,CACvB,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,CAAC;QAC5D,MAAM,EAAE,kBAAkB,EAAE;KAC7B,CAAC;AACJ,CAAC","sourcesContent":["import { lstat, readFile } from \"node:fs/promises\";\nimport {\n  assertSafeContextPaths,\n  assertSafePrototypeContextPaths,\n  type ResolvedContextPaths,\n  type ResolvedPrototypeContextPaths,\n} from \"./paths.js\";\n\nconst ROOT_SOURCE_LABEL = \"context/ROOT.md\";\nconst PROTOTYPE_SOURCE_LABEL = \"context/PROTOTYPE.md\";\n\nexport const GENERATED_CLAUDE_CONTENT = `<!--\n  This file is generated. Do not edit it directly.\n-->\n\n@AGENTS.md\n`;\n\nexport type MarkdownProjection = Readonly<{\n  agents: string;\n  claude: string;\n}>;\n\nexport class ContextRenderError extends Error {\n  readonly source: string;\n\n  constructor(source: string, message: string) {\n    super(`Unable to render ${source}: ${message}`);\n    this.name = \"ContextRenderError\";\n    this.source = source;\n  }\n}\n\nfunction generatedNotice(source: string) {\n  return `<!--\n  This file is generated from ${source}.\n  Do not edit it directly. Run \\`bonfire context sync\\` after changing the source.\n-->\n\n`;\n}\n\nfunction ensureFinalNewline(source: string) {\n  return source.endsWith(\"\\n\") ? source : `${source}\\n`;\n}\n\nexport function renderMarkdownSource(source: string, sourceLabel: string) {\n  return `${generatedNotice(sourceLabel)}${ensureFinalNewline(source)}`;\n}\n\nexport function renderClaudeBridge() {\n  return GENERATED_CLAUDE_CONTENT;\n}\n\nasync function readRequiredMarkdown(path: string, sourceLabel: string) {\n  try {\n    const stats = await lstat(path);\n    if (!stats.isFile() || stats.isSymbolicLink()) {\n      throw new Error(\"not a regular file\");\n    }\n    return await readFile(path, \"utf8\");\n  } catch {\n    throw new ContextRenderError(\n      sourceLabel,\n      \"the required source is missing or unreadable\",\n    );\n  }\n}\n\nexport async function renderRootMarkdown(\n  paths: ResolvedContextPaths,\n): Promise<MarkdownProjection> {\n  assertSafeContextPaths(paths);\n  const source = await readRequiredMarkdown(\n    paths.sources.rootInstructions,\n    ROOT_SOURCE_LABEL,\n  );\n\n  return {\n    agents: renderMarkdownSource(source, ROOT_SOURCE_LABEL),\n    claude: renderClaudeBridge(),\n  };\n}\n\nexport async function renderPrototypeMarkdown(\n  paths: ResolvedPrototypeContextPaths,\n): Promise<MarkdownProjection> {\n  assertSafePrototypeContextPaths(paths);\n  const source = await readRequiredMarkdown(\n    paths.sources.prototypeInstructions,\n    PROTOTYPE_SOURCE_LABEL,\n  );\n\n  return {\n    agents: renderMarkdownSource(source, PROTOTYPE_SOURCE_LABEL),\n    claude: renderClaudeBridge(),\n  };\n}\n"]}

package/dist/root-project.d.ts

@@ -0,0 +1,11 @@
+import { type RenderedSkillFile } from "./skills.js";
+import type { ContextProjectionResult } from "./types.js";
+export { ContextProjectionError } from "./errors.js";
+export type ProjectRootContextOptions = Readonly<{
+    repositoryRoot: string;
+    prototypeRoot?: string;
+}>;
+export declare function listSkillFiles(root: string, relativeDirectory?: string): Promise<string[]>;
+export declare function reconcileSkills(outputRoot: string, renderedFiles: readonly RenderedSkillFile[], repositoryRoot: string, written: string[], removed: string[], writePaths?: ReadonlySet<string>): Promise<void>;
+export declare function projectRootContext(options: ProjectRootContextOptions): Promise<ContextProjectionResult>;
+//# sourceMappingURL=root-project.d.ts.map

package/dist/root-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-project.d.ts","sourceRoot":"","sources":["../src/root-project.ts"],"names":[],"mappings":"AAKA,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAQvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,iBAAiB,SAAK,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB;AAiDD,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,iBA4BjC;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,uBAAuB,CAAC,CA+DlC","sourcesContent":["import { lstat, readdir, rmdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport { renderOptionalMcp, renderOptionalSettings } from \"./template.js\";\nimport { renderRootMarkdown } from \"./render.js\";\nimport { assertSafeContextPaths, resolveContextPaths } from \"./paths.js\";\nimport { renderSkillFiles, type RenderedSkillFile } from \"./skills.js\";\nimport {\n  atomicWrite,\n  assertWritableTarget,\n  isNotFound,\n  removeManagedFile,\n} from \"./internal/filesystem.js\";\nimport { ContextProjectionError } from \"./errors.js\";\nimport type { ContextProjectionResult } from \"./types.js\";\n\nexport { ContextProjectionError } from \"./errors.js\";\n\nexport type ProjectRootContextOptions = Readonly<{\n  repositoryRoot: string;\n  prototypeRoot?: string;\n}>;\n\nexport async function listSkillFiles(\n  root: string,\n  relativeDirectory = \"\",\n): Promise<string[]> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (error) {\n    if (isNotFound(error)) return [];\n    throw new ContextProjectionError(\n      relativeDirectory || \"rootOutputs.skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  const files: string[] = [];\n  for (const entry of entries.sort((left, right) =>\n    left.name < right.name ? -1 : left.name > right.name ? 1 : 0,\n  )) {\n    const relativePath = relativeDirectory\n      ? `${relativeDirectory}/${entry.name}`\n      : entry.name;\n    const path = join(root, entry.name);\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"could not be inspected safely\",\n      );\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"must not be a symbolic link\",\n      );\n    }\n    if (stats.isDirectory()) {\n      files.push(...(await listSkillFiles(path, relativePath)));\n    } else if (stats.isFile()) {\n      files.push(relativePath);\n    } else {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"must be a regular file or directory\",\n      );\n    }\n  }\n  return files;\n}\n\nasync function removeEmptySkillDirectories(root: string): Promise<boolean> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (error) {\n    if (isNotFound(error)) return false;\n    throw new ContextProjectionError(\n      \"rootOutputs.skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  for (const entry of entries) {\n    const path = join(root, entry.name);\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${entry.name}`,\n        \"could not be inspected safely\",\n      );\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${entry.name}`,\n        \"must not be a symbolic link\",\n      );\n    }\n    if (stats.isDirectory()) {\n      await removeEmptySkillDirectories(path);\n    }\n  }\n\n  const remaining = await readdir(root);\n  if (remaining.length !== 0) return false;\n  try {\n    await rmdir(root);\n  } catch {\n    throw new ContextProjectionError(\n      \"rootOutputs.skills\",\n      \"empty directory could not be removed\",\n    );\n  }\n  return true;\n}\n\nexport async function reconcileSkills(\n  outputRoot: string,\n  renderedFiles: readonly RenderedSkillFile[],\n  repositoryRoot: string,\n  written: string[],\n  removed: string[],\n  writePaths?: ReadonlySet<string>,\n) {\n  const existingFiles = await listSkillFiles(outputRoot);\n  const expected = new Set(renderedFiles.map((file) => file.relativePath));\n\n  for (const file of renderedFiles) {\n    const path = join(outputRoot, file.relativePath);\n    if (writePaths !== undefined && !writePaths.has(path)) continue;\n    await atomicWrite(\n      path,\n      file.content,\n      `rootOutputs.skills/${file.relativePath}`,\n      file.mode,\n    );\n    written.push(relative(repositoryRoot, path));\n  }\n\n  for (const file of existingFiles) {\n    if (expected.has(file)) continue;\n    const path = join(outputRoot, file);\n    if (await removeManagedFile(path, `rootOutputs.skills/${file}`)) {\n      removed.push(relative(repositoryRoot, path));\n    }\n  }\n\n  if (await removeEmptySkillDirectories(outputRoot)) {\n    removed.push(relative(repositoryRoot, outputRoot));\n  }\n}\n\nexport async function projectRootContext(\n  options: ProjectRootContextOptions,\n): Promise<ContextProjectionResult> {\n  const paths = resolveContextPaths(options);\n  assertSafeContextPaths(paths);\n  await Promise.all([\n    assertWritableTarget(paths.rootOutputs.agents, \"AGENTS.md\"),\n    assertWritableTarget(paths.rootOutputs.claude, \"CLAUDE.md\"),\n    assertWritableTarget(paths.rootOutputs.settings, \".claude/settings.json\"),\n    assertWritableTarget(paths.rootOutputs.mcp, \".mcp.json\"),\n    listSkillFiles(paths.rootOutputs.skills),\n  ]);\n\n  // Render every source before changing a generated target. Invalid source\n  // content must not leave a partially updated repository projection.\n  const [markdown, settings, mcp, skills] = await Promise.all([\n    renderRootMarkdown(paths),\n    renderOptionalSettings(paths),\n    renderOptionalMcp(paths),\n    renderSkillFiles(paths),\n  ]);\n\n  const written: string[] = [];\n  const removed: string[] = [];\n  await atomicWrite(paths.rootOutputs.agents, markdown.agents, \"AGENTS.md\");\n  written.push(relative(paths.repositoryRoot, paths.rootOutputs.agents));\n  await atomicWrite(paths.rootOutputs.claude, markdown.claude, \"CLAUDE.md\");\n  written.push(relative(paths.repositoryRoot, paths.rootOutputs.claude));\n\n  if (settings === undefined) {\n    if (\n      await removeManagedFile(\n        paths.rootOutputs.settings,\n        \".claude/settings.json\",\n      )\n    ) {\n      removed.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));\n    }\n  } else {\n    await atomicWrite(\n      paths.rootOutputs.settings,\n      settings,\n      \".claude/settings.json\",\n    );\n    written.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));\n  }\n\n  if (mcp === undefined) {\n    if (await removeManagedFile(paths.rootOutputs.mcp, \".mcp.json\")) {\n      removed.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));\n    }\n  } else {\n    await atomicWrite(paths.rootOutputs.mcp, mcp, \".mcp.json\");\n    written.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));\n  }\n\n  await reconcileSkills(\n    paths.rootOutputs.skills,\n    skills,\n    paths.repositoryRoot,\n    written,\n    removed,\n  );\n\n  return { written, removed };\n}\n"]}

package/dist/root-project.js

@@ -0,0 +1,152 @@
+import { lstat, readdir, rmdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { renderOptionalMcp, renderOptionalSettings } from "./template.js";
+import { renderRootMarkdown } from "./render.js";
+import { assertSafeContextPaths, resolveContextPaths } from "./paths.js";
+import { renderSkillFiles } from "./skills.js";
+import { atomicWrite, assertWritableTarget, isNotFound, removeManagedFile, } from "./internal/filesystem.js";
+import { ContextProjectionError } from "./errors.js";
+export { ContextProjectionError } from "./errors.js";
+export async function listSkillFiles(root, relativeDirectory = "") {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw new ContextProjectionError(relativeDirectory || "rootOutputs.skills", "directory could not be enumerated");
+    }
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
+        const relativePath = relativeDirectory
+            ? `${relativeDirectory}/${entry.name}`
+            : entry.name;
+        const path = join(root, entry.name);
+        let stats;
+        try {
+            stats = await lstat(path);
+        }
+        catch {
+            throw new ContextProjectionError(`rootOutputs.skills/${relativePath}`, "could not be inspected safely");
+        }
+        if (stats.isSymbolicLink()) {
+            throw new ContextProjectionError(`rootOutputs.skills/${relativePath}`, "must not be a symbolic link");
+        }
+        if (stats.isDirectory()) {
+            files.push(...(await listSkillFiles(path, relativePath)));
+        }
+        else if (stats.isFile()) {
+            files.push(relativePath);
+        }
+        else {
+            throw new ContextProjectionError(`rootOutputs.skills/${relativePath}`, "must be a regular file or directory");
+        }
+    }
+    return files;
+}
+async function removeEmptySkillDirectories(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return false;
+        throw new ContextProjectionError("rootOutputs.skills", "directory could not be enumerated");
+    }
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        let stats;
+        try {
+            stats = await lstat(path);
+        }
+        catch {
+            throw new ContextProjectionError(`rootOutputs.skills/${entry.name}`, "could not be inspected safely");
+        }
+        if (stats.isSymbolicLink()) {
+            throw new ContextProjectionError(`rootOutputs.skills/${entry.name}`, "must not be a symbolic link");
+        }
+        if (stats.isDirectory()) {
+            await removeEmptySkillDirectories(path);
+        }
+    }
+    const remaining = await readdir(root);
+    if (remaining.length !== 0)
+        return false;
+    try {
+        await rmdir(root);
+    }
+    catch {
+        throw new ContextProjectionError("rootOutputs.skills", "empty directory could not be removed");
+    }
+    return true;
+}
+export async function reconcileSkills(outputRoot, renderedFiles, repositoryRoot, written, removed, writePaths) {
+    const existingFiles = await listSkillFiles(outputRoot);
+    const expected = new Set(renderedFiles.map((file) => file.relativePath));
+    for (const file of renderedFiles) {
+        const path = join(outputRoot, file.relativePath);
+        if (writePaths !== undefined && !writePaths.has(path))
+            continue;
+        await atomicWrite(path, file.content, `rootOutputs.skills/${file.relativePath}`, file.mode);
+        written.push(relative(repositoryRoot, path));
+    }
+    for (const file of existingFiles) {
+        if (expected.has(file))
+            continue;
+        const path = join(outputRoot, file);
+        if (await removeManagedFile(path, `rootOutputs.skills/${file}`)) {
+            removed.push(relative(repositoryRoot, path));
+        }
+    }
+    if (await removeEmptySkillDirectories(outputRoot)) {
+        removed.push(relative(repositoryRoot, outputRoot));
+    }
+}
+export async function projectRootContext(options) {
+    const paths = resolveContextPaths(options);
+    assertSafeContextPaths(paths);
+    await Promise.all([
+        assertWritableTarget(paths.rootOutputs.agents, "AGENTS.md"),
+        assertWritableTarget(paths.rootOutputs.claude, "CLAUDE.md"),
+        assertWritableTarget(paths.rootOutputs.settings, ".claude/settings.json"),
+        assertWritableTarget(paths.rootOutputs.mcp, ".mcp.json"),
+        listSkillFiles(paths.rootOutputs.skills),
+    ]);
+    // Render every source before changing a generated target. Invalid source
+    // content must not leave a partially updated repository projection.
+    const [markdown, settings, mcp, skills] = await Promise.all([
+        renderRootMarkdown(paths),
+        renderOptionalSettings(paths),
+        renderOptionalMcp(paths),
+        renderSkillFiles(paths),
+    ]);
+    const written = [];
+    const removed = [];
+    await atomicWrite(paths.rootOutputs.agents, markdown.agents, "AGENTS.md");
+    written.push(relative(paths.repositoryRoot, paths.rootOutputs.agents));
+    await atomicWrite(paths.rootOutputs.claude, markdown.claude, "CLAUDE.md");
+    written.push(relative(paths.repositoryRoot, paths.rootOutputs.claude));
+    if (settings === undefined) {
+        if (await removeManagedFile(paths.rootOutputs.settings, ".claude/settings.json")) {
+            removed.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));
+        }
+    }
+    else {
+        await atomicWrite(paths.rootOutputs.settings, settings, ".claude/settings.json");
+        written.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));
+    }
+    if (mcp === undefined) {
+        if (await removeManagedFile(paths.rootOutputs.mcp, ".mcp.json")) {
+            removed.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));
+        }
+    }
+    else {
+        await atomicWrite(paths.rootOutputs.mcp, mcp, ".mcp.json");
+        written.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));
+    }
+    await reconcileSkills(paths.rootOutputs.skills, skills, paths.repositoryRoot, written, removed);
+    return { written, removed };
+}
+//# sourceMappingURL=root-project.js.map

package/dist/root-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-project.js","sourceRoot":"","sources":["../src/root-project.ts"],"names":[],"mappings":"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","sourcesContent":["import { lstat, readdir, rmdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport { renderOptionalMcp, renderOptionalSettings } from \"./template.js\";\nimport { renderRootMarkdown } from \"./render.js\";\nimport { assertSafeContextPaths, resolveContextPaths } from \"./paths.js\";\nimport { renderSkillFiles, type RenderedSkillFile } from \"./skills.js\";\nimport {\n  atomicWrite,\n  assertWritableTarget,\n  isNotFound,\n  removeManagedFile,\n} from \"./internal/filesystem.js\";\nimport { ContextProjectionError } from \"./errors.js\";\nimport type { ContextProjectionResult } from \"./types.js\";\n\nexport { ContextProjectionError } from \"./errors.js\";\n\nexport type ProjectRootContextOptions = Readonly<{\n  repositoryRoot: string;\n  prototypeRoot?: string;\n}>;\n\nexport async function listSkillFiles(\n  root: string,\n  relativeDirectory = \"\",\n): Promise<string[]> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (error) {\n    if (isNotFound(error)) return [];\n    throw new ContextProjectionError(\n      relativeDirectory || \"rootOutputs.skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  const files: string[] = [];\n  for (const entry of entries.sort((left, right) =>\n    left.name < right.name ? -1 : left.name > right.name ? 1 : 0,\n  )) {\n    const relativePath = relativeDirectory\n      ? `${relativeDirectory}/${entry.name}`\n      : entry.name;\n    const path = join(root, entry.name);\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"could not be inspected safely\",\n      );\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"must not be a symbolic link\",\n      );\n    }\n    if (stats.isDirectory()) {\n      files.push(...(await listSkillFiles(path, relativePath)));\n    } else if (stats.isFile()) {\n      files.push(relativePath);\n    } else {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${relativePath}`,\n        \"must be a regular file or directory\",\n      );\n    }\n  }\n  return files;\n}\n\nasync function removeEmptySkillDirectories(root: string): Promise<boolean> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch (error) {\n    if (isNotFound(error)) return false;\n    throw new ContextProjectionError(\n      \"rootOutputs.skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  for (const entry of entries) {\n    const path = join(root, entry.name);\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${entry.name}`,\n        \"could not be inspected safely\",\n      );\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextProjectionError(\n        `rootOutputs.skills/${entry.name}`,\n        \"must not be a symbolic link\",\n      );\n    }\n    if (stats.isDirectory()) {\n      await removeEmptySkillDirectories(path);\n    }\n  }\n\n  const remaining = await readdir(root);\n  if (remaining.length !== 0) return false;\n  try {\n    await rmdir(root);\n  } catch {\n    throw new ContextProjectionError(\n      \"rootOutputs.skills\",\n      \"empty directory could not be removed\",\n    );\n  }\n  return true;\n}\n\nexport async function reconcileSkills(\n  outputRoot: string,\n  renderedFiles: readonly RenderedSkillFile[],\n  repositoryRoot: string,\n  written: string[],\n  removed: string[],\n  writePaths?: ReadonlySet<string>,\n) {\n  const existingFiles = await listSkillFiles(outputRoot);\n  const expected = new Set(renderedFiles.map((file) => file.relativePath));\n\n  for (const file of renderedFiles) {\n    const path = join(outputRoot, file.relativePath);\n    if (writePaths !== undefined && !writePaths.has(path)) continue;\n    await atomicWrite(\n      path,\n      file.content,\n      `rootOutputs.skills/${file.relativePath}`,\n      file.mode,\n    );\n    written.push(relative(repositoryRoot, path));\n  }\n\n  for (const file of existingFiles) {\n    if (expected.has(file)) continue;\n    const path = join(outputRoot, file);\n    if (await removeManagedFile(path, `rootOutputs.skills/${file}`)) {\n      removed.push(relative(repositoryRoot, path));\n    }\n  }\n\n  if (await removeEmptySkillDirectories(outputRoot)) {\n    removed.push(relative(repositoryRoot, outputRoot));\n  }\n}\n\nexport async function projectRootContext(\n  options: ProjectRootContextOptions,\n): Promise<ContextProjectionResult> {\n  const paths = resolveContextPaths(options);\n  assertSafeContextPaths(paths);\n  await Promise.all([\n    assertWritableTarget(paths.rootOutputs.agents, \"AGENTS.md\"),\n    assertWritableTarget(paths.rootOutputs.claude, \"CLAUDE.md\"),\n    assertWritableTarget(paths.rootOutputs.settings, \".claude/settings.json\"),\n    assertWritableTarget(paths.rootOutputs.mcp, \".mcp.json\"),\n    listSkillFiles(paths.rootOutputs.skills),\n  ]);\n\n  // Render every source before changing a generated target. Invalid source\n  // content must not leave a partially updated repository projection.\n  const [markdown, settings, mcp, skills] = await Promise.all([\n    renderRootMarkdown(paths),\n    renderOptionalSettings(paths),\n    renderOptionalMcp(paths),\n    renderSkillFiles(paths),\n  ]);\n\n  const written: string[] = [];\n  const removed: string[] = [];\n  await atomicWrite(paths.rootOutputs.agents, markdown.agents, \"AGENTS.md\");\n  written.push(relative(paths.repositoryRoot, paths.rootOutputs.agents));\n  await atomicWrite(paths.rootOutputs.claude, markdown.claude, \"CLAUDE.md\");\n  written.push(relative(paths.repositoryRoot, paths.rootOutputs.claude));\n\n  if (settings === undefined) {\n    if (\n      await removeManagedFile(\n        paths.rootOutputs.settings,\n        \".claude/settings.json\",\n      )\n    ) {\n      removed.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));\n    }\n  } else {\n    await atomicWrite(\n      paths.rootOutputs.settings,\n      settings,\n      \".claude/settings.json\",\n    );\n    written.push(relative(paths.repositoryRoot, paths.rootOutputs.settings));\n  }\n\n  if (mcp === undefined) {\n    if (await removeManagedFile(paths.rootOutputs.mcp, \".mcp.json\")) {\n      removed.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));\n    }\n  } else {\n    await atomicWrite(paths.rootOutputs.mcp, mcp, \".mcp.json\");\n    written.push(relative(paths.repositoryRoot, paths.rootOutputs.mcp));\n  }\n\n  await reconcileSkills(\n    paths.rootOutputs.skills,\n    skills,\n    paths.repositoryRoot,\n    written,\n    removed,\n  );\n\n  return { written, removed };\n}\n"]}

package/dist/skills.d.ts

@@ -0,0 +1,13 @@
+import { type ResolvedContextPaths } from "./paths.js";
+export type RenderedSkillFile = Readonly<{
+    relativePath: string;
+    content: Buffer;
+    mode: number;
+}>;
+export declare class ContextSkillError extends Error {
+    readonly relativePath: string;
+    constructor(relativePath: string, message: string);
+}
+export declare function validateSkillNames(names: readonly string[]): void;
+export declare function renderSkillFiles(paths: ResolvedContextPaths): Promise<readonly RenderedSkillFile[]>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAM/E,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,YAAY,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIhD;CACF;AAuCD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,QAM1D;AAqFD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA0EvC","sourcesContent":["import { constants } from \"node:fs\";\nimport { lstat, open, readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { assertSafeContextPaths, type ResolvedContextPaths } from \"./paths.js\";\n\nconst SKILL_FILE_MODE = 0o644;\nconst SKILL_MARKER_FILE = \"SKILL.md\";\nconst FILE_OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);\n\nexport type RenderedSkillFile = Readonly<{\n  relativePath: string;\n  content: Buffer;\n  mode: number;\n}>;\n\nexport class ContextSkillError extends Error {\n  readonly relativePath: string;\n\n  constructor(relativePath: string, message: string) {\n    super(`Invalid context skill at ${relativePath}: ${message}`);\n    this.name = \"ContextSkillError\";\n    this.relativePath = relativePath;\n  }\n}\n\nfunction isSafeSegment(segment: string) {\n  return (\n    segment.length > 0 &&\n    segment !== \".\" &&\n    segment !== \"..\" &&\n    !segment.startsWith(\".\") &&\n    !segment.includes(\"/\") &&\n    !segment.includes(\"\\\\\") &&\n    !segment.includes(\"\\0\")\n  );\n}\n\nfunction assertSafeSkillSegment(segment: string, relativePath: string) {\n  if (!isSafeSegment(segment)) {\n    throw new ContextSkillError(\n      relativePath,\n      \"contains an unsafe path segment\",\n    );\n  }\n}\n\nfunction assertUniqueSkillName(\n  name: string,\n  relativePath: string,\n  seenNames: Set<string>,\n) {\n  const normalizedName = name.toLowerCase();\n  if (seenNames.has(normalizedName)) {\n    throw new ContextSkillError(relativePath, \"duplicates another skill name\");\n  }\n  seenNames.add(normalizedName);\n}\n\nfunction compareNames(left: string, right: string) {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n\nexport function validateSkillNames(names: readonly string[]) {\n  const seenNames = new Set<string>();\n  for (const name of names) {\n    assertSafeSkillSegment(name, name);\n    assertUniqueSkillName(name, name, seenNames);\n  }\n}\n\nasync function readRegularFile(path: string, relativePath: string) {\n  let file;\n  try {\n    file = await open(path, FILE_OPEN_FLAGS);\n    const stats = await file.stat();\n    if (!stats.isFile()) {\n      throw new ContextSkillError(relativePath, \"must be a regular file\");\n    }\n    return Buffer.from(await file.readFile());\n  } catch (error) {\n    if (error instanceof ContextSkillError) throw error;\n    throw new ContextSkillError(relativePath, \"could not be read safely\");\n  } finally {\n    await file?.close().catch(() => undefined);\n  }\n}\n\nasync function collectSkillFiles(\n  root: string,\n  relativeDirectory: string,\n): Promise<RenderedSkillFile[]> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch {\n    throw new ContextSkillError(\n      relativeDirectory,\n      \"directory could not be enumerated\",\n    );\n  }\n\n  const files: RenderedSkillFile[] = [];\n  for (const entry of entries.sort((left, right) =>\n    compareNames(left.name, right.name),\n  )) {\n    const relativePath = relativeDirectory\n      ? `${relativeDirectory}/${entry.name}`\n      : entry.name;\n    assertSafeSkillSegment(entry.name, relativePath);\n    const path = join(root, entry.name);\n\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextSkillError(relativePath, \"could not be inspected\");\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextSkillError(relativePath, \"must not be a symbolic link\");\n    }\n\n    if (stats.isDirectory()) {\n      files.push(...(await collectSkillFiles(path, relativePath)));\n      continue;\n    }\n    if (!stats.isFile()) {\n      throw new ContextSkillError(relativePath, \"must be a regular file\");\n    }\n\n    files.push({\n      relativePath,\n      content: await readRegularFile(path, relativePath),\n      mode: SKILL_FILE_MODE,\n    });\n  }\n\n  return files;\n}\n\nfunction assertUniqueRenderedPaths(files: readonly RenderedSkillFile[]) {\n  const seen = new Set<string>();\n  for (const file of files) {\n    const normalizedPath = file.relativePath.toLowerCase();\n    if (seen.has(normalizedPath)) {\n      throw new ContextSkillError(\n        file.relativePath,\n        \"duplicates another projected file\",\n      );\n    }\n    seen.add(normalizedPath);\n  }\n}\n\nexport async function renderSkillFiles(\n  paths: ResolvedContextPaths,\n): Promise<readonly RenderedSkillFile[]> {\n  assertSafeContextPaths(paths);\n\n  let stats;\n  try {\n    stats = await lstat(paths.sources.skills);\n  } catch (error) {\n    if (\n      error !== null &&\n      typeof error === \"object\" &&\n      \"code\" in error &&\n      error.code === \"ENOENT\"\n    ) {\n      return [];\n    }\n    throw new ContextSkillError(\"context/skills\", \"could not be inspected\");\n  }\n\n  if (stats.isSymbolicLink()) {\n    throw new ContextSkillError(\n      \"context/skills\",\n      \"must not be a symbolic link\",\n    );\n  }\n  if (!stats.isDirectory()) {\n    throw new ContextSkillError(\"context/skills\", \"must be a directory\");\n  }\n\n  let entries;\n  try {\n    entries = await readdir(paths.sources.skills, { withFileTypes: true });\n  } catch {\n    throw new ContextSkillError(\n      \"context/skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  validateSkillNames(entries.map((entry) => entry.name));\n  const files: RenderedSkillFile[] = [];\n  for (const entry of entries.sort((left, right) =>\n    compareNames(left.name, right.name),\n  )) {\n    const skillPath = join(paths.sources.skills, entry.name);\n\n    let stats;\n    try {\n      stats = await lstat(skillPath);\n    } catch {\n      throw new ContextSkillError(entry.name, \"could not be inspected\");\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextSkillError(entry.name, \"must not be a symbolic link\");\n    }\n    if (!stats.isDirectory()) {\n      throw new ContextSkillError(entry.name, \"skill must be a directory\");\n    }\n\n    const skillFiles = await collectSkillFiles(skillPath, entry.name);\n    if (\n      !skillFiles.some(\n        (file) => file.relativePath === `${entry.name}/${SKILL_MARKER_FILE}`,\n      )\n    ) {\n      throw new ContextSkillError(\n        entry.name,\n        `must contain ${SKILL_MARKER_FILE}`,\n      );\n    }\n    files.push(...skillFiles);\n  }\n\n  assertUniqueRenderedPaths(files);\n  return files;\n}\n"]}

package/dist/skills.js

@@ -0,0 +1,170 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSafeContextPaths } from "./paths.js";
+const SKILL_FILE_MODE = 0o644;
+const SKILL_MARKER_FILE = "SKILL.md";
+const FILE_OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
+export class ContextSkillError extends Error {
+    relativePath;
+    constructor(relativePath, message) {
+        super(`Invalid context skill at ${relativePath}: ${message}`);
+        this.name = "ContextSkillError";
+        this.relativePath = relativePath;
+    }
+}
+function isSafeSegment(segment) {
+    return (segment.length > 0 &&
+        segment !== "." &&
+        segment !== ".." &&
+        !segment.startsWith(".") &&
+        !segment.includes("/") &&
+        !segment.includes("\\") &&
+        !segment.includes("\0"));
+}
+function assertSafeSkillSegment(segment, relativePath) {
+    if (!isSafeSegment(segment)) {
+        throw new ContextSkillError(relativePath, "contains an unsafe path segment");
+    }
+}
+function assertUniqueSkillName(name, relativePath, seenNames) {
+    const normalizedName = name.toLowerCase();
+    if (seenNames.has(normalizedName)) {
+        throw new ContextSkillError(relativePath, "duplicates another skill name");
+    }
+    seenNames.add(normalizedName);
+}
+function compareNames(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+export function validateSkillNames(names) {
+    const seenNames = new Set();
+    for (const name of names) {
+        assertSafeSkillSegment(name, name);
+        assertUniqueSkillName(name, name, seenNames);
+    }
+}
+async function readRegularFile(path, relativePath) {
+    let file;
+    try {
+        file = await open(path, FILE_OPEN_FLAGS);
+        const stats = await file.stat();
+        if (!stats.isFile()) {
+            throw new ContextSkillError(relativePath, "must be a regular file");
+        }
+        return Buffer.from(await file.readFile());
+    }
+    catch (error) {
+        if (error instanceof ContextSkillError)
+            throw error;
+        throw new ContextSkillError(relativePath, "could not be read safely");
+    }
+    finally {
+        await file?.close().catch(() => undefined);
+    }
+}
+async function collectSkillFiles(root, relativeDirectory) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        throw new ContextSkillError(relativeDirectory, "directory could not be enumerated");
+    }
+    const files = [];
+    for (const entry of entries.sort((left, right) => compareNames(left.name, right.name))) {
+        const relativePath = relativeDirectory
+            ? `${relativeDirectory}/${entry.name}`
+            : entry.name;
+        assertSafeSkillSegment(entry.name, relativePath);
+        const path = join(root, entry.name);
+        let stats;
+        try {
+            stats = await lstat(path);
+        }
+        catch {
+            throw new ContextSkillError(relativePath, "could not be inspected");
+        }
+        if (stats.isSymbolicLink()) {
+            throw new ContextSkillError(relativePath, "must not be a symbolic link");
+        }
+        if (stats.isDirectory()) {
+            files.push(...(await collectSkillFiles(path, relativePath)));
+            continue;
+        }
+        if (!stats.isFile()) {
+            throw new ContextSkillError(relativePath, "must be a regular file");
+        }
+        files.push({
+            relativePath,
+            content: await readRegularFile(path, relativePath),
+            mode: SKILL_FILE_MODE,
+        });
+    }
+    return files;
+}
+function assertUniqueRenderedPaths(files) {
+    const seen = new Set();
+    for (const file of files) {
+        const normalizedPath = file.relativePath.toLowerCase();
+        if (seen.has(normalizedPath)) {
+            throw new ContextSkillError(file.relativePath, "duplicates another projected file");
+        }
+        seen.add(normalizedPath);
+    }
+}
+export async function renderSkillFiles(paths) {
+    assertSafeContextPaths(paths);
+    let stats;
+    try {
+        stats = await lstat(paths.sources.skills);
+    }
+    catch (error) {
+        if (error !== null &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw new ContextSkillError("context/skills", "could not be inspected");
+    }
+    if (stats.isSymbolicLink()) {
+        throw new ContextSkillError("context/skills", "must not be a symbolic link");
+    }
+    if (!stats.isDirectory()) {
+        throw new ContextSkillError("context/skills", "must be a directory");
+    }
+    let entries;
+    try {
+        entries = await readdir(paths.sources.skills, { withFileTypes: true });
+    }
+    catch {
+        throw new ContextSkillError("context/skills", "directory could not be enumerated");
+    }
+    validateSkillNames(entries.map((entry) => entry.name));
+    const files = [];
+    for (const entry of entries.sort((left, right) => compareNames(left.name, right.name))) {
+        const skillPath = join(paths.sources.skills, entry.name);
+        let stats;
+        try {
+            stats = await lstat(skillPath);
+        }
+        catch {
+            throw new ContextSkillError(entry.name, "could not be inspected");
+        }
+        if (stats.isSymbolicLink()) {
+            throw new ContextSkillError(entry.name, "must not be a symbolic link");
+        }
+        if (!stats.isDirectory()) {
+            throw new ContextSkillError(entry.name, "skill must be a directory");
+        }
+        const skillFiles = await collectSkillFiles(skillPath, entry.name);
+        if (!skillFiles.some((file) => file.relativePath === `${entry.name}/${SKILL_MARKER_FILE}`)) {
+            throw new ContextSkillError(entry.name, `must contain ${SKILL_MARKER_FILE}`);
+        }
+        files.push(...skillFiles);
+    }
+    assertUniqueRenderedPaths(files);
+    return files;
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from \"node:fs\";\nimport { lstat, open, readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { assertSafeContextPaths, type ResolvedContextPaths } from \"./paths.js\";\n\nconst SKILL_FILE_MODE = 0o644;\nconst SKILL_MARKER_FILE = \"SKILL.md\";\nconst FILE_OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);\n\nexport type RenderedSkillFile = Readonly<{\n  relativePath: string;\n  content: Buffer;\n  mode: number;\n}>;\n\nexport class ContextSkillError extends Error {\n  readonly relativePath: string;\n\n  constructor(relativePath: string, message: string) {\n    super(`Invalid context skill at ${relativePath}: ${message}`);\n    this.name = \"ContextSkillError\";\n    this.relativePath = relativePath;\n  }\n}\n\nfunction isSafeSegment(segment: string) {\n  return (\n    segment.length > 0 &&\n    segment !== \".\" &&\n    segment !== \"..\" &&\n    !segment.startsWith(\".\") &&\n    !segment.includes(\"/\") &&\n    !segment.includes(\"\\\\\") &&\n    !segment.includes(\"\\0\")\n  );\n}\n\nfunction assertSafeSkillSegment(segment: string, relativePath: string) {\n  if (!isSafeSegment(segment)) {\n    throw new ContextSkillError(\n      relativePath,\n      \"contains an unsafe path segment\",\n    );\n  }\n}\n\nfunction assertUniqueSkillName(\n  name: string,\n  relativePath: string,\n  seenNames: Set<string>,\n) {\n  const normalizedName = name.toLowerCase();\n  if (seenNames.has(normalizedName)) {\n    throw new ContextSkillError(relativePath, \"duplicates another skill name\");\n  }\n  seenNames.add(normalizedName);\n}\n\nfunction compareNames(left: string, right: string) {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n\nexport function validateSkillNames(names: readonly string[]) {\n  const seenNames = new Set<string>();\n  for (const name of names) {\n    assertSafeSkillSegment(name, name);\n    assertUniqueSkillName(name, name, seenNames);\n  }\n}\n\nasync function readRegularFile(path: string, relativePath: string) {\n  let file;\n  try {\n    file = await open(path, FILE_OPEN_FLAGS);\n    const stats = await file.stat();\n    if (!stats.isFile()) {\n      throw new ContextSkillError(relativePath, \"must be a regular file\");\n    }\n    return Buffer.from(await file.readFile());\n  } catch (error) {\n    if (error instanceof ContextSkillError) throw error;\n    throw new ContextSkillError(relativePath, \"could not be read safely\");\n  } finally {\n    await file?.close().catch(() => undefined);\n  }\n}\n\nasync function collectSkillFiles(\n  root: string,\n  relativeDirectory: string,\n): Promise<RenderedSkillFile[]> {\n  let entries;\n  try {\n    entries = await readdir(root, { withFileTypes: true });\n  } catch {\n    throw new ContextSkillError(\n      relativeDirectory,\n      \"directory could not be enumerated\",\n    );\n  }\n\n  const files: RenderedSkillFile[] = [];\n  for (const entry of entries.sort((left, right) =>\n    compareNames(left.name, right.name),\n  )) {\n    const relativePath = relativeDirectory\n      ? `${relativeDirectory}/${entry.name}`\n      : entry.name;\n    assertSafeSkillSegment(entry.name, relativePath);\n    const path = join(root, entry.name);\n\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch {\n      throw new ContextSkillError(relativePath, \"could not be inspected\");\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextSkillError(relativePath, \"must not be a symbolic link\");\n    }\n\n    if (stats.isDirectory()) {\n      files.push(...(await collectSkillFiles(path, relativePath)));\n      continue;\n    }\n    if (!stats.isFile()) {\n      throw new ContextSkillError(relativePath, \"must be a regular file\");\n    }\n\n    files.push({\n      relativePath,\n      content: await readRegularFile(path, relativePath),\n      mode: SKILL_FILE_MODE,\n    });\n  }\n\n  return files;\n}\n\nfunction assertUniqueRenderedPaths(files: readonly RenderedSkillFile[]) {\n  const seen = new Set<string>();\n  for (const file of files) {\n    const normalizedPath = file.relativePath.toLowerCase();\n    if (seen.has(normalizedPath)) {\n      throw new ContextSkillError(\n        file.relativePath,\n        \"duplicates another projected file\",\n      );\n    }\n    seen.add(normalizedPath);\n  }\n}\n\nexport async function renderSkillFiles(\n  paths: ResolvedContextPaths,\n): Promise<readonly RenderedSkillFile[]> {\n  assertSafeContextPaths(paths);\n\n  let stats;\n  try {\n    stats = await lstat(paths.sources.skills);\n  } catch (error) {\n    if (\n      error !== null &&\n      typeof error === \"object\" &&\n      \"code\" in error &&\n      error.code === \"ENOENT\"\n    ) {\n      return [];\n    }\n    throw new ContextSkillError(\"context/skills\", \"could not be inspected\");\n  }\n\n  if (stats.isSymbolicLink()) {\n    throw new ContextSkillError(\n      \"context/skills\",\n      \"must not be a symbolic link\",\n    );\n  }\n  if (!stats.isDirectory()) {\n    throw new ContextSkillError(\"context/skills\", \"must be a directory\");\n  }\n\n  let entries;\n  try {\n    entries = await readdir(paths.sources.skills, { withFileTypes: true });\n  } catch {\n    throw new ContextSkillError(\n      \"context/skills\",\n      \"directory could not be enumerated\",\n    );\n  }\n\n  validateSkillNames(entries.map((entry) => entry.name));\n  const files: RenderedSkillFile[] = [];\n  for (const entry of entries.sort((left, right) =>\n    compareNames(left.name, right.name),\n  )) {\n    const skillPath = join(paths.sources.skills, entry.name);\n\n    let stats;\n    try {\n      stats = await lstat(skillPath);\n    } catch {\n      throw new ContextSkillError(entry.name, \"could not be inspected\");\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextSkillError(entry.name, \"must not be a symbolic link\");\n    }\n    if (!stats.isDirectory()) {\n      throw new ContextSkillError(entry.name, \"skill must be a directory\");\n    }\n\n    const skillFiles = await collectSkillFiles(skillPath, entry.name);\n    if (\n      !skillFiles.some(\n        (file) => file.relativePath === `${entry.name}/${SKILL_MARKER_FILE}`,\n      )\n    ) {\n      throw new ContextSkillError(\n        entry.name,\n        `must contain ${SKILL_MARKER_FILE}`,\n      );\n    }\n    files.push(...skillFiles);\n  }\n\n  assertUniqueRenderedPaths(files);\n  return files;\n}\n"]}

package/dist/sync.d.ts

@@ -0,0 +1,23 @@
+import { type ContextPathOptions } from "./paths.js";
+export type SyncContextOptions = ContextPathOptions;
+export type CheckContextOptions = ContextPathOptions;
+export type ContextIssueKind = "missing" | "stale" | "unexpected";
+export type ContextCheckIssue = Readonly<{
+    kind: ContextIssueKind;
+    path: string;
+}>;
+export type ContextCheckResult = Readonly<{
+    ok: boolean;
+    issues: readonly ContextCheckIssue[];
+}>;
+export type ContextSyncResult = Readonly<ContextCheckResult & {
+    written: readonly string[];
+    removed: readonly string[];
+}>;
+export declare class ContextSyncError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function checkContext(options: CheckContextOptions): Promise<ContextCheckResult>;
+export declare function syncContext(options: SyncContextOptions): Promise<ContextSyncResult>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,kBAAkB,EAGxB,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtC,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CACtC,kBAAkB,GAAG;IACnB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CACF,CAAC;AAEF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIxC;CACF;AAwRD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAsC5B","sourcesContent":["import { lstat, readFile } from \"node:fs/promises\";\nimport { join, relative, sep } from \"node:path\";\nimport {\n  discoverPrototypeDirectoryPaths,\n  discoverPrototypePaths,\n} from \"./discover.js\";\nimport { listSkillFiles, reconcileSkills } from \"./root-project.js\";\nimport {\n  atomicWrite,\n  assertWritableTarget,\n  removeManagedFile,\n} from \"./internal/filesystem.js\";\nimport { renderPrototypeMarkdown, renderRootMarkdown } from \"./render.js\";\nimport {\n  assertSafeContextPaths,\n  assertSafeGeneratedPath,\n  assertSafePrototypeContextPaths,\n  resolveContextPaths,\n  resolvePrototypeContextPaths,\n  type ContextPathOptions,\n  type ResolvedContextPaths,\n  type ResolvedPrototypeContextPaths,\n} from \"./paths.js\";\nimport { renderSkillFiles, type RenderedSkillFile } from \"./skills.js\";\nimport { renderOptionalMcp, renderOptionalSettings } from \"./template.js\";\n\nexport type SyncContextOptions = ContextPathOptions;\nexport type CheckContextOptions = ContextPathOptions;\n\nexport type ContextIssueKind = \"missing\" | \"stale\" | \"unexpected\";\n\nexport type ContextCheckIssue = Readonly<{\n  kind: ContextIssueKind;\n  path: string;\n}>;\n\nexport type ContextCheckResult = Readonly<{\n  ok: boolean;\n  issues: readonly ContextCheckIssue[];\n}>;\n\nexport type ContextSyncResult = Readonly<\n  ContextCheckResult & {\n    written: readonly string[];\n    removed: readonly string[];\n  }\n>;\n\nexport class ContextSyncError extends Error {\n  readonly path: string;\n\n  constructor(path: string, message: string) {\n    super(`Unable to check context at ${path}: ${message}`);\n    this.name = \"ContextSyncError\";\n    this.path = path;\n  }\n}\n\ntype RenderedFile = Readonly<{\n  content: string | Uint8Array;\n  mode?: number;\n}>;\n\ntype PrototypeProjectionPlan = Readonly<{\n  paths: ResolvedPrototypeContextPaths;\n  files: ReadonlyMap<string, RenderedFile>;\n}>;\n\ntype ProjectionPlan = Readonly<{\n  paths: ResolvedContextPaths;\n  rootFiles: ReadonlyMap<string, RenderedFile>;\n  rootSkills: readonly RenderedSkillFile[];\n  prototypes: readonly PrototypeProjectionPlan[];\n  expected: ReadonlyMap<string, RenderedFile>;\n  managed: ReadonlySet<string>;\n}>;\n\nfunction isNotFound(error: unknown) {\n  return (\n    error !== null &&\n    typeof error === \"object\" &&\n    \"code\" in error &&\n    error.code === \"ENOENT\"\n  );\n}\n\nfunction relativePath(repositoryRoot: string, path: string) {\n  return relative(repositoryRoot, path).split(sep).join(\"/\");\n}\n\nfunction addExpected(\n  expected: Map<string, RenderedFile>,\n  path: string,\n  content: string | Uint8Array,\n  mode?: number,\n) {\n  expected.set(path, { content, mode });\n}\n\nasync function addExistingManagedPath(\n  managed: Set<string>,\n  path: string,\n  label: string,\n) {\n  assertSafeGeneratedPath(path, label);\n  try {\n    const stats = await lstat(path);\n    if (stats.isSymbolicLink()) {\n      throw new ContextSyncError(label, \"must not be a symbolic link\");\n    }\n    managed.add(path);\n  } catch (error) {\n    if (error instanceof ContextSyncError) throw error;\n    if (!isNotFound(error)) {\n      throw new ContextSyncError(label, \"could not be inspected safely\");\n    }\n  }\n}\n\nasync function buildProjectionPlan(\n  options: SyncContextOptions,\n): Promise<ProjectionPlan> {\n  const paths = resolveContextPaths(options);\n  assertSafeContextPaths(paths);\n\n  const [rootMarkdown, rootSettings, rootMcp, rootSkills] = await Promise.all([\n    renderRootMarkdown(paths),\n    renderOptionalSettings(paths),\n    renderOptionalMcp(paths),\n    renderSkillFiles(paths),\n  ]);\n  const prototypeDirectories = await discoverPrototypeDirectoryPaths(options);\n  const prototypePaths = await discoverPrototypePaths(options);\n  const prototypePathSet = new Set(prototypePaths);\n\n  const expected = new Map<string, RenderedFile>();\n  const rootFiles = new Map<string, RenderedFile>();\n  addExpected(rootFiles, paths.rootOutputs.agents, rootMarkdown.agents);\n  addExpected(rootFiles, paths.rootOutputs.claude, rootMarkdown.claude);\n  if (rootSettings !== undefined) {\n    addExpected(rootFiles, paths.rootOutputs.settings, rootSettings);\n  }\n  if (rootMcp !== undefined) {\n    addExpected(rootFiles, paths.rootOutputs.mcp, rootMcp);\n  }\n  for (const [path, file] of rootFiles) expected.set(path, file);\n  for (const skill of rootSkills) {\n    addExpected(\n      expected,\n      join(paths.rootOutputs.skills, skill.relativePath),\n      skill.content,\n      skill.mode,\n    );\n  }\n\n  const prototypes: PrototypeProjectionPlan[] = [];\n  for (const prototypePath of prototypePaths) {\n    const prototypeContextPaths = resolvePrototypeContextPaths({\n      ...options,\n      prototypePath,\n    });\n    assertSafePrototypeContextPaths(prototypeContextPaths);\n    const [markdown, settings] = await Promise.all([\n      renderPrototypeMarkdown(prototypeContextPaths),\n      renderOptionalSettings(prototypeContextPaths),\n    ]);\n    const files = new Map<string, RenderedFile>();\n    addExpected(\n      files,\n      prototypeContextPaths.prototypeOutputs.agents,\n      markdown.agents,\n    );\n    addExpected(\n      files,\n      prototypeContextPaths.prototypeOutputs.claude,\n      markdown.claude,\n    );\n    if (settings !== undefined) {\n      addExpected(\n        files,\n        prototypeContextPaths.prototypeOutputs.settings,\n        settings,\n      );\n    }\n    for (const [path, file] of files) expected.set(path, file);\n    prototypes.push({ paths: prototypeContextPaths, files });\n  }\n\n  const managed = new Set<string>([\n    paths.rootOutputs.agents,\n    paths.rootOutputs.claude,\n    paths.rootOutputs.mcp,\n    paths.rootOutputs.settings,\n  ]);\n  for (const path of await listSkillFiles(paths.rootOutputs.skills)) {\n    managed.add(join(paths.rootOutputs.skills, path));\n  }\n\n  for (const prototypePath of prototypeDirectories) {\n    const prototypeContextPaths = resolvePrototypeContextPaths({\n      ...options,\n      prototypePath,\n    });\n    if (prototypePathSet.has(prototypePath)) {\n      for (const path of Object.values(\n        prototypeContextPaths.prototypeOutputs,\n      )) {\n        managed.add(path);\n      }\n      continue;\n    }\n    for (const [label, path] of Object.entries(\n      prototypeContextPaths.prototypeOutputs,\n    )) {\n      await addExistingManagedPath(\n        managed,\n        path,\n        `prototype/${relativePath(paths.repositoryRoot, path)}:${label}`,\n      );\n    }\n  }\n\n  return {\n    paths,\n    rootFiles,\n    rootSkills,\n    prototypes,\n    expected,\n    managed,\n  };\n}\n\nasync function compareFile(\n  path: string,\n  expected: RenderedFile,\n  repositoryRoot: string,\n): Promise<ContextCheckIssue | undefined> {\n  const displayPath = relativePath(repositoryRoot, path);\n  let stats;\n  try {\n    stats = await lstat(path);\n  } catch (error) {\n    if (isNotFound(error)) return { kind: \"missing\", path: displayPath };\n    throw new ContextSyncError(displayPath, \"could not be inspected safely\");\n  }\n  if (stats.isSymbolicLink()) {\n    throw new ContextSyncError(displayPath, \"must not be a symbolic link\");\n  }\n  if (!stats.isFile()) return { kind: \"stale\", path: displayPath };\n\n  let actual;\n  try {\n    actual = await readFile(path);\n  } catch {\n    throw new ContextSyncError(displayPath, \"could not be read safely\");\n  }\n  const expectedBytes =\n    typeof expected.content === \"string\"\n      ? Buffer.from(expected.content)\n      : Buffer.from(expected.content);\n  return actual.equals(expectedBytes)\n    ? undefined\n    : { kind: \"stale\", path: displayPath };\n}\n\nasync function comparePlan(plan: ProjectionPlan): Promise<ContextCheckResult> {\n  const issues: ContextCheckIssue[] = [];\n  for (const [path, expected] of [...plan.expected.entries()].sort(\n    ([left], [right]) => (left < right ? -1 : left > right ? 1 : 0),\n  )) {\n    const issue = await compareFile(path, expected, plan.paths.repositoryRoot);\n    if (issue !== undefined) issues.push(issue);\n  }\n  for (const path of [...plan.managed].sort()) {\n    if (plan.expected.has(path)) continue;\n    const displayPath = relativePath(plan.paths.repositoryRoot, path);\n    let stats;\n    try {\n      stats = await lstat(path);\n    } catch (error) {\n      if (isNotFound(error)) continue;\n      throw new ContextSyncError(displayPath, \"could not be inspected safely\");\n    }\n    if (stats.isSymbolicLink()) {\n      throw new ContextSyncError(displayPath, \"must not be a symbolic link\");\n    }\n    if (!stats.isFile()) {\n      throw new ContextSyncError(displayPath, \"must be a regular file\");\n    }\n    issues.push({ kind: \"unexpected\", path: displayPath });\n  }\n\n  issues.sort((left, right) => {\n    if (left.path !== right.path) return left.path < right.path ? -1 : 1;\n    return left.kind < right.kind ? -1 : left.kind > right.kind ? 1 : 0;\n  });\n  return { ok: issues.length === 0, issues };\n}\n\nasync function preflightWrites(\n  plan: ProjectionPlan,\n  issues: readonly ContextCheckIssue[],\n) {\n  const issuePaths = new Set(\n    issues\n      .filter((issue) => issue.kind === \"missing\" || issue.kind === \"stale\")\n      .map((issue) => join(plan.paths.repositoryRoot, issue.path)),\n  );\n  await Promise.all(\n    [...issuePaths].map((path) =>\n      assertWritableTarget(path, relativePath(plan.paths.repositoryRoot, path)),\n    ),\n  );\n  return issuePaths;\n}\n\nasync function writeFiles(\n  files: ReadonlyMap<string, RenderedFile>,\n  writePaths: ReadonlySet<string>,\n  repositoryRoot: string,\n  written: string[],\n) {\n  for (const [path, file] of [...files.entries()].sort(([left], [right]) =>\n    left < right ? -1 : left > right ? 1 : 0,\n  )) {\n    if (!writePaths.has(path)) continue;\n    await atomicWrite(\n      path,\n      file.content,\n      relativePath(repositoryRoot, path),\n      file.mode,\n    );\n    written.push(relativePath(repositoryRoot, path));\n  }\n}\n\nexport async function checkContext(\n  options: CheckContextOptions,\n): Promise<ContextCheckResult> {\n  return comparePlan(await buildProjectionPlan(options));\n}\n\nexport async function syncContext(\n  options: SyncContextOptions,\n): Promise<ContextSyncResult> {\n  const plan = await buildProjectionPlan(options);\n  const before = await comparePlan(plan);\n  const writePaths = await preflightWrites(plan, before.issues);\n  const written: string[] = [];\n  const removed: string[] = [];\n\n  await writeFiles(\n    plan.rootFiles,\n    writePaths,\n    plan.paths.repositoryRoot,\n    written,\n  );\n  await reconcileSkills(\n    plan.paths.rootOutputs.skills,\n    plan.rootSkills,\n    plan.paths.repositoryRoot,\n    written,\n    removed,\n    writePaths,\n  );\n  for (const prototype of plan.prototypes) {\n    await writeFiles(\n      prototype.files,\n      writePaths,\n      plan.paths.repositoryRoot,\n      written,\n    );\n  }\n\n  for (const issue of before.issues) {\n    if (issue.kind !== \"unexpected\") continue;\n    const path = join(plan.paths.repositoryRoot, issue.path);\n    if (await removeManagedFile(path, issue.path)) removed.push(issue.path);\n  }\n\n  const after = await checkContext(options);\n  return { ...after, written, removed };\n}\n"]}