@cleocode/cleo 2026.3.49 → 2026.3.51

package/bin/postinstall.js

@@ -2,57 +2,68 @@
 /**
  * NPM Postinstall Hook - Bootstrap Global CLEO System
  *
- * This script runs automatically after `npm install -g @cleocode/cleo`.
- * It delegates to the shared bootstrap module in @cleocode/core so that
- * both postinstall and `cleo install-global` use the same logic.
+ * Runs automatically after `npm install -g @cleocode/cleo`.
+ * Delegates to @cleocode/core's bootstrapGlobalCleo().
  *
- * Bootstraps:
- *   - ~/.cleo/ directory structure
- *   - Global templates (CLEO-INJECTION.md)
- *   - CAAMP provider configs
- *   - MCP server to detected providers
- *   - Core skills globally
- *   - Provider adapters
+ * Detection: runs bootstrap when installed in a global node_modules path.
+ * Skips for workspace/dev installs (no global prefix in path).
  *
  * @task T5267
  */
 
-import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Determine if we're running from npm global install
-function isNpmGlobalInstall() {
-  const execPath = process.argv[1] || '';
-  // Check if running from node_modules/@cleocode/cleo/
-  return (
-    execPath.includes('node_modules/@cleocode/cleo/') ||
-    execPath.includes('node_modules\\@cleocode\\cleo\\')
-  );
+/**
+ * Detect if this is a global npm install (not a workspace/dev install).
+ * Checks multiple signals since npm staging paths vary by version.
+ */
+function isGlobalInstall() {
+  const pkgRoot = resolve(__dirname, '..');
+
+  // Signal 1: npm_config_global env var (set by npm during global installs)
+  if (process.env.npm_config_global === 'true') return true;
+
+  // Signal 2: path contains a global node_modules (npm, pnpm, yarn)
+  if (/[/\\]lib[/\\]node_modules[/\\]/.test(pkgRoot)) return true;
+
+  // Signal 3: npm_config_prefix matches the package path
+  const prefix = process.env.npm_config_prefix;
+  if (prefix && pkgRoot.startsWith(prefix)) return true;
+
+  // Signal 4: not inside a pnpm workspace (no workspace root marker)
+  const workspaceMarker = join(pkgRoot, '..', '..', 'pnpm-workspace.yaml');
+  if (existsSync(workspaceMarker)) return false;
+
+  return false;
 }
 
-// Get package root (bin/ is one level below package root)
 function getPackageRoot() {
   return resolve(__dirname, '..');
 }
 
 async function runPostinstall() {
-  // Only run for npm global installs, not local dev or other contexts
-  if (!isNpmGlobalInstall()) {
-    console.log('CLEO: Skipping global bootstrap (not npm global install)');
+  if (!isGlobalInstall()) {
+    console.log('CLEO: Skipping global bootstrap (not global install)');
     return;
   }
 
   console.log('CLEO: Bootstrapping global system...');
 
   try {
-    // Import the shared bootstrap from the built core dist.
-    // At postinstall time, dist/ should already be present in the published package.
-    const { bootstrapGlobalCleo } = await import(
-      '../dist/core/bootstrap.js'
-    );
+    // Import bootstrap from @cleocode/core.
+    // Try the internal subpath first (multi-file tsc build), fall back to main
+    // barrel (esbuild single-file bundle where internal.js doesn't exist).
+    let bootstrapGlobalCleo;
+    try {
+      ({ bootstrapGlobalCleo } = await import('@cleocode/core/internal'));
+    } catch {
+      ({ bootstrapGlobalCleo } = await import('@cleocode/core'));
+    }
 
     const result = await bootstrapGlobalCleo({
       packageRoot: getPackageRoot(),
@@ -68,16 +79,14 @@ async function runPostinstall() {
     console.log('CLEO: Global bootstrap complete!');
     console.log('CLEO: Run "cleo init" in any project to set up local CLEO.');
   } catch (err) {
-    // Bootstrap is best-effort — CAAMP/MCP may not be configured yet
-    console.log('CLEO: CAAMP/MCP setup deferred (will complete on first use)');
+    console.log('CLEO: Bootstrap deferred (will complete on first "cleo install-global")');
     if (process.env.CLEO_DEBUG) {
       console.error('CLEO: Bootstrap detail:', err);
     }
   }
 }
 
-// Run bootstrap — never fail npm install
 runPostinstall().catch((err) => {
   console.error('CLEO: Bootstrap error (non-fatal):', err.message);
-  process.exit(0); // Never fail npm install
+  process.exit(0);
 });

package/dist/cli/index.js

@@ -64979,6 +64979,224 @@ var init_project_info = __esm({
   }
 });
 
+// packages/core/src/bootstrap.ts
+import { existsSync as existsSync103, readFileSync as readFileSync76 } from "node:fs";
+import { mkdir as mkdir17, readFile as readFile19, writeFile as writeFile12 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join103 } from "node:path";
+async function bootstrapGlobalCleo(options) {
+  const ctx = {
+    created: [],
+    warnings: [],
+    isDryRun: options?.dryRun ?? false
+  };
+  try {
+    await ensureGlobalHome();
+  } catch {
+  }
+  await ensureGlobalTemplatesBootstrap(ctx, options?.packageRoot);
+  await injectAgentsHub(ctx);
+  await installMcpToProviders(ctx);
+  await installSkillsGlobally(ctx);
+  await installAgentDefinitionGlobally(ctx);
+  await installProviderAdapters(ctx, options?.packageRoot);
+  return ctx;
+}
+async function ensureGlobalTemplatesBootstrap(ctx, packageRootOverride) {
+  const globalTemplatesDir = getCleoTemplatesDir();
+  if (!ctx.isDryRun) {
+    await mkdir17(globalTemplatesDir, { recursive: true });
+  }
+  try {
+    const pkgRoot = packageRootOverride ?? getPackageRoot();
+    const templatePath = join103(pkgRoot, "templates", "CLEO-INJECTION.md");
+    if (existsSync103(templatePath)) {
+      const content = readFileSync76(templatePath, "utf-8");
+      const destPath = join103(globalTemplatesDir, "CLEO-INJECTION.md");
+      if (!ctx.isDryRun) {
+        await writeFile12(destPath, content);
+      }
+      ctx.created.push(
+        `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? "would refresh" : "refreshed"})`
+      );
+    } else {
+      try {
+        const { getInjectionTemplateContent: getInjectionTemplateContent2 } = await Promise.resolve().then(() => (init_injection(), injection_exports));
+        const content = getInjectionTemplateContent2();
+        if (content) {
+          const destPath = join103(globalTemplatesDir, "CLEO-INJECTION.md");
+          if (!ctx.isDryRun) {
+            await writeFile12(destPath, content);
+          }
+          ctx.created.push(
+            `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? "would refresh" : "refreshed"} from embedded)`
+          );
+        }
+      } catch {
+        ctx.warnings.push("Could not refresh CLEO-INJECTION.md template");
+      }
+    }
+  } catch {
+    ctx.warnings.push("Could not refresh CLEO-INJECTION.md template");
+  }
+}
+async function injectAgentsHub(ctx) {
+  const globalAgentsDir = getAgentsHome();
+  const globalAgentsMd = join103(globalAgentsDir, "AGENTS.md");
+  try {
+    const { inject: inject2, getInstalledProviders: getInstalledProviders5, injectAll: injectAll3, buildInjectionContent: buildInjectionContent2 } = await import("@cleocode/caamp");
+    if (!ctx.isDryRun) {
+      await mkdir17(globalAgentsDir, { recursive: true });
+      if (existsSync103(globalAgentsMd)) {
+        const content = await readFile19(globalAgentsMd, "utf8");
+        const stripped = content.replace(/\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g, "").replace(/\n?<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->\n?/g, "").trim();
+        await writeFile12(globalAgentsMd, stripped ? `${stripped}
+` : "", "utf8");
+      }
+      const expectedContent = "@~/.cleo/templates/CLEO-INJECTION.md";
+      const action = await inject2(globalAgentsMd, expectedContent);
+      ctx.created.push(`~/.agents/AGENTS.md (${action})`);
+    } else {
+      ctx.created.push("~/.agents/AGENTS.md (would create/update CAAMP block)");
+    }
+    const providers = getInstalledProviders5();
+    if (providers.length === 0) {
+      ctx.warnings.push("No AI provider installations detected");
+    } else {
+      const injectionContent = buildInjectionContent2({
+        references: ["@~/.agents/AGENTS.md"]
+      });
+      if (!ctx.isDryRun) {
+        for (const provider of providers) {
+          const instructFilePath = join103(provider.pathGlobal, provider.instructFile);
+          if (existsSync103(instructFilePath)) {
+            const fileContent = await readFile19(instructFilePath, "utf8");
+            const stripped = fileContent.replace(
+              /\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g,
+              ""
+            );
+            if (stripped !== fileContent) {
+              await writeFile12(instructFilePath, stripped, "utf8");
+            }
+          }
+        }
+        const results = await injectAll3(providers, homedir6(), "global", injectionContent);
+        for (const [filePath, action] of results) {
+          const displayPath = filePath.replace(homedir6(), "~");
+          ctx.created.push(`${displayPath} (${action})`);
+        }
+      } else {
+        for (const p of providers) {
+          const displayPath = join103(p.pathGlobal, p.instructFile).replace(homedir6(), "~");
+          ctx.created.push(`${displayPath} (would update CAAMP block)`);
+        }
+      }
+    }
+  } catch (err) {
+    ctx.warnings.push(`CAAMP injection: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function installMcpToProviders(ctx) {
+  try {
+    const { detectEnvMode: detectEnvMode2, generateMcpServerEntry: generateMcpServerEntry2, getMcpServerName: getMcpServerName2 } = await Promise.resolve().then(() => (init_mcp(), mcp_exports));
+    const { getInstalledProviders: getInstalledProviders5, installMcpServerToAll: installMcpServerToAll2 } = await import("@cleocode/caamp");
+    const env = detectEnvMode2();
+    const serverEntry = generateMcpServerEntry2(env);
+    const serverName = getMcpServerName2(env);
+    const providers = getInstalledProviders5();
+    if (providers.length > 0) {
+      if (!ctx.isDryRun) {
+        const results = await installMcpServerToAll2(
+          providers,
+          serverName,
+          serverEntry,
+          "global",
+          homedir6()
+        );
+        const successes = results.filter((r) => r.success);
+        if (successes.length > 0) {
+          ctx.created.push(
+            `MCP configs: ${successes.map((r) => r.provider.id).join(", ")}`
+          );
+        }
+      } else {
+        ctx.created.push("MCP configs (would update)");
+      }
+    }
+  } catch {
+    ctx.warnings.push("MCP config update skipped (non-critical)");
+  }
+}
+async function installSkillsGlobally(ctx) {
+  try {
+    if (!ctx.isDryRun) {
+      const { initCoreSkills: initCoreSkills2 } = await Promise.resolve().then(() => (init_init(), init_exports));
+      await initCoreSkills2(ctx.created, ctx.warnings);
+    } else {
+      ctx.created.push("core skills (would install/update)");
+    }
+  } catch (err) {
+    ctx.warnings.push(
+      `Core skills installation failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function installAgentDefinitionGlobally(ctx) {
+  try {
+    if (!ctx.isDryRun) {
+      const { initAgentDefinition: initAgentDefinition2 } = await Promise.resolve().then(() => (init_init(), init_exports));
+      await initAgentDefinition2(ctx.created, ctx.warnings);
+    } else {
+      ctx.created.push("agent: cleo-subagent (would symlink)");
+    }
+  } catch (err) {
+    ctx.warnings.push(
+      `Agent definition install: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function installProviderAdapters(ctx, packageRootOverride) {
+  try {
+    const { AdapterManager: AdapterManager2 } = await Promise.resolve().then(() => (init_adapters(), adapters_exports));
+    const pkgRoot = packageRootOverride ?? getPackageRoot();
+    const manager = AdapterManager2.getInstance(pkgRoot);
+    manager.discover();
+    const detected = manager.detectActive();
+    for (const adapterId of detected) {
+      try {
+        const adapter = await manager.activate(adapterId);
+        if (adapter.install) {
+          if (!ctx.isDryRun) {
+            const installResult = await adapter.install.install({
+              projectDir: process.cwd()
+            });
+            if (installResult.success) {
+              ctx.created.push(`${adapterId} adapter (installed)`);
+            }
+          } else {
+            ctx.created.push(`${adapterId} adapter (would install)`);
+          }
+        }
+      } catch (activateErr) {
+        ctx.warnings.push(
+          `Adapter ${adapterId} skipped: ${activateErr instanceof Error ? activateErr.message : String(activateErr)}`
+        );
+      }
+    }
+  } catch (err) {
+    ctx.warnings.push(
+      `Adapter install skipped: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+var init_bootstrap = __esm({
+  "packages/core/src/bootstrap.ts"() {
+    "use strict";
+    init_paths();
+    init_scaffold();
+  }
+});
+
 // packages/core/src/cleo.ts
 import path from "node:path";
 var Cleo;
@@ -65281,6 +65499,7 @@ __export(src_exports, {
   agentTypeSchema: () => agentTypeSchema,
   agents: () => agents_exports,
   archiveTasks: () => archiveTasks,
+  bootstrapGlobalCleo: () => bootstrapGlobalCleo,
   brainConfidenceLevelSchema: () => brainConfidenceLevelSchema,
   brainDecisionTypeSchema: () => brainDecisionTypeSchema,
   brainEdgeTypeSchema: () => brainEdgeTypeSchema,
@@ -65534,6 +65753,7 @@ var init_src2 = __esm({
     init_project_info();
     init_scaffold();
     init_adapters();
+    init_bootstrap();
     init_cleo();
     init_registry();
     init_brain_retrieval();
@@ -65556,225 +65776,6 @@ var init_src2 = __esm({
   }
 });
 
-// packages/core/src/bootstrap.ts
-import { existsSync as existsSync103, readFileSync as readFileSync76 } from "node:fs";
-import { mkdir as mkdir17, readFile as readFile19, writeFile as writeFile12 } from "node:fs/promises";
-import { homedir as homedir6 } from "node:os";
-import { join as join103 } from "node:path";
-async function bootstrapGlobalCleo(options) {
-  const ctx = {
-    created: [],
-    warnings: [],
-    isDryRun: options?.dryRun ?? false
-  };
-  try {
-    const { ensureGlobalHome: ensureGlobalHome2 } = await Promise.resolve().then(() => (init_scaffold(), scaffold_exports));
-    await ensureGlobalHome2();
-  } catch {
-  }
-  await ensureGlobalTemplatesBootstrap(ctx, options?.packageRoot);
-  await injectAgentsHub(ctx);
-  await installMcpToProviders(ctx);
-  await installSkillsGlobally(ctx);
-  await installAgentDefinitionGlobally(ctx);
-  await installProviderAdapters(ctx, options?.packageRoot);
-  return ctx;
-}
-async function ensureGlobalTemplatesBootstrap(ctx, packageRootOverride) {
-  const globalTemplatesDir = getCleoTemplatesDir();
-  if (!ctx.isDryRun) {
-    await mkdir17(globalTemplatesDir, { recursive: true });
-  }
-  try {
-    const pkgRoot = packageRootOverride ?? getPackageRoot();
-    const templatePath = join103(pkgRoot, "templates", "CLEO-INJECTION.md");
-    if (existsSync103(templatePath)) {
-      const content = readFileSync76(templatePath, "utf-8");
-      const destPath = join103(globalTemplatesDir, "CLEO-INJECTION.md");
-      if (!ctx.isDryRun) {
-        await writeFile12(destPath, content);
-      }
-      ctx.created.push(
-        `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? "would refresh" : "refreshed"})`
-      );
-    } else {
-      try {
-        const { getInjectionTemplateContent: getInjectionTemplateContent2 } = await Promise.resolve().then(() => (init_injection(), injection_exports));
-        const content = getInjectionTemplateContent2();
-        if (content) {
-          const destPath = join103(globalTemplatesDir, "CLEO-INJECTION.md");
-          if (!ctx.isDryRun) {
-            await writeFile12(destPath, content);
-          }
-          ctx.created.push(
-            `~/.cleo/templates/CLEO-INJECTION.md (${ctx.isDryRun ? "would refresh" : "refreshed"} from embedded)`
-          );
-        }
-      } catch {
-        ctx.warnings.push("Could not refresh CLEO-INJECTION.md template");
-      }
-    }
-  } catch {
-    ctx.warnings.push("Could not refresh CLEO-INJECTION.md template");
-  }
-}
-async function injectAgentsHub(ctx) {
-  const globalAgentsDir = getAgentsHome();
-  const globalAgentsMd = join103(globalAgentsDir, "AGENTS.md");
-  try {
-    const { inject: inject2, getInstalledProviders: getInstalledProviders5, injectAll: injectAll3, buildInjectionContent: buildInjectionContent2 } = await import("@cleocode/caamp");
-    if (!ctx.isDryRun) {
-      await mkdir17(globalAgentsDir, { recursive: true });
-      if (existsSync103(globalAgentsMd)) {
-        const content = await readFile19(globalAgentsMd, "utf8");
-        const stripped = content.replace(/\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g, "").replace(/\n?<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->\n?/g, "").trim();
-        await writeFile12(globalAgentsMd, stripped ? `${stripped}
-` : "", "utf8");
-      }
-      const expectedContent = "@~/.cleo/templates/CLEO-INJECTION.md";
-      const action = await inject2(globalAgentsMd, expectedContent);
-      ctx.created.push(`~/.agents/AGENTS.md (${action})`);
-    } else {
-      ctx.created.push("~/.agents/AGENTS.md (would create/update CAAMP block)");
-    }
-    const providers = getInstalledProviders5();
-    if (providers.length === 0) {
-      ctx.warnings.push("No AI provider installations detected");
-    } else {
-      const injectionContent = buildInjectionContent2({
-        references: ["@~/.agents/AGENTS.md"]
-      });
-      if (!ctx.isDryRun) {
-        for (const provider of providers) {
-          const instructFilePath = join103(provider.pathGlobal, provider.instructFile);
-          if (existsSync103(instructFilePath)) {
-            const fileContent = await readFile19(instructFilePath, "utf8");
-            const stripped = fileContent.replace(
-              /\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g,
-              ""
-            );
-            if (stripped !== fileContent) {
-              await writeFile12(instructFilePath, stripped, "utf8");
-            }
-          }
-        }
-        const results = await injectAll3(providers, homedir6(), "global", injectionContent);
-        for (const [filePath, action] of results) {
-          const displayPath = filePath.replace(homedir6(), "~");
-          ctx.created.push(`${displayPath} (${action})`);
-        }
-      } else {
-        for (const p of providers) {
-          const displayPath = join103(p.pathGlobal, p.instructFile).replace(homedir6(), "~");
-          ctx.created.push(`${displayPath} (would update CAAMP block)`);
-        }
-      }
-    }
-  } catch (err) {
-    ctx.warnings.push(`CAAMP injection: ${err instanceof Error ? err.message : String(err)}`);
-  }
-}
-async function installMcpToProviders(ctx) {
-  try {
-    const { detectEnvMode: detectEnvMode2, generateMcpServerEntry: generateMcpServerEntry2, getMcpServerName: getMcpServerName2 } = await Promise.resolve().then(() => (init_mcp(), mcp_exports));
-    const { getInstalledProviders: getInstalledProviders5, installMcpServerToAll: installMcpServerToAll2 } = await import("@cleocode/caamp");
-    const env = detectEnvMode2();
-    const serverEntry = generateMcpServerEntry2(env);
-    const serverName = getMcpServerName2(env);
-    const providers = getInstalledProviders5();
-    if (providers.length > 0) {
-      if (!ctx.isDryRun) {
-        const results = await installMcpServerToAll2(
-          providers,
-          serverName,
-          serverEntry,
-          "global",
-          homedir6()
-        );
-        const successes = results.filter((r) => r.success);
-        if (successes.length > 0) {
-          ctx.created.push(
-            `MCP configs: ${successes.map((r) => r.provider.id).join(", ")}`
-          );
-        }
-      } else {
-        ctx.created.push("MCP configs (would update)");
-      }
-    }
-  } catch {
-    ctx.warnings.push("MCP config update skipped (non-critical)");
-  }
-}
-async function installSkillsGlobally(ctx) {
-  try {
-    if (!ctx.isDryRun) {
-      const { initCoreSkills: initCoreSkills2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      await initCoreSkills2(ctx.created, ctx.warnings);
-    } else {
-      ctx.created.push("core skills (would install/update)");
-    }
-  } catch (err) {
-    ctx.warnings.push(
-      `Core skills installation failed: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-async function installAgentDefinitionGlobally(ctx) {
-  try {
-    if (!ctx.isDryRun) {
-      const { initAgentDefinition: initAgentDefinition2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      await initAgentDefinition2(ctx.created, ctx.warnings);
-    } else {
-      ctx.created.push("agent: cleo-subagent (would symlink)");
-    }
-  } catch (err) {
-    ctx.warnings.push(
-      `Agent definition install: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-async function installProviderAdapters(ctx, packageRootOverride) {
-  try {
-    const { AdapterManager: AdapterManager2 } = await Promise.resolve().then(() => (init_adapters(), adapters_exports));
-    const pkgRoot = packageRootOverride ?? getPackageRoot();
-    const manager = AdapterManager2.getInstance(pkgRoot);
-    manager.discover();
-    const detected = manager.detectActive();
-    for (const adapterId of detected) {
-      try {
-        const adapter = await manager.activate(adapterId);
-        if (adapter.install) {
-          if (!ctx.isDryRun) {
-            const installResult = await adapter.install.install({
-              projectDir: process.cwd()
-            });
-            if (installResult.success) {
-              ctx.created.push(`${adapterId} adapter (installed)`);
-            }
-          } else {
-            ctx.created.push(`${adapterId} adapter (would install)`);
-          }
-        }
-      } catch (activateErr) {
-        ctx.warnings.push(
-          `Adapter ${adapterId} skipped: ${activateErr instanceof Error ? activateErr.message : String(activateErr)}`
-        );
-      }
-    }
-  } catch (err) {
-    ctx.warnings.push(
-      `Adapter install skipped: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-var init_bootstrap = __esm({
-  "packages/core/src/bootstrap.ts"() {
-    "use strict";
-    init_paths();
-    init_scaffold();
-  }
-});
-
 // packages/core/src/compliance/protocol-rules.ts
 function hasField(obj, field) {
   const value = obj[field];