facult 2.7.4 → 2.8.0

package/src/mcp-config.ts

@@ -32,6 +32,11 @@ export function extractServersObject(
     return null;
   }
   const raw = parsed as Record<string, unknown>;
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.endsWith(".mcpServers") && isPlainObject(value)) {
+      return value as Record<string, unknown>;
+    }
+  }
   const servers =
     (raw.servers as Record<string, unknown> | undefined) ??
     (raw.mcpServers as Record<string, unknown> | undefined) ??

package/src/project-sync.ts

@@ -2,12 +2,17 @@ import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { projectRootFromAiRoot } from "./paths";
 
-type ProjectSyncNamedSurface = "skills" | "agents" | "mcpServers";
+type ProjectSyncNamedSurface =
+  | "skills"
+  | "agents"
+  | "automations"
+  | "mcpServers";
 type ProjectSyncToolSurface = "globalDocs" | "toolRules" | "toolConfig";
 
 interface ProjectSyncToolPolicy {
   skills: string[];
   agents: string[];
+  automations: string[];
   mcpServers: string[];
   globalDocs: boolean;
   toolRules: boolean;
@@ -69,6 +74,7 @@ function projectSyncToolPolicyFromObject(
   return {
     skills: parseStringList(table.skills),
     agents: parseStringList(table.agents),
+    automations: parseStringList(table.automations ?? table.automation),
     mcpServers: parseStringList(table.mcp_servers ?? table.mcp),
     globalDocs: parseBoolean(table.global_docs ?? table.docs),
     toolRules: parseBoolean(table.tool_rules ?? table.rules),
@@ -104,6 +110,7 @@ function emptyPolicy(): ProjectSyncToolPolicy {
   return {
     skills: [],
     agents: [],
+    automations: [],
     mcpServers: [],
     globalDocs: false,
     toolRules: false,
@@ -150,7 +157,9 @@ export async function projectSyncAllowsNamedAsset(args: {
       ? policy.skills
       : args.surface === "agents"
         ? policy.agents
-        : policy.mcpServers;
+        : args.surface === "automations"
+          ? policy.automations
+          : policy.mcpServers;
   return includesExplicitName(allowed, args.name);
 }
 
@@ -256,6 +265,9 @@ export async function writeProjectSyncPolicy(args: {
     const mergedPolicy: ProjectSyncToolPolicy = {
       skills: parseStringList(partialPolicy.skills ?? previousPolicy.skills),
       agents: parseStringList(partialPolicy.agents ?? previousPolicy.agents),
+      automations: parseStringList(
+        partialPolicy.automations ?? previousPolicy.automations
+      ),
       mcpServers: parseStringList(
         partialPolicy.mcpServers ?? previousPolicy.mcpServers
       ),
@@ -267,6 +279,7 @@ export async function writeProjectSyncPolicy(args: {
     projectSync[tool] = {
       skills: mergedPolicy.skills,
       agents: mergedPolicy.agents,
+      automations: mergedPolicy.automations,
       mcp_servers: mergedPolicy.mcpServers,
       global_docs: mergedPolicy.globalDocs,
       tool_rules: mergedPolicy.toolRules,

package/src/scan.ts

@@ -1189,6 +1189,44 @@ async function buildFromRootResult(args: {
     }
   };
 
+  const scanAiDir = async (aiDir: string) => {
+    await scanToolDotDir(aiDir);
+
+    for (const name of ["servers.json", "mcp.json"]) {
+      const p = join(aiDir, "mcp", name);
+      if ((await statSafe(p))?.isFile) {
+        if (addResult(1)) {
+          mcpConfigPaths.add(p);
+        } else {
+          return;
+        }
+      }
+    }
+
+    for (const name of ["AGENTS.global.md", "AGENTS.override.global.md"]) {
+      const p = join(aiDir, name);
+      if ((await statSafe(p))?.isFile) {
+        addAsset("agents-instructions", p);
+      }
+    }
+
+    const instructionsDir = join(aiDir, "instructions");
+    if ((await statSafe(instructionsDir))?.isDir) {
+      const files = await listFilesRecursive(instructionsDir, {
+        ignore: args.opts.ignoreDirNames,
+        maxFiles: 2000,
+      });
+      for (const f of files) {
+        if (f.endsWith(".md")) {
+          addAsset("canonical-instruction", f);
+        }
+        if (truncated) {
+          break;
+        }
+      }
+    }
+  };
+
   const MCP_NAMES = new Set([
     "mcp.json",
     "mcp.config.json",
@@ -1317,6 +1355,10 @@ async function buildFromRootResult(args: {
         await scanToolDotDir(child);
         continue;
       }
+      if (name === ".ai") {
+        await scanAiDir(child);
+        continue;
+      }
 
       // Skills directories are typically called "skills"; scan them and don't descend further.
       if (name === "skills") {
@@ -2268,6 +2310,7 @@ Notes:
 
 Options:
   --json              Print full JSON (ScanResult)
+  --persist           Persist scan state when using --json
   --show-duplicates   Print duplicates for skills, MCP servers, and hook assets
   --tui               Render scan output in an interactive TUI (skills list)
   --no-config-from    Disable default scan roots from ~/.ai/.facult/config.json (scanFrom)
@@ -2287,6 +2330,7 @@ export async function scanCommand(argv: string[]) {
   }
 
   const json = argv.includes("--json");
+  const persist = argv.includes("--persist") || !json;
   const showDuplicates = argv.includes("--show-duplicates");
   const tui = argv.includes("--tui");
   const noConfigFrom = argv.includes("--no-config-from");
@@ -2427,7 +2471,9 @@ export async function scanCommand(argv: string[]) {
       maxResults: fromMaxResults,
     },
   });
-  await writeState(res);
+  if (persist) {
+    await writeState(res);
+  }
 
   if (json) {
     if (tui) {

package/src/status.ts

@@ -0,0 +1,268 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
+import { loadManagedState } from "./manage";
+import {
+  facultAiGraphPath,
+  facultAiIndexPath,
+  facultAiProposalDir,
+  facultAiWritebackQueuePath,
+  facultMachineStateDir,
+  facultRootDir,
+  projectRootFromAiRoot,
+} from "./paths";
+import { parseJsonLenient } from "./util/json";
+
+export interface StatusIssue {
+  severity: "info" | "warning" | "error";
+  code: string;
+  message: string;
+}
+
+export interface FacultStatus {
+  version: 1;
+  packageVersion: string;
+  cwd: string;
+  globalRoot: string;
+  contextRoot: string;
+  projectRoot: string | null;
+  machineStateDir: string;
+  managedTools: string[];
+  generatedOnlyProjectRoot: boolean;
+  index: {
+    path: string;
+    exists: boolean;
+  };
+  graph: {
+    path: string;
+    exists: boolean;
+  };
+  writeback: {
+    queuePath: string;
+    pendingCount: number;
+    proposalDir: string;
+    proposalCount: number;
+  };
+  issues: StatusIssue[];
+}
+
+async function fileExists(pathValue: string): Promise<boolean> {
+  try {
+    return (await Bun.file(pathValue).stat()).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function dirHasVisibleEntries(pathValue: string): Promise<boolean> {
+  const entries = await readdir(pathValue).catch(() => [] as string[]);
+  return entries.some((entry) => !entry.startsWith("."));
+}
+
+async function hasCanonicalSource(rootDir: string): Promise<boolean> {
+  for (const relPath of [
+    "config.toml",
+    "config.local.toml",
+    "AGENTS.global.md",
+    "AGENTS.override.global.md",
+  ]) {
+    if (await fileExists(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  for (const relPath of [
+    "agents",
+    "automations",
+    "instructions",
+    "mcp",
+    "rules",
+    "skills",
+    "snippets",
+    "tools",
+  ]) {
+    if (await dirHasVisibleEntries(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function countPendingWritebacks(
+  homeDir: string,
+  rootDir: string
+): Promise<number> {
+  const { listWritebacks } = await import("./ai");
+  const rows = await listWritebacks({ homeDir, rootDir }).catch(() => []);
+  return rows.filter(
+    (row) =>
+      row.status !== "dismissed" &&
+      row.status !== "promoted" &&
+      row.status !== "resolved" &&
+      row.status !== "superseded"
+  ).length;
+}
+
+async function countActiveProposals(
+  homeDir: string,
+  rootDir: string
+): Promise<number> {
+  const { listProposals } = await import("./ai");
+  const rows = await listProposals({ homeDir, rootDir }).catch(() => []);
+  return rows.filter(
+    (row) =>
+      row.status !== "applied" &&
+      row.status !== "failed" &&
+      row.status !== "rejected" &&
+      row.status !== "superseded"
+  ).length;
+}
+
+export async function packageVersion(): Promise<string> {
+  const packagePath = join(dirname(import.meta.dir), "package.json");
+  const parsed = parseJsonLenient(await Bun.file(packagePath).text());
+  if (
+    parsed &&
+    typeof parsed === "object" &&
+    !Array.isArray(parsed) &&
+    typeof (parsed as Record<string, unknown>).version === "string"
+  ) {
+    const version = (parsed as Record<string, unknown>).version;
+    return typeof version === "string" ? version : "unknown";
+  }
+  return "unknown";
+}
+
+export async function buildStatus(opts?: {
+  cwd?: string;
+  homeDir?: string;
+  rootArg?: string;
+  scope?: "merged" | "global" | "project";
+}): Promise<FacultStatus> {
+  const homeDir = opts?.homeDir ?? process.env.HOME ?? "";
+  const cwd = opts?.cwd ?? process.cwd();
+  const globalRoot = facultRootDir(homeDir);
+  const contextRoot = resolveCliContextRoot({
+    homeDir,
+    cwd,
+    rootArg: opts?.rootArg,
+    scope: opts?.scope,
+  });
+  const projectRoot = projectRootFromAiRoot(contextRoot, homeDir);
+  const generatedOnlyProjectRoot =
+    projectRoot !== null && !(await hasCanonicalSource(contextRoot));
+  const indexPath = facultAiIndexPath(homeDir, contextRoot);
+  const graphPath = facultAiGraphPath(homeDir, contextRoot);
+  const queuePath = facultAiWritebackQueuePath(homeDir, contextRoot);
+  const proposalDir = facultAiProposalDir(homeDir, contextRoot);
+  const managed = await loadManagedState(homeDir, contextRoot);
+
+  const issues: StatusIssue[] = [];
+  if (generatedOnlyProjectRoot) {
+    issues.push({
+      severity: "warning",
+      code: "project-generated-only",
+      message:
+        "Project .ai contains generated state only; managed project sync should stay paused until canonical source is restored or initialized.",
+    });
+  }
+  if (!(await fileExists(indexPath))) {
+    issues.push({
+      severity: "info",
+      code: "missing-index",
+      message:
+        'Generated AI index is missing. Run "fclt index" after canonical source changes.',
+    });
+  }
+  if (!(await fileExists(graphPath))) {
+    issues.push({
+      severity: "info",
+      code: "missing-graph",
+      message: 'Generated AI graph is missing. Run "fclt index" to rebuild it.',
+    });
+  }
+
+  return {
+    version: 1,
+    packageVersion: await packageVersion(),
+    cwd,
+    globalRoot,
+    contextRoot,
+    projectRoot,
+    machineStateDir: facultMachineStateDir(homeDir, contextRoot),
+    managedTools: Object.keys(managed.tools).sort(),
+    generatedOnlyProjectRoot,
+    index: {
+      path: indexPath,
+      exists: await fileExists(indexPath),
+    },
+    graph: {
+      path: graphPath,
+      exists: await fileExists(graphPath),
+    },
+    writeback: {
+      queuePath,
+      pendingCount: await countPendingWritebacks(homeDir, contextRoot),
+      proposalDir,
+      proposalCount: await countActiveProposals(homeDir, contextRoot),
+    },
+    issues,
+  };
+}
+
+function printStatus(status: FacultStatus) {
+  console.log(`fclt ${status.packageVersion}`);
+  console.log(`cwd: ${status.cwd}`);
+  console.log(`global root: ${status.globalRoot}`);
+  console.log(`context root: ${status.contextRoot}`);
+  console.log(`project root: ${status.projectRoot ?? "(none)"}`);
+  console.log(`machine state: ${status.machineStateDir}`);
+  console.log(`managed tools: ${status.managedTools.join(", ") || "(none)"}`);
+  console.log(
+    `index: ${status.index.exists ? "present" : "missing"} (${status.index.path})`
+  );
+  console.log(
+    `graph: ${status.graph.exists ? "present" : "missing"} (${status.graph.path})`
+  );
+  console.log(
+    `writeback: ${status.writeback.pendingCount} queued, ${status.writeback.proposalCount} proposals`
+  );
+  if (status.issues.length > 0) {
+    console.log("issues:");
+    for (const issue of status.issues) {
+      console.log(`- [${issue.severity}] ${issue.code}: ${issue.message}`);
+    }
+  }
+}
+
+export async function statusCommand(argv: string[]) {
+  const parsed = parseCliContextArgs(argv);
+  if (
+    parsed.argv.includes("--help") ||
+    parsed.argv.includes("-h") ||
+    parsed.argv[0] === "help"
+  ) {
+    console.log(`fclt status
+
+Usage:
+  fclt status [--json] [--global|--project|--root <path>]
+
+Print the active canonical root, managed-tool state, generated index/graph state,
+writeback counts, and high-signal sync risks.
+`);
+    return;
+  }
+
+  const status = await buildStatus({
+    rootArg: parsed.rootArg,
+    scope: parsed.scope,
+    cwd: process.cwd(),
+  });
+
+  if (parsed.argv.includes("--json")) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  printStatus(status);
+}