facult 2.14.0 → 2.15.1

package/src/manage.ts

@@ -15,7 +15,11 @@ import { basename, dirname, join } from "node:path";
 import { getAdapter } from "./adapters";
 import { renderCanonicalText } from "./agents";
 import { ensureAiIndexPath } from "./ai-state";
-import { builtinSyncDefaultsEnabled, facultBuiltinPackRoot } from "./builtin";
+import {
+  builtinSyncDefaultsEnabled,
+  facultBuiltinCodexPluginRoot,
+  facultBuiltinPackRoot,
+} from "./builtin";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import { renderBullets, renderCode, renderPage } from "./cli-ui";
 import { contentHash, normalizeText } from "./conflicts";
@@ -86,6 +90,8 @@ export interface ManagedState {
 
 type SyncLedgerAction = "add" | "adopt" | "remove" | "skip" | "write";
 
+const FCLT_CODEX_PLUGIN_NAME = "fclt";
+
 interface SyncLedgerEvent {
   version: 1;
   id: string;
@@ -259,7 +265,8 @@ async function isGeneratedOnlyProjectRoot(args: {
 function renderedSourceKindForPath(
   sourcePath: string
 ): ManagedRenderedTargetState["sourceKind"] {
-  return sourcePath.startsWith(facultBuiltinPackRoot())
+  return sourcePath.startsWith(facultBuiltinPackRoot()) ||
+    sourcePath.startsWith(facultBuiltinCodexPluginRoot())
     ? "builtin"
     : "canonical";
 }
@@ -328,6 +335,45 @@ function normalizeCodexMarketplaceText(text: string): string {
   }
 }
 
+function fcltCodexMarketplaceEntry(): Record<string, unknown> {
+  return {
+    name: FCLT_CODEX_PLUGIN_NAME,
+    source: {
+      source: "local",
+      path: `./plugins/${FCLT_CODEX_PLUGIN_NAME}`,
+    },
+    policy: {
+      installation: "AVAILABLE",
+      authentication: "NONE",
+    },
+    category: "Productivity",
+  };
+}
+
+function withBuiltinFcltCodexMarketplaceEntry(text: string | null): string {
+  const base =
+    text == null
+      ? {
+          name: "local",
+          interface: { displayName: "Local Plugins" },
+          plugins: [],
+        }
+      : (JSON.parse(text) as unknown);
+  if (!isPlainObject(base)) {
+    return text == null ? normalizeCodexMarketplaceText("{}") : text;
+  }
+  const plugins = Array.isArray(base.plugins) ? [...base.plugins] : [];
+  const hasFclt = plugins.some(
+    (entry) => isPlainObject(entry) && entry.name === FCLT_CODEX_PLUGIN_NAME
+  );
+  if (!hasFclt) {
+    plugins.push(fcltCodexMarketplaceEntry());
+  }
+  return normalizeCodexMarketplaceText(
+    JSON.stringify({ ...base, plugins }, null, 2)
+  );
+}
+
 function isSafeCodexPluginName(name: string): boolean {
   const trimmed = name.trim();
   return (
@@ -899,7 +945,8 @@ async function listRelativeFilesWithDotfiles(root: string): Promise<string[]> {
 }
 
 async function loadCanonicalCodexPlugins(
-  rootDir: string
+  rootDir: string,
+  homeDir?: string
 ): Promise<CanonicalPluginEntry[]> {
   const pluginsRoot = codexCanonicalPluginsRoot(rootDir);
   const entries = await readdir(pluginsRoot, { withFileTypes: true }).catch(
@@ -907,36 +954,81 @@ async function loadCanonicalCodexPlugins(
   );
   const out: CanonicalPluginEntry[] = [];
 
+  async function loadEntry(
+    name: string,
+    sourceDir: string
+  ): Promise<CanonicalPluginEntry | null> {
+    if (!(await fileExists(join(sourceDir, ".codex-plugin", "plugin.json")))) {
+      return null;
+    }
+    const files = new Map<string, Uint8Array>();
+    for (const relPath of await listRelativeFilesWithDotfiles(sourceDir)) {
+      files.set(relPath, await Bun.file(join(sourceDir, relPath)).bytes());
+    }
+    return { name, sourceDir, files };
+  }
+
   for (const entry of entries) {
     if (!entry.isDirectory() || entry.name.startsWith(".")) {
       continue;
     }
     const sourceDir = join(pluginsRoot, entry.name);
-    if (!(await fileExists(join(sourceDir, ".codex-plugin", "plugin.json")))) {
-      continue;
+    const plugin = await loadEntry(entry.name, sourceDir);
+    if (plugin) {
+      out.push(plugin);
     }
-    const files = new Map<string, Uint8Array>();
-    for (const relPath of await listRelativeFilesWithDotfiles(sourceDir)) {
-      files.set(relPath, await Bun.file(join(sourceDir, relPath)).bytes());
+  }
+
+  if (
+    (await builtinSyncDefaultsEnabled(rootDir, homeDir)) &&
+    !out.some((entry) => entry.name === FCLT_CODEX_PLUGIN_NAME)
+  ) {
+    const plugin = await loadEntry(
+      FCLT_CODEX_PLUGIN_NAME,
+      facultBuiltinCodexPluginRoot()
+    );
+    if (plugin) {
+      out.push(plugin);
     }
-    out.push({ name: entry.name, sourceDir, files });
   }
 
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-async function canonicalCodexPluginsExist(rootDir: string): Promise<boolean> {
+async function canonicalCodexPluginsExist(
+  rootDir: string,
+  homeDir?: string
+): Promise<boolean> {
   if (await fileExists(codexCanonicalPluginMarketplacePath(rootDir))) {
     return true;
   }
-  return (await loadCanonicalCodexPlugins(rootDir)).length > 0;
+  return (await loadCanonicalCodexPlugins(rootDir, homeDir)).length > 0;
 }
 
 async function loadCanonicalCodexMarketplaceText(
-  rootDir: string
+  rootDir: string,
+  homeDir?: string
 ): Promise<{ text: string | null; sourcePath: string }> {
   const sourcePath = codexCanonicalPluginMarketplacePath(rootDir);
   const raw = await readTextOrNull(sourcePath);
+  const builtinEnabled = await builtinSyncDefaultsEnabled(rootDir, homeDir);
+  if (builtinEnabled) {
+    try {
+      return {
+        text: withBuiltinFcltCodexMarketplaceEntry(raw),
+        sourcePath:
+          raw == null
+            ? join(
+                facultBuiltinCodexPluginRoot(),
+                ".codex-plugin",
+                "plugin.json"
+              )
+            : sourcePath,
+      };
+    } catch {
+      // Fall back to the canonical marketplace text if it is not JSON.
+    }
+  }
   return {
     text: raw == null ? null : normalizeCodexMarketplaceText(raw),
     sourcePath,
@@ -2919,6 +3011,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
   const pluginPreview =
     tool === "codex" && toolPaths.pluginsDir && toolPaths.pluginMarketplacePath
       ? await planCodexPluginFileChanges({
+          homeDir: home,
           rootDir,
           pluginsDir: toolPaths.pluginsDir,
           pluginMarketplacePath: toolPaths.pluginMarketplacePath,
@@ -3390,7 +3483,7 @@ async function repairManagedToolEntry(args: {
     !(next.pluginsDir && next.pluginMarketplacePath) &&
     toolPaths.pluginsDir &&
     toolPaths.pluginMarketplacePath &&
-    (await canonicalCodexPluginsExist(rootDir))
+    (await canonicalCodexPluginsExist(rootDir, homeDir))
   ) {
     if (!next.pluginsDir) {
       next.pluginsBackup = await backupPath(toolPaths.pluginsDir);
@@ -4409,6 +4502,7 @@ async function adoptExistingCodexPlugins(args: {
 }
 
 async function planCodexPluginFileChanges(args: {
+  homeDir?: string;
   rootDir: string;
   pluginsDir: string;
   pluginMarketplacePath?: string;
@@ -4423,14 +4517,20 @@ async function planCodexPluginFileChanges(args: {
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
 
-  const marketplace = await loadCanonicalCodexMarketplaceText(args.rootDir);
+  const marketplace = await loadCanonicalCodexMarketplaceText(
+    args.rootDir,
+    args.homeDir
+  );
   if (marketplace.text != null && args.pluginMarketplacePath) {
     desiredPaths.add(args.pluginMarketplacePath);
     contents.set(args.pluginMarketplacePath, marketplace.text);
     sources.set(args.pluginMarketplacePath, marketplace.sourcePath);
   }
 
-  for (const plugin of await loadCanonicalCodexPlugins(args.rootDir)) {
+  for (const plugin of await loadCanonicalCodexPlugins(
+    args.rootDir,
+    args.homeDir
+  )) {
     for (const [relPath, bytes] of plugin.files.entries()) {
       const targetPath = join(args.pluginsDir, plugin.name, relPath);
       desiredPaths.add(targetPath);
@@ -4641,6 +4741,7 @@ async function syncManagedToolEntry({
   const pluginPlan =
     tool === "codex" && entry.pluginsDir
       ? await planCodexPluginFileChanges({
+          homeDir,
           rootDir,
           pluginsDir: entry.pluginsDir,
           pluginMarketplacePath: entry.pluginMarketplacePath,

package/src/remote.ts

@@ -11,7 +11,10 @@ import {
   resolve,
 } from "node:path";
 import { isCancel, multiselect, select, text } from "@clack/prompts";
-import { facultBuiltinPackRoot } from "./builtin";
+import {
+  builtinOperatingModelInstallRelPath,
+  facultBuiltinPackRoot,
+} from "./builtin";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   renderBullets,
@@ -22,7 +25,11 @@ import {
   renderTable,
 } from "./cli-ui";
 import { buildIndex } from "./index-builder";
-import { facultRootDir, readFacultConfig } from "./paths";
+import {
+  facultRootDir,
+  projectRootFromAiRoot,
+  readFacultConfig,
+} from "./paths";
 import {
   assertManifestIntegrity,
   assertManifestSignature,
@@ -1341,6 +1348,84 @@ function serializeBuiltinPackManifest(manifest: BuiltinPackManifest): string {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
+const OPERATING_MODEL_SNIPPET_FRAME = `## Working mode
+
+<!-- fclty:global/baseline -->
+<!-- /fclty:global/baseline -->
+
+<!-- fclty:global/core/work-units -->
+<!-- /fclty:global/core/work-units -->
+
+<!-- fclty:global/core/feedback-loops -->
+<!-- /fclty:global/core/feedback-loops -->
+
+<!-- fclty:global/core/verification -->
+<!-- /fclty:global/core/verification -->
+
+<!-- fclty:global/core/writeback -->
+<!-- /fclty:global/core/writeback -->
+
+## Shared instruction sources
+
+- For work-unit definition and scope clarification, read \${refs.work_units}.
+- For identifying, improving, and validating feedback loops, read \${refs.feedback_loops}.
+- For verification and anti-false-positive checks, read \${refs.verification}.
+- For checking integration boundaries, read \${refs.integration}.
+- For learning, decisions, and writeback, read \${refs.learning_writeback}.
+- For capability evolution, proposal kinds, and \`facult ai\` workflow, read \${refs.evolution}.
+- For deciding whether something belongs in global or project scope, read \${refs.project_capability}.
+- Add private language, coding, or writing refs in local config only when they belong to the user's own operating layer.
+`;
+
+function appendOperatingModelFrame(seedText: string): string {
+  const normalized = seedText.trimEnd();
+  if (normalized.includes("<!-- fclty:global/baseline -->")) {
+    return `${normalized}\n`;
+  }
+  return `${normalized}\n\n## Facult Operating Model\n\n${OPERATING_MODEL_SNIPPET_FRAME}`;
+}
+
+async function firstExistingFileText(
+  candidates: string[]
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return await Bun.file(candidate).text();
+    }
+  }
+  return null;
+}
+
+async function seedAgentsGlobalText(args: {
+  rootDir: string;
+  homeDir?: string;
+  fallbackText: string;
+}): Promise<{ text: string; seededFromExisting: boolean }> {
+  const home = args.homeDir ?? homedir();
+  const projectRoot = projectRootFromAiRoot(args.rootDir, home);
+  const seedText = await firstExistingFileText(
+    projectRoot
+      ? [
+          join(projectRoot, "AGENTS.md"),
+          join(projectRoot, "CLAUDE.md"),
+          join(projectRoot, ".codex", "AGENTS.md"),
+          join(projectRoot, ".claude", "CLAUDE.md"),
+        ]
+      : [
+          join(home, ".codex", "AGENTS.md"),
+          join(home, ".claude", "CLAUDE.md"),
+          join(home, ".cursor", "AGENTS.md"),
+        ]
+  );
+  if (!seedText?.trim()) {
+    return { text: args.fallbackText, seededFromExisting: false };
+  }
+  return {
+    text: appendOperatingModelFrame(seedText),
+    seededFromExisting: true,
+  };
+}
+
 async function scaffoldBuiltinOperatingModelPack(args: {
   rootDir: string;
   homeDir?: string;
@@ -1364,20 +1449,33 @@ async function scaffoldBuiltinOperatingModelPack(args: {
     if (!relPath || relPath.startsWith("..")) {
       continue;
     }
-    const targetPath = join(rootDir, relPath);
-    const sourceText = await Bun.file(sourcePath).text();
+    const targetRelPath = builtinOperatingModelInstallRelPath(relPath);
+    const targetPath = join(rootDir, targetRelPath);
+    const rawSourceText = await Bun.file(sourcePath).text();
+    const targetExists = await pathExists(targetPath);
+    const seed =
+      targetRelPath === "AGENTS.global.md" && !targetExists
+        ? await seedAgentsGlobalText({
+            rootDir,
+            homeDir: args.homeDir,
+            fallbackText: rawSourceText,
+          })
+        : null;
+    const sourceText = seed?.text ?? rawSourceText;
+    const trackInManifest = !seed?.seededFromExisting;
     const sourceHash = sha256Text(sourceText);
-    const exists = await pathExists(targetPath);
-    let shouldWrite = !exists || Boolean(args.force);
+    let shouldWrite = !targetExists || Boolean(args.force);
 
-    if (exists && !shouldWrite) {
+    if (targetExists && !shouldWrite) {
       const targetText = await Bun.file(targetPath).text();
       const targetHash = sha256Text(targetText);
       if (targetHash === sourceHash) {
-        manifestFiles[relPath] = { sha256: sourceHash };
+        if (trackInManifest) {
+          manifestFiles[targetRelPath] = { sha256: sourceHash };
+        }
       } else if (
         args.update &&
-        existingManifest?.files[relPath]?.sha256 === targetHash
+        existingManifest?.files[targetRelPath]?.sha256 === targetHash
       ) {
         shouldWrite = true;
       } else if (args.update) {
@@ -1389,7 +1487,11 @@ async function scaffoldBuiltinOperatingModelPack(args: {
       continue;
     }
     changedPaths.push(targetPath);
-    manifestFiles[relPath] = { sha256: sourceHash };
+    if (trackInManifest) {
+      manifestFiles[targetRelPath] = { sha256: sourceHash };
+    } else {
+      delete manifestFiles[targetRelPath];
+    }
     if (!args.dryRun) {
       await mkdir(dirname(targetPath), { recursive: true });
       await Bun.write(targetPath, sourceText);