facult 2.7.1 → 2.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "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/ai.ts

@@ -308,6 +308,7 @@ function mapGraphNodeKind(kind: GraphNodeKind): string {
     case "agent":
     case "skill":
     case "mcp":
+    case "automation":
     case "doc":
     case "rendered-target":
       return kind;

package/src/audit/update-index.ts

@@ -16,6 +16,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     skills: index.skills ?? {},
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
+    automations: index.automations ?? {},
     snippets: index.snippets ?? {},
     instructions: index.instructions ?? {},
   };

package/src/enable-disable.ts

@@ -36,6 +36,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     skills: index.skills ?? {},
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
+    automations: index.automations ?? {},
     snippets: index.snippets ?? {},
     instructions: index.instructions ?? {},
   };

package/src/graph-query.ts

@@ -12,6 +12,7 @@ type QueryableGraphKind =
   | GraphNodeKind
   | "skills"
   | "agents"
+  | "automations"
   | "snippets"
   | "instructions"
   | "docs"
@@ -34,6 +35,8 @@ const KIND_ALIASES: Record<QueryableGraphKind, GraphNodeKind> = {
   skills: "skill",
   agent: "agent",
   agents: "agent",
+  automation: "automation",
+  automations: "automation",
   snippet: "snippet",
   snippets: "snippet",
   instruction: "instruction",

package/src/graph.ts

@@ -11,6 +11,7 @@ export type GraphNodeKind =
   | "skill"
   | "mcp"
   | "agent"
+  | "automation"
   | "snippet"
   | "instruction"
   | "doc"

package/src/index-builder.ts

@@ -69,6 +69,18 @@ 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 AutomationEntry {
+  name: string;
+  path: string;
+  lastModifiedAt?: string;
 }
 
 export interface SnippetEntry {
@@ -96,6 +108,7 @@ interface ToolAssetEntry extends AssetEntryBase {
 export interface SkillEntry extends AssetEntryBase {}
 export interface McpEntry extends AssetEntryBase {}
 export interface AgentEntry extends AssetEntryBase {}
+export interface AutomationEntry extends AssetEntryBase {}
 export interface SnippetEntry extends AssetEntryBase {}
 export interface InstructionEntry extends AssetEntryBase {}
 
@@ -105,6 +118,7 @@ export interface FacultIndex {
   skills: Record<string, SkillEntry>;
   mcp: { servers: Record<string, McpEntry> };
   agents: Record<string, AgentEntry>;
+  automations?: Record<string, AutomationEntry>;
   snippets: Record<string, SnippetEntry>;
   instructions: Record<string, InstructionEntry>;
 }
@@ -121,6 +135,7 @@ interface SourceAssets {
   skills: Record<string, SkillEntry>;
   mcpServers: Record<string, McpEntry>;
   agents: Record<string, AgentEntry>;
+  automations: Record<string, AutomationEntry>;
   snippets: Record<string, SnippetEntry>;
   instructions: Record<string, InstructionEntry>;
   toolConfigs: Record<string, ToolAssetEntry>;
@@ -197,6 +212,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 (
@@ -407,6 +469,7 @@ function canonicalRefForPath(
   category:
     | "skills"
     | "agents"
+    | "automations"
     | "snippets"
     | "instructions"
     | "mcp"
@@ -489,8 +552,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 +565,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 +617,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 +644,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 +665,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,14 +683,53 @@ 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),
     };
   }
   return out;
 }
 
+async function indexAutomations(
+  automationsDir: string,
+  source: IndexedSource
+): Promise<Record<string, AutomationEntry>> {
+  const out: Record<string, AutomationEntry> = {};
+  const dirs = await listSubdirs(automationsDir);
+  for (const d of dirs) {
+    const automationToml = join(d, "automation.toml");
+    try {
+      const st = await Bun.file(automationToml).stat();
+      if (!st.isFile()) {
+        continue;
+      }
+
+      const name = basename(d);
+      out[name] = {
+        name,
+        path: automationToml,
+        canonicalRef: canonicalRefForPath(
+          source,
+          "automations",
+          automationToml
+        ),
+        lastModifiedAt: await statIsoTime(automationToml),
+        ...entryScopeMeta(source),
+      };
+    } catch {
+      // Ignore malformed automation entries.
+    }
+  }
+  return out;
+}
+
 async function indexSnippets(
   snippetsDir: string,
   source: IndexedSource
@@ -770,6 +881,7 @@ async function indexSourceAssets(
 ): Promise<SourceAssets> {
   const skillsDir = join(source.rootDir, "skills");
   const agentsDir = join(source.rootDir, "agents");
+  const automationsDir = join(source.rootDir, "automations");
   const snippetsDir = join(source.rootDir, "snippets");
   const instructionsDir = join(source.rootDir, "instructions");
   const toolsDir = join(source.rootDir, "tools");
@@ -782,6 +894,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)
@@ -791,20 +906,29 @@ async function indexSourceAssets(
         >)
       : undefined;
 
-  const [skills, mcpServers, agents, snippets, instructions, toolAssets] =
-    await Promise.all([
-      indexSkills(skillsDir, source, prevSkills),
-      indexMcpServers(canonicalMcpPath, source, prevMcpMap),
-      indexAgents(agentsDir, source),
-      indexSnippets(snippetsDir, source),
-      indexInstructions(instructionsDir, source),
-      indexToolAssets(toolsDir, source),
-    ]);
+  const [
+    skills,
+    mcpServers,
+    agents,
+    automations,
+    snippets,
+    instructions,
+    toolAssets,
+  ] = await Promise.all([
+    indexSkills(skillsDir, source, prevSkills),
+    indexMcpServers(canonicalMcpPath, source, prevMcpMap),
+    indexAgents(agentsDir, source, prevAgents),
+    indexAutomations(automationsDir, source),
+    indexSnippets(snippetsDir, source),
+    indexInstructions(instructionsDir, source),
+    indexToolAssets(toolsDir, source),
+  ]);
 
   return {
     skills,
     mcpServers,
     agents,
+    automations,
     snippets,
     instructions,
     toolConfigs: toolAssets.toolConfigs,
@@ -836,6 +960,7 @@ function registerGraphEntries<
     | "skill"
     | "mcp"
     | "agent"
+    | "automation"
     | "snippet"
     | "instruction"
     | "doc"
@@ -935,6 +1060,11 @@ function buildActiveEntryMap(
     for (const [name, entry] of Object.entries(sourceEntry.assets.agents)) {
       active.set(activeEntryKey("agent", name), sourceIdentity(entry));
     }
+    for (const [name, entry] of Object.entries(
+      sourceEntry.assets.automations
+    )) {
+      active.set(activeEntryKey("automation", name), sourceIdentity(entry));
+    }
     for (const [name, entry] of Object.entries(sourceEntry.assets.snippets)) {
       active.set(activeEntryKey("snippet", name), sourceIdentity(entry));
     }
@@ -1018,6 +1148,7 @@ async function addReferenceEdgesForEntries<
   kind:
     | "skill"
     | "agent"
+    | "automation"
     | "snippet"
     | "instruction"
     | "doc"
@@ -1172,6 +1303,7 @@ function sourceNodeIdForEntry(args: {
     | "skill"
     | "mcp"
     | "agent"
+    | "automation"
     | "snippet"
     | "instruction"
     | "doc"
@@ -1463,6 +1595,9 @@ export async function buildIndex(opts?: {
     sourceIndexes.map((entry) => entry.assets.mcpServers)
   );
   const agents = mergeByName(sourceIndexes.map((entry) => entry.assets.agents));
+  const automations = mergeByName(
+    sourceIndexes.map((entry) => entry.assets.automations)
+  );
   const snippets = mergeByName(
     sourceIndexes.map((entry) => entry.assets.snippets)
   );
@@ -1476,6 +1611,7 @@ export async function buildIndex(opts?: {
     skills,
     mcp: { servers },
     agents,
+    automations,
     snippets,
     instructions,
   };
@@ -1508,6 +1644,12 @@ export async function buildIndex(opts?: {
       "agent",
       activeSelections
     );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.automations,
+      "automation",
+      activeSelections
+    );
     registerGraphEntries(
       graph,
       sourceEntry.assets.snippets,
@@ -1562,6 +1704,12 @@ export async function buildIndex(opts?: {
       "agent",
       refsByRoot
     );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.automations,
+      "automation",
+      refsByRoot
+    );
     await addReferenceEdgesForEntries(
       graph,
       sourceEntry.assets.snippets,

package/src/trust-list.ts

@@ -234,6 +234,7 @@ export async function applyOrgTrustList(
       }),
     },
     agents: index.agents ?? {},
+    automations: index.automations ?? {},
     snippets: index.snippets ?? {},
     instructions: index.instructions ?? {},
   };

package/src/trust.ts

@@ -23,6 +23,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     skills: index.skills ?? {},
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
+    automations: index.automations ?? {},
     snippets: index.snippets ?? {},
     instructions: index.instructions ?? {},
   };