@refactco/refact-os 1.5.0

package/lib/adapters.js

@@ -0,0 +1,302 @@
+const fs = require("fs");
+const path = require("path");
+const { parseFrontmatter } = require("./frontmatter");
+
+// Above this many skills, walking every SKILL.md's frontmatter each session is
+// wasteful — generate a derived index instead. Below it, walking the directory
+// is fine. The index is a build artifact (regenerated on sync, drift-checked by
+// validate), so it cannot silently drift.
+const INDEX_THRESHOLD = 25;
+const INDEX_FILE = path.join("agent", "skills", ".index.json");
+
+// Generate tool-native adapter folders (.cursor/, .claude/) from the canonical
+// agent/ directory. Adapters are disposable, regenerated output — never edited
+// by hand. The canonical source of truth is agent/.
+
+const GENERATED_NOTE =
+  "This folder is GENERATED from agent/ by refact-os. Do not edit by hand.\n" +
+  "Change the canonical files under agent/ and run `npm run refact:sync`.\n";
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function replaceDir(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  fs.rmSync(dst, { recursive: true, force: true });
+  copyDir(src, dst);
+  return true;
+}
+
+// Records, inside a generated skills dir, which skill folders refact-os owns
+// (i.e. generated from agent/skills/). Anything in the dir NOT listed here is a
+// foreign skill placed by another tool — preserved across syncs, never deleted.
+const OWNED_SKILLS_MANIFEST = ".refact-os-owned.json";
+
+function listSkillDirs(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")))
+    .map((e) => e.name);
+}
+
+// Reconcile a generated skills dir with agent/skills/ WITHOUT clobbering foreign
+// skills. Unlike replaceDir (wipe + copy), this mirrors each agent skill, prunes
+// only skills refact-os previously generated but agent/ no longer has, and leaves
+// any skill we never generated (e.g. a third-party Cursor skill pack) untouched.
+function syncSkillsDir(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  const agentSkills = listSkillDirs(src);
+  const agentSet = new Set(agentSkills);
+
+  const manifestPath = path.join(dst, OWNED_SKILLS_MANIFEST);
+  let prevOwned = [];
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      if (Array.isArray(m.skills)) prevOwned = m.skills;
+    } catch (_err) {
+      prevOwned = [];
+    }
+  }
+
+  fs.mkdirSync(dst, { recursive: true });
+  // Prune skills we generated last time that agent/ has since dropped (rename or
+  // package prune). Never touch a dir we don't have on record as ours.
+  for (const name of prevOwned) {
+    if (!agentSet.has(name)) fs.rmSync(path.join(dst, name), { recursive: true, force: true });
+  }
+  // (Re)write every current agent skill, replacing any prior copy.
+  for (const name of agentSkills) {
+    const d = path.join(dst, name);
+    fs.rmSync(d, { recursive: true, force: true });
+    copyDir(path.join(src, name), d);
+  }
+  // Mirror any top-level files (e.g. the generated .index.json) the same way the
+  // old wipe-and-copy did, so resolver artifacts still land in the adapter dir.
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.isFile()) fs.copyFileSync(path.join(src, entry.name), path.join(dst, entry.name));
+  }
+  fs.writeFileSync(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        generatedBy: "refact-os",
+        note: "Skill folders refact-os generated from agent/skills/ and will prune/regenerate. Skills NOT listed here are foreign (placed by another tool) and are preserved on sync. Do not edit by hand.",
+        skills: [...agentSkills].sort(),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  return true;
+}
+
+// Merge refact-os's canonical Claude settings (hook groups + a permission
+// allowlist) into an existing settings object.
+//  - Hooks: we own (and replace on every sync) only the groups whose command
+//    references our hook script — any other event keys, and any user-authored
+//    hooks on the same events, are preserved.
+//  - Permissions: the managed `allow` entries are unioned into the existing
+//    allow list (so re-syncing is idempotent and never drops a user-added rule),
+//    and any other permission keys the user set (deny, ask) are left untouched.
+// Keys prefixed with "_" in the spec are treated as comments and skipped.
+function mergeClaudeSettings(existing, managed) {
+  const settings = existing && typeof existing === "object" ? { ...existing } : {};
+  const hooks = settings.hooks && typeof settings.hooks === "object" ? { ...settings.hooks } : {};
+  for (const [key, value] of Object.entries(managed)) {
+    if (key.startsWith("_") || key === "permissions") continue;
+    const prior = Array.isArray(hooks[key]) ? hooks[key] : [];
+    const userGroups = prior.filter((group) => {
+      const cmds = (group && Array.isArray(group.hooks) ? group.hooks : []).map((h) => (h && h.command) || "");
+      return !cmds.some((c) => String(c).includes(CLAUDE_HOOK_MARKER));
+    });
+    hooks[key] = [...userGroups, ...(Array.isArray(value) ? value : [])];
+  }
+  settings.hooks = hooks;
+  if (managed.permissions && Array.isArray(managed.permissions.allow)) {
+    const perms = settings.permissions && typeof settings.permissions === "object" ? { ...settings.permissions } : {};
+    const curAllow = Array.isArray(perms.allow) ? perms.allow : [];
+    perms.allow = [...new Set([...curAllow, ...managed.permissions.allow])];
+    settings.permissions = perms;
+  }
+  return settings;
+}
+
+// Generate/merge the Claude-format hooks block into .claude/settings.json.
+// Returns the relative filename written, or null when there is no spec to apply.
+function writeClaudeSettings(agentDir, toolRoot) {
+  const specPath = path.join(agentDir, CLAUDE_HOOKS_FILE);
+  if (!fs.existsSync(specPath)) return null;
+  let managed;
+  try {
+    managed = JSON.parse(fs.readFileSync(specPath, "utf8"));
+  } catch (_err) {
+    return null;
+  }
+  const settingsPath = path.join(toolRoot, "settings.json");
+  let existing = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    } catch (_err) {
+      existing = {};
+    }
+  }
+  fs.mkdirSync(toolRoot, { recursive: true });
+  fs.writeFileSync(settingsPath, `${JSON.stringify(mergeClaudeSettings(existing, managed), null, 2)}\n`, "utf8");
+  return "settings.json";
+}
+
+// Which agent/ subtrees each tool surface receives.
+const SURFACES = {
+  cursor: {
+    dir: ".cursor",
+    subdirs: ["skills", "references", "hooks", "scripts"],
+    files: ["hooks.json"],
+  },
+  claude: {
+    // Claude gets hooks/ + scripts/ too (for the transcript-capture hook and
+    // the chat-import backfill). Claude ignores hooks.json and reads hooks from
+    // settings.json instead, so that block is generated separately below.
+    dir: ".claude",
+    subdirs: ["skills", "hooks", "scripts"],
+    files: [],
+  },
+};
+
+// Canonical Claude hooks spec (event -> hook groups) and the marker that
+// identifies the groups refact-os owns inside .claude/settings.json.
+const CLAUDE_HOOKS_FILE = "claude-hooks.json";
+const CLAUDE_HOOK_MARKER = "claude-sync-transcript.py";
+
+function generateAdapters(targetRoot, options = {}) {
+  const agentDir = path.join(targetRoot, "agent");
+  if (!fs.existsSync(agentDir)) {
+    throw new Error(`No agent/ directory at ${targetRoot} — nothing to generate adapters from.`);
+  }
+  const tools = options.tools || ["cursor", "claude"];
+  const result = { tools: [], surfaces: {} };
+
+  for (const tool of tools) {
+    const surface = SURFACES[tool];
+    if (!surface) continue;
+    const toolRoot = path.join(targetRoot, surface.dir);
+    const written = [];
+
+    for (const sub of surface.subdirs) {
+      const src = path.join(agentDir, sub);
+      const dst = path.join(toolRoot, sub);
+      // skills/ may hold foreign (non-refact-os) skill packs — reconcile instead
+      // of wiping. Other subdirs are wholly refact-os-owned, so a clean replace
+      // is correct (and drops files removed upstream).
+      const ok = sub === "skills" ? syncSkillsDir(src, dst) : replaceDir(src, dst);
+      if (ok) written.push(sub);
+    }
+    for (const file of surface.files) {
+      const src = path.join(agentDir, file);
+      if (fs.existsSync(src)) {
+        fs.mkdirSync(toolRoot, { recursive: true });
+        fs.copyFileSync(src, path.join(toolRoot, file));
+        written.push(file);
+      }
+    }
+    if (tool === "claude") {
+      const settingsFile = writeClaudeSettings(agentDir, toolRoot);
+      if (settingsFile) written.push(settingsFile);
+    }
+    if (written.length > 0) {
+      fs.writeFileSync(path.join(toolRoot, "GENERATED.md"), `# ${surface.dir} (generated)\n\n${GENERATED_NOTE}`, "utf8");
+      result.tools.push(tool);
+      result.surfaces[tool] = written;
+    }
+  }
+
+  writeSurfaceMap(targetRoot, result);
+  result.index = generateSkillIndex(targetRoot);
+  return result;
+}
+
+// The "resolver slice": the frontmatter fields the agent reads at selection
+// time. Each field changes a routing decision — when_to_use ("might fit"),
+// when_not_to_use ("but not when…", prevents misfires), next_skills ("leads
+// to…", enables chaining), requires_approval ("proceed or stop?"). Keep this in
+// sync with the spec's "How Skills Are Selected".
+function skillFrontmatterSlice(targetRoot, name) {
+  const p = path.join(targetRoot, "agent", "skills", name, "SKILL.md");
+  const fm = parseFrontmatter(fs.readFileSync(p, "utf8")) || {};
+  return {
+    name,
+    pattern: fm.pattern || null,
+    description: fm.description || null,
+    when_to_use: fm.when_to_use || null,
+    when_not_to_use: fm.when_not_to_use || null,
+    next_skills: Array.isArray(fm.next_skills) ? fm.next_skills : [],
+    requires_approval: String(fm.requires_approval) === "true",
+  };
+}
+
+// Build (or remove) the derived skill index, threshold-gated.
+function generateSkillIndex(targetRoot, options = {}) {
+  const threshold = options.threshold || INDEX_THRESHOLD;
+  const skills = listSkills(targetRoot);
+  const indexPath = path.join(targetRoot, INDEX_FILE);
+  if (skills.length < threshold) {
+    if (fs.existsSync(indexPath)) fs.rmSync(indexPath);
+    return { generated: false, count: skills.length, threshold };
+  }
+  const payload = {
+    generatedBy: "refact-os",
+    note: "Derived index of agent/skills frontmatter. Regenerated by `npm run refact:sync`; do not edit.",
+    threshold,
+    skills: skills.map((n) => skillFrontmatterSlice(targetRoot, n)),
+  };
+  fs.writeFileSync(indexPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return { generated: true, count: skills.length, threshold };
+}
+
+function readSkillIndex(targetRoot) {
+  const indexPath = path.join(targetRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  } catch (_err) {
+    return { _invalid: true };
+  }
+}
+
+function writeSurfaceMap(targetRoot, result) {
+  const mapPath = path.join(targetRoot, "agent", "agent-surface-map.json");
+  const map = {
+    generatedBy: "refact-os",
+    canonical: "agent/",
+    surfaces: Object.fromEntries(
+      result.tools.map((t) => [SURFACES[t].dir, { from: "agent/", contains: result.surfaces[t] }]),
+    ),
+  };
+  fs.writeFileSync(mapPath, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+}
+
+// Returns the list of canonical skill names (folders under agent/skills with a SKILL.md).
+function listSkills(targetRoot) {
+  const skillsDir = path.join(targetRoot, "agent", "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(skillsDir, e.name, "SKILL.md")))
+    .map((e) => e.name)
+    .sort();
+}
+
+module.exports = { generateAdapters, listSkills, generateSkillIndex, readSkillIndex, skillFrontmatterSlice, INDEX_THRESHOLD };

package/lib/company.js

@@ -0,0 +1,76 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { loadConfig, saveConfig } = require("./refact-config");
+
+// Company context lives canonically in the refact-operation repo. `sync company`
+// pulls a folder from it into the project's docs/context/company/ — local and
+// fast for the agent to read, but re-syncable so it never permanently drifts.
+
+const DEFAULT_SOURCE = "github:refactco/refact-operation";
+const DEFAULT_SOURCE_PATH = "docs/company";
+const DEST = path.join("docs", "context", "company");
+
+const GENERATED_NOTE =
+  "This folder is SYNCED from the company source repo by `npx refact-os sync company`.\n" +
+  "Do not edit here — change it in the source and re-sync. Local edits are overwritten.\n";
+
+function toGitUrl(source) {
+  if (/^github:/.test(source)) {
+    return `git@github.com:${source.slice("github:".length)}.git`;
+  }
+  return source; // assume a full git URL (https or ssh)
+}
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function syncCompany(targetRoot, options = {}) {
+  const config = loadConfig(targetRoot);
+  const companyCfg = (config.company && typeof config.company === "object") ? config.company : {};
+  const source = options.source || companyCfg.source || DEFAULT_SOURCE;
+  const sourcePath = options.sourcePath || companyCfg.sourcePath || DEFAULT_SOURCE_PATH;
+  const gitUrl = toGitUrl(source);
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "refact-company-"));
+  let sha;
+  try {
+    execFileSync("git", ["clone", "--depth", "1", gitUrl, tmp], { stdio: ["ignore", "ignore", "pipe"] });
+    sha = execFileSync("git", ["-C", tmp, "rev-parse", "HEAD"]).toString().trim();
+    const srcDir = path.join(tmp, sourcePath);
+    if (!fs.existsSync(srcDir)) {
+      throw new Error(`Source path "${sourcePath}" not found in ${source}.`);
+    }
+    const destDir = path.join(targetRoot, DEST);
+    fs.rmSync(destDir, { recursive: true, force: true });
+    const fileCount = copyDir(srcDir, destDir);
+    fs.writeFileSync(path.join(destDir, "GENERATED.md"), `# Company context (synced)\n\n${GENERATED_NOTE}\nSource: ${source} (${sourcePath}) @ ${sha}\n`, "utf8");
+
+    config.company = { source, sourcePath, syncedSha: sha, syncedAt: new Date().toISOString().slice(0, 10) };
+    saveConfig(targetRoot, config);
+    return { dest: DEST, source, sourcePath, sha, fileCount };
+  } catch (err) {
+    if (err && err.stderr) {
+      throw new Error(`git clone failed for ${gitUrl}: ${err.stderr.toString().trim()}`);
+    }
+    throw err;
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+module.exports = { syncCompany, DEFAULT_SOURCE, DEFAULT_SOURCE_PATH };

package/lib/frontmatter.js

@@ -0,0 +1,30 @@
+// Minimal YAML frontmatter reader for SKILL.md files. Returns top-level scalar
+// keys plus list keys (next_skills, sub_agents, inputs, outputs). Shared by the
+// validator and the adapter/index generator.
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const lines = match[1].split("\n");
+  const data = {};
+  let currentList = null;
+  for (const line of lines) {
+    if (/^\s*-\s+/.test(line) && currentList) {
+      data[currentList].push(line.replace(/^\s*-\s+/, "").replace(/\s+#.*$/, "").trim());
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const value = kv[2].trim();
+    if (value === "" || value === "[]") {
+      data[key] = [];
+      currentList = value === "[]" ? null : key;
+    } else {
+      data[key] = value;
+      currentList = null;
+    }
+  }
+  return data;
+}
+
+module.exports = { parseFrontmatter };

package/lib/migrate.js

@@ -0,0 +1,116 @@
+const fs = require("fs");
+const path = require("path");
+
+// Migrate an older-model refact-os repo to the v2.3 substrate. Non-destructive:
+// a file move never overwrites an existing destination file. Directory moves
+// MERGE into the destination — the seed pre-creates the role dirs (each with a
+// .gitkeep), so a wholesale rename would always be blocked and old chats would
+// be stranded in the legacy folder. Instead we move the contents file-by-file,
+// leaving anything already at the destination untouched. Returns the moves
+// performed so the caller can report them.
+
+// Old working-memory + raw-input layout -> v2.3 roles.
+const FILE_MOVES = [
+  ["context/decisions.md", "docs/decisions.md"],
+  ["context/roles.md", "docs/context/people.md"],
+  ["context/open-decisions.md", "docs/context/open-decisions.md"],
+  ["context/learnings.md", "docs/context/learnings.md"],
+];
+
+const DIR_MOVES = [
+  ["docs/emails", "docs/sources/raw/email"],
+  ["docs/call-transcripts", "docs/sources/raw/call-transcripts"],
+  ["docs/agent-transcripts", "docs/sources/raw/agent-transcripts"],
+  ["docs/asana/closed", "docs/task/closed"],
+  ["docs/asana", "docs/task/open"],
+];
+
+function pruneEmptyDir(dir) {
+  try {
+    if (fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0) {
+      fs.rmdirSync(dir);
+    }
+  } catch (_err) {
+    // leave non-empty / undeletable dirs for the user
+  }
+}
+
+// Move a single file, but never clobber a file already at the destination.
+function moveFileIfPresent(targetRoot, from, to) {
+  const src = path.join(targetRoot, from);
+  const dst = path.join(targetRoot, to);
+  if (!fs.existsSync(src)) return null;
+  if (fs.existsSync(dst)) return { from, to, skipped: "destination exists" };
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.renameSync(src, dst);
+  return { from, to };
+}
+
+// Recursively move files from src into dst without overwriting anything already
+// there. Returns how many files were moved vs. left in place.
+function mergeInto(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  let moved = 0;
+  let kept = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      const sub = mergeInto(s, d);
+      moved += sub.moved;
+      kept += sub.kept;
+      pruneEmptyDir(s);
+    } else if (fs.existsSync(d)) {
+      kept += 1; // non-destructive: keep the existing copy
+    } else {
+      fs.renameSync(s, d);
+      moved += 1;
+    }
+  }
+  return { moved, kept };
+}
+
+// Move a whole directory. Fast path is a plain rename when the destination is
+// absent; otherwise merge file-by-file so old content lands in a seed-created
+// role dir instead of being skipped.
+function moveDirIfPresent(targetRoot, from, to) {
+  const src = path.join(targetRoot, from);
+  const dst = path.join(targetRoot, to);
+  if (!fs.existsSync(src)) return null;
+  if (!fs.existsSync(dst)) {
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.renameSync(src, dst);
+    return { from, to };
+  }
+  const { moved, kept } = mergeInto(src, dst);
+  pruneEmptyDir(src);
+  if (moved === 0) {
+    return { from, to, skipped: kept > 0 ? "destination already has these files" : "destination exists, source empty" };
+  }
+  return { from, to, merged: moved };
+}
+
+function migrateRepo(targetRoot) {
+  const moved = [];
+  const skipped = [];
+
+  for (const [from, to] of DIR_MOVES) {
+    const r = moveDirIfPresent(targetRoot, from, to);
+    if (r && r.skipped) skipped.push(r);
+    else if (r) moved.push(r);
+  }
+  for (const [from, to] of FILE_MOVES) {
+    const r = moveFileIfPresent(targetRoot, from, to);
+    if (r && r.skipped) skipped.push(r);
+    else if (r) moved.push(r);
+  }
+
+  // Clean up now-empty legacy roots.
+  for (const dir of ["context", "docs/asana"]) {
+    pruneEmptyDir(path.join(targetRoot, dir));
+  }
+
+  return { moved, skipped };
+}
+
+module.exports = { migrateRepo };