skillrepo 1.6.2 → 1.7.1

package/src/hooks/skillrepo-sync.mjs

@@ -0,0 +1,769 @@
+#!/usr/bin/env node
+/**
+ * SkillRepo SessionStart hook — syncs skill library to local files and writes
+ * deterministic .claude/rules/ files for skill delivery.
+ *
+ * Standalone script: no npm dependencies, Node.js built-ins only.
+ * Installed by `npx skillrepo init` to `.claude/hooks/skillrepo-sync.mjs`.
+ *
+ * Part of #531 (Re-architect skill delivery, Phase B).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SYNC_TIMEOUT_MS = 10_000;
+const DEFAULT_SERVER_URL = "https://skillrepo.dev";
+// Default: no cap — governance requires parity with manually created rules files.
+// Users can override via config.json: { "maxRulesFiles": 10, "maxRulesBudgetBytes": 512000 }
+const DEFAULT_MAX_RULES_FILES = Infinity;
+const DEFAULT_MAX_RULES_BUDGET_BYTES = Infinity;
+const RULES_FILE_PREFIX = "skillrepo-";
+
+// ---------------------------------------------------------------------------
+// Path safety — prevent traversal from server-controlled strings
+// ---------------------------------------------------------------------------
+
+/** Validate a path segment (owner, name) is safe for use in file paths. */
+export function isSafeSegment(segment) {
+  if (!segment || typeof segment !== "string") return false;
+  if (segment.includes("..")) return false;
+  if (segment.includes("/") || segment.includes("\\")) return false;
+  if (segment.startsWith(".")) return false;
+  // agentskills.io spec: lowercase alphanumeric + hyphens,
+  // no leading/trailing/consecutive hyphens
+  return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(segment);
+}
+
+/** Validate a file path from the server is contained within a base directory. */
+export function isSafeFilePath(baseDir, filePath) {
+  const resolved = resolve(baseDir, filePath);
+  return resolved.startsWith(resolve(baseDir) + "/") || resolved === resolve(baseDir);
+}
+
+// ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Read config from ~/.claude/skillrepo/config.json with fallbacks.
+ * Returns null if no config/key can be found.
+ */
+export function readConfig() {
+  const configPath = join(homedir(), ".claude", "skillrepo", "config.json");
+
+  // Primary: global config file (written by `npx skillrepo init`, #535)
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    if (cfg.apiKey) {
+      return {
+        apiKey: cfg.apiKey,
+        serverUrl: cfg.serverUrl || DEFAULT_SERVER_URL,
+        maxRulesFiles: cfg.maxRulesFiles ?? DEFAULT_MAX_RULES_FILES,
+        maxRulesBudgetBytes: cfg.maxRulesBudgetBytes ?? DEFAULT_MAX_RULES_BUDGET_BYTES,
+      };
+    }
+  } catch { /* config not found or invalid — try fallbacks */ }
+
+  // Fallback: environment variable
+  const envKey = process.env.SKILLREPO_ACCESS_KEY;
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      serverUrl: process.env.SKILLREPO_SERVER_URL || DEFAULT_SERVER_URL,
+      maxRulesFiles: DEFAULT_MAX_RULES_FILES,
+      maxRulesBudgetBytes: DEFAULT_MAX_RULES_BUDGET_BYTES,
+    };
+  }
+
+  // Fallback: .env.local in project root
+  const projectKey = readEnvFileKey(process.cwd());
+  if (projectKey) {
+    return {
+      apiKey: projectKey,
+      serverUrl: DEFAULT_SERVER_URL,
+      maxRulesFiles: DEFAULT_MAX_RULES_FILES,
+      maxRulesBudgetBytes: DEFAULT_MAX_RULES_BUDGET_BYTES,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Read SKILLREPO_ACCESS_KEY from .env.local or .env in a directory.
+ */
+export function readEnvFileKey(dir) {
+  for (const file of [".env.local", ".env"]) {
+    try {
+      const lines = readFileSync(join(dir, file), "utf-8").split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        const key = trimmed.slice(0, eqIdx).trim();
+        if (key === "SKILLREPO_ACCESS_KEY") {
+          let val = trimmed.slice(eqIdx + 1).trim();
+          if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+          }
+          val = val.replace(/\s+#.*$/, "");
+          if (val) return val;
+        }
+      }
+    } catch { /* file doesn't exist */ }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Sync API
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch library data from the sync endpoint.
+ * Returns the parsed response or null on failure.
+ */
+export async function fetchSync(config, lastSync) {
+  const url = new URL("/api/v1/sync/library", config.serverUrl);
+  if (lastSync) url.searchParams.set("since", lastSync);
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), SYNC_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        Accept: "application/json",
+      },
+      signal: controller.signal,
+    });
+
+    if (res.status === 304) return { notModified: true };
+    if (!res.ok) {
+      process.stderr.write(`[skillrepo] Sync API returned ${res.status}\n`);
+      return null;
+    }
+
+    try {
+      return await res.json();
+    } catch {
+      process.stderr.write("[skillrepo] Sync API returned non-JSON response\n");
+      return null;
+    }
+  } catch (err) {
+    const msg = err?.name === "AbortError" ? "timed out" : err?.message ?? "unknown error";
+    process.stderr.write(`[skillrepo] Sync failed: ${msg}\n`);
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File operations (atomic writes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically write a file: write to a temp file then rename.
+ * Prevents race conditions between concurrent sessions.
+ */
+export function atomicWrite(filePath, content, encoding = "utf-8") {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const tmpName = `.tmp-${randomBytes(8).toString("hex")}`;
+  const tmpPath = join(dir, tmpName);
+
+  if (encoding === "base64") {
+    writeFileSync(tmpPath, Buffer.from(content, "base64"));
+  } else {
+    writeFileSync(tmpPath, content, "utf-8");
+  }
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Recursively remove a directory if it exists.
+ */
+function removeDir(dirPath) {
+  try {
+    rmSync(dirPath, { recursive: true, force: true });
+  } catch { /* ignore */ }
+}
+
+/**
+ * Remove a single file if it exists.
+ */
+function removeFile(filePath) {
+  try {
+    rmSync(filePath, { force: true });
+  } catch { /* ignore */ }
+}
+
+// ---------------------------------------------------------------------------
+// Skill file writing
+// ---------------------------------------------------------------------------
+
+/**
+ * Write synced skill files to the local cache.
+ * Returns the set of file paths that should exist for each skill (manifest).
+ */
+export function writeSkillFiles(skills, skillsDir) {
+  const manifests = new Map(); // owner/name → Set of relative paths
+
+  for (const skill of skills) {
+    if (!isSafeSegment(skill.owner) || !isSafeSegment(skill.name)) continue;
+
+    const skillDir = join(skillsDir, skill.owner, skill.name);
+    const currentPaths = new Set();
+
+    for (const file of skill.files ?? []) {
+      if (!isSafeFilePath(skillDir, file.path)) continue; // skip traversal attempts
+      const filePath = join(skillDir, file.path);
+      const encoding = file.encoding === "base64" ? "base64" : "utf-8";
+      atomicWrite(filePath, file.content, encoding);
+      currentPaths.add(file.path);
+    }
+
+    manifests.set(`${skill.owner}/${skill.name}`, currentPaths);
+  }
+
+  return manifests;
+}
+
+/**
+ * Manifest-diff cleanup: remove files that existed in a previous version
+ * but are absent in the current version.
+ */
+export function cleanupStaleSkillFiles(manifests, skillsDir) {
+  for (const [key, expectedPaths] of manifests) {
+    const [owner, name] = key.split("/");
+    const skillDir = join(skillsDir, owner, name);
+    if (!existsSync(skillDir)) continue;
+
+    // Walk the skill directory and remove files not in the manifest
+    walkDir(skillDir, (filePath) => {
+      const relativePath = filePath.slice(skillDir.length + 1).replace(/\\/g, "/");
+      if (!expectedPaths.has(relativePath)) {
+        removeFile(filePath);
+      }
+    });
+  }
+}
+
+/**
+ * Walk directory recursively, calling fn for each file (not directory).
+ */
+function walkDir(dir, fn) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(full, fn);
+    } else {
+      fn(full);
+    }
+  }
+}
+
+/**
+ * Process removals: delete cache directories and corresponding rules files.
+ */
+export function processRemovals(removals, skillsDir, projectDir) {
+  for (const removal of removals) {
+    if (!isSafeSegment(removal.owner) || !isSafeSegment(removal.name)) continue;
+    const cacheDir = join(skillsDir, removal.owner, removal.name);
+    removeDir(cacheDir);
+
+    // Also remove the owner dir if now empty
+    const ownerDir = join(skillsDir, removal.owner);
+    try {
+      const remaining = readdirSync(ownerDir);
+      if (remaining.length === 0) removeDir(ownerDir);
+    } catch { /* ignore */ }
+
+    // Remove corresponding rules files
+    const rulesName = `${RULES_FILE_PREFIX}${removal.owner}-${removal.name}`;
+    removeFile(join(projectDir, ".claude", "rules", `${rulesName}.md`));
+    removeFile(join(projectDir, ".cursor", "rules", `${rulesName}.mdc`));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Repo profiling
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect project tech stack by inspecting config files.
+ * Returns { frameworks, languages, tools }.
+ */
+export function buildRepoProfile(projectDir) {
+  const profile = { frameworks: [], languages: [], tools: [] };
+
+  // package.json dependencies
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf-8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps["next"]) profile.frameworks.push("next.js");
+    if (deps["react"] && !deps["next"]) profile.frameworks.push("react");
+    if (deps["vue"]) profile.frameworks.push("vue");
+    if (deps["angular"] || deps["@angular/core"]) profile.frameworks.push("angular");
+    if (deps["svelte"]) profile.frameworks.push("svelte");
+    if (deps["express"]) profile.frameworks.push("express");
+    if (deps["fastify"]) profile.frameworks.push("fastify");
+    if (deps["hono"]) profile.frameworks.push("hono");
+    if (deps["playwright"] || deps["@playwright/test"]) profile.tools.push("playwright");
+    if (deps["jest"]) profile.tools.push("jest");
+    if (deps["vitest"]) profile.tools.push("vitest");
+    if (deps["drizzle-orm"]) profile.tools.push("drizzle");
+    if (deps["prisma"] || deps["@prisma/client"]) profile.tools.push("prisma");
+    if (deps["tailwindcss"]) profile.tools.push("tailwindcss");
+  } catch { /* no package.json */ }
+
+  // Language detection
+  const langFiles = [
+    ["tsconfig.json", "typescript"],
+    ["pyproject.toml", "python"],
+    ["go.mod", "go"],
+    ["Cargo.toml", "rust"],
+    ["Gemfile", "ruby"],
+  ];
+  for (const [file, lang] of langFiles) {
+    try { readFileSync(join(projectDir, file)); profile.languages.push(lang); }
+    catch { /* not found */ }
+  }
+
+  return profile;
+}
+
+// ---------------------------------------------------------------------------
+// Profile-based scoring
+// ---------------------------------------------------------------------------
+
+/**
+ * Score a single skill's relevance to the repo profile.
+ * Returns a numeric score (higher = more relevant).
+ *
+ * Scoring:
+ * - Skills with matching contextSignals.project tags: base score 10 + 2 per match
+ * - Skills with no project tags: base score 5 (neutral, not penalized)
+ * - Skills with project tags that don't overlap: base score 1 (demoted)
+ */
+export function scoreSkillRelevance(skill, profile) {
+  const projectTags = skill.contextSignals?.project ?? [];
+  if (projectTags.length === 0) return 5; // Neutral — no tags means general-purpose
+
+  const profileTags = new Set([
+    ...profile.frameworks,
+    ...profile.languages,
+    ...profile.tools,
+  ].map(t => t.toLowerCase()));
+
+  if (profileTags.size === 0) return 5; // No profile detected — treat all as neutral
+
+  const matchCount = projectTags.filter(t => profileTags.has(t.toLowerCase())).length;
+  if (matchCount > 0) return 10 + (matchCount * 2);
+  return 1; // Tags exist but none match — demoted
+}
+
+/**
+ * Select top-N skills for rules delivery, enforcing budget constraints.
+ */
+export function selectRulesSkills(skills, profile, config) {
+  const maxFiles = config.maxRulesFiles ?? DEFAULT_MAX_RULES_FILES;
+  const maxBudget = config.maxRulesBudgetBytes ?? DEFAULT_MAX_RULES_BUDGET_BYTES;
+
+  // Score and sort
+  const scored = skills
+    .map(skill => ({ skill, score: scoreSkillRelevance(skill, profile) }))
+    .sort((a, b) => b.score - a.score);
+
+  // Select within budget
+  const selected = [];
+  let totalBytes = 0;
+
+  for (const { skill } of scored) {
+    if (selected.length >= maxFiles) break;
+
+    // Find SKILL.md content size
+    const skillMd = skill.files?.find(f => f.path === "SKILL.md");
+    if (!skillMd) continue;
+
+    const contentBytes = Buffer.byteLength(skillMd.content, "utf-8");
+    if (totalBytes + contentBytes > maxBudget) continue; // Skip if over budget
+
+    selected.push(skill);
+    totalBytes += contentBytes;
+  }
+
+  return selected;
+}
+
+// ---------------------------------------------------------------------------
+// Rules file writing
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the rules file naming key: skillrepo-{owner}-{name}
+ */
+export function rulesFileName(owner, name) {
+  return `${RULES_FILE_PREFIX}${owner}-${name}`;
+}
+
+/**
+ * Write selected skills as .claude/rules/ and .cursor/rules/ files.
+ * Returns the set of rules file base names that were written.
+ */
+export function writeRulesFiles(selectedSkills, projectDir) {
+  const written = new Set();
+
+  const claudeRulesDir = join(projectDir, ".claude", "rules");
+  const cursorRulesDir = join(projectDir, ".cursor", "rules");
+
+  for (const skill of selectedSkills) {
+    const skillMd = skill.files?.find(f => f.path === "SKILL.md");
+    if (!skillMd) continue;
+
+    const baseName = rulesFileName(skill.owner, skill.name);
+    written.add(baseName);
+
+    // Claude Code: .claude/rules/skillrepo-{owner}-{name}.md
+    atomicWrite(join(claudeRulesDir, `${baseName}.md`), skillMd.content);
+
+    // Cursor: .cursor/rules/skillrepo-{owner}-{name}.mdc
+    const mdcContent = buildCursorMdc(skill, skillMd.content);
+    atomicWrite(join(cursorRulesDir, `${baseName}.mdc`), mdcContent);
+  }
+
+  return written;
+}
+
+/**
+ * Build Cursor .mdc file content with frontmatter.
+ */
+function buildCursorMdc(skill, content) {
+  const cs = skill.contextSignals;
+  const desc = (skill.description || skill.name).replace(/"/g, '\\"').replace(/[\r\n]+/g, " ");
+
+  // If skill has file signals, use them as globs; otherwise alwaysApply
+  if (cs?.files?.length > 0) {
+    const globs = cs.files.join(", ");
+    return `---\ndescription: "${desc}"\nglobs: ${globs}\n---\n\n${content}`;
+  }
+
+  return `---\ndescription: "${desc}"\nalwaysApply: true\n---\n\n${content}`;
+}
+
+/**
+ * Remove stale .claude/rules/skillrepo-*.md and .cursor/rules/skillrepo-*.mdc
+ * files that are not in the current selection. Only touches skillrepo- prefixed files.
+ */
+export function cleanupStaleRules(currentSet, projectDir) {
+  const claudeRulesDir = join(projectDir, ".claude", "rules");
+  const cursorRulesDir = join(projectDir, ".cursor", "rules");
+
+  cleanupRulesDir(claudeRulesDir, ".md", currentSet);
+  cleanupRulesDir(cursorRulesDir, ".mdc", currentSet);
+}
+
+function cleanupRulesDir(dir, extension, currentSet) {
+  let entries;
+  try { entries = readdirSync(dir); }
+  catch { return; } // Directory doesn't exist — nothing to clean
+
+  for (const entry of entries) {
+    if (!entry.startsWith(RULES_FILE_PREFIX)) continue;
+    if (!entry.endsWith(extension)) continue;
+
+    const baseName = entry.slice(0, -extension.length);
+    if (!currentSet.has(baseName)) {
+      removeFile(join(dir, entry));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Local index builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the local skill index consumed by the UserPromptSubmit hook (#532).
+ */
+export function buildLocalIndex(skills, selectedRulesNames, syncedAt, skillsDir = null) {
+  if (!skillsDir) skillsDir = join(homedir(), ".claude", "skillrepo", "skills");
+
+  return {
+    version: 1,
+    syncedAt,
+    skills: skills.map(skill => ({
+      owner: skill.owner,
+      name: skill.name,
+      version: skill.version ?? null,
+      description: skill.description ?? "",
+      keywords: skill.keywords ?? [],
+      contextSignals: skill.contextSignals ?? null,
+      localPath: join(skillsDir, skill.owner, skill.name, "SKILL.md"),
+      isRulesDelivered: selectedRulesNames.has(rulesFileName(skill.owner, skill.name)),
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Delta merge — combine incremental sync with existing index
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge delta sync results with the existing local index.
+ * Keeps existing skills that weren't updated or removed, loading their
+ * SKILL.md content from the local cache.
+ */
+export function mergeDeltaWithIndex(newSkills, removedKeys, indexPath) {
+  let existingIndex;
+  try {
+    existingIndex = JSON.parse(readFileSync(indexPath, "utf-8"));
+  } catch { return newSkills; }
+
+  if (!existingIndex?.skills?.length) return newSkills;
+
+  const updatedKeys = new Set(newSkills.map(s => `${s.owner}/${s.name}`));
+
+  // Keep existing skills that weren't updated or removed
+  const kept = existingIndex.skills.filter(s => {
+    const key = `${s.owner}/${s.name}`;
+    return !updatedKeys.has(key) && !removedKeys.has(key);
+  });
+
+  // Load SKILL.md content from cache for kept skills
+  const keptWithContent = kept.map(s => {
+    try {
+      const content = readFileSync(s.localPath, "utf-8");
+      return { ...s, files: [{ path: "SKILL.md", content, encoding: "utf-8" }] };
+    } catch { return null; }
+  }).filter(Boolean);
+
+  return [...newSkills, ...keptWithContent];
+}
+
+// ---------------------------------------------------------------------------
+// Migration detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect if this is the first run after upgrading from template-string hooks
+ * to rules-based delivery (Phase C migration).
+ *
+ * Detection signals (checked in order):
+ * 1. Migration marker file (.claude/skillrepo-migrated) — written by init
+ *    before it cleans up old files. This is the primary signal for users
+ *    who upgrade via `npx skillrepo init`.
+ * 2. Old format files (.claude/skillrepo-config.json or .claude/skillrepo.md)
+ *    still present AND no rules files yet. This covers users who upgrade
+ *    the CLI without re-running init.
+ *
+ * Returns true if a migration is detected. The caller should show the
+ * one-time migration message and delete the marker file.
+ */
+export function detectUpgradeMigration(projectDir) {
+  // Signal 1: migration marker from init
+  const markerPath = join(projectDir, ".claude", "skillrepo-migrated");
+  if (existsSync(markerPath)) return true;
+
+  // Signal 2: old files present, no rules files yet
+  const oldFiles = [
+    join(projectDir, ".claude", "skillrepo-config.json"),
+    join(projectDir, ".claude", "skillrepo.md"),
+  ];
+
+  const hasOldFiles = oldFiles.some(f => existsSync(f));
+  if (!hasOldFiles) return false;
+
+  // Check if rules files already exist
+  const rulesDir = join(projectDir, ".claude", "rules");
+  try {
+    const entries = readdirSync(rulesDir);
+    const hasRulesFiles = entries.some(e => e.startsWith(RULES_FILE_PREFIX) && e.endsWith(".md"));
+    return !hasRulesFiles;
+  } catch {
+    // .claude/rules/ doesn't exist yet — definitely a migration
+    return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function main() {
+  const globalDir = join(homedir(), ".claude", "skillrepo");
+  const skillsDir = join(globalDir, "skills");
+  const lastSyncPath = join(globalDir, ".last-sync");
+  const indexPath = join(globalDir, "index.json");
+  const projectDir = process.cwd();
+
+  // ── Config ──────────────────────────────────────────────────
+  const config = readConfig();
+  if (!config) {
+    // No config → can't sync. Check if we have a cache to work from.
+    if (!existsSync(indexPath)) {
+      // No config AND no cache — user needs to run init
+      process.stderr.write("[skillrepo] No config found. Run `npx skillrepo init` to set up.\n");
+    }
+    process.exit(0);
+  }
+
+  // ── Read last sync timestamp ────────────────────────────────
+  let lastSync = null;
+  try {
+    lastSync = readFileSync(lastSyncPath, "utf-8").trim();
+    if (!lastSync || isNaN(new Date(lastSync).getTime())) lastSync = null;
+  } catch { /* first sync */ }
+
+  // ── Fetch from sync endpoint ────────────────────────────────
+  const syncResult = await fetchSync(config, lastSync);
+
+  if (!syncResult || syncResult.notModified) {
+    // Sync failed or not modified — but we may still need to write rules
+    // from the existing cache
+    if (syncResult?.notModified) {
+      // Cache is current — re-run rules selection from existing index
+      await writeRulesFromExistingIndex(config, projectDir, indexPath);
+      process.exit(0);
+    }
+
+    // Sync failed
+    if (!existsSync(indexPath)) {
+      // First sync failed with no cache — surface warning
+      const warning = JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: "[skillrepo] Sync failed. No skills available. Check your API key and network connection, or run `npx skillrepo init`.",
+        },
+      });
+      process.stdout.write(warning);
+    }
+    // Sync failure with existing cache: preserve everything, exit
+    process.exit(0);
+  }
+
+  // ── Write new/updated skill files to cache ───────────────────
+  if (syncResult.skills.length > 0) {
+    const manifests = writeSkillFiles(syncResult.skills, skillsDir);
+    cleanupStaleSkillFiles(manifests, skillsDir);
+  }
+
+  // ── Process removals ────────────────────────────────────────
+  const removedKeys = new Set();
+  if (syncResult.removals?.length > 0) {
+    processRemovals(syncResult.removals, skillsDir, projectDir);
+    for (const r of syncResult.removals) removedKeys.add(`${r.owner}/${r.name}`);
+  }
+
+  // ── Update .last-sync ───────────────────────────────────────
+  atomicWrite(lastSyncPath, syncResult.syncedAt);
+
+  // ── Merge delta with existing index ─────────────────────────
+  const allSkills = lastSync
+    ? mergeDeltaWithIndex(syncResult.skills, removedKeys, indexPath)
+    : syncResult.skills;
+
+  // ── Profile scoring + rules selection ───────────────────────
+  const profile = buildRepoProfile(projectDir);
+  const selected = selectRulesSkills(allSkills, profile, config);
+
+  // ── Detect pre-upgrade state (before writing rules) ─────────
+  const isUpgradeMigration = detectUpgradeMigration(projectDir);
+
+  // ── Write rules files ───────────────────────────────────────
+  const writtenNames = writeRulesFiles(selected, projectDir);
+
+  // ── Cleanup stale rules ─────────────────────────────────────
+  cleanupStaleRules(writtenNames, projectDir);
+
+  // ── Write local index ───────────────────────────────────────
+  const index = buildLocalIndex(allSkills, writtenNames, syncResult.syncedAt);
+  atomicWrite(indexPath, JSON.stringify(index, null, 2) + "\n");
+
+  // ── One-time migration message ─────────────────────────────
+  // On the first run after upgrading from template-string hooks to
+  // rules-based delivery, rules files are written but won't take
+  // effect until the next session. Inform the user.
+  if (isUpgradeMigration && writtenNames.size > 0) {
+    const msg = JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "[skillrepo] SkillRepo has been updated to rules-based delivery. Please restart this session to activate your skills.",
+      },
+    });
+    process.stdout.write(msg);
+
+    // Delete the migration marker so the message only fires once
+    removeFile(join(projectDir, ".claude", "skillrepo-migrated"));
+  }
+}
+
+/**
+ * Re-run rules selection from an existing index (304 Not Modified case).
+ * Reads the index, loads SKILL.md content from cache, and writes rules.
+ */
+export async function writeRulesFromExistingIndex(config, projectDir, indexPath) {
+  let index;
+  try {
+    index = JSON.parse(readFileSync(indexPath, "utf-8"));
+  } catch { return; }
+
+  const profile = buildRepoProfile(projectDir);
+
+  // Rebuild skills with file content from local cache
+  const skillsWithContent = [];
+  for (const skill of index.skills ?? []) {
+    try {
+      const content = readFileSync(skill.localPath, "utf-8");
+      skillsWithContent.push({
+        ...skill,
+        files: [{ path: "SKILL.md", content, encoding: "utf-8" }],
+      });
+    } catch { /* skill cache missing — skip */ }
+  }
+
+  const selected = selectRulesSkills(skillsWithContent, profile, config);
+  const writtenNames = writeRulesFiles(selected, projectDir);
+  cleanupStaleRules(writtenNames, projectDir);
+
+  // Update index with current rules delivery status
+  const updatedIndex = {
+    ...index,
+    skills: index.skills.map(s => ({
+      ...s,
+      isRulesDelivered: writtenNames.has(rulesFileName(s.owner, s.name)),
+    })),
+  };
+  atomicWrite(indexPath, JSON.stringify(updatedIndex, null, 2) + "\n");
+}
+
+// ── Run ───────────────────────────────────────────────────────
+// Only execute main when run as a script (not when imported for testing).
+const __filename = fileURLToPath(import.meta.url);
+const isMainModule = process.argv[1] === __filename;
+
+if (isMainModule) {
+  // Consume stdin (hook input) — SessionStart doesn't use the payload
+  for await (const _chunk of process.stdin) { /* drain */ }
+
+  main().catch((err) => {
+    process.stderr.write(`[skillrepo] Sync error: ${err.message}\n`);
+    process.exit(0); // Don't block session start
+  });
+}