facult 1.0.1

package/src/migrate.ts

@@ -0,0 +1,272 @@
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readlink,
+  rename,
+  stat,
+  symlink,
+  utimes,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+function printHelp() {
+  console.log(`facult migrate — migrate a legacy canonical store to the facult path
+
+Usage:
+  facult migrate [--from <path>] [--dry-run] [--move] [--write-config]
+
+What it does:
+  - Auto-detects a legacy store under ~/agents/ (or use --from)
+  - Copies it to ~/agents/.facult (default, safe)
+  - Or moves it with --move (destructive; removes the legacy directory)
+
+Options:
+  --from           Path to a legacy store root directory
+  --dry-run        Print what would happen without changing anything
+  --move           Rename legacy dir to the new location instead of copying
+  --write-config   Write ~/.facult/config.json to pin rootDir to ~/agents/.facult
+`);
+}
+
+async function dirExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function looksLikeStore(root: string): Promise<boolean> {
+  if (!(await dirExists(root))) {
+    return false;
+  }
+  // Heuristic: treat as a store if it contains something we'd create.
+  if (await fileExists(join(root, "index.json"))) {
+    return true;
+  }
+  for (const d of ["skills", "mcp", "snippets"]) {
+    if (await dirExists(join(root, d))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function expandHomePath(p: string, home: string): string {
+  if (p === "~") {
+    return home;
+  }
+  if (p.startsWith("~/")) {
+    return join(home, p.slice(2));
+  }
+  return p;
+}
+
+function resolvePath(p: string, home: string): string {
+  const expanded = expandHomePath(p, home);
+  return expanded.startsWith("/") ? expanded : resolve(expanded);
+}
+
+function parseFromFlag(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--from") {
+      const next = argv[i + 1];
+      if (!next) {
+        throw new Error("--from requires a path");
+      }
+      return next;
+    }
+    if (arg.startsWith("--from=")) {
+      const raw = arg.slice("--from=".length);
+      if (!raw) {
+        throw new Error("--from requires a path");
+      }
+      return raw;
+    }
+  }
+  return null;
+}
+
+async function findLegacyStoreUnderAgents(home: string): Promise<string[]> {
+  const agentsDir = join(home, "agents");
+  let entries: any[];
+  try {
+    entries = await readdir(agentsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const out: string[] = [];
+  for (const ent of entries) {
+    if (!ent?.isDirectory?.()) {
+      continue;
+    }
+    const name = String(ent.name ?? "");
+    if (!name || name === ".facult") {
+      continue;
+    }
+    const abs = join(agentsDir, name);
+    if (await looksLikeStore(abs)) {
+      out.push(abs);
+    }
+  }
+  return out.sort();
+}
+
+async function copyTree(
+  src: string,
+  dst: string,
+  opts: { dryRun: boolean }
+): Promise<void> {
+  const st = await lstat(src);
+
+  if (st.isSymbolicLink()) {
+    const target = await readlink(src);
+    if (opts.dryRun) {
+      return;
+    }
+    await mkdir(dirname(dst), { recursive: true });
+    // Best-effort: preserve symlinks as symlinks (do not dereference).
+    await symlink(target, dst);
+    return;
+  }
+
+  if (st.isDirectory()) {
+    if (!opts.dryRun) {
+      await mkdir(dst, { recursive: true });
+      // Preserve directory timestamps best-effort after contents are copied.
+    }
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const ent of entries) {
+      const name = String(ent.name ?? "");
+      if (!name) {
+        continue;
+      }
+      await copyTree(join(src, name), join(dst, name), opts);
+    }
+    if (!opts.dryRun) {
+      const s = await stat(src);
+      await utimes(dst, s.atime, s.mtime).catch(() => null);
+    }
+    return;
+  }
+
+  if (st.isFile()) {
+    if (opts.dryRun) {
+      return;
+    }
+    await mkdir(dirname(dst), { recursive: true });
+    await copyFile(src, dst);
+    const s = await stat(src);
+    await utimes(dst, s.atime, s.mtime).catch(() => null);
+  }
+}
+
+export async function migrateCommand(argv: string[]) {
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    printHelp();
+    return;
+  }
+
+  const dryRun = argv.includes("--dry-run");
+  const move = argv.includes("--move");
+  const writeConfig = argv.includes("--write-config");
+
+  const home = homedir();
+  const dest = join(home, "agents", ".facult");
+  const stateDir = join(home, ".facult");
+  const configPath = join(stateDir, "config.json");
+
+  let legacy: string | null = null;
+  try {
+    const from = parseFromFlag(argv);
+    if (from) {
+      legacy = resolvePath(from, home);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 2;
+    return;
+  }
+
+  if (!legacy) {
+    const candidates = await findLegacyStoreUnderAgents(home);
+    if (candidates.length === 0) {
+      console.error(
+        "No legacy store found under ~/agents. Pass --from <path> to migrate from a specific directory."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (candidates.length > 1) {
+      const names = candidates.map((p) => basename(p)).join(", ");
+      console.error(
+        `Multiple legacy stores found under ~/agents: ${names}\nPass --from <path> to choose one.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    legacy = candidates[0] ?? null;
+  }
+
+  if (!(legacy && (await dirExists(legacy)))) {
+    console.error(
+      "Legacy store not found. Pass --from <path> to migrate from a specific directory."
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (await dirExists(dest)) {
+    if (await looksLikeStore(dest)) {
+      console.log(`Destination already exists: ${dest}`);
+      console.log("Nothing to do.");
+      return;
+    }
+    console.error(
+      `Destination exists but does not look like a facult store: ${dest}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (move) {
+    if (dryRun) {
+      console.log(`[dry-run] Would move ${legacy} -> ${dest}`);
+    } else {
+      await rename(legacy, dest);
+      console.log(`Moved ${legacy} -> ${dest}`);
+    }
+  } else if (dryRun) {
+    console.log(`[dry-run] Would copy ${legacy} -> ${dest}`);
+  } else {
+    await mkdir(dest, { recursive: true });
+    await copyTree(legacy, dest, { dryRun: false });
+    console.log(`Copied ${legacy} -> ${dest}`);
+  }
+
+  if (writeConfig) {
+    if (dryRun) {
+      console.log(`[dry-run] Would write ${configPath} with rootDir=${dest}`);
+    } else {
+      await mkdir(stateDir, { recursive: true });
+      await Bun.write(configPath, JSON.stringify({ rootDir: dest }, null, 2));
+      console.log(`Wrote ${configPath}`);
+    }
+  }
+}

package/src/paths.ts

@@ -0,0 +1,238 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseJsonLenient } from "./util/json";
+
+export interface FacultConfig {
+  /**
+   * Override the canonical root directory.
+   *
+   * This is where facult stores the consolidated "canonical" skill + MCP state
+   * (skills/, mcp/, snippets/, index.json, ...).
+   */
+  rootDir?: string;
+
+  /**
+   * Default scan roots (equivalent to passing `facult scan --from <path>`).
+   * Example: ["~", "~/dev", "~/work"]
+   */
+  scanFrom?: string[];
+
+  /**
+   * Extra ignore directory basenames applied under `scanFrom` roots.
+   * Example: ["vendor", ".venv"]
+   */
+  scanFromIgnore?: string[];
+
+  /** Disable the default ignore list for `scanFrom` roots. */
+  scanFromNoDefaultIgnore?: boolean;
+
+  /** Default max directories visited per scanFrom root (same as --from-max-visits). */
+  scanFromMaxVisits?: number;
+
+  /** Default max discovered paths per scanFrom root (same as --from-max-results). */
+  scanFromMaxResults?: number;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function isSafePathString(p: string): boolean {
+  // Protect filesystem APIs from null-byte paths.
+  return !p.includes("\0");
+}
+
+function expandHomePath(p: string, home: string): string {
+  if (p === "~") {
+    return home;
+  }
+  if (p.startsWith("~/")) {
+    return join(home, p.slice(2));
+  }
+  return p;
+}
+
+function resolvePath(p: string, home: string): string {
+  const expanded = expandHomePath(p, home);
+  return expanded.startsWith("/") ? expanded : resolve(expanded);
+}
+
+function dirExists(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function fileExists(p: string): boolean {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function looksLikeFacultRoot(root: string): boolean {
+  if (!dirExists(root)) {
+    return false;
+  }
+  // Heuristic: treat as a facult store if it contains something we'd create.
+  return (
+    fileExists(join(root, "index.json")) ||
+    dirExists(join(root, "skills")) ||
+    dirExists(join(root, "mcp")) ||
+    dirExists(join(root, "snippets"))
+  );
+}
+
+function detectLegacyStoreUnderAgents(home: string): string | null {
+  const agentsDir = join(home, "agents");
+  let entries: any[];
+  try {
+    entries = readdirSync(agentsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const candidates: string[] = [];
+  for (const ent of entries) {
+    if (!ent?.isDirectory?.()) {
+      continue;
+    }
+    const name = String(ent.name ?? "");
+    if (!name || name === ".facult") {
+      continue;
+    }
+    const abs = join(agentsDir, name);
+    if (looksLikeFacultRoot(abs)) {
+      candidates.push(abs);
+    }
+  }
+
+  // Only auto-select when there is exactly one candidate.
+  // If there are multiple, require explicit config/env to choose.
+  candidates.sort();
+  return candidates.length === 1 ? (candidates[0] ?? null) : null;
+}
+
+export function facultStateDir(home: string = homedir()): string {
+  return join(home, ".facult");
+}
+
+export function facultConfigPath(home: string = homedir()): string {
+  return join(facultStateDir(home), "config.json");
+}
+
+export function readFacultConfig(
+  home: string = homedir()
+): FacultConfig | null {
+  const p = facultConfigPath(home);
+  if (!(isSafePathString(p) && fileExists(p))) {
+    return null;
+  }
+
+  try {
+    const txt = readFileSync(p, "utf8");
+    const parsed = parseJsonLenient(txt) as unknown;
+    if (!isPlainObject(parsed)) {
+      return null;
+    }
+    const rootDir =
+      typeof parsed.rootDir === "string" ? parsed.rootDir : undefined;
+
+    const scanFromRaw = (parsed as Record<string, unknown>).scanFrom;
+    const scanFrom = Array.isArray(scanFromRaw)
+      ? scanFromRaw
+          .filter((v) => typeof v === "string")
+          .map((v) => v.trim())
+          .filter(Boolean)
+      : undefined;
+
+    const scanFromIgnoreRaw = (parsed as Record<string, unknown>)
+      .scanFromIgnore;
+    const scanFromIgnore = Array.isArray(scanFromIgnoreRaw)
+      ? scanFromIgnoreRaw
+          .filter((v) => typeof v === "string")
+          .map((v) => v.trim())
+          .filter(Boolean)
+      : undefined;
+
+    const scanFromNoDefaultIgnore =
+      typeof (parsed as Record<string, unknown>).scanFromNoDefaultIgnore ===
+      "boolean"
+        ? ((parsed as Record<string, unknown>)
+            .scanFromNoDefaultIgnore as boolean)
+        : undefined;
+
+    const scanFromMaxVisitsRaw = (parsed as Record<string, unknown>)
+      .scanFromMaxVisits;
+    const scanFromMaxVisits =
+      typeof scanFromMaxVisitsRaw === "number" &&
+      Number.isFinite(scanFromMaxVisitsRaw) &&
+      scanFromMaxVisitsRaw > 0
+        ? Math.floor(scanFromMaxVisitsRaw)
+        : undefined;
+
+    const scanFromMaxResultsRaw = (parsed as Record<string, unknown>)
+      .scanFromMaxResults;
+    const scanFromMaxResults =
+      typeof scanFromMaxResultsRaw === "number" &&
+      Number.isFinite(scanFromMaxResultsRaw) &&
+      scanFromMaxResultsRaw > 0
+        ? Math.floor(scanFromMaxResultsRaw)
+        : undefined;
+
+    return {
+      rootDir,
+      scanFrom,
+      scanFromIgnore,
+      scanFromNoDefaultIgnore,
+      scanFromMaxVisits,
+      scanFromMaxResults,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the canonical facult root directory.
+ *
+ * Precedence:
+ * 1) `FACULT_ROOT_DIR` env var
+ * 2) `~/.facult/config.json` { "rootDir": "..." }
+ * 3) `~/agents/.facult` (if it looks like a store)
+ * 4) a legacy store under `~/agents/` (if it looks like a store)
+ * 5) default: `~/agents/.facult`
+ */
+export function facultRootDir(home: string = homedir()): string {
+  const envRoot = process.env.FACULT_ROOT_DIR?.trim();
+  if (envRoot) {
+    const resolved = resolvePath(envRoot, home);
+    return isSafePathString(resolved)
+      ? resolved
+      : join(home, "agents", ".facult");
+  }
+
+  const cfg = readFacultConfig(home);
+  const cfgRoot = cfg?.rootDir?.trim();
+  if (cfgRoot) {
+    const resolved = resolvePath(cfgRoot, home);
+    return isSafePathString(resolved)
+      ? resolved
+      : join(home, "agents", ".facult");
+  }
+
+  const preferred = join(home, "agents", ".facult");
+
+  if (looksLikeFacultRoot(preferred)) {
+    return preferred;
+  }
+  const legacy = detectLegacyStoreUnderAgents(home);
+  if (legacy) {
+    return legacy;
+  }
+  return preferred;
+}

package/src/quarantine.ts

@@ -0,0 +1,217 @@
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readlink,
+  rename,
+  rm,
+  stat,
+  symlink,
+  utimes,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+export type QuarantineMode = "move" | "copy";
+
+export interface QuarantineItem {
+  /** Absolute or relative path to a file or directory. */
+  path: string;
+  /** Optional label metadata for manifest/debugging. */
+  kind?: string;
+  item?: string;
+}
+
+export interface QuarantineEntry {
+  originalPath: string;
+  quarantinedPath: string;
+  mode: QuarantineMode;
+  kind?: string;
+  item?: string;
+}
+
+export interface QuarantineManifest {
+  version: 1;
+  timestamp: string;
+  entries: QuarantineEntry[];
+}
+
+function isSafePathString(p: string): boolean {
+  return !p.includes("\0");
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(p: string) {
+  await mkdir(p, { recursive: true });
+}
+
+function isSubpath(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel === "" || !(rel.startsWith("..") || rel.startsWith(`..${sep}`));
+}
+
+function relPathInQuarantine(args: { absPath: string; home: string }): string {
+  const { absPath, home } = args;
+
+  // Prefer preserving relative layout under the user's home for readability.
+  if (absPath === home) {
+    return join("home");
+  }
+  if (absPath.startsWith(home + sep)) {
+    return join("home", absPath.slice(home.length + 1));
+  }
+
+  // Fallback: treat as absolute path materialized under "abs/".
+  // On Unix, strip leading "/" so join doesn't ignore the prefix.
+  if (absPath.startsWith("/")) {
+    return join("abs", absPath.slice(1));
+  }
+
+  // Last resort: sanitize path-ish strings (e.g. Windows drive letters).
+  return join("abs", absPath.replace(/[:\\\\/]+/g, "_"));
+}
+
+async function uniqueDestinationPath(p: string): Promise<string> {
+  if (!(await pathExists(p))) {
+    return p;
+  }
+  const base = p;
+  for (let i = 2; i < 10_000; i += 1) {
+    const next = `${base}.dup${i}`;
+    if (!(await pathExists(next))) {
+      return next;
+    }
+  }
+  throw new Error(`Could not find unique quarantine path for ${p}`);
+}
+
+async function copyTree(src: string, dst: string): Promise<void> {
+  const st = await lstat(src);
+
+  if (st.isSymbolicLink()) {
+    const target = await readlink(src);
+    await ensureDir(dirname(dst));
+    await symlink(target, dst);
+    return;
+  }
+
+  if (st.isDirectory()) {
+    await ensureDir(dst);
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const ent of entries) {
+      const name = String(ent.name ?? "");
+      if (!name) {
+        continue;
+      }
+      await copyTree(join(src, name), join(dst, name));
+    }
+    const s = await stat(src);
+    await utimes(dst, s.atime, s.mtime).catch(() => null);
+    return;
+  }
+
+  if (st.isFile()) {
+    await ensureDir(dirname(dst));
+    await copyFile(src, dst);
+    const s = await stat(src);
+    await utimes(dst, s.atime, s.mtime).catch(() => null);
+  }
+}
+
+async function movePath(src: string, dst: string): Promise<void> {
+  await ensureDir(dirname(dst));
+  try {
+    await rename(src, dst);
+    return;
+  } catch (e: unknown) {
+    const err = e as NodeJS.ErrnoException | null;
+    if (err?.code !== "EXDEV") {
+      throw e;
+    }
+  }
+
+  // Cross-device move fallback.
+  await copyTree(src, dst);
+  await rm(src, { recursive: true, force: true });
+}
+
+export async function quarantineItems(args: {
+  items: QuarantineItem[];
+  mode: QuarantineMode;
+  dryRun?: boolean;
+  timestamp?: string;
+  homeDir?: string;
+  /** Optional explicit destination directory (for deterministic runs). */
+  destDir?: string;
+}): Promise<{ quarantineDir: string; manifest: QuarantineManifest }> {
+  const home = args.homeDir ?? homedir();
+  const ts = args.timestamp ?? new Date().toISOString();
+  const stamp = ts.replace(/[:.]/g, "-");
+  const quarantineDir =
+    args.destDir ?? join(home, ".facult", "quarantine", stamp);
+
+  const entries: QuarantineEntry[] = [];
+
+  for (const it of args.items) {
+    const raw = it.path;
+    const abs = raw.startsWith("/") ? raw : resolve(raw);
+
+    if (!isSafePathString(abs)) {
+      continue;
+    }
+
+    const rel = relPathInQuarantine({ absPath: abs, home });
+    const planned = resolve(quarantineDir, rel);
+    if (!isSubpath(quarantineDir, planned)) {
+      continue;
+    }
+
+    const dst = await uniqueDestinationPath(planned);
+    entries.push({
+      originalPath: abs,
+      quarantinedPath: dst,
+      mode: args.mode,
+      kind: it.kind,
+      item: it.item,
+    });
+  }
+
+  const manifest: QuarantineManifest = {
+    version: 1,
+    timestamp: ts,
+    entries,
+  };
+
+  if (args.dryRun) {
+    return { quarantineDir, manifest };
+  }
+
+  await ensureDir(quarantineDir);
+
+  for (const e of entries) {
+    if (!(await pathExists(e.originalPath))) {
+      continue;
+    }
+    if (args.mode === "move") {
+      await movePath(e.originalPath, e.quarantinedPath);
+    } else {
+      await copyTree(e.originalPath, e.quarantinedPath);
+    }
+  }
+
+  await Bun.write(
+    join(quarantineDir, "manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`
+  );
+
+  return { quarantineDir, manifest };
+}