agent-enderun 0.9.0 → 0.9.2

package/src/cli/utils/claude.ts

@@ -0,0 +1,56 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Finds the Claude config file path (if it exists).
+ */
+export function findClaudeConfigPath(): string | null {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home) return null;
+
+    const possiblePaths = [
+        path.join(home, ".config", "claude", "config.json"),
+        path.join(home, ".claude", "config.json"),
+        path.join(home, "Library", "Application Support", "Claude", "config.json"), // macOS Claude Desktop
+        path.join(home, "Library", "Application Support", "Claude Code", "config.json"), // macOS Claude Code
+        path.join(home, ".config", "Claude", "config.json"), // some Linux setups
+    ];
+
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
+
+/**
+ * Adds or updates an MCP server entry in Claude's config file.
+ */
+export function addMcpServerToClaude(configPath: string, serverName: string, serverConfig: Record<string, unknown>): boolean {
+    try {
+        let config: { mcpServers?: Record<string, Record<string, unknown>> } = { mcpServers: {} };
+
+        if (fs.existsSync(configPath)) {
+            const content = fs.readFileSync(configPath, "utf8");
+            config = JSON.parse(content);
+        }
+
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+
+        config.mcpServers[serverName] = serverConfig;
+
+        // Ensure parent directory exists
+        const dir = path.dirname(configPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+
+        fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/cli/utils/fs.ts

@@ -0,0 +1,139 @@
+import fs from "fs";
+import path from "path";
+
+import { remapFrameworkContent } from "../adapters.js"; // Import from the new adapters.js
+import type { AdapterId } from "../adapters.js";
+
+export function updateGitIgnore(targetPath: string, frameworkDir = ".gemini"): void {
+    const IGNORE_LINES = [
+        "# AI-Enderun",
+        `${frameworkDir}/logs/*.json`,
+        `${frameworkDir}/*.lock`,
+        ".env",
+        ".DS_Store",
+    ];
+
+    let content = "";
+    if (fs.existsSync(targetPath)) {
+        content = fs.readFileSync(targetPath, "utf8");
+    }
+
+    const lines = content.split("\n").map((l) => l.trim());
+    let added = false;
+
+    for (const line of IGNORE_LINES) {
+        if (!lines.includes(line)) {
+            content += (content.endsWith("\n") || content === "" ? "" : "\n") + line + "\n";
+            added = true;
+        }
+    }
+
+    if (added) {
+        fs.writeFileSync(targetPath, content);
+        console.warn("✅ .gitignore updated.");
+    }
+}
+
+export function ensureDir(dirPath: string): void {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+
+export function writeTextFile(filePath: string, content: string): void {
+    ensureDir(path.dirname(filePath));
+    // Use template literal for content handling to avoid issues with raw newlines
+    fs.writeFileSync(filePath, content.endsWith("\n") ? content : `${content}\n`);
+}
+
+export function writeJsonFile(filePath: string, value: unknown): void {
+    writeTextFile(filePath, JSON.stringify(value, null, 2));
+}
+
+interface SanitizeJsonFunction {
+  (obj: any, targetScope?: string): any;
+}
+
+export function copyDir(
+    src: string,
+    dest: string,
+    skipSet = new Set<string>(),
+    nonDestructive = false,
+    frameworkDir = ".gemini",
+    targetScope = "",
+    sanitizeJson: SanitizeJsonFunction,
+    adapterId: AdapterId = "gemini",
+): void {
+    const DEFAULT_SKIP = new Set(["node_modules", ".git", ".DS_Store", "package-lock.json"]);
+    const actualSkip = new Set([...DEFAULT_SKIP, ...skipSet]);
+
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+
+    fs.readdirSync(src, { withFileTypes: true }).forEach((entry) => {
+        if (actualSkip.has(entry.name)) return;
+
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            copyDir(
+                srcPath,
+                destPath,
+                skipSet,
+                nonDestructive,
+                frameworkDir,
+                targetScope,
+                sanitizeJson,
+                adapterId,
+            );
+        } else {
+            if (nonDestructive && fs.existsSync(destPath)) {
+                return;
+            }
+
+            const ext = path.extname(entry.name);
+            const textExtensions = [".md", ".json", ".js", ".ts", ".txt", ""];
+
+            if (textExtensions.includes(ext)) {
+                let content = fs.readFileSync(srcPath, "utf8");
+                content = remapFrameworkContent(content, frameworkDir, adapterId); // Use the new remap function
+
+                if (ext === ".json") {
+                    try {
+                        const json = JSON.parse(content);
+                        content = JSON.stringify(sanitizeJson(json, targetScope), null, 2);
+                        content = remapFrameworkContent(content, frameworkDir, adapterId); // Remap again after JSON.stringify for any placeholders
+                    } catch {
+                        content = content.replace(/workspace:[^"'\s]*/g, "*");
+                    }
+                } else {
+                    content = content.replace(/workspace:[^"'\s]*/g, "*");
+                }
+
+                fs.writeFileSync(destPath, content);
+            } else {
+                fs.copyFileSync(srcPath, destPath);
+            }
+        }
+    });
+}
+
+export function collectFiles(dir: string, extensions: string[]): string[] {
+    let results: string[] = [];
+    if (!fs.existsSync(dir)) return results;
+    const list = fs.readdirSync(dir);
+    list.forEach((file) => {
+        file = path.join(dir, file);
+        const stat = fs.statSync(file);
+        if (stat && stat.isDirectory()) {
+            if (!file.includes("node_modules") && !file.includes(".git")) {
+                results = results.concat(collectFiles(file, extensions));
+            }
+        } else if (extensions.includes(path.extname(file))) {
+            results.push(file);
+        }
+    });
+    return results;
+}

package/src/cli/utils/memory.ts

@@ -0,0 +1,141 @@
+import fs from "fs";
+import path from "path";
+import { sleep } from "./time.js";
+import { generateULID } from "./time.js";
+import { FRAMEWORK_DIR_CANDIDATES } from "../adapters.js";
+
+const targetDir = process.cwd();
+
+export function getFrameworkDir(): string {
+    for (const dir of FRAMEWORK_DIR_CANDIDATES) {
+        const dirPath = path.join(targetDir, dir);
+        if (!fs.existsSync(dirPath)) continue;
+        const hasMemory = fs.existsSync(path.join(dirPath, "PROJECT_MEMORY.md"));
+        const hasAgents = fs.existsSync(path.join(dirPath, "agents"));
+        if (hasMemory || hasAgents) {
+            return dir;
+        }
+    }
+    for (const dir of FRAMEWORK_DIR_CANDIDATES) {
+        if (fs.existsSync(path.join(targetDir, dir))) {
+            return dir;
+        }
+    }
+    return ".gemini";
+}
+
+export function getMemoryPath() {
+    return path.join(targetDir, getFrameworkDir(), "PROJECT_MEMORY.md");
+}
+
+export function getConfiguredPaths(): { backend: string; frontend: string; docs: string; tests: string } {
+    let backend = "apps/backend";
+    let frontend = "apps/web";
+    let docs = "docs";
+    let tests = "tests";
+    
+    try {
+        const frameworkDir = getFrameworkDir();
+        const configPath = path.join(targetDir, frameworkDir, "config.json");
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            if (config.paths) {
+                if (config.paths.backend) backend = config.paths.backend;
+                if (config.paths.frontend) frontend = config.paths.frontend;
+                if (config.paths.docs) docs = config.paths.docs;
+                if (config.paths.tests) tests = config.paths.tests;
+            }
+        }
+    } catch {
+        // ignore
+    }
+    return { backend, frontend, docs, tests };
+}
+
+export function acquireMemoryLock(lockPath: string, maxRetries = 5): boolean {
+    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        try {
+            const fd = fs.openSync(lockPath, "wx");
+            fs.closeSync(fd);
+            return true;
+        } catch (error: unknown) {
+            const err = error as NodeJS.ErrnoException;
+            if (err?.code !== "EEXIST") throw error;
+            if (attempt < maxRetries - 1) sleep(1000);
+        }
+    }
+    return false;
+}
+
+export function releaseMemoryLock(lockPath: string): void {
+    if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+}
+
+/**
+ * Create initial PROJECT_MEMORY.md if missing.
+ */
+export function initializeMemory(memoryPath: string, targetBase: string): void {
+    if (fs.existsSync(memoryPath)) return;
+
+    const traceId = generateULID();
+    const date = new Date().toISOString().split("T")[0];
+    const template = `# PROJECT MEMORY — Agent Enderun
+
+This file is the Single Source of Truth (SSOT) and the persistent memory of the project.
+
+## CURRENT STATUS
+
+| Active Phase | Profile | Last Update | Active Trace ID | Blockers |
+| :----------- | :------ | :---------- | :-------------- | :------- |
+| PHASE_0      | Lightweight | ${date} | ${traceId} | NONE |
+
+## PROJECT DEFINITION
+
+| Field | Value |
+| :--- | :--- |
+| Project Name | ${path.basename(process.cwd())} |
+| Platform | Not defined |
+| Frontend | React 19 + Vite + Panda CSS |
+| Backend | Node.js 20+ + Fastify |
+| DB | PostgreSQL |
+
+## DOD STATUS
+
+| Phase | Status | Note |
+| :--- | :--- | :--- |
+| PHASE_0 | IN_PROGRESS | Initializing project structure |
+| PHASE_1 | PENDING | |
+| PHASE_2 | PENDING | |
+| PHASE_3 | PENDING | |
+| PHASE_4 | PENDING | |
+
+## CRITICAL DECISIONS
+
+| Date | Decision | Rationale | Agent |
+| :--- | :--- | :--- | :--- |
+| ${date} | Project Initialized | Framework setup via CLI | @manager |
+
+## DELIVERABLES
+
+| Module | Status | Agent | Date |
+| :--- | :--- | :--- | :--- |
+
+## ACTIVE TASKS
+
+| Trace ID | Task | Agent | Priority | Status |
+| :--- | :--- | :--- | :--- | :--- |
+| ${traceId} | Framework setup and architecture alignment | @manager | P1 | IN_PROGRESS |
+
+## HISTORY (Persistent Memory)
+
+### ${date} — Framework Initialization
+
+- **Agent:** @manager
+- **Trace ID:** ${traceId}
+- **Action:** Initialized Agent Enderun framework and project structure.
+`;
+
+    const finalTemplate = template.replace(/\{\{FRAMEWORK_DIR\}\}/g, targetBase);
+    fs.writeFileSync(memoryPath, finalTemplate);
+    console.warn(`✅ PROJECT_MEMORY.md initialized in ${targetBase}`);
+}

package/src/cli/utils/pkg.ts

@@ -0,0 +1,215 @@
+import fs from "fs";
+import path from "path";
+
+const __filename = new URL(import.meta.url).pathname;
+const __dirname = path.dirname(__filename);
+const sourceDir = path.join(__dirname, "../../.."); // Adjust path as necessary to reach project root
+
+export function getPackageVersion() {
+    const pkg = JSON.parse(fs.readFileSync(path.join(sourceDir, "package.json"), "utf8"));
+    return pkg.version;
+}
+
+export function getPackageManager() {
+    const override = process.env.AGENT_ENDERUN_PACKAGE_MANAGER || process.env.AGENT_ENDERUN_PM || process.env.AI_ENDERUN_PACKAGE_MANAGER || process.env.AI_ENDERUN_PM;
+    if (override) return override.toLowerCase();
+
+    const userAgent = process.env.npm_config_user_agent || "";
+    const npmExecPath = process.env.npm_execpath || "";
+
+    if (userAgent.includes("pnpm") || npmExecPath.includes("pnpm")) return "pnpm";
+    if (userAgent.includes("yarn") || npmExecPath.includes("yarn")) return "yarn";
+
+    // Check for lockfiles in target directory
+    if (fs.existsSync(path.join(process.cwd(), "pnpm-lock.yaml")) || fs.existsSync(path.join(process.cwd(), "pnpm-workspace.yaml"))) return "pnpm";
+    if (fs.existsSync(path.join(process.cwd(), "yarn.lock"))) return "yarn";
+  
+    return "npm";
+}
+
+interface PackageJson {
+    name?: string;
+    version?: string;
+    type?: string;
+    workspaces?: string[];
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+    enderun?: Record<string, unknown>;
+  }
+
+export function mergePackageJson(targetPath: string, sourcePath: string): void {
+    let targetPkg: PackageJson = {}; 
+    if (fs.existsSync(targetPath)) {
+        try {
+            targetPkg = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+        } catch {
+            console.warn("⚠️  Could not parse existing package.json, creating a new one.");
+        }
+    }
+
+    const sourcePkg: PackageJson = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+  
+  type PackageMap = Record<string, string>;
+  const sanitizeDeps = (deps: PackageMap | Record<string, unknown> | undefined): Record<string, string> | undefined => {
+      if (!deps) return deps as undefined;
+      const cleaned: Record<string, string> = {};
+      for (const [name, version] of Object.entries(deps)) {
+          cleaned[name] = (typeof version === "string" && version.startsWith("workspace:")) ? "*" : String(version || "");
+      }
+      return cleaned;
+  };
+
+  const actualTargetScope = targetPkg.name && targetPkg.name.startsWith("@")
+      ? targetPkg.name.split("/")[0]
+      : (targetPkg.name ? `@${targetPkg.name}` : "");
+
+  // Cleanup potential leftovers from previous bugged runs where agent-enderun was renamed to target name
+  if (actualTargetScope) {
+      const scopeName = actualTargetScope.startsWith("@") ? actualTargetScope.slice(1) : actualTargetScope;
+      const cleanup = (obj: Record<string, string> | undefined): void => {
+          if (!obj) return;
+          delete obj[scopeName];
+          delete obj[actualTargetScope];
+          delete obj["agent-enderun"]; // Will be re-added correctly
+      };
+      cleanup(targetPkg.devDependencies);
+      cleanup(targetPkg.dependencies);
+  }
+
+  targetPkg.dependencies = sanitizeDeps({
+      ...targetPkg.dependencies,
+      ...sourcePkg.dependencies
+  });
+
+  // Merge scripts
+  const pkgMgr = getPackageManager();
+  const runCmd = pkgMgr === "yarn" ? "yarn" : (pkgMgr === "pnpm" ? "pnpm" : "npm run");
+  
+  targetPkg.scripts = {
+      ...targetPkg.scripts,
+      "enderun:status": "agent-enderun status",
+      "enderun:trace": "agent-enderun trace:new",
+      "enderun:verify": "agent-enderun verify-contract",
+      "enderun:check": "agent-enderun check",
+      "enderun:test": "vitest run",
+      "enderun:test:watch": "vitest",
+      "enderun:build": `${runCmd} build --prefix framework-mcp`,
+  };
+
+  const sourceDevDeps = sourcePkg.devDependencies || {};
+  targetPkg.devDependencies = sanitizeDeps({
+      ...targetPkg.devDependencies,
+      "agent-enderun": `^${sourcePkg.version}`,
+      ...(sourceDevDeps["@modelcontextprotocol/sdk"] ? {"@modelcontextprotocol/sdk": sourceDevDeps["@modelcontextprotocol/sdk"]} : {}),
+      ...(sourceDevDeps["zod"] ? {"zod": sourceDevDeps["zod"]} : {}),
+      ...(sourceDevDeps["ts-morph"] ? {"ts-morph": sourceDevDeps["ts-morph"]} : {}),
+      ...(sourceDevDeps["typescript"] ? {"typescript": sourceDevDeps["typescript"]} : {}),
+      ...(sourceDevDeps["@types/node"] ? {"@types/node": sourceDevDeps["@types/node"]} : {}),
+      ...(sourceDevDeps["tsx"] ? {"tsx": sourceDevDeps["tsx"]} : {}),
+      ...(sourceDevDeps["vitest"] ? {"vitest": sourceDevDeps["vitest"]} : {}),
+      "@pandacss/dev": sourceDevDeps["@pandacss/dev"] || "^1.11.1"
+  });
+
+  if (targetPkg.peerDependencies) {
+      targetPkg.peerDependencies = sanitizeDeps(targetPkg.peerDependencies);
+  }
+  if (targetPkg.optionalDependencies) {
+      targetPkg.optionalDependencies = sanitizeDeps(targetPkg.optionalDependencies);
+  }
+
+  // Ensure basic fields
+  if (!targetPkg.name) targetPkg.name = path.basename(process.cwd());
+  if (!targetPkg.version) targetPkg.version = "0.1.0";
+  if (!targetPkg.type) targetPkg.type = "module";
+  if (!targetPkg.workspaces) targetPkg.workspaces = ["apps/*", "framework-mcp"];
+
+  // Add metadata
+  targetPkg.enderun = {
+      version: sourcePkg.version || "0.0.0",
+      initializedAt: new Date().toISOString(),
+  };
+
+  fs.writeFileSync(targetPath, JSON.stringify(targetPkg, null, 2));
+  console.warn("✅ package.json updated with Enderun scripts and dependencies.");
+}
+
+export function sanitizeJson(obj: Record<string, unknown>, targetScope = ""): Record<string, unknown> {
+    if (typeof obj !== "object" || obj === null) return obj;
+    if (Array.isArray(obj)) return obj.map(item => sanitizeJson(item as Record<string, unknown>, targetScope)) as unknown as Record<string, unknown>;
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+        let finalKey = key;
+        let finalValue = value;
+
+        // Remove UnoCSS related keys or values
+        if (typeof key === "string" && key.includes("unocss")) continue;
+        if (typeof value === "string" && value.includes("unocss")) {
+            continue; // Skip this script/field
+        }
+
+        // Replace scope if needed
+        if (targetScope) {
+            const scopeName = targetScope.startsWith("@") ? targetScope.slice(1) : targetScope;
+
+            // Handle scoped: @ai-enderun/foo -> @target/foo
+            if (typeof key === "string" && key.startsWith("@ai-enderun/")) {
+                finalKey = key.replace("@ai-enderun/", `${targetScope}/`);
+            }
+            if (typeof value === "string" && value.startsWith("@ai-enderun/")) {
+                finalValue = value.replace("@ai-enderun/", `${targetScope}/`);
+            }
+
+            // Handle unscoped: ai-enderun-foo -> target-foo
+            if (typeof key === "string" && key.startsWith("ai-enderun-")) {
+                finalKey = key.replace("ai-enderun-", `${scopeName}-`);
+            }
+            if (typeof value === "string" && value.startsWith("ai-enderun-")) {
+                finalValue = value.replace("ai-enderun-", `${scopeName}-`);
+            }
+      
+            // Handle agent-enderun -> target (ONLY for the package name)
+            if (key === "name" && value === "agent-enderun") {
+                finalValue = scopeName;
+            }
+      
+            // Preserve agent-enderun in dependencies and bin
+            // (No action needed as finalKey/finalValue default to original)
+
+            if (typeof value === "string" && value.startsWith("workspace:")) {
+                finalValue = "*";
+            }
+        } else if (typeof value === "string" && value.startsWith("workspace:")) {
+            finalValue = "*";
+        }
+
+        cleaned[finalKey] = (typeof finalValue === "object" && finalValue !== null) ? sanitizeJson(finalValue as Record<string, unknown>, targetScope) : finalValue;
+    }
+    return cleaned;
+}
+
+export function deepCleanProtocols(dir: string, targetScope = ""): void {
+    if (!fs.existsSync(dir)) return;
+  
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === ".git") continue;
+            deepCleanProtocols(fullPath, targetScope);
+        } else if (entry.name === "package.json") {
+            try {
+                const content = fs.readFileSync(fullPath, "utf8");
+                const json = JSON.parse(content);
+                const cleaned = JSON.stringify(sanitizeJson(json, targetScope), null, 2);
+                fs.writeFileSync(fullPath, cleaned);
+            } catch {
+                // ignore malformed json
+            }
+        } else if (entry.name === "package-lock.json") {
+            fs.unlinkSync(fullPath);
+        }
+    }
+}

package/src/cli/utils/string.ts

@@ -0,0 +1,48 @@
+export function insertTaskRow(memoryContent: string, row: string): string | null {
+    const sectionHeader = "## ACTIVE TASKS";
+    const tableDivider = "| :--- | :--- | :--- | :--- | :--- |";
+    const sectionIndex = memoryContent.indexOf(sectionHeader);
+    if (sectionIndex === -1) return null;
+    const dividerIndex = memoryContent.indexOf(tableDivider, sectionIndex);
+    if (dividerIndex === -1) return null;
+    const dividerLineEnd = memoryContent.indexOf("\n", dividerIndex);
+    if (dividerLineEnd === -1) return null;
+
+    return (
+        memoryContent.slice(0, dividerLineEnd + 1) +
+    `${row}\n` +
+    memoryContent.slice(dividerLineEnd + 1)
+    );
+}
+
+export function sanitizeTableCell(value: unknown): string {
+    return String(value)
+        .replace(/\|/g, "\\|")
+        .replace(/\r?\n/g, " ")
+        .trim();
+}
+
+export function normalizeAgentName(agent?: unknown): string {
+    return String(agent || "manager").replace(/^@+/, "").trim() || "manager";
+}
+
+export function normalizePriority(priority?: unknown): string {
+    const normalized = String(priority || "P2").toUpperCase().trim();
+    return /^P[0-3]$/.test(normalized) ? normalized : "P2";
+}
+
+export function slugifyName(value: string): string {
+    const slug = String(value || "enderun-app")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "enderun-app";
+}
+
+export function titleCase(value: string): string {
+    return String(value || "Enderun App")
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (char) => char.toUpperCase());
+}

package/src/cli/utils/time.ts

@@ -0,0 +1,27 @@
+export function generateULID(seedTime = Date.now(), seed?: number) {
+    const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    const ENCODING_LEN = ENCODING.length;
+    let time = seedTime;
+    const timeChars = new Array(10);
+    for (let i = 9; i >= 0; i--) {
+        timeChars[i] = ENCODING.charAt(time % ENCODING_LEN);
+        time = Math.floor(time / ENCODING_LEN);
+    }
+    const randomChars = new Array(16);
+    if (seed) {
+        let pseudoRandom = seed;
+        for (let i = 0; i < 16; i++) {
+            pseudoRandom = (pseudoRandom * 16807) % 2147483647;
+            randomChars[i] = ENCODING.charAt(pseudoRandom % ENCODING_LEN);
+        }
+    } else {
+        for (let i = 0; i < 16; i++) {
+            randomChars[i] = ENCODING.charAt(Math.floor(Math.random() * ENCODING_LEN));
+        }
+    }
+    return timeChars.join("") + randomChars.join("");
+}
+
+export function sleep(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}