@cleocode/cleo 2026.3.10 → 2026.3.12

package/README.md

@@ -1,4 +1,4 @@
-<p alis|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.10-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2025.3.10-|gn="center">
+<p alis|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.12-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.11-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2026.3.10-|g|version-[0-9]\+\.[0-9]\+\.[0-9]\+-|version-2025.3.10-|gn="center">
   <img src="docs/images/banner.png" alt="CLEO banner" width="900">
 </p>
 
@@ -269,36 +269,36 @@ cleo-dev env info --json
 
 ### TL;DR - Just Install It
 
-**Option 1: One-liner (Easiest)**
+**Option 1: NPM (Recommended)**
 
 ```bash
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
-
-# Reinstalling over existing installation? Use --force:
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --force
+npm install -g @cleocode/cleo
 ```
 
-**Option 2: Download and Run**
+This automatically bootstraps the global CLEO system:
+- Sets up `~/.cleo/` with templates and configuration
+- Installs MCP server to detected AI providers (Claude Code, Cursor, etc.)
+- Creates `~/.agents/AGENTS.md` hub for agent instructions
 
-<p align="center">
-  <a href="https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh">
-    <img src="https://img.shields.io/badge/Download-install.sh-brightgreen?style=for-the-badge&logo=github" alt="Download install.sh">
-  </a>
-</p>
+Then initialize in any project:
+```bash
+cd /path/to/your/project && cleo init
+```
+
+**Option 2: One-liner Bash (Legacy/Offline)**
 
-After downloading, open Terminal and run:
+For systems without npm or offline installs:
 ```bash
-# macOS/Linux: Run with bash (no chmod needed)
-bash ~/Downloads/install.sh
+curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
 ```
 
-**Option 3: From source (for contributors)**
+**Option 3: From source (Contributors)**
 
 ```bash
 git clone https://github.com/kryptobaseddev/cleo.git && cd cleo && ./installer/install.sh --dev
 ```
 
-Then initialize in your project:
+Then use `cleo-dev` for isolated development:
 ```bash
 cd /path/to/your/project && cleo-dev init
 ```
@@ -327,25 +327,43 @@ cd /path/to/your/project && cleo-dev init
 <details>
 <summary><strong>Detailed Installation Options</strong></summary>
 
-#### Download from Releases (Recommended for Users)
+#### NPM Install (Recommended for Users)
+
+The NPM package auto-bootstraps the global CLEO system on install:
 
-1. Go to [Releases](https://github.com/kryptobaseddev/cleo/releases/latest)
-2. Download `cleo-X.Y.Z.tar.gz`
-3. Extract and install:
-   ```bash
-   tar xzf cleo-*.tar.gz
-   cd cleo-*
-   ./installer/install.sh
-   ```
+```bash
+# Install from npm registry
+npm install -g @cleocode/cleo
+
+# Or install specific version
+npm install -g @cleocode/cleo@2026.3.10
+```
+
+What happens during install:
+1. Creates `~/.cleo/` directory structure
+2. Installs global templates (`CLEO-INJECTION.md`)
+3. Detects AI providers and installs MCP server configs
+4. Creates `~/.agents/AGENTS.md` hub
+
+#### Initialize in Your Project
 
-#### One-liner Install (for Developers)
+After global install, initialize each project:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/cleo/main/install.sh | bash
+cd /path/to/your/project
+cleo init
 ```
 
+This creates only the local project structure:
+- `./.cleo/` directory with `config.json` and `tasks.db`
+- Registers project with NEXUS
+- Sets up git hooks
+- Injects CLEO references into local `AGENTS.md`
+
 #### From Source (for Contributors)
 
+For CLEO development or testing unreleased changes:
+
 ```bash
 # Clone repository
 git clone https://github.com/kryptobaseddev/cleo.git
@@ -356,38 +374,37 @@ cd cleo
 
 # Verify isolated runtime
 cleo-dev env info --json
-
-# Or install as release (copies files)
-./installer/install.sh --release
 ```
 
-`npm link` caveat: raw `npm link` follows package bin mappings and can expose `cleo`/`ct`. Use `./installer/install.sh --dev` when you need strict `cleo-dev` isolation.
+The dev channel uses:
+- Isolated commands: `cleo-dev` (no `ct` alias)
+- Isolated home: `~/.cleo-dev/`
+- Symlinks to repo for rapid iteration
 
-#### Verify Installation
-
-```bash
-cleo version
-cleo env info --json
-```
+`npm link` caveat: raw `npm link` follows package bin mappings and can expose `cleo`/`ct`. Use `./installer/install.sh --dev` when you need strict `cleo-dev` isolation.
 
-Provider alias/config utilities are managed by CAAMP.
+#### Legacy Bash Installer (Offline/Restricted Systems)
 
-#### Initialize in Your Project
+For systems without npm access:
 
 ```bash
-cd /path/to/your/project
-cleo init
+# One-liner install
+curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
+
+# Or download and run manually
+bash install.sh
 ```
 
-For contributor dev channel:
+This copies files (not symlinks) and provides the same functionality as npm install.
+
+#### Verify Installation
 
 ```bash
-cd /path/to/your/project
-cleo-dev init
+cleo version
+cleo env info --json
+cleo doctor
 ```
 
-> **Note**: The installer creates symlinks in `~/.local/bin/`, which works immediately with Claude Code and most modern shells.
-
 </details>
 
 <details>

package/bin/postinstall.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * NPM Postinstall Hook - Bootstrap Global CLEO System
+ * 
+ * This script runs automatically after `npm install -g @cleocode/cleo`.
+ * It bootstraps the global CLEO system:
+ *   - Creates ~/.cleo/ directory structure
+ *   - Installs global templates (CLEO-INJECTION.md)
+ *   - Sets up CAAMP provider configs
+ *   - Installs MCP server to detected providers
+ *   - Creates ~/.agents/AGENTS.md hub
+ * 
+ * This is the ONLY place global setup should happen. Project `cleo init`
+ * only creates local ./.cleo/ and registers with NEXUS.
+ * 
+ * @task T5267
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, readFile, copyFile } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Determine if we're running from npm global install or local dev
+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\\');
+}
+
+// Get package root
+function getPackageRoot() {
+  // When running from bin/, go up to package root
+  return resolve(__dirname, '..');
+}
+
+async function bootstrapGlobalCleo() {
+  // Only run for npm global installs, not local dev or other contexts
+  if (!isNpmGlobalInstall()) {
+    console.log('CLEO: Skipping global bootstrap (not npm global install)');
+    return;
+  }
+
+  console.log('CLEO: Bootstrapping global system...');
+
+  const cleoHome = join(homedir(), '.cleo');
+  const globalTemplatesDir = join(cleoHome, 'templates');
+  const globalAgentsDir = join(homedir(), '.agents');
+
+  // Create directories
+  await mkdir(globalTemplatesDir, { recursive: true });
+  await mkdir(globalAgentsDir, { recursive: true });
+
+  // Copy CLEO-INJECTION.md template
+  const packageRoot = getPackageRoot();
+  const templateSource = join(packageRoot, 'templates', 'CLEO-INJECTION.md');
+  const templateDest = join(globalTemplatesDir, 'CLEO-INJECTION.md');
+
+  if (existsSync(templateSource)) {
+    await copyFile(templateSource, templateDest);
+    console.log('CLEO: Installed global template (CLEO-INJECTION.md)');
+  }
+
+  // Setup CAAMP and MCP (these may fail gracefully if CAAMP isn't fully configured yet)
+  try {
+    const { getInstalledProviders, inject, buildInjectionContent } = await import('@cleocode/caamp');
+    
+    // Create ~/.agents/AGENTS.md with CLEO block
+    const globalAgentsMd = join(globalAgentsDir, 'AGENTS.md');
+    let agentsContent = '';
+    
+    if (existsSync(globalAgentsMd)) {
+      agentsContent = await readFile(globalAgentsMd, 'utf-8');
+      // Strip old CLEO blocks
+      agentsContent = agentsContent.replace(/\n?<!-- CLEO:START -->[\s\S]*?<!-- CLEO:END -->\n?/g, '');
+    }
+
+    // Inject CLEO reference
+    await inject(globalAgentsMd, '@~/.cleo/templates/CLEO-INJECTION.md');
+    console.log('CLEO: Updated ~/.agents/AGENTS.md');
+
+    // Install MCP server to detected providers
+    const providers = getInstalledProviders();
+    if (providers.length > 0) {
+      const { generateMcpServerEntry, getMcpServerName } = await import('../dist/core/mcp/index.js');
+      const { installMcpServerToAll } = await import('@cleocode/caamp');
+      
+      // Detect environment (stable/beta/dev)
+      const env = generateMcpServerEntry.length === 1 
+        ? { mode: 'stable', source: 'npm' }
+        : { mode: 'stable', source: 'npm' };
+      
+      const serverEntry = generateMcpServerEntry(env);
+      const serverName = getMcpServerName(env);
+      
+      await installMcpServerToAll(providers, serverName, serverEntry, 'global', process.cwd());
+      console.log(`CLEO: Installed MCP server to ${providers.length} provider(s)`);
+    }
+  } catch (err) {
+    // CAAMP/MCP setup is optional at install time - will be set up on first use
+    console.log('CLEO: CAAMP/MCP setup deferred (will complete on first use)');
+  }
+
+  console.log('CLEO: Global bootstrap complete!');
+  console.log('CLEO: Run "cleo init" in any project to set up local CLEO.');
+}
+
+// Run bootstrap
+bootstrapGlobalCleo().catch(err => {
+  console.error('CLEO: Bootstrap error (non-fatal):', err.message);
+  process.exit(0); // Never fail npm install
+});