facult 2.16.0 → 2.17.1

package/README.md

@@ -181,6 +181,7 @@ fclt index
 Managed mode writes rendered files into a tool home. Use it only when `fclt` should own that rendered surface.
 
 ```bash
+fclt setup codex-plugin
 fclt manage codex --dry-run
 fclt manage codex --adopt-existing
 fclt sync codex --dry-run
@@ -377,6 +378,7 @@ fclt index [--force]
 Managed mode:
 
 ```bash
+fclt setup codex-plugin [--dry-run] [--json]
 fclt manage <tool> [--dry-run] [--adopt-existing]
 fclt sync [tool] [--dry-run] [--adopt-live]
 fclt enable <selector> --for codex,claude
@@ -426,7 +428,7 @@ Start with:
 
 ### Does fclt run an MCP server?
 
-The core product is still CLI-first. The first-party Codex plugin includes a small stdio MCP wrapper that delegates to the installed `fclt` binary for status, doctor, paths, setup, writeback, and evolution workflows. See [Codex plugin](./docs/codex-plugin.md).
+The core product is still CLI-first. `fclt setup codex-plugin` installs the first-party Codex plugin without putting all of Codex under managed mode. The plugin includes a small stdio MCP wrapper that delegates to the installed `fclt` binary for status, doctor, paths, setup, writeback, and evolution workflows. See [Codex plugin](./docs/codex-plugin.md).
 
 ### Does fclt have to manage Codex or Claude files?
 

package/docs/codex-plugin.md

@@ -34,15 +34,28 @@ These tools are thin wrappers around CLI commands and return command output. Mut
 
 ## Install In Codex
 
-From this repository, the plugin can be rendered into the Codex plugin marketplace by managed sync:
+Use the narrow setup command for normal installs:
+
+```bash
+fclt setup codex-plugin
+```
+
+That updates only the local `fclt` plugin payload under `~/plugins/fclt`, merges the `hack-local` marketplace entry at `~/.agents/plugins/marketplace.json`, and runs `codex plugin add fclt@hack-local --json` when the `codex` command is available. It does not enter managed mode, adopt Codex state, render `~/.codex/AGENTS.md`, or touch existing Codex skills/rules/config.
+
+Useful flags:
+
+```bash
+fclt setup codex-plugin --dry-run --json
+fclt setup codex-plugin --no-codex-install
+```
+
+Use managed sync only when you intentionally want `fclt` to render broader Codex tool files:
 
 ```bash
 fclt manage codex --global
 fclt sync codex --global
 ```
 
-That writes plugin files under the Codex plugin location and updates the personal marketplace entry. Use managed sync only when you want `fclt` to write Codex tool files.
-
 For local plugin development, run the lightweight checks that ship with the repository:
 
 ```bash

package/docs/managed-mode.md

@@ -2,6 +2,14 @@
 
 Managed mode is optional. Use it when you want `fclt` to write rendered files into a tool home. Do not use it just to inspect or normalize existing tool-native state.
 
+If you only want the first-party fclt Codex plugin, use the narrow setup path instead:
+
+```bash
+fclt setup codex-plugin
+```
+
+That installs/exposes the bundled plugin without adopting or rendering the rest of Codex state.
+
 Prefer this default workflow:
 
 ```bash

package/docs/reference.md

@@ -65,6 +65,7 @@ Use these to create or normalize canonical capability in `~/.ai` or `<repo>/.ai`
 ## Managed mode
 
 ```bash
+fclt setup codex-plugin [--dry-run] [--json] [--no-codex-install]
 fclt manage <tool> [--dry-run] [--adopt-existing]
 fclt sync [tool] [--dry-run] [--adopt-live]
 fclt enable <selector> --for codex,claude
@@ -73,7 +74,7 @@ fclt managed
 fclt unmanage <tool>
 ```
 
-Managed mode writes rendered output into tool homes. Read [Managed mode](./managed-mode.md) before using it on an existing setup.
+`setup codex-plugin` is the narrow path for exposing the bundled fclt Codex plugin without entering managed mode. Managed mode writes rendered output into tool homes. Read [Managed mode](./managed-mode.md) before using it on an existing setup.
 
 ## Writeback and evolution
 

package/package.json

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

package/src/index.ts

@@ -142,6 +142,10 @@ function printHelp() {
                 "manage/sync",
                 "Enter managed mode and render tool-native output",
               ],
+              [
+                "setup",
+                "Install narrow agent integrations without full managed mode",
+              ],
               ["ai", "Capture writeback and evolve canonical assets"],
             ],
           }),
@@ -1365,6 +1369,9 @@ async function main(argv: string[]) {
     case "sync":
       await import("./manage").then(({ syncCommand }) => syncCommand(rest));
       return;
+    case "setup":
+      await import("./manage").then(({ setupCommand }) => setupCommand(rest));
+      return;
     case "autosync":
       await import("./autosync").then(({ autosyncCommand }) =>
         autosyncCommand(rest)

package/src/manage.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import {
   appendFile,
@@ -146,6 +147,29 @@ export interface SyncOptions {
   adoptLive?: boolean;
 }
 
+export interface SetupCodexPluginOptions {
+  homeDir?: string;
+  dryRun?: boolean;
+  installInCodex?: boolean;
+  codexBin?: string | null;
+}
+
+export interface SetupCodexPluginResult {
+  pluginDir: string;
+  marketplacePath: string;
+  marketplaceName: string;
+  changedPaths: string[];
+  dryRun: boolean;
+  codexInstall: {
+    status: "skipped" | "succeeded" | "failed";
+    command?: string[];
+    stdout?: string;
+    stderr?: string;
+    code?: number | null;
+    reason?: string;
+  };
+}
+
 const MANAGED_VERSION = 1 as const;
 
 function nowIso(now?: () => Date): string {
@@ -350,6 +374,54 @@ function fcltCodexMarketplaceEntry(): Record<string, unknown> {
   };
 }
 
+function hackLocalCodexMarketplaceText(text: string | null): string {
+  const base =
+    text == null
+      ? {
+          name: "hack-local",
+          interface: { displayName: "Hack Local Plugins" },
+          plugins: [],
+        }
+      : (JSON.parse(text) as unknown);
+  if (!isPlainObject(base)) {
+    throw new Error("Codex plugin marketplace must be a JSON object.");
+  }
+  const plugins = Array.isArray(base.plugins) ? [...base.plugins] : [];
+  const nextPlugins = plugins.filter(
+    (entry) => !(isPlainObject(entry) && entry.name === FCLT_CODEX_PLUGIN_NAME)
+  );
+  nextPlugins.push(fcltCodexMarketplaceEntry());
+  return normalizeCodexMarketplaceText(
+    JSON.stringify(
+      {
+        ...base,
+        name:
+          typeof base.name === "string" && base.name.trim()
+            ? base.name
+            : "hack-local",
+        interface: isPlainObject(base.interface)
+          ? base.interface
+          : { displayName: "Hack Local Plugins" },
+        plugins: nextPlugins,
+      },
+      null,
+      2
+    )
+  );
+}
+
+function codexMarketplaceNameFromText(text: string): string {
+  const parsed = JSON.parse(text) as unknown;
+  if (
+    isPlainObject(parsed) &&
+    typeof parsed.name === "string" &&
+    parsed.name.trim()
+  ) {
+    return parsed.name;
+  }
+  return "hack-local";
+}
+
 function withBuiltinFcltCodexMarketplaceEntry(text: string | null): string {
   const base =
     text == null
@@ -4600,6 +4672,125 @@ async function planCodexPluginFileChanges(args: {
   };
 }
 
+async function runCodexPluginAdd(args: {
+  codexBin: string;
+  cwd: string;
+  marketplaceName: string;
+}): Promise<SetupCodexPluginResult["codexInstall"]> {
+  const command = [
+    args.codexBin,
+    "plugin",
+    "add",
+    `fclt@${args.marketplaceName}`,
+    "--json",
+  ];
+  return await new Promise((resolve) => {
+    const child = spawn(args.codexBin, command.slice(1), {
+      cwd: args.cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      resolve({
+        status: "failed",
+        command,
+        stdout,
+        stderr: error.message,
+        code: null,
+      });
+    });
+    child.on("close", (code) => {
+      resolve({
+        status: code === 0 ? "succeeded" : "failed",
+        command,
+        stdout,
+        stderr,
+        code,
+      });
+    });
+  });
+}
+
+export async function setupCodexPlugin(
+  opts: SetupCodexPluginOptions = {}
+): Promise<SetupCodexPluginResult> {
+  const home = opts.homeDir ?? homedir();
+  const pluginDir = codexPluginsDir(home);
+  const marketplacePath = codexPluginMarketplacePath(home);
+  const sourceDir = facultBuiltinCodexPluginRoot();
+  const changedPaths: string[] = [];
+  const sourceHash = await hashDirectoryTree(sourceDir);
+  const pluginTargetDir = join(pluginDir, FCLT_CODEX_PLUGIN_NAME);
+  const targetHash = await hashDirectoryTree(pluginTargetDir);
+
+  if (sourceHash !== targetHash) {
+    changedPaths.push(pluginTargetDir);
+  }
+
+  const marketplaceRaw = await readTextOrNull(marketplacePath);
+  let marketplaceText: string;
+  try {
+    marketplaceText = hackLocalCodexMarketplaceText(marketplaceRaw);
+  } catch (error) {
+    throw new Error(
+      `Cannot update Codex plugin marketplace at ${marketplacePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  const marketplaceName = codexMarketplaceNameFromText(marketplaceText);
+  if (
+    (await readTargetHash(marketplacePath, { normalizeText: false })) !==
+    targetContentHash(marketplaceText, { normalizeText: false })
+  ) {
+    changedPaths.push(marketplacePath);
+  }
+
+  const installInCodex = opts.installInCodex ?? true;
+  let codexInstall: SetupCodexPluginResult["codexInstall"] = {
+    status: "skipped",
+    reason: installInCodex
+      ? "dry-run"
+      : "codex plugin install disabled by --no-codex-install",
+  };
+
+  if (!opts.dryRun) {
+    await rm(pluginTargetDir, { recursive: true, force: true });
+    await ensureDir(pluginDir);
+    await cp(sourceDir, pluginTargetDir, { recursive: true });
+    await ensureDir(dirname(marketplacePath));
+    await Bun.write(marketplacePath, marketplaceText);
+
+    if (installInCodex) {
+      const codexBin =
+        opts.codexBin === undefined ? Bun.which("codex") : opts.codexBin;
+      codexInstall = codexBin
+        ? await runCodexPluginAdd({ codexBin, cwd: home, marketplaceName })
+        : {
+            status: "skipped",
+            reason: "codex command not found",
+          };
+    }
+  }
+
+  return {
+    pluginDir: pluginTargetDir,
+    marketplacePath,
+    marketplaceName,
+    changedPaths: changedPaths.sort(),
+    dryRun: Boolean(opts.dryRun),
+    codexInstall,
+  };
+}
+
 async function syncManagedToolEntry({
   homeDir,
   tool,
@@ -5329,6 +5520,68 @@ export async function managedCommand(argv: string[] = []) {
   );
 }
 
+export async function setupCommand(argv: string[]) {
+  const args = [...argv];
+  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+    console.log(`fclt setup — set up narrow integrations without full managed mode
+
+Usage:
+  fclt setup codex-plugin [--dry-run] [--json] [--no-codex-install]
+
+Options:
+  --dry-run             Show paths that would change without writing files
+  --json                Print machine-readable setup result
+  --no-codex-install    Only expose the local marketplace entry; do not run codex plugin add
+`);
+    return;
+  }
+  const target = args.find((arg) => !arg.startsWith("-"));
+  const dryRun = args.includes("--dry-run");
+  const json = args.includes("--json");
+  const installInCodex = !args.includes("--no-codex-install");
+  if (target !== "codex-plugin") {
+    console.error("setup requires a target: codex-plugin");
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = await setupCodexPlugin({
+      dryRun,
+      installInCodex,
+    });
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+      if (result.codexInstall.status === "failed") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (dryRun) {
+      console.log("codex plugin setup dry-run");
+    } else {
+      console.log("codex plugin setup complete");
+    }
+    console.log(`plugin: ${result.pluginDir}`);
+    console.log(`marketplace: ${result.marketplacePath}`);
+    console.log(`changed: ${result.changedPaths.length}`);
+    if (result.codexInstall.status === "succeeded") {
+      console.log("codex install: succeeded");
+    } else if (result.codexInstall.status === "failed") {
+      console.log("codex install: failed");
+      if (result.codexInstall.stderr?.trim()) {
+        console.log(result.codexInstall.stderr.trim());
+      }
+      process.exitCode = 1;
+    } else {
+      console.log(`codex install: skipped (${result.codexInstall.reason})`);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+
 export async function syncCommand(argv: string[]) {
   const parsed = parseCliContextArgs(argv);
   if (