facult 2.7.3 → 2.7.7

package/README.md

@@ -344,13 +344,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
 
@@ -603,7 +604,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.3",
+  "version": "2.7.7",
   "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,

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;
@@ -177,7 +186,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 +503,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 +606,7 @@ async function listCommand(argv: string[]) {
     | SkillEntry[]
     | McpEntry[]
     | AgentEntry[]
+    | AutomationEntry[]
     | SnippetEntry[]
     | InstructionEntry[] = [];
 
@@ -584,6 +620,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 +696,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 +890,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 +966,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 +1184,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 +1202,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({