facult 2.7.0 → 2.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/adapters/codex.ts

@@ -10,7 +10,7 @@ export const codexAdapter: ToolAdapter = {
   detectVersion: detectExplicitVersion,
   getDefaultPaths: () => ({
     mcp: "~/.codex/mcp.json",
-    skills: "~/.codex/skills",
+    skills: ["~/.agents/skills", "~/.codex/skills"],
     agents: "~/.codex/agents",
     config: "~/.config/openai/codex.json",
   }),

package/src/ai-state.ts

@@ -1,10 +1,13 @@
-import { copyFile, mkdir, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { copyFile, mkdir, readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildIndex } from "./index-builder";
 import {
   facultAiGraphPath,
   facultAiIndexPath,
   legacyFacultStateDirForRoot,
+  preferredGlobalAiRoot,
+  projectRootFromAiRoot,
 } from "./paths";
 
 async function fileExists(path: string): Promise<boolean> {
@@ -15,6 +18,99 @@ async function fileExists(path: string): Promise<boolean> {
   }
 }
 
+async function newestPathMtime(path: string): Promise<number> {
+  try {
+    const st = await stat(path);
+    if (st.isFile()) {
+      return st.mtimeMs;
+    }
+    if (!st.isDirectory()) {
+      return 0;
+    }
+    let newest = st.mtimeMs;
+    let entries: Dirent<string>[] = [];
+    try {
+      entries = await readdir(path, { withFileTypes: true, encoding: "utf8" });
+    } catch {
+      return newest;
+    }
+
+    for (const entry of entries) {
+      const child = join(path, entry.name);
+      if (entry.isFile()) {
+        try {
+          const childStat = await stat(child);
+          newest = Math.max(newest, childStat.mtimeMs);
+        } catch {
+          // ignore unreadable children
+        }
+        continue;
+      }
+      if (entry.isDirectory()) {
+        newest = Math.max(newest, await newestPathMtime(child));
+      }
+    }
+    return newest;
+  } catch {
+    return 0;
+  }
+}
+
+async function watchedPathMtime(path: string): Promise<number> {
+  const newest = await newestPathMtime(path);
+  if (newest > 0) {
+    return newest;
+  }
+  try {
+    return (await stat(dirname(path))).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+async function canonicalAssetsNewerThanIndex(args: {
+  homeDir: string;
+  rootDir: string;
+  indexPath: string;
+}): Promise<boolean> {
+  let indexMtimeMs = 0;
+  try {
+    indexMtimeMs = (await stat(args.indexPath)).mtimeMs;
+  } catch {
+    return true;
+  }
+
+  const watchedRelPaths = [
+    "AGENTS.global.md",
+    "AGENTS.override.global.md",
+    "agents",
+    "config.toml",
+    "instructions",
+    "mcp",
+    "skills",
+    "snippets",
+    "tools",
+  ];
+  const watchedRoots = [args.rootDir];
+
+  if (projectRootFromAiRoot(args.rootDir, args.homeDir)) {
+    const globalRoot = preferredGlobalAiRoot(args.homeDir);
+    if (globalRoot !== args.rootDir) {
+      watchedRoots.push(globalRoot);
+    }
+  }
+
+  for (const root of watchedRoots) {
+    for (const rel of watchedRelPaths) {
+      if ((await watchedPathMtime(join(root, rel))) > indexMtimeMs) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
 export function legacyAiIndexPath(rootDir: string): string {
   return join(rootDir, "index.json");
 }
@@ -46,6 +142,21 @@ export async function ensureAiIndexPath(args: {
 }> {
   const generatedPath = facultAiIndexPath(args.homeDir, args.rootDir);
   if (await fileExists(generatedPath)) {
+    if (
+      args.repair !== false &&
+      (await canonicalAssetsNewerThanIndex({
+        homeDir: args.homeDir,
+        rootDir: args.rootDir,
+        indexPath: generatedPath,
+      }))
+    ) {
+      const { outputPath } = await buildIndex({
+        rootDir: args.rootDir,
+        homeDir: args.homeDir,
+        force: false,
+      });
+      return { path: outputPath, repaired: true, source: "rebuilt" };
+    }
     return { path: generatedPath, repaired: false, source: "generated" };
   }
 
@@ -100,6 +211,25 @@ export async function ensureAiGraphPath(args: {
 }> {
   const generatedPath = facultAiGraphPath(args.homeDir, args.rootDir);
   if (await fileExists(generatedPath)) {
+    const generatedIndexPath = facultAiIndexPath(args.homeDir, args.rootDir);
+    const freshnessAnchor = (await fileExists(generatedIndexPath))
+      ? generatedIndexPath
+      : generatedPath;
+    if (
+      args.repair !== false &&
+      (await canonicalAssetsNewerThanIndex({
+        homeDir: args.homeDir,
+        rootDir: args.rootDir,
+        indexPath: freshnessAnchor,
+      }))
+    ) {
+      const { graphPath } = await buildIndex({
+        rootDir: args.rootDir,
+        homeDir: args.homeDir,
+        force: false,
+      });
+      return { path: graphPath, rebuilt: true };
+    }
     return { path: generatedPath, rebuilt: false };
   }
 

package/src/builtin.ts

@@ -1,5 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { projectRootFromAiRoot } from "./paths";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -39,7 +40,8 @@ function readBooleanConfig(
 }
 
 export async function builtinSyncDefaultsEnabled(
-  rootDir: string
+  rootDir: string,
+  homeDir?: string
 ): Promise<boolean> {
   const [tracked, local] = await Promise.all([
     readTomlObject(join(rootDir, "config.toml")),
@@ -57,5 +59,9 @@ export async function builtinSyncDefaultsEnabled(
     }
   }
 
+  if (projectRootFromAiRoot(rootDir, homeDir) != null) {
+    return false;
+  }
+
   return true;
 }

package/src/doctor.ts

@@ -22,6 +22,8 @@ import {
 } from "./ai-state";
 import { repairAutosyncServices } from "./autosync";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
+import { loadManagedState } from "./manage";
+import { extractServersObject } from "./mcp-config";
 import {
   facultAiGraphPath,
   facultAiIndexPath,
@@ -30,7 +32,14 @@ import {
   facultStateDir,
   legacyExternalFacultStateDir,
   legacyFacultStateDirForRoot,
+  projectRootFromAiRoot,
 } from "./paths";
+import {
+  loadConfiguredProjectSyncTools,
+  writeProjectSyncPolicy,
+} from "./project-sync";
+
+const TOML_FILE_SUFFIX_RE = /\.toml$/;
 
 function legacyDefaultRoot(home: string): string {
   return join(home, "agents", ".facult");
@@ -223,6 +232,275 @@ async function repairLegacyState(args: {
   return { changed, conflicts };
 }
 
+function normalizeCodexMarketplaceText(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return text.endsWith("\n") ? text : `${text}\n`;
+    }
+    const plugins = Array.isArray((parsed as { plugins?: unknown[] }).plugins)
+      ? ((parsed as { plugins: unknown[] }).plugins ?? [])
+      : null;
+    if (plugins) {
+      (parsed as { plugins: unknown[] }).plugins = plugins.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+          return entry;
+        }
+        const source =
+          "source" in entry &&
+          (entry as { source?: unknown }).source &&
+          typeof (entry as { source?: unknown }).source === "object" &&
+          !Array.isArray((entry as { source?: unknown }).source)
+            ? {
+                ...((entry as { source: Record<string, unknown> }).source ??
+                  {}),
+              }
+            : null;
+        if (
+          source?.source === "local" &&
+          typeof source.path === "string" &&
+          source.path.startsWith("./.codex/plugins/")
+        ) {
+          source.path = source.path.replace("./.codex/plugins/", "./plugins/");
+        }
+        return source
+          ? { ...(entry as Record<string, unknown>), source }
+          : entry;
+      });
+    }
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+  } catch {
+    return text.endsWith("\n") ? text : `${text}\n`;
+  }
+}
+
+async function repairLegacyCodexAuthoringLayout(args: {
+  home: string;
+  rootDir: string;
+}): Promise<{ changed: boolean; conflicts: string[] }> {
+  const liveRoot = projectRootFromAiRoot(args.rootDir, args.home) ?? args.home;
+  const legacySkillsDir = join(liveRoot, ".codex", "skills");
+  const preferredSkillsDir = join(liveRoot, ".agents", "skills");
+  const legacyPluginsDir = join(liveRoot, ".codex", "plugins");
+  const preferredPluginsDir = join(liveRoot, "plugins");
+  const marketplacePath = join(
+    liveRoot,
+    ".agents",
+    "plugins",
+    "marketplace.json"
+  );
+  const conflicts: string[] = [];
+  let changed = false;
+
+  if (await moveMissingTree(legacySkillsDir, preferredSkillsDir, conflicts)) {
+    changed = true;
+  }
+
+  if (await moveMissingTree(legacyPluginsDir, preferredPluginsDir, conflicts)) {
+    changed = true;
+  }
+
+  try {
+    const current = await readFile(marketplacePath, "utf8");
+    const normalized = normalizeCodexMarketplaceText(current);
+    if (normalized !== current) {
+      await mkdir(dirname(marketplacePath), { recursive: true });
+      await writeFile(marketplacePath, normalized, "utf8");
+      changed = true;
+    }
+  } catch {
+    // Ignore missing or unreadable marketplace files.
+  }
+
+  return { changed, conflicts };
+}
+
+async function listProjectSkillNames(rootDir: string): Promise<string[]> {
+  const skillsDir = join(rootDir, "skills");
+  const entries = await readdir(skillsDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function listProjectAgentNames(rootDir: string): Promise<string[]> {
+  const agentsDir = join(rootDir, "agents");
+  const entries = await readdir(agentsDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  return entries
+    .flatMap((entry) => {
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+        return [entry.name];
+      }
+      if (entry.isFile() && entry.name.endsWith(".toml")) {
+        return [entry.name.replace(TOML_FILE_SUFFIX_RE, "")];
+      }
+      return [];
+    })
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function listProjectMcpNames(rootDir: string): Promise<string[]> {
+  const trackedPaths = [
+    join(rootDir, "mcp", "servers.json"),
+    join(rootDir, "mcp", "mcp.json"),
+  ];
+
+  for (const candidate of trackedPaths) {
+    try {
+      const raw = await Bun.file(candidate).text();
+      const parsed = JSON.parse(raw) as unknown;
+      const servers = extractServersObject(parsed) ?? {};
+      return Object.keys(servers).sort((a, b) => a.localeCompare(b));
+    } catch {
+      // Try next candidate.
+    }
+  }
+
+  return [];
+}
+
+async function hasProjectGlobalDocs(rootDir: string): Promise<boolean> {
+  return (
+    (await pathExists(join(rootDir, "AGENTS.global.md"))) ||
+    (await pathExists(join(rootDir, "AGENTS.override.global.md")))
+  );
+}
+
+async function hasProjectToolRules(
+  rootDir: string,
+  tool: string
+): Promise<boolean> {
+  const rulesDir = join(rootDir, "tools", tool, "rules");
+  const entries = await readdir(rulesDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  return entries.some(
+    (entry) => entry.isFile() && entry.name.endsWith(".rules")
+  );
+}
+
+async function hasProjectToolConfig(
+  rootDir: string,
+  tool: string
+): Promise<boolean> {
+  return (
+    (await pathExists(join(rootDir, "tools", tool, "config.toml"))) ||
+    (await pathExists(join(rootDir, "tools", tool, "config.local.toml")))
+  );
+}
+
+async function planProjectSyncPolicyRepair(args: {
+  home: string;
+  rootDir: string;
+}): Promise<{
+  needed: boolean;
+  toolPolicies: Record<
+    string,
+    {
+      skills?: string[];
+      agents?: string[];
+      mcpServers?: string[];
+      globalDocs?: boolean;
+      toolRules?: boolean;
+      toolConfig?: boolean;
+    }
+  >;
+}> {
+  if (projectRootFromAiRoot(args.rootDir, args.home) == null) {
+    return { needed: false, toolPolicies: {} };
+  }
+
+  const managedState = await loadManagedState(args.home, args.rootDir);
+  const managedTools = Object.keys(managedState.tools).sort((a, b) =>
+    a.localeCompare(b)
+  );
+  if (managedTools.length === 0) {
+    return { needed: false, toolPolicies: {} };
+  }
+
+  const configuredTools = new Set(
+    await loadConfiguredProjectSyncTools({ rootDir: args.rootDir })
+  );
+  const [skills, agents, mcpServers, globalDocs] = await Promise.all([
+    listProjectSkillNames(args.rootDir),
+    listProjectAgentNames(args.rootDir),
+    listProjectMcpNames(args.rootDir),
+    hasProjectGlobalDocs(args.rootDir),
+  ]);
+
+  const toolPolicies: Record<
+    string,
+    {
+      skills?: string[];
+      agents?: string[];
+      mcpServers?: string[];
+      globalDocs?: boolean;
+      toolRules?: boolean;
+      toolConfig?: boolean;
+    }
+  > = {};
+
+  for (const tool of managedTools) {
+    if (configuredTools.has(tool)) {
+      continue;
+    }
+    const [toolRules, toolConfig] = await Promise.all([
+      hasProjectToolRules(args.rootDir, tool),
+      hasProjectToolConfig(args.rootDir, tool),
+    ]);
+
+    if (
+      skills.length === 0 &&
+      agents.length === 0 &&
+      mcpServers.length === 0 &&
+      !globalDocs &&
+      !toolRules &&
+      !toolConfig
+    ) {
+      continue;
+    }
+
+    toolPolicies[tool] = {
+      ...(skills.length > 0 ? { skills } : {}),
+      ...(agents.length > 0 ? { agents } : {}),
+      ...(mcpServers.length > 0 ? { mcpServers } : {}),
+      ...(globalDocs ? { globalDocs: true } : {}),
+      ...(toolRules ? { toolRules: true } : {}),
+      ...(toolConfig ? { toolConfig: true } : {}),
+    };
+  }
+
+  return {
+    needed: Object.keys(toolPolicies).length > 0,
+    toolPolicies,
+  };
+}
+
+async function repairProjectSyncPolicy(args: {
+  home: string;
+  rootDir: string;
+}): Promise<{ changed: boolean; path?: string; tools: string[] }> {
+  const plan = await planProjectSyncPolicyRepair(args);
+  if (!plan.needed) {
+    return { changed: false, tools: [] };
+  }
+  const result = await writeProjectSyncPolicy({
+    rootDir: args.rootDir,
+    toolPolicies: plan.toolPolicies,
+    targetFile: "config.local.toml",
+  });
+  return {
+    changed: result.changed,
+    path: result.path,
+    tools: Object.keys(plan.toolPolicies).sort((a, b) => a.localeCompare(b)),
+  };
+}
+
 function printHelp() {
   console.log(`fclt doctor — inspect and repair local fclt state
 
@@ -258,6 +536,12 @@ export async function doctorCommand(argv: string[]) {
     let stateRepaired = false;
     let stateConflicts: string[] = [];
     let autosyncRepaired = false;
+    let codexAuthoringRepaired = false;
+    let codexAuthoringConflicts: string[] = [];
+    let projectSyncRepairNeeded = false;
+    let projectSyncRepaired = false;
+    let projectSyncRepairTools: string[] = [];
+    let projectSyncRepairPath: string | undefined;
     if (repair) {
       rootConfigRepaired = await repairLegacyRootConfig(home);
     }
@@ -266,6 +550,28 @@ export async function doctorCommand(argv: string[]) {
       stateRepaired = stateRepair.changed;
       stateConflicts = stateRepair.conflicts;
       autosyncRepaired = await repairAutosyncServices(home, rootDir);
+      const authoringRepair = await repairLegacyCodexAuthoringLayout({
+        home,
+        rootDir,
+      });
+      codexAuthoringRepaired = authoringRepair.changed;
+      codexAuthoringConflicts = authoringRepair.conflicts;
+      const projectSyncRepair = await repairProjectSyncPolicy({
+        home,
+        rootDir,
+      });
+      projectSyncRepaired = projectSyncRepair.changed;
+      projectSyncRepairTools = projectSyncRepair.tools;
+      projectSyncRepairPath = projectSyncRepair.path;
+    } else {
+      const projectSyncPlan = await planProjectSyncPolicyRepair({
+        home,
+        rootDir,
+      });
+      projectSyncRepairNeeded = projectSyncPlan.needed;
+      projectSyncRepairTools = Object.keys(projectSyncPlan.toolPolicies).sort(
+        (a, b) => a.localeCompare(b)
+      );
     }
     const generated = facultAiIndexPath(home, rootDir);
     const generatedGraph = facultAiGraphPath(home, rootDir);
@@ -300,6 +606,27 @@ export async function doctorCommand(argv: string[]) {
     if (autosyncRepaired) {
       console.log("Repaired autosync launch agent configuration.");
     }
+    if (codexAuthoringRepaired) {
+      console.log(
+        "Migrated legacy Codex authoring paths to .agents/skills, .agents/plugins/marketplace.json, and plugins/."
+      );
+    }
+    if (codexAuthoringConflicts.length) {
+      console.log("Skipped conflicting Codex authoring paths:");
+      for (const conflict of codexAuthoringConflicts) {
+        console.log(`- ${conflict}`);
+      }
+    }
+    if (projectSyncRepaired && projectSyncRepairPath) {
+      console.log(
+        `Materialized explicit project sync policy in ${projectSyncRepairPath} for: ${projectSyncRepairTools.join(", ")}`
+      );
+    }
+    if (!repair && projectSyncRepairNeeded) {
+      console.log(
+        `Project sync is still implicit for managed tools (${projectSyncRepairTools.join(", ")}). Run \`fclt doctor --repair\` to write explicit [project_sync.<tool>] entries.`
+      );
+    }
 
     if (result.source === "generated") {
       console.log("AI index is healthy.");

package/src/global-docs.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { renderCanonicalText } from "./agents";
 import { builtinSyncDefaultsEnabled, facultBuiltinPackRoot } from "./builtin";
 import { projectRootFromAiRoot } from "./paths";
+import { projectSyncAllowsToolSurface } from "./project-sync";
 import { renderSnippetText } from "./snippets";
 
 export interface GlobalDocPlan {
@@ -156,13 +157,24 @@ function stringifyTomlObject(obj: Record<string, unknown>): string {
 }
 
 async function listGlobalDocSources(args: {
+  homeDir: string;
   rootDir: string;
   tool: string;
   toolHome: string;
 }): Promise<SourceTarget[]> {
-  const { rootDir, tool, toolHome } = args;
+  const { homeDir, rootDir, tool, toolHome } = args;
+  if (
+    !(await projectSyncAllowsToolSurface({
+      homeDir,
+      rootDir,
+      tool,
+      surface: "globalDocs",
+    }))
+  ) {
+    return [];
+  }
   const targets = globalDocTargetPaths(tool, toolHome);
-  const useBuiltinDefaults = await builtinSyncDefaultsEnabled(rootDir);
+  const useBuiltinDefaults = await builtinSyncDefaultsEnabled(rootDir, homeDir);
 
   const candidates: SourceTarget[] = [];
   const base = join(rootDir, "AGENTS.global.md");
@@ -309,9 +321,20 @@ export async function syncToolGlobalDocs(args: {
 }
 
 async function listToolRules(args: {
+  homeDir: string;
   rootDir: string;
   tool: string;
 }): Promise<{ sourcePath: string; targetPath: string }[]> {
+  if (
+    !(await projectSyncAllowsToolSurface({
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      tool: args.tool,
+      surface: "toolRules",
+    }))
+  ) {
+    return [];
+  }
   const sourceRoot = join(args.rootDir, "tools", args.tool, "rules");
   const entries = await readdir(sourceRoot, { withFileTypes: true }).catch(
     () => [] as import("node:fs").Dirent[]
@@ -425,6 +448,24 @@ export async function planToolConfigSync(args: {
   existingConfigPath?: string;
   previouslyManaged?: boolean;
 }): Promise<ToolConfigPlan> {
+  if (
+    !(await projectSyncAllowsToolSurface({
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      tool: args.tool,
+      surface: "toolConfig",
+    }))
+  ) {
+    return {
+      targetPath: args.toolConfigPath,
+      write: false,
+      remove: false,
+      contents: null,
+      sourcePath: join(args.rootDir, "tools", args.tool, "config.toml"),
+      managedConfig: false,
+    };
+  }
+
   const sourcePath = join(args.rootDir, "tools", args.tool, "config.toml");
   const localSourcePath = join(
     args.rootDir,