facult 2.7.1 → 2.7.2

package/package.json

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

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/index-builder.ts

@@ -69,6 +69,12 @@ export interface AgentEntry {
   path: string;
   description?: string;
   lastModifiedAt?: string;
+  enabledFor?: string[];
+  trusted?: boolean;
+  trustedAt?: string;
+  trustedBy?: string;
+  auditStatus?: "pending" | "passed" | "flagged";
+  lastAuditAt?: string;
 }
 
 export interface SnippetEntry {
@@ -197,6 +203,53 @@ function extractIndexMeta(entry: unknown): {
   };
 }
 
+function findPreviousEntryByCanonicalRef(
+  previous: Record<string, unknown> | undefined,
+  canonicalRef: string | undefined,
+  fallbackName: string
+): unknown {
+  if (!previous) {
+    return undefined;
+  }
+  if (typeof canonicalRef === "string") {
+    for (const value of Object.values(previous)) {
+      if (!isPlainObject(value)) {
+        continue;
+      }
+      if (value.canonicalRef === canonicalRef) {
+        return value;
+      }
+    }
+  }
+  const legacyFallback = previous[fallbackName];
+  if (
+    isPlainObject(legacyFallback) &&
+    typeof legacyFallback.canonicalRef !== "string"
+  ) {
+    return legacyFallback;
+  }
+  return undefined;
+}
+
+function findPreviousMcpEntry(
+  previous: Record<string, unknown> | undefined,
+  canonicalRef: string | undefined,
+  name: string
+): unknown {
+  if (!previous) {
+    return undefined;
+  }
+  const candidate = previous[name];
+  if (!isPlainObject(candidate)) {
+    return undefined;
+  }
+  return typeof candidate.canonicalRef !== "string" ||
+    (typeof canonicalRef === "string" &&
+      candidate.canonicalRef === canonicalRef)
+    ? candidate
+    : undefined;
+}
+
 function stripQuotes(s: string): string {
   const t = s.trim();
   if (
@@ -489,8 +542,12 @@ async function indexSkills(
       const md = await Bun.file(skillMd).text();
       const { description, tags } = parseSkillMarkdown(md);
       const name = basename(d);
-
-      const prev = previous?.[name];
+      const canonicalRef = canonicalRefForPath(source, "skills", d);
+      const prev = findPreviousEntryByCanonicalRef(
+        previous,
+        canonicalRef,
+        name
+      );
       const meta = extractIndexMeta(prev);
 
       out[name] = {
@@ -498,7 +555,7 @@ async function indexSkills(
         path: d,
         description,
         tags,
-        canonicalRef: canonicalRefForPath(source, "skills", d),
+        canonicalRef,
         lastModifiedAt: await statIsoTime(skillMd),
         enabledFor: meta.enabledFor,
         trusted: meta.trusted ?? false,
@@ -550,12 +607,13 @@ async function indexMcpServers(
 
     const lm = await statIsoTime(mcpConfigPath);
     for (const name of Object.keys(serversObj).sort()) {
-      const prev = previous?.[name];
+      const canonicalRef = canonicalRefForPath(source, "mcp", mcpConfigPath);
+      const prev = findPreviousMcpEntry(previous, canonicalRef, name);
       const meta = extractIndexMeta(prev);
       out[name] = {
         name,
         path: mcpConfigPath,
-        canonicalRef: canonicalRefForPath(source, "mcp", mcpConfigPath),
+        canonicalRef,
         lastModifiedAt: lm,
         definition: serversObj[name],
         enabledFor: meta.enabledFor,
@@ -576,7 +634,8 @@ async function indexMcpServers(
 
 async function indexAgents(
   agentsDir: string,
-  source: IndexedSource
+  source: IndexedSource,
+  previous?: Record<string, unknown>
 ): Promise<Record<string, AgentEntry>> {
   const out: Record<string, AgentEntry> = {};
   const files: string[] = [];
@@ -596,6 +655,9 @@ async function indexAgents(
   for (const p of files) {
     const name =
       basename(p) === "agent.toml" ? basename(dirname(p)) : basename(p);
+    const canonicalRef = canonicalRefForPath(source, "agents", p);
+    const prev = findPreviousEntryByCanonicalRef(previous, canonicalRef, name);
+    const meta = extractIndexMeta(prev);
     let description: string | undefined;
     try {
       const raw = await Bun.file(p).text();
@@ -611,8 +673,14 @@ async function indexAgents(
       name,
       path: p,
       description,
-      canonicalRef: canonicalRefForPath(source, "agents", p),
+      canonicalRef,
       lastModifiedAt: await statIsoTime(p),
+      enabledFor: meta.enabledFor,
+      trusted: meta.trusted ?? false,
+      trustedAt: meta.trustedAt,
+      trustedBy: meta.trustedBy,
+      auditStatus: meta.auditStatus ?? "pending",
+      lastAuditAt: meta.lastAuditAt,
       ...entryScopeMeta(source),
     };
   }
@@ -782,6 +850,9 @@ async function indexSourceAssets(
   const prevSkills = isPlainObject(previousIndex?.skills)
     ? (previousIndex?.skills as Record<string, unknown>)
     : undefined;
+  const prevAgents = isPlainObject(previousIndex?.agents)
+    ? (previousIndex?.agents as Record<string, unknown>)
+    : undefined;
   const prevMcpMap =
     isPlainObject(previousIndex?.mcp) &&
     isPlainObject((previousIndex.mcp as Record<string, unknown>).servers)
@@ -795,7 +866,7 @@ async function indexSourceAssets(
     await Promise.all([
       indexSkills(skillsDir, source, prevSkills),
       indexMcpServers(canonicalMcpPath, source, prevMcpMap),
-      indexAgents(agentsDir, source),
+      indexAgents(agentsDir, source, prevAgents),
       indexSnippets(snippetsDir, source),
       indexInstructions(instructionsDir, source),
       indexToolAssets(toolsDir, source),