pulse-framework-cli 0.4.1

package/dist/commands/init.js

@@ -0,0 +1,570 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInitCommand = registerInitCommand;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const artifacts_js_1 = require("../lib/artifacts.js");
+const config_js_1 = require("../lib/config.js");
+const paths_js_1 = require("../lib/paths.js");
+const install_js_1 = require("../hooks/install.js");
+const input_js_1 = require("../lib/input.js");
+async function fileExists(p) {
+    try {
+        await promises_1.default.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function packageRoot() {
+    // dist/index.js -> dist/.. (package root)
+    return node_path_1.default.resolve(__dirname, "..", "..");
+}
+// ════════════════════════════════════════════════════════════════════════════
+// Helper Functions for MCP Setup
+// ════════════════════════════════════════════════════════════════════════════
+/**
+ * Get absolute path to Node.js executable
+ */
+function getNodePath() {
+    try {
+        return (0, node_child_process_1.execSync)("which node", { encoding: "utf8" }).trim();
+    }
+    catch {
+        // Fallback for common locations
+        const fallbacks = [
+            "/usr/local/bin/node",
+            "/opt/homebrew/bin/node",
+            `${node_os_1.default.homedir()}/.nvm/current/bin/node`,
+        ];
+        for (const p of fallbacks) {
+            try {
+                (0, node_child_process_1.execSync)(`${p} --version`, { encoding: "utf8" });
+                return p;
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error("Node.js not found. Please ensure node is in your PATH.");
+    }
+}
+/**
+ * Find pulse-mcp, install if not found
+ */
+async function ensurePulseMcpInstalled() {
+    // First check if already installed
+    try {
+        const mcpPath = (0, node_child_process_1.execSync)("which pulse-mcp", { encoding: "utf8" }).trim();
+        if (mcpPath)
+            return mcpPath;
+    }
+    catch {
+        // Not in PATH, continue to check other locations
+    }
+    // Check common npm global locations
+    const globalLocations = [
+        `${node_os_1.default.homedir()}/.npm-global/bin/pulse-mcp`,
+        "/usr/local/bin/pulse-mcp",
+        `${node_os_1.default.homedir()}/.pulse/node_modules/.bin/pulse-mcp`,
+    ];
+    for (const loc of globalLocations) {
+        if (await fileExists(loc)) {
+            return loc;
+        }
+    }
+    // Check if we're in the PulseFramework monorepo (development)
+    const monorepoBin = node_path_1.default.resolve(__dirname, "..", "..", "..", "pulse-mcp", "dist", "index.js");
+    if (await fileExists(monorepoBin)) {
+        return monorepoBin;
+    }
+    // Not found - try to install
+    // eslint-disable-next-line no-console
+    console.log("\n⚠️  pulse-mcp not found. Attempting to install...\n");
+    try {
+        // Try npm link first (for development)
+        (0, node_child_process_1.execSync)("npm link @pulseframework/pulse-mcp 2>/dev/null || npm install -g @pulseframework/pulse-mcp", {
+            encoding: "utf8",
+            stdio: "inherit",
+        });
+        const newPath = (0, node_child_process_1.execSync)("which pulse-mcp", { encoding: "utf8" }).trim();
+        // eslint-disable-next-line no-console
+        console.log(`✅ pulse-mcp installed: ${newPath}\n`);
+        return newPath;
+    }
+    catch (installError) {
+        // eslint-disable-next-line no-console
+        console.log("\n⚠️  Could not auto-install pulse-mcp.");
+        // eslint-disable-next-line no-console
+        console.log("   Please run manually:");
+        // eslint-disable-next-line no-console
+        console.log("   npm install -g @pulseframework/pulse-mcp");
+        // eslint-disable-next-line no-console
+        console.log("   OR (from PulseFramework repo):");
+        // eslint-disable-next-line no-console
+        console.log("   npm link -w packages/pulse-mcp\n");
+        throw new Error("pulse-mcp installation failed");
+    }
+}
+/**
+ * Detect if we're in a subdirectory of a Cursor workspace
+ * Returns the workspace root if found, null otherwise
+ */
+async function detectCursorWorkspace(repoRoot) {
+    let current = node_path_1.default.dirname(repoRoot);
+    // Walk up the directory tree
+    while (current !== "/" && current !== node_path_1.default.dirname(current)) {
+        const cursorDir = node_path_1.default.join(current, ".cursor");
+        if (await fileExists(cursorDir)) {
+            return current;
+        }
+        current = node_path_1.default.dirname(current);
+    }
+    return null;
+}
+/**
+ * Get the global Cursor MCP config path
+ */
+function getGlobalMcpConfigPath() {
+    return node_path_1.default.join(node_os_1.default.homedir(), ".cursor", "mcp.json");
+}
+function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Initialize project for PULSE (.pulse/, Config, MCP, Cursor Rules)")
+        .option("-p, --path <path>", "Target path (default: cwd)")
+        .option("--hooks", "Install Git hooks (pre-commit, pre-push)")
+        .option("--preset <name>", "Preset: frontend, backend, fullstack, monorepo, custom")
+        .option("--mcp", "Install MCP + Cursor Rules")
+        .option("--global", "Install MCP config globally (~/.cursor/mcp.json)")
+        .option("--agents", "Create AGENTS.md (universal for all editors)")
+        .option("--no-interactive", "No interactive prompts")
+        .action(async (opts) => {
+        const start = node_path_1.default.resolve(opts.path ?? process.cwd());
+        const repoRoot = await (0, paths_js_1.findRepoRoot)(start);
+        if (!repoRoot) {
+            throw new Error(`Not in a git repository: ${start}`);
+        }
+        // eslint-disable-next-line no-console
+        console.log("\n🎯 PULSE Init\n");
+        await (0, artifacts_js_1.ensurePulseDirs)(repoRoot);
+        // eslint-disable-next-line no-console
+        console.log(`✅ .pulse/ directory created`);
+        // ════════════════════════════════════════════════════════════════════════
+        // Preset Auswahl
+        // ════════════════════════════════════════════════════════════════════════
+        let preset = "custom";
+        if (opts.preset && (0, config_js_1.getPresetNames)().includes(opts.preset)) {
+            preset = opts.preset;
+        }
+        else if (opts.interactive !== false) {
+            // eslint-disable-next-line no-console
+            console.log("\n📦 Choose a preset for your project:\n");
+            const choices = [
+                { value: "frontend", label: "🎨 Frontend - React/Vue/Angular (stricter limits)" },
+                { value: "backend", label: "⚙️ Backend - API/Services (moderate limits)" },
+                { value: "fullstack", label: "🔄 Fullstack - Frontend + Backend" },
+                { value: "monorepo", label: "📦 Monorepo - Multiple packages (looser limits)" },
+                { value: "custom", label: "⚙️ Custom - Standard settings" },
+            ];
+            preset = await (0, input_js_1.promptSelect)("Preset", choices, "fullstack");
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Create config
+        // ════════════════════════════════════════════════════════════════════════
+        const cfgPath = (0, paths_js_1.configFile)(repoRoot);
+        if (!(await fileExists(cfgPath))) {
+            const presetConfig = config_js_1.PRESETS[preset];
+            const config = {
+                ...config_js_1.DEFAULT_CONFIG,
+                preset,
+                thresholds: {
+                    warnMaxFilesChanged: presetConfig.warnMaxFilesChanged,
+                    warnMaxLinesChanged: presetConfig.warnMaxLinesChanged,
+                    warnMaxDeletions: presetConfig.warnMaxDeletions,
+                },
+                checkpointReminderMinutes: presetConfig.checkpointReminderMinutes,
+            };
+            await promises_1.default.writeFile(cfgPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+            // eslint-disable-next-line no-console
+            console.log(`✅ Config created: ${cfgPath} (Preset: ${preset})`);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.log(`ℹ️ Config exists: ${cfgPath}`);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // .cursorrules kopieren (Fallback ohne MCP)
+        // ════════════════════════════════════════════════════════════════════════
+        const cursorrulesDst = node_path_1.default.join(repoRoot, ".cursorrules");
+        if (!(await fileExists(cursorrulesDst))) {
+            const src = node_path_1.default.join(packageRoot(), "templates", ".cursorrules");
+            if (await fileExists(src)) {
+                await promises_1.default.copyFile(src, cursorrulesDst);
+                // eslint-disable-next-line no-console
+                console.log(`✅ .cursorrules created (Fallback rules)`);
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.log(`⚠️ .cursorrules template not found: ${src}`);
+            }
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.log(`ℹ️ .cursorrules exists`);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // MCP + Cursor Rules (interactive or via flag)
+        // ════════════════════════════════════════════════════════════════════════
+        let installMcp = opts.mcp === true || opts.global === true;
+        const useGlobalMcp = opts.global === true;
+        if (!installMcp && opts.interactive !== false) {
+            // eslint-disable-next-line no-console
+            console.log("");
+            installMcp = await (0, input_js_1.promptConfirm)("Install MCP + Cursor Rules? (recommended for Cursor IDE)", true);
+        }
+        if (installMcp) {
+            await installCursorIntegration(repoRoot, useGlobalMcp);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // AGENTS.md (Universal for other editors)
+        // ════════════════════════════════════════════════════════════════════════
+        let installAgents = opts.agents === true;
+        if (!installAgents && !installMcp && opts.interactive !== false) {
+            // eslint-disable-next-line no-console
+            console.log("");
+            installAgents = await (0, input_js_1.promptConfirm)("Create AGENTS.md? (universal for Windsurf, Copilot, etc.)", true);
+        }
+        if (installAgents) {
+            await installAgentsMd(repoRoot);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Role Templates kopieren
+        // ════════════════════════════════════════════════════════════════════════
+        const rolesSrcDir = node_path_1.default.join(packageRoot(), "templates", "roles");
+        const rolesDstDir = node_path_1.default.join(repoRoot, ".pulse", "templates", "roles");
+        if (await fileExists(rolesSrcDir)) {
+            await promises_1.default.mkdir(rolesDstDir, { recursive: true });
+            const roleFiles = await promises_1.default.readdir(rolesSrcDir);
+            for (const f of roleFiles) {
+                if (!f.endsWith(".cursorrules"))
+                    continue;
+                await promises_1.default.copyFile(node_path_1.default.join(rolesSrcDir, f), node_path_1.default.join(rolesDstDir, f));
+            }
+            // eslint-disable-next-line no-console
+            console.log(`✅ Role templates copied`);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Git Hooks
+        // ════════════════════════════════════════════════════════════════════════
+        if (opts.hooks) {
+            await (0, install_js_1.installHooks)(repoRoot);
+            // eslint-disable-next-line no-console
+            console.log(`✅ Git hooks installed`);
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Summary
+        // ════════════════════════════════════════════════════════════════════════
+        // eslint-disable-next-line no-console
+        console.log(`\n${"─".repeat(50)}`);
+        // eslint-disable-next-line no-console
+        console.log(`\n✨ PULSE initialized!\n`);
+        // eslint-disable-next-line no-console
+        console.log(`Preset: ${preset}`);
+        // eslint-disable-next-line no-console
+        console.log(`Max Lines: ${config_js_1.PRESETS[preset].warnMaxLinesChanged}`);
+        // eslint-disable-next-line no-console
+        console.log(`Checkpoint: ${config_js_1.PRESETS[preset].checkpointReminderMinutes} min`);
+        // eslint-disable-next-line no-console
+        console.log(`MCP: ${installMcp ? "✅ Installed" : "❌ Not installed"}`);
+        // eslint-disable-next-line no-console
+        console.log(`AGENTS.md: ${installAgents ? "✅ Created" : "❌ Not created"}\n`);
+        if (installMcp) {
+            // eslint-disable-next-line no-console
+            console.log(`📋 Next steps for MCP:`);
+            // eslint-disable-next-line no-console
+            console.log(`   1. Restart Cursor (MCP loads automatically)`);
+            // eslint-disable-next-line no-console
+            console.log(`   2. In Cursor: Settings > Features > Enable MCP`);
+            // eslint-disable-next-line no-console
+            console.log(`   3. Test: pulse status\n`);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.log(`Next steps:`);
+            // eslint-disable-next-line no-console
+            console.log(`  1. pulse status      - Check current state`);
+            // eslint-disable-next-line no-console
+            console.log(`  2. pulse run         - Start workflow`);
+            // eslint-disable-next-line no-console
+            console.log(`  3. pulse s           - Create single prompt\n`);
+        }
+    });
+}
+/**
+ * Install Cursor MCP integration
+ * Creates .cursor/rules/pulse.mdc and .cursor/mcp.json (or global ~/.cursor/mcp.json)
+ */
+async function installCursorIntegration(repoRoot, useGlobal) {
+    // ────────────────────────────────────────────────────────────────────────────
+    // 0. Workspace Detection - check if Git root differs from Cursor workspace
+    // ────────────────────────────────────────────────────────────────────────────
+    const workspaceRoot = await detectCursorWorkspace(repoRoot);
+    const installLocations = [repoRoot];
+    if (workspaceRoot && workspaceRoot !== repoRoot) {
+        // eslint-disable-next-line no-console
+        console.log(`\n⚠️  Workspace mismatch detected:`);
+        // eslint-disable-next-line no-console
+        console.log(`   Git root:        ${repoRoot}`);
+        // eslint-disable-next-line no-console
+        console.log(`   Cursor workspace: ${workspaceRoot}`);
+        // eslint-disable-next-line no-console
+        console.log(`   → Installing rules in BOTH locations\n`);
+        installLocations.push(workspaceRoot);
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // 1. Install Cursor Rules in all locations
+    // ────────────────────────────────────────────────────────────────────────────
+    for (const location of installLocations) {
+        const cursorDir = node_path_1.default.join(location, ".cursor");
+        const rulesDir = node_path_1.default.join(cursorDir, "rules");
+        await promises_1.default.mkdir(rulesDir, { recursive: true });
+        const rulesDst = node_path_1.default.join(rulesDir, "pulse.mdc");
+        const rulesSrc = node_path_1.default.join(packageRoot(), "templates", "cursor", "pulse.mdc");
+        if (await fileExists(rulesSrc)) {
+            await promises_1.default.copyFile(rulesSrc, rulesDst);
+        }
+        else {
+            await promises_1.default.writeFile(rulesDst, generatePulseRules(), "utf8");
+        }
+        const relPath = node_path_1.default.relative(process.cwd(), rulesDst);
+        // eslint-disable-next-line no-console
+        console.log(`✅ Cursor rules: ${relPath}`);
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // 2. MCP Config with absolute paths
+    // ────────────────────────────────────────────────────────────────────────────
+    let nodePath;
+    let pulseMcpPath;
+    try {
+        nodePath = getNodePath();
+        pulseMcpPath = await ensurePulseMcpInstalled();
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.log(`\n❌ MCP setup failed: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    // Determine MCP config location
+    const mcpDst = useGlobal
+        ? getGlobalMcpConfigPath()
+        : node_path_1.default.join(repoRoot, ".cursor", "mcp.json");
+    // Ensure directory exists
+    await promises_1.default.mkdir(node_path_1.default.dirname(mcpDst), { recursive: true });
+    // Check if we need a wrapper script (for workspace mismatch)
+    let mcpCommand = nodePath;
+    let mcpArgs = [pulseMcpPath];
+    if (!useGlobal && workspaceRoot && workspaceRoot !== repoRoot) {
+        // Create wrapper script that changes to the correct directory
+        const wrapperPath = node_path_1.default.join(repoRoot, ".pulse", "run-mcp.sh");
+        // Determine how to execute pulse-mcp:
+        // - If it's a .js file, use node to run it
+        // - If it's an executable (from npm global bin), run it directly
+        const isJsFile = pulseMcpPath.endsWith(".js");
+        const execCommand = isJsFile
+            ? `exec "${nodePath}" "${pulseMcpPath}"`
+            : `exec "${pulseMcpPath}"`;
+        const wrapperContent = `#!/bin/bash
+# PULSE MCP Wrapper - ensures correct working directory
+cd "${repoRoot}"
+${execCommand}
+`;
+        await promises_1.default.writeFile(wrapperPath, wrapperContent, "utf8");
+        await promises_1.default.chmod(wrapperPath, 0o755);
+        mcpCommand = wrapperPath;
+        mcpArgs = [];
+        // eslint-disable-next-line no-console
+        console.log(`✅ Wrapper script: .pulse/run-mcp.sh (fixes workspace mismatch)`);
+    }
+    // Build MCP config
+    const mcpConfig = {
+        mcpServers: {
+            pulse: {
+                command: mcpCommand,
+                args: mcpArgs,
+                env: {
+                    PULSE_PROJECT_ROOT: repoRoot,
+                },
+            },
+        },
+    };
+    // Merge with existing config if present
+    if (await fileExists(mcpDst)) {
+        try {
+            const existing = JSON.parse(await promises_1.default.readFile(mcpDst, "utf8"));
+            if (existing.mcpServers && typeof existing.mcpServers === "object") {
+                mcpConfig.mcpServers = {
+                    ...existing.mcpServers,
+                    pulse: mcpConfig.mcpServers.pulse,
+                };
+            }
+        }
+        catch {
+            // Ignore parse errors, overwrite
+        }
+    }
+    await promises_1.default.writeFile(mcpDst, JSON.stringify(mcpConfig, null, 2) + "\n", "utf8");
+    const mcpLocation = useGlobal ? "~/.cursor/mcp.json (global)" : ".cursor/mcp.json (local)";
+    // eslint-disable-next-line no-console
+    console.log(`✅ MCP config: ${mcpLocation}`);
+    // ────────────────────────────────────────────────────────────────────────────
+    // 3. Post-Init Validation
+    // ────────────────────────────────────────────────────────────────────────────
+    await validateMcpSetup(nodePath, pulseMcpPath, mcpDst);
+}
+/**
+ * Validate MCP setup after installation
+ */
+async function validateMcpSetup(nodePath, pulseMcpPath, mcpConfigPath) {
+    // eslint-disable-next-line no-console
+    console.log(`\n🔍 Validating MCP setup...\n`);
+    let allOk = true;
+    // Check 1: Node executable
+    try {
+        (0, node_child_process_1.execSync)(`"${nodePath}" --version`, { encoding: "utf8" });
+        // eslint-disable-next-line no-console
+        console.log(`   ✅ Node: ${nodePath}`);
+    }
+    catch {
+        // eslint-disable-next-line no-console
+        console.log(`   ❌ Node not executable: ${nodePath}`);
+        allOk = false;
+    }
+    // Check 2: pulse-mcp executable
+    if (await fileExists(pulseMcpPath)) {
+        // eslint-disable-next-line no-console
+        console.log(`   ✅ pulse-mcp: ${pulseMcpPath}`);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.log(`   ❌ pulse-mcp not found: ${pulseMcpPath}`);
+        allOk = false;
+    }
+    // Check 3: MCP config exists
+    if (await fileExists(mcpConfigPath)) {
+        // eslint-disable-next-line no-console
+        console.log(`   ✅ MCP config: ${mcpConfigPath}`);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.log(`   ❌ MCP config missing: ${mcpConfigPath}`);
+        allOk = false;
+    }
+    if (allOk) {
+        // eslint-disable-next-line no-console
+        console.log(`\n   ✨ All checks passed!`);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.log(`\n   ⚠️  Some checks failed. See above for details.`);
+    }
+}
+/**
+ * Generate pulse.mdc rules content (fallback if template not found)
+ */
+function generatePulseRules() {
+    return `---
+description: PULSE Framework - Automated safeguards for every message
+globs: *
+alwaysApply: true
+---
+
+# PULSE Framework Safeguards
+
+## MANDATORY: Before every answer
+
+**Before you answer, run the following MCP tools:**
+
+1. **\`pulse_status\`**
+   - Shows: Profile, time since checkpoint, changes, findings
+   - If >15 min since checkpoint → Recommend checkpoint
+
+2. **\`pulse_doctor\`** (if you changed code)
+   - Checks: Secrets, deletes, scope, loop signals
+   - Critical findings → STOP
+
+## Safeguards (non-negotiable)
+
+- ⏱️ **MAX 30 min autonomous** - Then STOP + ask user
+- 🗑️ **NO DELETE** without explicit confirmation
+- 📤 **NO GIT PUSH** without confirmation
+- 🔐 **NO Secrets** in code
+- 📋 **Git commit every 5-10 min** via \`pulse_checkpoint\`
+
+## In case of problems
+
+If you get stuck after 2-3 attempts:
+1. **STOP** - No further changes
+2. **\`pulse_escalate\`**
+3. Wait for user instruction
+
+## MCP Tools
+
+| Tool | When |
+|------|------|
+| \`pulse_status\` | BEFORE EVERY ANSWER |
+| \`pulse_checkpoint\` | After changes (5-10 min) |
+| \`pulse_doctor\` | Before commits |
+| \`pulse_escalate\` | When stuck |
+`;
+}
+/**
+ * Install AGENTS.md (universal format for all AI editors)
+ */
+async function installAgentsMd(repoRoot) {
+    const agentsDst = node_path_1.default.join(repoRoot, "AGENTS.md");
+    const agentsSrc = node_path_1.default.join(packageRoot(), "templates", "AGENTS.md");
+    if (await fileExists(agentsDst)) {
+        // eslint-disable-next-line no-console
+        console.log(`ℹ️ AGENTS.md already exists`);
+        return;
+    }
+    if (await fileExists(agentsSrc)) {
+        await promises_1.default.copyFile(agentsSrc, agentsDst);
+    }
+    else {
+        // Fallback: Minimal inline version
+        const content = `# AI Agent Instructions
+
+> Universal agent configuration for PULSE Framework.
+
+## Critical Safeguards
+
+1. 🗑️ **DELETE Guard** - Never delete without confirmation
+2. 📤 **PUSH Guard** - Never push without confirmation  
+3. 🔐 **SECRETS Guard** - Never commit secrets
+4. ⏱️ **30-Min Rule** - Stop after 30 min autonomous work
+
+## Commands
+
+| Command | When |
+|---------|------|
+| \`pulse status\` | Check state before work |
+| \`pulse checkpoint\` | After changes (5-10 min) |
+| \`pulse doctor\` | Before commits |
+| \`pulse escalate\` | When stuck |
+| \`pulse reset\` | To go back |
+
+*Generated by PULSE Framework*
+`;
+        await promises_1.default.writeFile(agentsDst, content, "utf8");
+    }
+    // eslint-disable-next-line no-console
+    console.log(`✅ AGENTS.md created (universal for all AI editors)`);
+}

package/dist/commands/learn.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerLearnCommand(program: Command): void;