facult 1.0.3 → 1.1.0

package/src/doctor.ts

@@ -0,0 +1,128 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ensureAiIndexPath, legacyAiIndexPath } from "./ai-state";
+import { repairAutosyncServices } from "./autosync";
+import { facultAiIndexPath, facultConfigPath, facultRootDir } from "./paths";
+
+function legacyDefaultRoot(home: string): string {
+  return join(home, "agents", ".facult");
+}
+
+async function repairLegacyRootConfig(home: string): Promise<boolean> {
+  const configPath = facultConfigPath(home);
+  const preferredRoot = join(home, ".ai");
+  const legacyRoot = legacyDefaultRoot(home);
+
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    const text = await Bun.file(configPath).text();
+    const value = JSON.parse(text) as unknown;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      parsed = value as Record<string, unknown>;
+    }
+  } catch {
+    return false;
+  }
+
+  if (parsed?.rootDir !== legacyRoot) {
+    return false;
+  }
+
+  try {
+    const stat = await Bun.file(preferredRoot).stat();
+    if (!stat.isDirectory()) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  const next = {
+    ...parsed,
+    rootDir: preferredRoot,
+  };
+  await mkdir(join(home, ".facult"), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return true;
+}
+
+function printHelp() {
+  console.log(`facult doctor — inspect and repair local facult state
+
+Usage:
+  facult doctor [--repair]
+
+Options:
+  --repair   Reconcile legacy AI state, canonical root config, and autosync service config when needed
+`);
+}
+
+export async function doctorCommand(argv: string[]) {
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    printHelp();
+    return;
+  }
+
+  const repair = argv.includes("--repair");
+  const home = process.env.HOME?.trim() || homedir();
+
+  try {
+    let rootConfigRepaired = false;
+    let autosyncRepaired = false;
+    if (repair) {
+      rootConfigRepaired = await repairLegacyRootConfig(home);
+      autosyncRepaired = await repairAutosyncServices(home);
+    }
+    const rootDir = facultRootDir(home);
+    const generated = facultAiIndexPath(home);
+    const legacy = legacyAiIndexPath(rootDir);
+    const result = await ensureAiIndexPath({ homeDir: home, rootDir, repair });
+
+    console.log(`Canonical root: ${rootDir}`);
+    console.log(`Generated AI index: ${generated}`);
+    console.log(`Legacy root index: ${legacy}`);
+
+    if (rootConfigRepaired) {
+      console.log(`Updated facult root config to ${join(home, ".ai")}`);
+    }
+    if (autosyncRepaired) {
+      console.log("Repaired autosync launch agent configuration.");
+    }
+
+    if (result.source === "generated") {
+      console.log("AI index is healthy.");
+      return;
+    }
+
+    if (repair && result.source === "legacy") {
+      console.log(
+        `Repaired generated AI index from legacy root index: ${generated}`
+      );
+      return;
+    }
+
+    if (repair && result.source === "rebuilt") {
+      console.log(
+        `Rebuilt generated AI index from canonical source: ${generated}`
+      );
+      return;
+    }
+
+    if (result.source === "legacy") {
+      console.log(
+        "Legacy root index detected. Run `facult doctor --repair` to reconcile it."
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(
+      "Generated AI index is missing. Run `facult doctor --repair` or `facult index`."
+    );
+    process.exitCode = 1;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}

package/src/enable-disable.ts

@@ -1,8 +1,9 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { ensureAiIndexPath } from "./ai-state";
 import type { FacultIndex } from "./index-builder";
 import { loadManagedState, syncManagedTools } from "./manage";
-import { facultRootDir } from "./paths";
+import { facultAiIndexPath, facultRootDir } from "./paths";
 
 type EntryKind = "skills" | "mcp";
 
@@ -61,8 +62,12 @@ function computeNextEnabledFor({
   return uniqueSorted(base.filter((tool) => !targetTools.includes(tool)));
 }
 
-async function loadIndex(rootDir: string): Promise<FacultIndex> {
-  const indexPath = join(rootDir, "index.json");
+async function loadIndex(homeDir: string): Promise<FacultIndex> {
+  const { path: indexPath } = await ensureAiIndexPath({
+    homeDir,
+    rootDir: facultRootDir(homeDir),
+    repair: true,
+  });
   const file = Bun.file(indexPath);
   if (!(await file.exists())) {
     throw new Error(`Index not found at ${indexPath}. Run "facult index".`);
@@ -71,8 +76,8 @@ async function loadIndex(rootDir: string): Promise<FacultIndex> {
   return JSON.parse(raw) as FacultIndex;
 }
 
-async function writeIndex(rootDir: string, index: FacultIndex) {
-  const indexPath = join(rootDir, "index.json");
+async function writeIndex(homeDir: string, index: FacultIndex) {
+  const indexPath = facultAiIndexPath(homeDir);
   await Bun.write(indexPath, `${JSON.stringify(index, null, 2)}\n`);
 }
 
@@ -200,7 +205,7 @@ export async function applyEnableDisable({
 
   const allTools = managedTools.length ? managedTools : targetTools;
 
-  const index = ensureIndexStructure(await loadIndex(root));
+  const index = ensureIndexStructure(await loadIndex(home));
   const missing: string[] = [];
   const mcpUpdates: string[] = [];
 
@@ -241,7 +246,7 @@ export async function applyEnableDisable({
   }
 
   index.updatedAt = new Date().toISOString();
-  await writeIndex(root, index);
+  await writeIndex(home, index);
 
   await updateCanonicalServers({
     rootDir: root,

package/src/global-docs.ts

@@ -0,0 +1,461 @@
+import { mkdir, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { renderCanonicalText } from "./agents";
+import { renderSnippetText } from "./snippets";
+
+export interface GlobalDocPlan {
+  write: string[];
+  remove: string[];
+  contents: Map<string, string>;
+  managedTargets: string[];
+}
+
+export interface RulesPlan {
+  write: string[];
+  remove: string[];
+  contents: Map<string, string>;
+  managedRulesDir: boolean;
+}
+
+export interface ToolConfigPlan {
+  targetPath: string;
+  write: boolean;
+  remove: boolean;
+  contents: string | null;
+  managedConfig: boolean;
+}
+
+interface SourceTarget {
+  sourcePath: string;
+  targetPath: string;
+}
+
+const TOML_BARE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+async function fileExists(pathValue: string): Promise<boolean> {
+  try {
+    const stat = await Bun.file(pathValue).stat();
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function readTextIfExists(pathValue: string): Promise<string | null> {
+  if (!(await fileExists(pathValue))) {
+    return null;
+  }
+  return await Bun.file(pathValue).text();
+}
+
+async function readTomlFile(
+  pathValue: string
+): Promise<Record<string, unknown> | null> {
+  const text = await readTextIfExists(pathValue);
+  if (text == null) {
+    return null;
+  }
+  const parsed = Bun.TOML.parse(text);
+  return isPlainObject(parsed) ? parsed : null;
+}
+
+function mergeTomlObjects(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = merged[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      merged[key] = mergeTomlObjects(current, value);
+      continue;
+    }
+    merged[key] = value;
+  }
+  return merged;
+}
+
+function shouldQuoteTomlKey(key: string): boolean {
+  return !TOML_BARE_KEY_PATTERN.test(key);
+}
+
+function escapeTomlString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n");
+}
+
+function formatTomlKey(key: string): string {
+  return shouldQuoteTomlKey(key) ? `"${escapeTomlString(key)}"` : key;
+}
+
+function formatTomlValue(value: unknown): string {
+  if (typeof value === "string") {
+    return `"${escapeTomlString(value)}"`;
+  }
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => formatTomlValue(entry)).join(", ")}]`;
+  }
+  throw new Error(`Unsupported TOML value: ${typeof value}`);
+}
+
+function stringifyTomlObject(obj: Record<string, unknown>): string {
+  const lines: string[] = [];
+
+  function emitTable(table: Record<string, unknown>, pathParts: string[] = []) {
+    const scalars: [string, unknown][] = [];
+    const subtables: [string, Record<string, unknown>][] = [];
+
+    for (const [key, value] of Object.entries(table)) {
+      if (isPlainObject(value)) {
+        subtables.push([key, value]);
+      } else {
+        scalars.push([key, value]);
+      }
+    }
+
+    if (pathParts.length > 0) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(`[${pathParts.map((part) => formatTomlKey(part)).join(".")}]`);
+    }
+
+    for (const [key, value] of scalars) {
+      lines.push(`${formatTomlKey(key)} = ${formatTomlValue(value)}`);
+    }
+
+    for (const [key, subtable] of subtables) {
+      emitTable(subtable, [...pathParts, key]);
+    }
+  }
+
+  emitTable(obj);
+  return lines.join("\n");
+}
+
+async function listGlobalDocSources(args: {
+  rootDir: string;
+  tool: string;
+  toolHome: string;
+}): Promise<SourceTarget[]> {
+  const { rootDir, tool, toolHome } = args;
+  if (tool !== "codex") {
+    return [];
+  }
+
+  const candidates: SourceTarget[] = [];
+  const base = join(rootDir, "AGENTS.global.md");
+  if (await fileExists(base)) {
+    candidates.push({
+      sourcePath: base,
+      targetPath: join(toolHome, "AGENTS.md"),
+    });
+  }
+
+  const override = join(rootDir, "AGENTS.override.global.md");
+  if (await fileExists(override)) {
+    candidates.push({
+      sourcePath: override,
+      targetPath: join(toolHome, "AGENTS.override.md"),
+    });
+  }
+
+  return candidates;
+}
+
+async function renderSourceTarget(args: {
+  homeDir: string;
+  rootDir: string;
+  sourcePath: string;
+  targetPath: string;
+  tool: string;
+}): Promise<string> {
+  const raw = await Bun.file(args.sourcePath).text();
+  const withSnippets = await renderSnippetText({
+    text: raw,
+    filePath: args.sourcePath,
+    rootDir: args.rootDir,
+  });
+  if (withSnippets.errors.length) {
+    throw new Error(withSnippets.errors.join("\n"));
+  }
+  return await renderCanonicalText(withSnippets.text, {
+    homeDir: args.homeDir,
+    rootDir: args.rootDir,
+    targetTool: args.tool,
+    targetPath: args.targetPath,
+  });
+}
+
+export async function planToolGlobalDocsSync(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  toolHome: string;
+  previouslyManagedTargets?: string[];
+}): Promise<GlobalDocPlan> {
+  const docs = await listGlobalDocSources(args);
+  const contents = new Map<string, string>();
+  const managedTargets = docs.map((doc) => doc.targetPath).sort();
+
+  for (const doc of docs) {
+    const rendered = await renderSourceTarget({
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      sourcePath: doc.sourcePath,
+      targetPath: doc.targetPath,
+      tool: args.tool,
+    });
+    contents.set(doc.targetPath, rendered);
+  }
+
+  const write: string[] = [];
+  for (const targetPath of managedTargets) {
+    const current = await readTextIfExists(targetPath);
+    const desired = contents.get(targetPath);
+    if (desired != null && current !== desired) {
+      write.push(targetPath);
+    }
+  }
+
+  const remove = (args.previouslyManagedTargets ?? [])
+    .filter((targetPath) => !contents.has(targetPath))
+    .sort();
+
+  return {
+    write: write.sort(),
+    remove,
+    contents,
+    managedTargets,
+  };
+}
+
+export async function syncToolGlobalDocs(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  toolHome: string;
+  previouslyManagedTargets?: string[];
+  dryRun?: boolean;
+}): Promise<GlobalDocPlan> {
+  const plan = await planToolGlobalDocsSync(args);
+  if (args.dryRun) {
+    return plan;
+  }
+
+  for (const pathValue of plan.remove) {
+    await rm(pathValue, { force: true });
+  }
+  for (const pathValue of plan.write) {
+    const desired = plan.contents.get(pathValue);
+    if (desired != null) {
+      await mkdir(dirname(pathValue), { recursive: true });
+      await Bun.write(
+        pathValue,
+        desired.endsWith("\n") ? desired : `${desired}\n`
+      );
+    }
+  }
+  return plan;
+}
+
+async function listToolRules(args: {
+  rootDir: string;
+  tool: string;
+}): Promise<{ sourcePath: string; targetPath: string }[]> {
+  const sourceRoot = join(args.rootDir, "tools", args.tool, "rules");
+  const entries = await readdir(sourceRoot, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  const out: { sourcePath: string; targetPath: string }[] = [];
+  for (const entry of entries) {
+    if (!(entry.isFile() && entry.name.endsWith(".rules"))) {
+      continue;
+    }
+    out.push({
+      sourcePath: join(sourceRoot, entry.name),
+      targetPath: entry.name,
+    });
+  }
+  return out.sort((a, b) => a.targetPath.localeCompare(b.targetPath));
+}
+
+export async function planToolRulesSync(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  rulesDir: string;
+  previouslyManaged?: boolean;
+}): Promise<RulesPlan> {
+  const rules = await listToolRules(args);
+  const contents = new Map<string, string>();
+
+  for (const rule of rules) {
+    const targetPath = join(args.rulesDir, rule.targetPath);
+    const raw = await Bun.file(rule.sourcePath).text();
+    const rendered = await renderCanonicalText(raw, {
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      targetTool: args.tool,
+      targetPath,
+    });
+    contents.set(targetPath, rendered);
+  }
+
+  const write: string[] = [];
+  for (const [targetPath, desired] of contents.entries()) {
+    const current = await readTextIfExists(targetPath);
+    if (current !== desired) {
+      write.push(targetPath);
+    }
+  }
+
+  const remove: string[] = [];
+  if (args.previouslyManaged) {
+    const existing = await readdir(args.rulesDir, {
+      withFileTypes: true,
+    }).catch(() => [] as import("node:fs").Dirent[]);
+    for (const entry of existing) {
+      if (!(entry.isFile() && entry.name.endsWith(".rules"))) {
+        continue;
+      }
+      const existingPath = join(args.rulesDir, entry.name);
+      if (!contents.has(existingPath)) {
+        remove.push(existingPath);
+      }
+    }
+  }
+
+  return {
+    write: write.sort(),
+    remove: remove.sort(),
+    contents,
+    managedRulesDir: rules.length > 0,
+  };
+}
+
+export async function syncToolRules(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  rulesDir: string;
+  previouslyManaged?: boolean;
+  dryRun?: boolean;
+}): Promise<RulesPlan> {
+  const plan = await planToolRulesSync(args);
+  if (args.dryRun) {
+    return plan;
+  }
+
+  for (const pathValue of plan.remove) {
+    await rm(pathValue, { force: true });
+  }
+  for (const pathValue of plan.write) {
+    const desired = plan.contents.get(pathValue);
+    if (desired != null) {
+      await mkdir(dirname(pathValue), { recursive: true });
+      await Bun.write(
+        pathValue,
+        desired.endsWith("\n") ? desired : `${desired}\n`
+      );
+    }
+  }
+  return plan;
+}
+
+export async function planToolConfigSync(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  toolConfigPath: string;
+  existingConfigPath?: string;
+  previouslyManaged?: boolean;
+}): Promise<ToolConfigPlan> {
+  const sourcePath = join(args.rootDir, "tools", args.tool, "config.toml");
+  if (!(await fileExists(sourcePath))) {
+    return {
+      targetPath: args.toolConfigPath,
+      write: false,
+      remove: false,
+      contents: null,
+      managedConfig: false,
+    };
+  }
+
+  const rendered = await renderSourceTarget({
+    homeDir: args.homeDir,
+    rootDir: args.rootDir,
+    sourcePath,
+    targetPath: args.toolConfigPath,
+    tool: args.tool,
+  });
+  const canonicalConfig = Bun.TOML.parse(rendered);
+  const existingConfig =
+    (await readTomlFile(args.toolConfigPath)) ??
+    (args.existingConfigPath
+      ? await readTomlFile(args.existingConfigPath)
+      : null) ??
+    ({} as Record<string, unknown>);
+  const merged = mergeTomlObjects(
+    existingConfig,
+    isPlainObject(canonicalConfig) ? canonicalConfig : {}
+  );
+  const nextContents = stringifyTomlObject(merged);
+  const current = await readTextIfExists(args.toolConfigPath);
+  return {
+    targetPath: args.toolConfigPath,
+    write: current !== `${nextContents}\n`,
+    remove: false,
+    contents: nextContents,
+    managedConfig: true,
+  };
+}
+
+export async function syncToolConfig(args: {
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  toolConfigPath: string;
+  existingConfigPath?: string;
+  previouslyManaged?: boolean;
+  dryRun?: boolean;
+}): Promise<ToolConfigPlan> {
+  const plan = await planToolConfigSync({
+    homeDir: args.homeDir,
+    rootDir: args.rootDir,
+    tool: args.tool,
+    toolConfigPath: args.toolConfigPath,
+    existingConfigPath: args.existingConfigPath,
+    previouslyManaged: args.previouslyManaged,
+  });
+  if (args.dryRun) {
+    return plan;
+  }
+
+  if (plan.remove) {
+    await rm(plan.targetPath, { force: true });
+    return plan;
+  }
+
+  if (plan.write && plan.contents != null) {
+    await mkdir(dirname(plan.targetPath), { recursive: true });
+    await Bun.write(
+      plan.targetPath,
+      plan.contents.endsWith("\n") ? plan.contents : `${plan.contents}\n`
+    );
+  }
+
+  return plan;
+}

package/src/index-builder.ts

@@ -1,6 +1,6 @@
 import { mkdir, readdir } from "node:fs/promises";
-import { basename, join, relative } from "node:path";
-import { facultRootDir } from "./paths";
+import { basename, dirname, join, relative } from "node:path";
+import { facultAiIndexPath, facultRootDir } from "./paths";
 import { lastModified } from "./util/skills";
 
 export interface SkillEntry {
@@ -472,6 +472,8 @@ export async function buildIndex(opts?: {
   force?: boolean;
   /** Override the default canonical root dir (useful for tests). */
   rootDir?: string;
+  /** Override home directory for generated state placement (useful for tests). */
+  homeDir?: string;
 }): Promise<{ index: FacultIndex; outputPath: string }> {
   const force = Boolean(opts?.force);
 
@@ -485,7 +487,7 @@ export async function buildIndex(opts?: {
     ? serversJsonPath
     : mcpJsonPath;
 
-  const outputPath = join(rootDir, "index.json");
+  const outputPath = facultAiIndexPath(opts?.homeDir);
 
   let previousIndex: Record<string, unknown> | null = null;
   if (!force) {
@@ -538,7 +540,7 @@ export async function buildIndex(opts?: {
     snippets,
   };
 
-  await mkdir(rootDir, { recursive: true });
+  await mkdir(dirname(outputPath), { recursive: true });
   await Bun.write(outputPath, `${JSON.stringify(index, null, 2)}\n`);
 
   return { index, outputPath };
@@ -546,7 +548,7 @@ export async function buildIndex(opts?: {
 
 export async function indexCommand(argv: string[]) {
   if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
-    console.log(`facult index — rebuild index.json under the canonical store
+    console.log(`facult index — rebuild the generated index for the canonical store
 
 Usage:
   facult index [--force]