stackfit 0.0.0-stage → 0.1.0

package/src/render.mjs

@@ -0,0 +1,93 @@
+// Text transforms between the catalog format and each agent's expected files.
+
+// Minimal YAML frontmatter editing for top-level scalar keys; enough for upstream overrides.
+export function setFrontmatter(content, fields) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  const lines = match ? match[1].split(/\r?\n/) : [];
+  const body = match ? content.slice(match[0].length) : content;
+  const isKey = (line) => /^[A-Za-z][\w-]*:/.test(line);
+  for (const [key, value] of Object.entries(fields)) {
+    const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+    let end = start + 1;
+    if (start !== -1) while (end < lines.length && !isKey(lines[end])) end += 1;
+    const rendered = value === null ? [] : [`${key}: ${typeof value === "string" ? JSON.stringify(value) : value}`];
+    if (start === -1) lines.push(...rendered);
+    else lines.splice(start, end - start, ...rendered);
+  }
+  return `---\n${lines.join("\n")}\n---\n${body}`;
+}
+
+// Reads top-level keys, joining folded/literal block scalars (`description: >-`).
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { fields: {}, body: content };
+  const fields = {};
+  let current = null;
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (field) {
+      current = field[1];
+      fields[current] = field[2].trim().replace(/^['"]|['"]$/g, "");
+    } else if (current && /^\s+\S/.test(line)) {
+      fields[current] = `${fields[current].replace(/^[>|]-?$/, "")} ${line.trim()}`.trim();
+    }
+  }
+  return { fields, body: content.slice(match[0].length).replace(/^\r?\n/, "") };
+}
+
+// Split a Cursor `globs` value on commas that are not inside `{...}`.
+export function splitGlobs(value) {
+  const globs = [];
+  let depth = 0;
+  let current = "";
+  for (const char of value) {
+    if (char === "{") depth += 1;
+    if (char === "}") depth -= 1;
+    if (char === "," && depth === 0) {
+      globs.push(current);
+      current = "";
+    } else current += char;
+  }
+  globs.push(current);
+  return globs.map((glob) => glob.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+}
+
+// Cursor .mdc → Claude Code .claude/rules/*.md. Always-apply rules load every session;
+// glob rules become `paths:`; description-only rules stay routed through AGENTS.md.
+export function claudeRule(content) {
+  const { fields, body } = parseFrontmatter(content);
+  if (fields.alwaysApply === "true") return body;
+  if (fields.globs) {
+    const paths = splitGlobs(fields.globs).map((glob) => `  - ${JSON.stringify(glob)}`).join("\n");
+    return `---\npaths:\n${paths}\n---\n\n${body}`;
+  }
+  return null;
+}
+
+export function cursorRule(content, name) {
+  if (content.startsWith("---\n")) return content;
+  return `---\ndescription: Repository-specific ${name} guidance; read when relevant\nalwaysApply: false\n---\n\n${content}`;
+}
+
+// Claude Code treats commands as skills; keep side-effecting workflows manual-only.
+export function claudeCommand(content) {
+  if (/^---\r?\n/.test(content)) return content;
+  const summary = content.split(/\r?\n/).map((line) => line.trim()).find((line) => line && !line.startsWith("#")) ?? "";
+  return `---\ndescription: ${JSON.stringify(summary.slice(0, 200))}\ndisable-model-invocation: true\n---\n\n${content}`;
+}
+
+export function claudeAgent(content) {
+  return content.replace(/^model:\s*.+$/m, "model: inherit").replace(/^readonly:\s*true$/m, "permissionMode: plan");
+}
+
+// Effective skill metadata = SKILL.md frontmatter + render overrides from skill-sources.json.
+export function effectiveMetadata(skillContent, overrides = {}) {
+  const { fields } = parseFrontmatter(skillContent);
+  return { ...fields, ...Object.fromEntries(Object.entries(overrides).map(([key, value]) => [key, String(value)])) };
+}
+
+// Characters of a skill that sit in every session: its name + description, unless manual-only.
+export function listingCost(metadata, name) {
+  if (!metadata || metadata["disable-model-invocation"] === "true") return 0;
+  return (metadata.description?.length ?? 0) + name.length;
+}

package/src/report.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { loadSources } from "./catalog.mjs";
+import { resolveSelection } from "./detect.mjs";
+import { effectiveMetadata, listingCost } from "./render.mjs";
+import { loadProjectConfig } from "./sync.mjs";
+
+// Rough rule of thumb for English prose in current tokenizers.
+export const charsToTokens = (chars) => Math.round(chars / 4);
+
+export function skillCosts(catalog, registry) {
+  const sources = loadSources(catalog).skills;
+  const costs = new Map();
+  for (const name of registry.skills) {
+    const path = resolve(catalog.skills, name, "SKILL.md");
+    const metadata = existsSync(path) ? effectiveMetadata(readFileSync(path, "utf8"), sources[name]?.render?.frontmatter) : null;
+    costs.set(name, listingCost(metadata, name));
+  }
+  return costs;
+}
+
+export function projectReport(catalog, registry, project, costs) {
+  const { projectConfig } = loadProjectConfig(project.path, registry, project.scaffold);
+  const selection = resolveSelection(project.path, registry, projectConfig, project.selection);
+  const sum = (names) => names.reduce((total, name) => total + (costs.get(name) ?? 0), 0);
+  const everything = sum(registry.skills);
+  const selected = sum(selection.skills);
+  return {
+    project: basename(project.path),
+    packs: selection.packs,
+    skills: selection.skills.length,
+    catalogSkills: registry.skills.length,
+    tokens: charsToTokens(selected),
+    tokensIfEverything: charsToTokens(everything),
+    saved: everything ? Math.round((1 - selected / everything) * 100) : 0,
+  };
+}
+
+const formatTokens = (tokens) => (tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens));
+
+export function printReport(rows) {
+  const width = Math.max(7, ...rows.map((row) => row.project.length));
+  console.log(`${"project".padEnd(width)}  skills  always-loaded  vs. everything  packs`);
+  for (const row of rows) {
+    console.log(
+      `${row.project.padEnd(width)}  ${`${row.skills}/${row.catalogSkills}`.padStart(6)}  `
+      + `${`~${formatTokens(row.tokens)} tok`.padStart(13)}  ${`-${row.saved}%`.padStart(14)}  ${row.packs.join(", ")}`,
+    );
+  }
+  if (rows.length > 1) {
+    const tokens = rows.reduce((total, row) => total + row.tokens, 0);
+    const everything = rows.reduce((total, row) => total + row.tokensIfEverything, 0);
+    console.log(`\n${rows.length} projects load ~${formatTokens(tokens)} tokens of skill listings in total, `
+      + `instead of ~${formatTokens(everything)} if every skill went everywhere (-${Math.round((1 - tokens / everything) * 100)}%).`);
+  }
+  console.log("Counts the skill names and descriptions every session loads; bodies load only when a skill is used. Manual-only skills cost 0.");
+}

package/src/scaffold.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expandHome } from "./catalog.mjs";
+
+const STARTER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../starter");
+
+async function writeMissing(root, files, { dryRun }) {
+  const created = [];
+  for (const [key, content] of Object.entries(files)) {
+    const destination = resolve(root, key);
+    if (existsSync(destination)) continue;
+    created.push(key);
+    if (dryRun) continue;
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, content);
+  }
+  return created;
+}
+
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+// Tracked per-project context. Never overwrites.
+export async function initProject(projectPath, options) {
+  if (options.scaffold === false) {
+    console.log(`${basename(projectPath)}: skipped scaffold (adapter-only project)`);
+    return 0;
+  }
+  const created = await writeMissing(projectPath, {
+    "AGENTS.md": "# Repository agent instructions\n\nRead `docs/agent/index.md` first, then load only the pages and repo-owned components relevant to the task. Repository instructions take precedence over shared defaults when they conflict.\n",
+    "CLAUDE.md": "@AGENTS.md\n",
+    "docs/agent/config.json": json({ schemaVersion: 1, packs: [], excludePacks: [], skills: [], overrides: { skills: [], agents: [], commands: [], rules: [] } }),
+    "docs/agent/index.md": "# Agent context\n\nRead only the page relevant to the task:\n\n- `architecture.md`: structure, boundaries, and generated code\n- `design-system.md`: UI primitives, tokens, and visual conventions\n- `workflows.md`: package manager, checks, Git, PR, and release policy\n- `rules/*.md`: additional repository constraints, when relevant\n\nRepository-owned components live under `docs/agent/` (`skills/<name>/SKILL.md`, `commands/*.md`, `agents/*.md`, `rules/*.md`). Run `stackfit sync` to render them for each agent.\n",
+    "docs/agent/architecture.md": "# Architecture\n\nDocument stable repository boundaries and where new code belongs. Link existing detailed docs instead of duplicating them.\n",
+    "docs/agent/design-system.md": "# Design system\n\nDocument the canonical UI primitives, tokens, typography, and accessibility conventions. Remove this page for repositories without a UI.\n",
+    "docs/agent/workflows.md": "# Workflows\n\nDocument the package manager, validation commands, generated files, branch/PR policy, and release automation.\n",
+  }, options);
+  console.log(`${basename(projectPath)}: ${created.length ? `${created.length} tracked docs file(s)` : "already initialized"}`);
+  if (!options.quiet) for (const key of created) console.log(`  create ${key}`);
+  return created.length;
+}
+
+async function listFiles(root) {
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else files.push(path);
+    }
+  }
+  await walk(root);
+  return files;
+}
+
+// A catalog is a plain folder you keep in your own (usually private) Git repository.
+export async function initCatalog(target, options) {
+  const root = expandHome(target ?? "~/.stackfit");
+  const created = [];
+  if (options.starter) {
+    for (const source of await listFiles(STARTER_ROOT)) {
+      const key = relative(STARTER_ROOT, source);
+      const destination = resolve(root, key === "gitignore" ? ".gitignore" : key);
+      if (existsSync(destination)) continue;
+      created.push(relative(root, destination));
+      if (options.dryRun) continue;
+      await mkdir(dirname(destination), { recursive: true });
+      await cp(source, destination);
+    }
+  } else {
+    created.push(...await writeMissing(root, {
+      "stackfit.json": json({ $schema: "https://unpkg.com/stackfit/schemas/stackfit.schema.json", schemaVersion: 3, skills: [], packs: { core: { description: "Every repository.", always: true, skills: [] } }, adapters: { agents: [], commands: [], rules: [] } }),
+      "skill-sources.json": json({ schemaVersion: 2, skills: {} }),
+      "stackfit.local.example.json": json({ schemaVersion: 1, machines: [{ id: "laptop", match: { platform: "darwin" }, roots: ["~/code"] }] }),
+      ".env.example": "# Copy to .env (gitignored). Values here fill {{env:NAME}} placeholders in commands, rules, and agents.\n# STACKFIT_CATALOG=~/path/to/this/catalog\n# GITHUB_TOKEN=\n",
+      ".gitignore": "stackfit.local.json\n.env\nskills/.*.refresh/\n.DS_Store\n",
+      "skills/.gitkeep": "",
+    }, options));
+  }
+  console.log(`${options.dryRun ? "Would create" : "Created"} catalog at ${root} (${created.length} file(s)).`);
+  if (!options.quiet) for (const key of created) console.log(`  create ${key}`);
+  console.log(options.starter
+    ? "\nNext:\n  stackfit refresh --all      # vendor the starter's upstream skills\n  stackfit audit\n  stackfit report --root ~/code\n  stackfit sync --root ~/code"
+    : "\nNext: add skills under skills/<name>/SKILL.md, list them in stackfit.json and a pack, then `stackfit sync --project <repo>`.");
+  if (!root.endsWith(".stackfit")) console.log(`\nPoint stackfit at it with --catalog ${target}, STACKFIT_CATALOG, or run commands from inside the folder.`);
+  return created.length;
+}

package/src/sync.mjs

@@ -0,0 +1,279 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { basename, dirname, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { expandEnv, loadJson, loadSources } from "./catalog.mjs";
+import { resolveSelection } from "./detect.mjs";
+import { claudeAgent, claudeCommand, claudeRule, cursorRule, setFrontmatter } from "./render.mjs";
+
+export const LOCK_NAME = ".stackfit.lock.json";
+// Older names of the lock, from before the tool was called stackfit; read once, then replaced.
+const LEGACY_LOCK_NAMES = [".skillfit.lock.json", ".agent-config.lock.json"];
+const LOCAL_EXCLUDES = [LOCK_NAME, ".agents/", ".cursor/", ".claude/"];
+const LOCAL_SCAFFOLD_EXCLUDES = ["CLAUDE.md", "docs/agent/"];
+
+export function lstatMaybe(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+export const toPosixPath = (path) => path.replaceAll("\\", "/");
+const projectKey = (projectPath, destination) => toPosixPath(relative(projectPath, destination));
+const normalizeEntries = (entries = {}) => Object.fromEntries(Object.entries(entries).map(([key, value]) => [toPosixPath(key), value]));
+
+function loadLock(projectPath) {
+  const found = [LOCK_NAME, ...LEGACY_LOCK_NAMES].map((name) => resolve(projectPath, name)).find((path) => existsSync(path));
+  const previous = loadJson(found, { files: {}, links: {} }) ?? { files: {}, links: {} };
+  return { ...previous, files: normalizeEntries(previous.files), links: normalizeEntries(previous.links) };
+}
+
+export function git(args, cwd, stdio = "pipe") {
+  return spawnSync("git", args, { cwd, encoding: "utf8", stdio });
+}
+
+function currentRevision(cwd) {
+  const result = git(["rev-parse", "HEAD"], cwd);
+  return result.status === 0 ? result.stdout.trim() : "unknown";
+}
+
+async function walkFiles(root) {
+  if (!existsSync(root)) return [];
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile()) files.push(path);
+    }
+  }
+  await walk(root);
+  return files.sort();
+}
+
+function addFile(plan, source, destination, transform = undefined) {
+  if (!existsSync(source)) throw new Error(`Configured source does not exist: ${source}`);
+  const raw = readFileSync(source);
+  const content = transform ? Buffer.from(transform(raw.toString("utf8"))) : raw;
+  plan.set(destination, { source, content, hash: sha256(content) });
+}
+
+async function addTree(plan, sourceRoot, destinationRoot, render = {}) {
+  const exclude = new Set(render.exclude ?? []);
+  for (const source of await walkFiles(sourceRoot)) {
+    const file = toPosixPath(relative(sourceRoot, source));
+    if (exclude.has(file) || basename(file) === ".DS_Store") continue;
+    const transform = file === "SKILL.md" && render.frontmatter ? (content) => setFrontmatter(content, render.frontmatter) : undefined;
+    addFile(plan, source, resolve(destinationRoot, file), transform);
+  }
+}
+
+const componentName = (file) => file.replace(/\.(md|mdc)$/, "");
+
+function assertLocalComponentAllowed(projectName, projectConfig, kind, name, sharedNames) {
+  if (!sharedNames.has(name)) return;
+  if (new Set(projectConfig.overrides?.[kind] ?? []).has(name)) return;
+  throw new Error(
+    `${projectName}: repo-owned ${kind.slice(0, -1)} '${name}' conflicts with shared ${kind}; `
+    + `rename it or add '${name}' to overrides.${kind} in docs/agent/config.json`,
+  );
+}
+
+function addCommand(plan, projectPath, source, file) {
+  const fill = (content) => expandEnv(content, `commands/${file}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/commands", file), fill);
+  addFile(plan, source, resolve(projectPath, ".claude/commands", file), (content) => claudeCommand(fill(content)));
+}
+
+function addRule(plan, projectPath, source, name, cursorTransform = (content) => content) {
+  const cursorContent = expandEnv(cursorTransform(readFileSync(source, "utf8")), `rules/${name}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/rules", `${name}.mdc`), () => cursorContent);
+  const claudeContent = claudeRule(cursorContent);
+  if (claudeContent !== null) addFile(plan, source, resolve(projectPath, ".claude/rules", `${name}.md`), () => claudeContent);
+}
+
+function addAgent(plan, projectPath, source, file) {
+  const fill = (content) => expandEnv(content, `agents/${file}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/agents", file), fill);
+  addFile(plan, source, resolve(projectPath, ".claude/agents", file), (content) => claudeAgent(fill(content)));
+}
+
+export function loadProjectConfig(projectPath, registry, scaffold) {
+  const configPath = resolve(projectPath, registry.projectConfigPath);
+  const projectConfig = scaffold ? loadJson(configPath, { schemaVersion: 1 }) : { schemaVersion: 1 };
+  if (projectConfig.schemaVersion !== 1) throw new Error(`${basename(projectPath)}: unsupported ${registry.projectConfigPath} schema`);
+  return { projectConfig, configPath };
+}
+
+export async function createPlan(catalog, projectPath, registry, { scaffold = true, selection: localSelection = {} } = {}) {
+  const projectName = basename(projectPath);
+  const { projectConfig, configPath } = loadProjectConfig(projectPath, registry, scaffold);
+  const selection = resolveSelection(projectPath, registry, projectConfig, localSelection);
+  const renderOptions = loadSources(catalog).skills;
+  const sharedSkills = new Set(selection.skills);
+  const sharedAgents = new Set(registry.adapters.agents.map(componentName));
+  const sharedCommands = new Set(registry.adapters.commands.map(componentName));
+  const sharedRules = new Set(registry.adapters.rules.map(componentName));
+  const plan = new Map();
+  const links = new Map([
+    [resolve(projectPath, ".claude/skills"), "../.agents/skills"],
+    [resolve(projectPath, ".cursor/skills"), "../.agents/skills"],
+  ]);
+
+  for (const skill of selection.skills) {
+    const source = resolve(catalog.skills, skill);
+    if (!existsSync(resolve(source, "SKILL.md"))) {
+      throw new Error(`Skill '${skill}' is enabled but not in the catalog. Run \`stackfit refresh --skill ${skill}\` or add skills/${skill}/SKILL.md.`);
+    }
+    await addTree(plan, source, resolve(projectPath, ".agents/skills", skill), renderOptions[skill]?.render);
+  }
+  for (const file of registry.adapters.agents) addAgent(plan, projectPath, resolve(catalog.agents, file), file);
+  for (const file of registry.adapters.commands) addCommand(plan, projectPath, resolve(catalog.commands, file), file);
+  for (const file of registry.adapters.rules) addRule(plan, projectPath, resolve(catalog.rules, file), componentName(file));
+
+  if (scaffold) {
+    const localSkills = resolve(projectPath, "docs/agent/skills");
+    if (existsSync(localSkills)) {
+      for (const entry of await readdir(localSkills, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const source = resolve(localSkills, entry.name);
+        if (!existsSync(resolve(source, "SKILL.md"))) throw new Error(`${projectName}: docs/agent/skills/${entry.name} lacks SKILL.md`);
+        assertLocalComponentAllowed(projectName, projectConfig, "skills", entry.name, sharedSkills);
+        await addTree(plan, source, resolve(projectPath, ".agents/skills", entry.name));
+      }
+    }
+    const localKinds = [
+      ["agents", "docs/agent/agents", sharedAgents, (source, file) => addAgent(plan, projectPath, source, file)],
+      ["commands", "docs/agent/commands", sharedCommands, (source, file) => addCommand(plan, projectPath, source, file)],
+      ["rules", "docs/agent/rules", sharedRules, (source, file) => {
+        const name = componentName(file);
+        addRule(plan, projectPath, source, name, (content) => cursorRule(content, name));
+      }],
+    ];
+    for (const [kind, folder, shared, add] of localKinds) {
+      const root = resolve(projectPath, folder);
+      for (const source of await walkFiles(root)) {
+        if (!source.endsWith(".md")) continue;
+        const file = relative(root, source);
+        assertLocalComponentAllowed(projectName, projectConfig, kind, componentName(file), shared);
+        add(source, file);
+      }
+    }
+  }
+
+  return { plan, links, projectName, scaffold, packs: selection.packs, skills: selection.skills, configPath: scaffold ? relative(projectPath, configPath) : null };
+}
+
+async function ensureLocalGitExclude(projectPath, { scaffold = true } = {}) {
+  const gitPath = git(["rev-parse", "--git-path", "info/exclude"], projectPath);
+  const excludePath = gitPath.status === 0 ? resolve(projectPath, gitPath.stdout.trim()) : resolve(projectPath, ".git/info/exclude");
+  const existing = existsSync(excludePath) ? await readFile(excludePath, "utf8") : "";
+  const lines = new Set(existing.split(/\r?\n/));
+  const wanted = scaffold ? LOCAL_EXCLUDES : [...LOCAL_EXCLUDES, ...LOCAL_SCAFFOLD_EXCLUDES];
+  const additions = wanted.filter((entry) => !lines.has(entry));
+  if (!additions.length) return;
+  await mkdir(dirname(excludePath), { recursive: true });
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+  await writeFile(excludePath, `${existing}${prefix}# Managed locally by stackfit\n${additions.join("\n")}\n`);
+}
+
+// After removing a dropped skill's files, remove its now-empty folders (never the project root).
+async function pruneEmptyParents(projectPath, directory) {
+  let current = directory;
+  while (current.startsWith(`${projectPath}${sep}`) && !lstatMaybe(current)?.isSymbolicLink()) {
+    let entries;
+    try {
+      entries = await readdir(current);
+    } catch {
+      return;
+    }
+    if (entries.length) return;
+    await rm(current, { recursive: true, force: true });
+    current = dirname(current);
+  }
+}
+
+// Windows junctions need no admin rights or developer mode; they store absolute targets.
+const LINK_TYPE = platform() === "win32" ? "junction" : "dir";
+const sameLinkTarget = (linkPath, target) => resolve(dirname(linkPath), readlinkSync(linkPath)) === resolve(dirname(linkPath), target);
+
+export async function applyPlan(catalog, projectPath, planData, options) {
+  const previous = loadLock(projectPath);
+  const nextFiles = {};
+  const nextLinks = {};
+  const actions = [];
+  // Managed symlinks this plan no longer wants. Files "found" through them are not
+  // real collisions: the link is deleted before writes.
+  const retiredLinks = Object.keys(previous.links ?? {})
+    .map((key) => resolve(projectPath, key))
+    .filter((linkPath) => !planData.links.has(linkPath) && lstatMaybe(linkPath)?.isSymbolicLink());
+  const throughRetiredLink = (destination) => retiredLinks.some((linkPath) => destination.startsWith(`${linkPath}${sep}`));
+
+  for (const [destination, item] of planData.plan) {
+    const key = projectKey(projectPath, destination);
+    nextFiles[key] = item.hash;
+    const existing = existsSync(destination) && !throughRetiredLink(destination) ? await readFile(destination) : null;
+    if (existing && sha256(existing) === item.hash) continue;
+    if (existing && !previous.files[key] && !options.force) {
+      throw new Error(`${planData.projectName}: unmanaged collision at ${key}; review it, then rerun with --force`);
+    }
+    actions.push({ type: existing ? "update" : "create", key, destination, item });
+  }
+  for (const key of Object.keys(previous.files)) {
+    if (nextFiles[key]) continue;
+    const destination = resolve(projectPath, key);
+    const underLink = [...planData.links.keys()].find((linkPath) => destination.startsWith(`${linkPath}${sep}`) && lstatMaybe(linkPath)?.isSymbolicLink());
+    if (!underLink && lstatMaybe(destination)) actions.push({ type: "delete", key, destination });
+  }
+  for (const [destination, target] of planData.links) {
+    const key = projectKey(projectPath, destination);
+    nextLinks[key] = target;
+    const stat = lstatMaybe(destination);
+    if (stat?.isSymbolicLink() && sameLinkTarget(destination, target)) continue;
+    if (stat?.isDirectory()) {
+      const unmanaged = (await walkFiles(destination)).map((path) => projectKey(projectPath, path)).filter((path) => !previous.files[path]);
+      if (unmanaged.length && !options.force) throw new Error(`${planData.projectName}: unmanaged collision under ${key}: ${unmanaged[0]}`);
+    } else if (stat && !previous.links?.[key] && !options.force) {
+      throw new Error(`${planData.projectName}: unmanaged collision at ${key}; review it, then rerun with --force`);
+    }
+    actions.push({ type: stat ? "link" : "create-link", key, destination, target });
+  }
+  for (const key of Object.keys(previous.links ?? {})) {
+    if (!nextLinks[key] && lstatMaybe(resolve(projectPath, key))) actions.push({ type: "delete", key, destination: resolve(projectPath, key) });
+  }
+
+  if (!options.dryRun) {
+    await ensureLocalGitExclude(projectPath, { scaffold: planData.scaffold !== false });
+    for (const action of actions.filter((item) => item.type === "delete")) {
+      await rm(action.destination, { recursive: true, force: true });
+      await pruneEmptyParents(projectPath, dirname(action.destination));
+    }
+    for (const action of actions.filter((item) => ["create", "update"].includes(item.type))) {
+      await mkdir(dirname(action.destination), { recursive: true });
+      await writeFile(action.destination, action.item.content);
+    }
+    for (const action of actions.filter((item) => ["link", "create-link"].includes(item.type))) {
+      await rm(action.destination, { recursive: true, force: true });
+      await mkdir(dirname(action.destination), { recursive: true });
+      await symlink(action.target, action.destination, LINK_TYPE);
+    }
+    await writeFile(resolve(projectPath, LOCK_NAME), `${JSON.stringify({
+      schemaVersion: 3,
+      sourceRevision: currentRevision(catalog.root),
+      projectConfig: planData.configPath,
+      scaffold: planData.scaffold !== false,
+      packs: planData.packs,
+      generatedAt: new Date().toISOString(),
+      files: nextFiles,
+      links: nextLinks,
+    }, null, 2)}\n`);
+    for (const name of LEGACY_LOCK_NAMES) await rm(resolve(projectPath, name), { force: true });
+  }
+  return actions;
+}

package/starter/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env next to stackfit.json (it is gitignored). Never commit real values.
+
+# Optional: where this catalog lives, so stackfit works from any folder.
+# STACKFIT_CATALOG=~/code/my-skill-catalog
+
+# Optional: lets `stackfit refresh` read private GitHub repositories.
+# GITHUB_TOKEN=
+
+# Any NAME here can be used as {{env:NAME}} in commands/, rules/, and agents/, e.g.
+# REVIEWER_HANDLE=@your-handle

package/starter/README.md

@@ -0,0 +1,12 @@
+# My stackfit catalog
+
+Started from the stackfit starter. This folder is yours: keep it in a (private) Git repository.
+
+- `stackfit.json`: enabled skills and packs (which skills reach which repos).
+- `skill-sources.json`: where each vendored skill comes from, when you last reviewed it, and sync-time overrides.
+- `skills/`: the skills themselves. `stackfit refresh --all` vendors the upstream ones.
+- `rules/`, `commands/`, `agents/`: shared adapters rendered for Cursor and Claude Code.
+- `stackfit.local.json` (gitignored): where your projects live on each machine. Copy the example.
+- `.env` (gitignored): personal values for `{{env:NAME}}` placeholders. Copy `.env.example`.
+
+Add your own skills under `skills/<name>/SKILL.md`, list them in `stackfit.json` and a pack, set `kind: custom` in `skill-sources.json`, then `stackfit audit`.

package/starter/gitignore

@@ -0,0 +1,4 @@
+stackfit.local.json
+.env
+skills/.*.refresh/
+.DS_Store

package/starter/rules/defaults.mdc

@@ -0,0 +1,11 @@
+---
+description: Starter defaults for any repository (edit or replace with your own)
+alwaysApply: true
+---
+
+# Defaults
+
+- Follow the repository's own instructions (`AGENTS.md`, `CLAUDE.md`, contributing docs) over these.
+- Match existing conventions, package manager, and scripts before introducing new ones.
+- Keep changes focused on the request and say which checks you ran.
+- Ask before running anything that changes external systems.