facult 2.7.4 → 2.8.0

package/README.md

@@ -43,6 +43,7 @@ Recommended global install:
 brew tap hack-dance/tap
 brew install hack-dance/tap/fclt
 fclt --help
+fclt --version
 ```
 
 Package-manager install:
@@ -89,10 +90,26 @@ fclt self-update --version 0.0.1
 
 ```bash
 fclt scan --show-duplicates
+fclt status
+fclt inventory --json
 ```
 
 `scan` is read-only. It inspects local configs and reports what `fclt` found without changing files.
 
+`status` reports the active canonical root, managed-tool state, generated index/graph state, writeback/proposal queue state, and high-signal sync risks.
+
+`inventory` is the stable machine-readable discovery surface for agent harnesses. It returns a JSON catalog of discovered MCP servers, skills, and instruction/rule assets across known tool configs and configured scan roots. MCP definitions are redacted by default, including env values, inline `KEY=value` args, bearer tokens, and secret-looking URL query params, but include safe auth metadata such as env keys, env references, and whether inline secret values were found.
+
+Useful inventory slices:
+
+```bash
+fclt inventory --json --global
+fclt inventory --json --project
+fclt inventory --json --tool codex
+```
+
+Use `mcpCapabilities` for the de-duplicated agent-facing MCP view. Use `mcpServers` when you need raw per-source occurrences for diagnostics.
+
 If you want a repo-local `.ai`:
 
 ```bash
@@ -137,6 +154,8 @@ If you run these commands inside a repo that has `<repo>/.ai`, `fclt` targets th
 
 ```bash
 fclt list skills
+fclt inventory --json
+fclt status --json
 fclt show instruction:WRITING
 fclt show mcp:github
 fclt find verification
@@ -344,13 +363,14 @@ version = 1
 [project_sync.codex]
 skills = ["hack-cli", "hack-tickets"]
 agents = ["review-operator"]
+automations = ["project-check"]
 mcp_servers = ["github"]
 global_docs = true
 tool_rules = true
 tool_config = true
 ```
 
-That policy applies to project-managed tool renders, including assets inherited from the merged global index. If you want a global skill inside a repo-local managed Codex output, name it explicitly here. `fclt doctor --repair` can materialize repo-local project assets into `config.local.toml` for already-managed project roots.
+That policy applies to project-managed tool renders, including assets inherited from the merged global index. If you want a global skill or shared Codex automation inside project-managed output, name it explicitly here. `fclt doctor --repair` can materialize repo-local project assets into `config.local.toml` for already-managed project roots.
 
 ### Snippets
 
@@ -513,6 +533,7 @@ Recommended security flow:
 - Inventory and discovery
 ```bash
 fclt scan [--from <path>] [--json] [--show-duplicates]
+fclt inventory [--from <path>] [--json] [--show-secrets]
 fclt list [skills|mcp|agents|snippets|instructions] [--enabled-for <tool>] [--untrusted] [--flagged] [--pending]
 fclt show <name>
 fclt show instruction:<name>
@@ -603,7 +624,7 @@ When Codex is in managed mode, canonical automation sources live under:
 - `~/.ai/automations/<name>/...` for global automation state
 - `<repo>/.ai/automations/<name>/...` for project-scoped canonical state
 
-Managed sync renders those canonical automation directories into the shared live Codex automation store at `~/.codex/automations/` and only removes automation files that were previously rendered by the same canonical root.
+Managed sync renders global canonical automation directories into the shared live Codex automation store at `~/.codex/automations/` and only removes automation files that were previously rendered by the same canonical root. Project-scoped automation sources are default-deny; add their names to `[project_sync.codex].automations` before project managed sync can render them into that shared live store.
 
 Example project automation:
 

package/package.json

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

package/src/adapters/codex.ts

@@ -12,7 +12,7 @@ export const codexAdapter: ToolAdapter = {
     mcp: "~/.codex/mcp.json",
     skills: ["~/.agents/skills", "~/.codex/skills"],
     agents: "~/.codex/agents",
-    config: "~/.config/openai/codex.json",
+    config: "~/.codex/config.toml",
   }),
   parseMcp: (config) => parseMcpConfig(config),
   generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),

package/src/ai.ts

@@ -1,5 +1,6 @@
+import { existsSync } from "node:fs";
 import { appendFile, mkdir, readdir, readFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { ensureAiGraphPath } from "./ai-state";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import type { AssetScope, GraphNodeKind } from "./graph";
@@ -242,7 +243,17 @@ function canonicalRefToPath(args: {
     return join(facultRootDir(args.homeDir), args.ref.slice("@ai/".length));
   }
   if (args.ref.startsWith("@project/")) {
-    return join(args.rootDir, args.ref.slice("@project/".length));
+    const relPath = args.ref.slice("@project/".length);
+    const canonicalPath = join(args.rootDir, relPath);
+    const projectRoot = projectRootFromAiRoot(args.rootDir, args.homeDir);
+    if (projectRoot) {
+      const projectPath = join(projectRoot, relPath);
+      if (existsSync(canonicalPath)) {
+        return canonicalPath;
+      }
+      return existsSync(projectPath) ? projectPath : canonicalPath;
+    }
+    return canonicalPath;
   }
   return null;
 }
@@ -337,7 +348,27 @@ async function resolveAssetSelection(args: {
   });
   const node = resolveGraphNode(graph, args.asset);
   if (!node) {
-    throw new Error(`Asset not found in graph: ${args.asset}`);
+    const projectRoot = projectRootFromAiRoot(args.rootDir, args.homeDir);
+    if (projectRoot) {
+      const resolvedPath = resolve(projectRoot, args.asset);
+      const relPath = relative(projectRoot, resolvedPath);
+      if (
+        relPath &&
+        !relPath.startsWith("..") &&
+        !relPath.includes("\0") &&
+        (await fileExists(resolvedPath))
+      ) {
+        const normalizedRef = relPath.replaceAll("\\", "/");
+        return {
+          assetRef: `@project/${normalizedRef}`,
+          assetId: `file:project:${normalizedRef}`,
+          assetType: "file",
+        };
+      }
+    }
+    throw new Error(
+      `Asset not found in graph: ${args.asset}. Run "fclt graph show <selector>" to check indexed assets, or use a project-relative file path that exists.`
+    );
   }
   return {
     assetRef: node.canonicalRef ?? node.id,
@@ -1514,6 +1545,11 @@ async function writebackCommand(argv: string[]) {
     return;
   }
 
+  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+    console.log(writebackHelp());
+    return;
+  }
+
   const rootDir = resolveCliContextRoot({
     rootArg: parsed.rootArg,
     scope: parsed.scope,
@@ -1625,6 +1661,11 @@ async function evolveCommand(argv: string[]) {
     return;
   }
 
+  if (parsed.argv.includes("--help") || parsed.argv.includes("-h")) {
+    console.log(evolveHelp());
+    return;
+  }
+
   const rootDir = resolveCliContextRoot({
     rootArg: parsed.rootArg,
     scope: parsed.scope,

package/src/doctor.ts

@@ -103,6 +103,51 @@ async function pathExists(pathValue: string): Promise<boolean> {
   }
 }
 
+async function hasCanonicalSource(rootDir: string): Promise<boolean> {
+  const fileCandidates = [
+    "config.toml",
+    "config.local.toml",
+    "AGENTS.global.md",
+    "AGENTS.override.global.md",
+  ];
+  for (const relPath of fileCandidates) {
+    if (await pathExists(join(rootDir, relPath))) {
+      return true;
+    }
+  }
+
+  const dirCandidates = [
+    "agents",
+    "automations",
+    "instructions",
+    "mcp",
+    "rules",
+    "skills",
+    "snippets",
+    "tools",
+  ];
+  for (const relPath of dirCandidates) {
+    const entries = await readdir(join(rootDir, relPath)).catch(
+      () => [] as string[]
+    );
+    if (entries.some((entry) => !entry.startsWith("."))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function isGeneratedOnlyProjectRoot(args: {
+  home: string;
+  rootDir: string;
+}): Promise<boolean> {
+  if (projectRootFromAiRoot(args.rootDir, args.home) == null) {
+    return false;
+  }
+  return !(await hasCanonicalSource(args.rootDir));
+}
+
 async function hashFile(pathValue: string): Promise<string> {
   const data = await readFile(pathValue);
   return createHash("sha256").update(data).digest("hex");
@@ -344,6 +389,23 @@ async function listProjectAgentNames(rootDir: string): Promise<string[]> {
     .sort((a, b) => a.localeCompare(b));
 }
 
+async function listProjectAutomationNames(rootDir: string): Promise<string[]> {
+  const automationsDir = join(rootDir, "automations");
+  const entries = await readdir(automationsDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) {
+      continue;
+    }
+    if (await pathExists(join(automationsDir, entry.name, "automation.toml"))) {
+      names.push(entry.name);
+    }
+  }
+  return names.sort((a, b) => a.localeCompare(b));
+}
+
 async function listProjectMcpNames(rootDir: string): Promise<string[]> {
   const trackedPaths = [
     join(rootDir, "mcp", "servers.json"),
@@ -404,6 +466,7 @@ async function planProjectSyncPolicyRepair(args: {
     {
       skills?: string[];
       agents?: string[];
+      automations?: string[];
       mcpServers?: string[];
       globalDocs?: boolean;
       toolRules?: boolean;
@@ -426,18 +489,21 @@ async function planProjectSyncPolicyRepair(args: {
   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 [skills, agents, automations, mcpServers, globalDocs] =
+    await Promise.all([
+      listProjectSkillNames(args.rootDir),
+      listProjectAgentNames(args.rootDir),
+      listProjectAutomationNames(args.rootDir),
+      listProjectMcpNames(args.rootDir),
+      hasProjectGlobalDocs(args.rootDir),
+    ]);
 
   const toolPolicies: Record<
     string,
     {
       skills?: string[];
       agents?: string[];
+      automations?: string[];
       mcpServers?: string[];
       globalDocs?: boolean;
       toolRules?: boolean;
@@ -457,6 +523,7 @@ async function planProjectSyncPolicyRepair(args: {
     if (
       skills.length === 0 &&
       agents.length === 0 &&
+      automations.length === 0 &&
       mcpServers.length === 0 &&
       !globalDocs &&
       !toolRules &&
@@ -468,6 +535,7 @@ async function planProjectSyncPolicyRepair(args: {
     toolPolicies[tool] = {
       ...(skills.length > 0 ? { skills } : {}),
       ...(agents.length > 0 ? { agents } : {}),
+      ...(automations.length > 0 ? { automations } : {}),
       ...(mcpServers.length > 0 ? { mcpServers } : {}),
       ...(globalDocs ? { globalDocs: true } : {}),
       ...(toolRules ? { toolRules: true } : {}),
@@ -627,6 +695,13 @@ export async function doctorCommand(argv: string[]) {
         `Project sync is still implicit for managed tools (${projectSyncRepairTools.join(", ")}). Run \`fclt doctor --repair\` to write explicit [project_sync.<tool>] entries.`
       );
     }
+    if (await isGeneratedOnlyProjectRoot({ home, rootDir })) {
+      console.log(
+        "Project .ai root contains generated state only. Canonical project source is missing, so managed project sync should be treated as unsafe until source is initialized, restored, or management is detached."
+      );
+      process.exitCode = 1;
+      return;
+    }
 
     if (result.source === "generated") {
       console.log("AI index is healthy.");

package/src/index.ts

@@ -25,6 +25,7 @@ import {
 } from "./graph-query";
 import type {
   AgentEntry,
+  AutomationEntry,
   FacultIndex,
   InstructionEntry,
   McpEntry,
@@ -43,12 +44,19 @@ import {
 } from "./query";
 import { parseJsonLenient } from "./util/json";
 
-type ListKind = "skills" | "mcp" | "agents" | "snippets" | "instructions";
+type ListKind =
+  | "skills"
+  | "mcp"
+  | "agents"
+  | "automations"
+  | "snippets"
+  | "instructions";
 
 const LIST_KINDS: ListKind[] = [
   "skills",
   "mcp",
   "agents",
+  "automations",
   "snippets",
   "instructions",
 ];
@@ -65,6 +73,7 @@ export interface FindCommandOptions {
 }
 
 type GraphCommandKind = "show" | "deps" | "dependents";
+type ShowKind = ListKind | "mcp";
 
 interface ContextualCommandOptions {
   rootArg?: string;
@@ -99,6 +108,14 @@ function printHelp() {
             headers: ["Command", "Purpose"],
             rows: [
               ["scan", "Scan local tool configs and discovered assets"],
+              [
+                "inventory",
+                "Print a JSON inventory of usable skills, instructions, and MCP servers",
+              ],
+              [
+                "status",
+                "Show active roots, managed tools, graph/index, and sync risks",
+              ],
               [
                 "audit",
                 "Run security audits with interactive or scripted flows",
@@ -177,7 +194,7 @@ function printListHelp() {
           title: "Usage",
           lines: renderBullets([
             renderCode(
-              "fclt list [skills|mcp|agents|snippets|instructions] [options]"
+              "fclt list [skills|mcp|agents|automations|snippets|instructions] [options]"
             ),
             renderCode("fclt list"),
           ]),
@@ -494,6 +511,32 @@ function auditBadge(status?: string): string {
   return renderBadge("audit pending", "warn");
 }
 
+function showKindForToken(token: string): ShowKind | null {
+  switch (token) {
+    case "agent":
+    case "agents":
+      return "agents";
+    case "automation":
+    case "automations":
+      return "automations";
+    case "instruction":
+    case "instructions":
+      return "instructions";
+    case "mcp":
+    case "mcp-server":
+    case "mcp-servers":
+      return "mcp";
+    case "skill":
+    case "skills":
+      return "skills";
+    case "snippet":
+    case "snippets":
+      return "snippets";
+    default:
+      return null;
+  }
+}
+
 function displayDescription(value?: string): string {
   const normalized = value
     ?.trim()
@@ -571,6 +614,7 @@ async function listCommand(argv: string[]) {
     | SkillEntry[]
     | McpEntry[]
     | AgentEntry[]
+    | AutomationEntry[]
     | SnippetEntry[]
     | InstructionEntry[] = [];
 
@@ -584,6 +628,20 @@ async function listCommand(argv: string[]) {
     case "agents":
       entries = filterAgents(index.agents ?? {}, opts.filters);
       break;
+    case "automations":
+      entries = Object.values(index.automations ?? {}).filter((entry) => {
+        if (
+          opts.filters.sourceKind &&
+          entry.sourceKind !== opts.filters.sourceKind
+        ) {
+          return false;
+        }
+        if (opts.filters.scope && entry.scope !== opts.filters.scope) {
+          return false;
+        }
+        return true;
+      });
+      break;
     case "snippets":
       entries = filterSnippets(index.snippets ?? {}, opts.filters);
       break;
@@ -646,11 +704,17 @@ async function listCommand(argv: string[]) {
       };
     }
 
-    const detailEntry = entry as AgentEntry | SnippetEntry | InstructionEntry;
+    const detailEntry = entry as
+      | AgentEntry
+      | AutomationEntry
+      | SnippetEntry
+      | InstructionEntry;
     return {
       title: entry.name,
       meta: sourceLabel(entry),
-      description: displayDescription(detailEntry.description),
+      description: displayDescription(
+        "description" in detailEntry ? detailEntry.description : undefined
+      ),
     };
   });
 
@@ -834,45 +898,59 @@ async function showCommand(argv: string[]) {
     return;
   }
 
+  const rootDir = resolveCliContextRoot({
+    rootArg: context.rootArg,
+    scope: context.scopeMode,
+    cwd: process.cwd(),
+  });
+
   let index: FacultIndex;
   try {
-    index = await loadIndex({
-      rootDir: resolveCliContextRoot({
-        rootArg: context.rootArg,
-        scope: context.scopeMode,
-        cwd: process.cwd(),
-      }),
-    });
+    index = await loadIndex({ rootDir });
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));
     process.exitCode = 1;
     return;
   }
 
-  let kind: ListKind | "mcp" = "skills";
+  let kind: ShowKind = "skills";
   let name = raw;
+  const colonIndex = raw.indexOf(":");
+  if (colonIndex > 0) {
+    const tokenKind = showKindForToken(raw.slice(0, colonIndex));
+    if (tokenKind) {
+      kind = tokenKind;
+      name = raw.slice(colonIndex + 1);
+    }
+  }
 
-  if (raw.startsWith("mcp:")) {
-    kind = "mcp";
-    name = raw.slice("mcp:".length);
-  } else if (raw.startsWith("instruction:")) {
-    kind = "instructions";
-    name = raw.slice("instruction:".length);
-  } else if (raw.startsWith("instructions:")) {
-    kind = "instructions";
-    name = raw.slice("instructions:".length);
+  try {
+    const graph = await loadGraph({ rootDir });
+    const node = resolveGraphNode(graph, raw, {
+      sourceKind: context.sourceKind,
+      scope: scopeFilterForMode(context.scopeMode),
+    });
+    const graphKind = node ? showKindForToken(node.kind) : null;
+    if (node && graphKind) {
+      kind = graphKind;
+      name = node.name;
+    }
+  } catch {
+    // A missing or stale graph should not make basic index-backed show fail.
   }
 
   let entry:
     | SkillEntry
     | McpEntry
     | AgentEntry
+    | AutomationEntry
     | SnippetEntry
     | InstructionEntry
     | null = null;
   const skill = index.skills[name];
   const mcpServer = index.mcp?.servers?.[name];
   const agent = index.agents?.[name];
+  const automation = index.automations?.[name];
   const snippet = index.snippets?.[name];
   const instruction = index.instructions?.[name];
   const matchesContext = (candidate: {
@@ -896,6 +974,15 @@ async function showCommand(argv: string[]) {
   } else if (kind === "skills" && agent && matchesContext(agent)) {
     kind = "agents";
     entry = agent;
+  } else if (
+    kind === "automations" &&
+    automation &&
+    matchesContext(automation)
+  ) {
+    entry = automation;
+  } else if (kind === "skills" && automation && matchesContext(automation)) {
+    kind = "automations";
+    entry = automation;
   } else if (kind === "skills" && snippet && matchesContext(snippet)) {
     kind = "snippets";
     entry = snippet;
@@ -1105,6 +1192,7 @@ async function graphCommand(argv: string[]) {
 }
 
 async function adaptersCommand(argv: string[]) {
+  const json = argv.includes("--json");
   if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
     console.log(
       renderPage({
@@ -1122,6 +1210,21 @@ async function adaptersCommand(argv: string[]) {
   }
   const { getAllAdapters } = await import("./adapters");
   const adapters = getAllAdapters();
+  if (json) {
+    console.log(
+      JSON.stringify(
+        adapters.map((adapter) => ({
+          id: adapter.id,
+          name: adapter.name,
+          versions: adapter.versions,
+          defaultPaths: adapter.getDefaultPaths?.() ?? {},
+        })),
+        null,
+        2
+      )
+    );
+    return;
+  }
   if (!adapters.length) {
     console.log(
       renderPage({
@@ -1158,6 +1261,12 @@ async function main(argv: string[]) {
     return;
   }
 
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    const { packageVersion } = await import("./status");
+    console.log(await packageVersion());
+    return;
+  }
+
   // Convenience: allow `fclt --show-duplicates` as shorthand for `fclt scan --show-duplicates`.
   if (cmd === "--show-duplicates") {
     const { scanCommand } = await import("./scan");
@@ -1169,6 +1278,14 @@ async function main(argv: string[]) {
     case "scan":
       await import("./scan").then(({ scanCommand }) => scanCommand(rest));
       return;
+    case "inventory":
+      await import("./inventory").then(({ inventoryCommand }) =>
+        inventoryCommand(rest)
+      );
+      return;
+    case "status":
+      await import("./status").then(({ statusCommand }) => statusCommand(rest));
+      return;
     case "audit":
       await import("./audit").then(({ auditCommand }) => auditCommand(rest));
       return;