facult 2.4.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.4.0",
+  "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;
 }
 

package/src/index-builder.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getAdapter } from "./adapters";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   type AssetScope,
@@ -31,6 +32,10 @@ interface AssetEntryBase {
   shadow?: boolean;
 }
 
+function managedAgentFileExtension(tool: string): string {
+  return getAdapter(tool)?.agentFileExtension ?? ".toml";
+}
+
 export interface SkillEntry {
   name: string;
   path: string;
@@ -1213,6 +1218,7 @@ function registerManagedRenderedTargets(args: {
   const nodes = args.graph.nodes;
   for (const toolState of toolStates) {
     if (toolState.agentsDir) {
+      const extension = managedAgentFileExtension(toolState.tool);
       for (const entry of Object.values(args.index.agents)) {
         const sourceNodeId = sourceNodeIdForEntry({
           kind: "agent",
@@ -1221,7 +1227,10 @@ function registerManagedRenderedTargets(args: {
         if (!nodes[sourceNodeId]) {
           continue;
         }
-        const targetPath = join(toolState.agentsDir, `${entry.name}.toml`);
+        const targetPath = join(
+          toolState.agentsDir,
+          `${entry.name}${extension}`
+        );
         registerRenderedTargetNode({
           graph: args.graph,
           currentScope: args.currentScope,

package/src/manage.ts

@@ -203,6 +203,19 @@ function defaultToolPaths(
       skillsDir: toolBase(".antigravity", "skills"),
       mcpConfig: toolBase(".antigravity", "mcp.json"),
     },
+    factory: {
+      tool: "factory",
+      skillsDir: projectRoot
+        ? join(projectRoot, ".factory", "skills")
+        : homePath(home, ".factory", "skills"),
+      mcpConfig: projectRoot
+        ? join(projectRoot, ".factory", "mcp.json")
+        : homePath(home, ".factory", "mcp.json"),
+      agentsDir: projectRoot
+        ? join(projectRoot, ".factory", "droids")
+        : homePath(home, ".factory", "droids"),
+      toolHome: projectRoot ? undefined : homePath(home, ".factory"),
+    },
   };
 
   const adapterDefaults = (tool: string): ToolPaths | null => {
@@ -436,6 +449,69 @@ async function loadCanonicalAgents(
   return await loadAgentsFromRoot(homePath(rootDir, "agents"));
 }
 
+function managedAgentFileExtension(tool: string): string {
+  return getAdapter(tool)?.agentFileExtension ?? ".toml";
+}
+
+async function renderManagedAgentFile(args: {
+  agent: { name: string; sourcePath: string; raw: string };
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  targetPath: string;
+}): Promise<string> {
+  const adapter = getAdapter(args.tool);
+  if (adapter?.renderAgent) {
+    return await adapter.renderAgent({
+      raw: args.agent.raw,
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      projectRoot:
+        projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+      tool: args.tool,
+      targetPath: args.targetPath,
+    });
+  }
+
+  return await renderCanonicalText(args.agent.raw, {
+    homeDir: args.homeDir,
+    rootDir: args.rootDir,
+    projectRoot: projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+    targetTool: args.tool,
+    targetPath: args.targetPath,
+  });
+}
+
+async function loadManagedAgentsFromTool(args: {
+  tool: string;
+  agentsDir: string;
+}): Promise<{ name: string; sourcePath: string; raw: string }[]> {
+  const adapter = getAdapter(args.tool);
+  if (!adapter?.parseManagedAgentFile) {
+    return await loadAgentsFromRoot(args.agentsDir);
+  }
+
+  const extension = managedAgentFileExtension(args.tool);
+  const entries = await readdir(args.agentsDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  const out: { name: string; sourcePath: string; raw: string }[] = [];
+
+  for (const entry of entries) {
+    if (!(entry.isFile() && entry.name.endsWith(extension))) {
+      continue;
+    }
+    const sourcePath = join(args.agentsDir, entry.name);
+    const parsed = await adapter.parseManagedAgentFile(sourcePath);
+    if (!parsed) {
+      continue;
+    }
+    out.push(parsed);
+  }
+
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 interface AutomationEntry {
   name: string;
   sourceDir: string;
@@ -637,14 +713,15 @@ async function planAgentFileChanges({
   const contents = new Map<string, string>();
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
+  const extension = managedAgentFileExtension(tool);
 
   for (const agent of agents) {
-    const target = homePath(agentsDir, `${agent.name}.toml`);
-    const rendered = await renderCanonicalText(agent.raw, {
+    const target = homePath(agentsDir, `${agent.name}${extension}`);
+    const rendered = await renderManagedAgentFile({
+      agent,
       homeDir,
       rootDir,
-      projectRoot: projectRootFromAiRoot(rootDir, homeDir) ?? undefined,
-      targetTool: tool,
+      tool,
       targetPath: target,
     });
     desiredPaths.add(target);
@@ -659,7 +736,7 @@ async function planAgentFileChanges({
   const remove = new Set<string>();
 
   for (const entry of existing) {
-    if (!(entry.isFile() && entry.name.endsWith(".toml"))) {
+    if (!(entry.isFile() && entry.name.endsWith(extension))) {
       continue;
     }
     const p = homePath(agentsDir, entry.name);
@@ -1214,11 +1291,15 @@ function logManagedImportPlan(tool: string, plan: ExistingManagedImportPlan) {
 }
 
 async function planExistingToolAgentAdoption(args: {
+  tool: string;
   rootDir: string;
   agentsDir: string;
 }): Promise<ExistingManagedImportPlan> {
   const plan = emptyManagedImportPlan();
-  const agents = await loadAgentsFromRoot(args.agentsDir);
+  const agents = await loadManagedAgentsFromTool({
+    tool: args.tool,
+    agentsDir: args.agentsDir,
+  });
   for (const agent of agents) {
     const canonicalPath = join(
       args.rootDir,
@@ -1245,12 +1326,16 @@ async function planExistingToolAgentAdoption(args: {
 }
 
 async function adoptExistingToolAgents(args: {
+  tool: string;
   rootDir: string;
   agentsDir: string;
   conflictMode: "keep-canonical" | "keep-existing";
 }): Promise<ExistingManagedItem[]> {
   const adopted: ExistingManagedItem[] = [];
-  const agents = await loadAgentsFromRoot(args.agentsDir);
+  const agents = await loadManagedAgentsFromTool({
+    tool: args.tool,
+    agentsDir: args.agentsDir,
+  });
   for (const agent of agents) {
     const canonicalPath = join(
       args.rootDir,
@@ -2019,6 +2104,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
     asManagedSkillPlan(existingSkillPlan),
     toolPaths.agentsDir
       ? await planExistingToolAgentAdoption({
+          tool,
           rootDir,
           agentsDir: toolPaths.agentsDir,
         })
@@ -2142,6 +2228,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
   }
   if (toolPaths.agentsDir && opts.adoptExisting) {
     const result = await adoptExistingToolAgents({
+      tool,
       rootDir,
       agentsDir: toolPaths.agentsDir,
       conflictMode: importConflictMode,
@@ -3006,6 +3093,7 @@ async function repairManagedCanonicalContent(args: {
 
   if (args.entry.agentsBackup) {
     const items = await adoptExistingToolAgents({
+      tool: args.entry.tool,
       rootDir: args.rootDir,
       agentsDir: args.entry.agentsBackup,
       conflictMode: "keep-canonical",

package/src/scan.ts

@@ -601,6 +601,19 @@ function defaultSourceSpecs(
         "~/.codex/mcp.json",
       ],
     },
+    {
+      id: "factory",
+      name: "Factory",
+      candidates: ["~/.factory", "~/.factory/mcp.json"],
+      skillDirs: ["~/.factory/skills"],
+      configFiles: ["~/.factory/mcp.json"],
+      assets: [
+        {
+          kind: "agents-instructions",
+          patterns: ["~/.factory/AGENTS.md"],
+        },
+      ],
+    },
     {
       id: "claude",
       name: "Claude (CLI)",
@@ -784,6 +797,13 @@ function defaultSourceSpecs(
         },
       ],
     },
+    {
+      id: "factory-project",
+      name: "Factory (project)",
+      candidates: [join(cwd, ".factory")],
+      skillDirs: [join(cwd, ".factory", "skills")],
+      configFiles: [join(cwd, ".factory", "mcp.json")],
+    },
   ];
 
   if (includeGitHooks) {
@@ -1288,7 +1308,12 @@ async function buildFromRootResult(args: {
         }
         continue;
       }
-      if (name === ".codex" || name === ".agents" || name === ".clawdbot") {
+      if (
+        name === ".codex" ||
+        name === ".agents" ||
+        name === ".clawdbot" ||
+        name === ".factory"
+      ) {
         await scanToolDotDir(child);
         continue;
       }