facult 2.3.1 → 2.5.0

package/README.md

@@ -260,9 +260,17 @@ fclt index
 
 Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
 
-Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work. Facult-owned generated/config/runtime state lives inside the active canonical root:
-- global: `~/.ai/.facult`
-- project: `<repo>/.ai/.facult`
+Canonical source root: `~/.ai` for global work, or `<repo>/.ai` for project-local work.
+
+Generated AI state that belongs with the canonical root lives inside that root:
+- global: `~/.ai/.facult/ai/...`
+- project: `<repo>/.ai/.facult/ai/...`
+
+Machine-local operational state lives outside the canonical root:
+- macOS state: `~/Library/Application Support/fclt/...`
+- macOS cache: `~/Library/Caches/fclt/...`
+- Linux/other state: `${XDG_STATE_HOME:-~/.local/state}/fclt/...`
+- Linux/other cache: `${XDG_CACHE_HOME:-~/.cache}/fclt/...`
 
 ### 3b. Bootstrap a repo-local `.ai`
 
@@ -420,7 +428,8 @@ Typical layout:
 
 Important split:
 - `.ai/` is canonical source
-- `.ai/.facult/` is Facult-owned generated state, trust state, managed tool state, autosync state, and caches
+- `.ai/.facult/ai/` is generated AI state that belongs with the canonical root
+- machine-local Facult state such as managed-tool state, autosync runtime/config, install metadata, and launcher caches lives outside `.ai/`
 - tool homes such as `.codex/` and `.claude/` are rendered outputs
 - the generated capability graph lives at `.ai/.facult/ai/graph.json`
 
@@ -714,6 +723,13 @@ Files are written to:
 - `~/.codex/automations/<name>/automation.toml`
 - `~/.codex/automations/<name>/memory.md`
 
+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.
+
 Example project automation:
 
 ```bash
@@ -774,17 +790,21 @@ fclt <command> --help
 
 ### State and report files
 
-Under `~/.ai/.facult/`:
+Under canonical generated AI state (`~/.ai/.facult/` or `<repo>/.ai/.facult/`):
 - `sources.json` (latest inventory scan state)
 - `consolidated.json` (consolidation state)
-- `managed.json` (managed tool state)
 - `ai/index.json` (generated canonical AI inventory)
 - `audit/static-latest.json` (latest static audit report)
 - `audit/agent-latest.json` (latest agent audit report)
 - `trust/sources.json` (source trust policy state)
-- `autosync/services/*.json` (autosync service configs)
-- `autosync/state/*.json` (autosync runtime state)
-- `autosync/logs/*` (autosync service logs)
+
+Under machine-local Facult state:
+- `install.json` (machine-local install metadata)
+- `global/managed.json` or `projects/<slug-hash>/managed.json` (managed tool state)
+- `.../autosync/services/*.json` (autosync service configs)
+- `.../autosync/state/*.json` (autosync runtime state)
+- `.../autosync/logs/*` (autosync service logs)
+- `runtime/<version>/<platform-arch>/...` under the machine-local cache root (npm launcher binary cache)
 
 ### Config reference
 
@@ -890,7 +910,7 @@ Release behavior:
 4. npm publish runs only after binary asset upload succeeds (`publish-npm` depends on `publish-assets`).
 5. Published release assets include platform binaries, `fclt-install.sh`, `facult-install.sh`, and `SHA256SUMS`.
 6. When `HOMEBREW_TAP_TOKEN` is configured, the release workflow also updates the Homebrew tap at `hack-dance/homebrew-tap`.
-7. The npm package launcher resolves your platform, downloads the matching release binary, caches it under `~/.ai/.facult/runtime/<version>/<platform-arch>/`, and runs it.
+7. The npm package launcher resolves your platform, downloads the matching release binary, caches it under the machine-local cache root (`~/Library/Caches/fclt/runtime/...` on macOS or `${XDG_CACHE_HOME:-~/.cache}/fclt/runtime/...` elsewhere), and runs it.
 
 Current prebuilt binary targets:
 - `darwin-x64`

package/bin/fclt.cjs

@@ -16,6 +16,43 @@ const PACKAGE_NAME = "facult";
 const DOWNLOAD_RETRIES = 12;
 const DOWNLOAD_RETRY_DELAY_MS = 5000;
 
+function isHelpLikeArgs(args) {
+  return (
+    args.length === 0 ||
+    args.includes("--help") ||
+    args.includes("-h") ||
+    args[0] === "help"
+  );
+}
+
+function localStateRoot(home) {
+  const override = String(process.env.FACULT_LOCAL_STATE_DIR || "").trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "fclt");
+  }
+  const xdg = String(process.env.XDG_STATE_HOME || "").trim();
+  return xdg
+    ? path.join(path.resolve(xdg), "fclt")
+    : path.join(home, ".local", "state", "fclt");
+}
+
+function localCacheRoot(home) {
+  const override = String(process.env.FACULT_CACHE_DIR || "").trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Caches", "fclt");
+  }
+  const xdg = String(process.env.XDG_CACHE_HOME || "").trim();
+  return xdg
+    ? path.join(path.resolve(xdg), "fclt")
+    : path.join(home, ".cache", "fclt");
+}
+
 async function main() {
   const resolved = resolveTarget();
   if (!resolved.ok) {
@@ -30,7 +67,7 @@ async function main() {
   }
 
   const home = os.homedir();
-  const cacheRoot = path.join(home, ".ai", ".facult", "runtime");
+  const cacheRoot = path.join(localCacheRoot(home), "runtime");
   const installDir = path.join(
     cacheRoot,
     version,
@@ -39,9 +76,34 @@ async function main() {
   const binaryName = resolved.platform === "windows" ? "fclt.exe" : "fclt";
   const binaryPath = path.join(installDir, binaryName);
   const sourceEntry = path.join(__dirname, "..", "src", "index.ts");
+  const args = process.argv.slice(2);
   let installedBinaryThisRun = false;
 
   if (!(await fileExists(binaryPath))) {
+    const packageManager = detectPackageManager();
+    const hasSourceFallback = await canUseSourceFallback(sourceEntry);
+    const incompleteCache = await hasIncompleteRuntimeCache({
+      installDir,
+      binaryName,
+    });
+
+    if (incompleteCache) {
+      await removeIncompleteRuntimeTemps({ installDir, binaryName });
+    }
+
+    if (hasSourceFallback && (incompleteCache || isHelpLikeArgs(args))) {
+      return runSourceFallback({
+        sourceEntry,
+        version,
+        packageManager,
+        reason: new Error(
+          incompleteCache
+            ? "incomplete cached runtime download"
+            : "runtime binary missing for help-like command"
+        ),
+      });
+    }
+
     const tag = `v${version}`;
     const assetName = `${PACKAGE_NAME}-${version}-${resolved.platform}-${resolved.arch}${resolved.ext}`;
     const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${assetName}`;
@@ -95,7 +157,6 @@ async function main() {
     });
   }
 
-  const args = process.argv.slice(2);
   const result = spawnSync(binaryPath, args, {
     stdio: "inherit",
     env: {
@@ -281,6 +342,28 @@ async function fileExists(filePath) {
   }
 }
 
+async function hasIncompleteRuntimeCache({ installDir, binaryName }) {
+  try {
+    const entries = await fsp.readdir(installDir);
+    return entries.some((entry) => entry.startsWith(`${binaryName}.tmp-`));
+  } catch {
+    return false;
+  }
+}
+
+async function removeIncompleteRuntimeTemps({ installDir, binaryName }) {
+  try {
+    const entries = await fsp.readdir(installDir);
+    await Promise.all(
+      entries
+        .filter((entry) => entry.startsWith(`${binaryName}.tmp-`))
+        .map((entry) => safeUnlink(path.join(installDir, entry)))
+    );
+  } catch {
+    // Ignore missing runtime dirs while cleaning stale temp files.
+  }
+}
+
 async function safeUnlink(filePath) {
   try {
     await fsp.unlink(filePath);
@@ -295,7 +378,7 @@ function sleep(ms) {
 
 async function writeInstallState(state) {
   const home = os.homedir();
-  const installStateDir = path.join(home, ".ai", ".facult");
+  const installStateDir = localStateRoot(home);
   const installStatePath = path.join(installStateDir, "install.json");
   await fsp.mkdir(installStateDir, { recursive: true });
   await fsp.writeFile(

package/package.json

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

package/src/adapters/factory.ts

@@ -0,0 +1,228 @@
+import { basename, extname } from "node:path";
+import { renderCanonicalText } from "../agents";
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type {
+  CanonicalMcpConfig,
+  CanonicalMcpServer,
+  ParsedManagedAgentFile,
+  RenderManagedAgentOptions,
+  ToolAdapter,
+} from "./types";
+import { detectExplicitVersion } from "./version";
+
+const FRONTMATTER_LINE_SPLIT_REGEX = /\r?\n/;
+const FACTORY_AGENT_FRONTMATTER_REGEX =
+  /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const LEADING_WHITESPACE_REGEX = /^\s+/;
+const TRAILING_WHITESPACE_REGEX = /\s+$/;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function escapeTomlMultiline(value: string): string {
+  return value.replace(/"""/g, '\\"""');
+}
+
+function escapeYamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function stringifyFrontmatter(values: Record<string, string>): string {
+  return Object.entries(values)
+    .map(([key, value]) => `${key}: ${escapeYamlString(value)}`)
+    .join("\n");
+}
+
+function parseFrontmatterScalar(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    const quote = trimmed[0];
+    const inner = trimmed.slice(1, -1);
+    if (quote === '"') {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        return inner;
+      }
+    }
+    return inner;
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of text.split(FRONTMATTER_LINE_SPLIT_REGEX)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const separator = trimmed.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, separator).trim();
+    const value = parseFrontmatterScalar(trimmed.slice(separator + 1));
+    if (key) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function normalizeFactoryServer(
+  server: CanonicalMcpServer
+): CanonicalMcpServer {
+  if (!isPlainObject(server.vendorExtensions)) {
+    return server;
+  }
+
+  const { type, ...vendorExtensions } = server.vendorExtensions;
+  return {
+    ...server,
+    transport:
+      typeof type === "string" && !server.transport ? type : server.transport,
+    vendorExtensions:
+      Object.keys(vendorExtensions).length > 0 ? vendorExtensions : undefined,
+  };
+}
+
+function parseFactoryMcp(config: unknown): CanonicalMcpConfig {
+  const parsed = parseMcpConfig(config);
+  for (const [name, server] of Object.entries(parsed.servers)) {
+    parsed.servers[name] = normalizeFactoryServer({ ...server });
+  }
+  return parsed;
+}
+
+function generateFactoryMcp(
+  canonical: CanonicalMcpConfig
+): Record<string, unknown> {
+  const generated = generateMcpConfig(canonical, "mcpServers");
+  const servers = generated.mcpServers;
+  if (!isPlainObject(servers)) {
+    return generated;
+  }
+
+  for (const [name, value] of Object.entries(servers)) {
+    if (!isPlainObject(value)) {
+      continue;
+    }
+    const { transport, ...server } = value as Record<string, unknown>;
+    const inferredType =
+      (typeof transport === "string" ? transport : undefined) ??
+      (typeof server.url === "string"
+        ? "http"
+        : typeof server.command === "string"
+          ? "stdio"
+          : undefined);
+    if (inferredType && typeof server.type !== "string") {
+      server.type = inferredType;
+    }
+    if (typeof server.disabled !== "boolean") {
+      server.disabled = false;
+    }
+    servers[name] = server;
+  }
+
+  return generated;
+}
+
+async function renderFactoryAgent(
+  options: RenderManagedAgentOptions
+): Promise<string> {
+  const parsed = Bun.TOML.parse(options.raw) as Record<string, unknown>;
+  const name =
+    typeof parsed.name === "string"
+      ? parsed.name
+      : basename(options.targetPath, extname(options.targetPath));
+  const description =
+    typeof parsed.description === "string" ? parsed.description : undefined;
+  const instructions =
+    typeof parsed.developer_instructions === "string"
+      ? parsed.developer_instructions
+      : "";
+  const renderedInstructions = await renderCanonicalText(instructions, {
+    homeDir: options.homeDir,
+    rootDir: options.rootDir,
+    projectRoot: options.projectRoot,
+    targetTool: options.tool,
+    targetPath: options.targetPath,
+  });
+
+  const frontmatter = stringifyFrontmatter({
+    name,
+    ...(description ? { description } : {}),
+    model: "inherit",
+  });
+  const body = renderedInstructions.trim();
+
+  return body
+    ? `---\n${frontmatter}\n---\n\n${body}\n`
+    : `---\n${frontmatter}\n---\n`;
+}
+
+async function parseFactoryManagedAgentFile(
+  path: string
+): Promise<ParsedManagedAgentFile | null> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  const raw = await file.text();
+  const match = raw.match(FACTORY_AGENT_FRONTMATTER_REGEX);
+  if (!match) {
+    return null;
+  }
+
+  const [, frontmatterRaw, bodyRaw] = match;
+  const frontmatter = parseFrontmatter(frontmatterRaw ?? "");
+  const name = frontmatter.name || basename(path, extname(path));
+  const description = frontmatter.description || undefined;
+  const body = (bodyRaw ?? "")
+    .replace(LEADING_WHITESPACE_REGEX, "")
+    .replace(TRAILING_WHITESPACE_REGEX, "");
+  const lines = [`name = ${JSON.stringify(name)}`];
+  if (description) {
+    lines.push(`description = ${JSON.stringify(description)}`);
+  }
+  lines.push("", 'developer_instructions = """');
+  if (body) {
+    lines.push(escapeTomlMultiline(body));
+  }
+  lines.push('"""', "");
+
+  return {
+    name,
+    raw: lines.join("\n"),
+    sourcePath: path,
+  };
+}
+
+export const factoryAdapter: ToolAdapter = {
+  id: "factory",
+  name: "Factory",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.factory/mcp.json",
+    skills: ["~/.factory/skills", ".factory/skills"],
+    agents: ["~/.factory/droids", ".factory/droids"],
+  }),
+  parseMcp: (config) => parseFactoryMcp(config),
+  generateMcp: (canonical) => generateFactoryMcp(canonical),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+  agentFileExtension: ".md",
+  renderAgent: async (options) => await renderFactoryAgent(options),
+  parseManagedAgentFile: async (path) =>
+    await parseFactoryManagedAgentFile(path),
+};

package/src/adapters/index.ts

@@ -3,6 +3,7 @@ import { claudeDesktopAdapter } from "./claude-desktop";
 import { clawdbotAdapter } from "./clawdbot";
 import { codexAdapter } from "./codex";
 import { cursorAdapter } from "./cursor";
+import { factoryAdapter } from "./factory";
 import { referenceAdapter } from "./reference";
 import type { ResolveVersionOptions, ToolAdapter } from "./types";
 
@@ -64,6 +65,7 @@ export async function resolveAdapterVersion(
 registerAdapter(referenceAdapter);
 registerAdapter(cursorAdapter);
 registerAdapter(codexAdapter);
+registerAdapter(factoryAdapter);
 registerAdapter(claudeCliAdapter);
 registerAdapter(claudeDesktopAdapter);
 registerAdapter(clawdbotAdapter);

package/src/adapters/types.ts

@@ -18,6 +18,21 @@ export interface CanonicalSkill {
   path?: string;
 }
 
+export interface RenderManagedAgentOptions {
+  raw: string;
+  rootDir: string;
+  tool: string;
+  targetPath: string;
+  homeDir?: string;
+  projectRoot?: string;
+}
+
+export interface ParsedManagedAgentFile {
+  name: string;
+  raw: string;
+  sourcePath: string;
+}
+
 export interface AdapterDefaultPaths {
   mcp?: string;
   skills?: string | string[];
@@ -34,6 +49,13 @@ export interface ToolAdapter {
   parseSkills?: (skillsDir: string) => Promise<CanonicalSkill[]>;
   generateMcp?: (canonical: CanonicalMcpConfig, version?: string) => unknown;
   generateSkillsDir?: (skills: CanonicalSkill[]) => Promise<void>;
+  agentFileExtension?: string;
+  renderAgent?: (
+    options: RenderManagedAgentOptions
+  ) => Promise<string> | string;
+  parseManagedAgentFile?: (
+    path: string
+  ) => Promise<ParsedManagedAgentFile | null>;
   getDefaultPaths?: () => AdapterDefaultPaths;
 }