@aslomon/effectum 0.4.0 → 0.5.0

package/bin/lib/tool-loader.js

@@ -0,0 +1,243 @@
+/**
+ * Dynamic tool loader — loads JSON-based tool definitions from system/tools/,
+ * merges foundation + stack + community definitions, and deduplicates by key.
+ *
+ * New stacks require only a new JSON file in system/tools/ — zero code changes.
+ * Community/local overrides are loaded from .effectum/tools/ and ~/.effectum/tools/.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ─── JSON loading helpers ────────────────────────────────────────────────────
+
+/**
+ * Load tools from a JSON file. Returns empty array if file doesn't exist or is invalid.
+ * @param {string} filePath - absolute path to JSON file
+ * @returns {Array<object>}
+ */
+function loadJsonTools(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed.tools)) return parsed.tools;
+    if (Array.isArray(parsed)) return parsed;
+    return [];
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Load all JSON files from a directory.
+ * Skips files starting with _ (e.g., _schema.json).
+ * @param {string} dirPath - directory to scan
+ * @returns {Array<object>}
+ */
+function loadToolsFromDir(dirPath) {
+  const tools = [];
+  try {
+    if (!fs.existsSync(dirPath)) return tools;
+    const files = fs
+      .readdirSync(dirPath)
+      .filter((f) => f.endsWith(".json") && !f.startsWith("_"));
+    for (const file of files) {
+      tools.push(...loadJsonTools(path.join(dirPath, file)));
+    }
+  } catch (_) {
+    // Directory doesn't exist or isn't readable
+  }
+  return tools;
+}
+
+// ─── Tool resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Find the system/tools/ directory relative to this module (which lives in bin/lib/).
+ * @returns {string}
+ */
+function getSystemToolsDir() {
+  return path.resolve(__dirname, "..", "..", "system", "tools");
+}
+
+/**
+ * Get the JSON filename for a stack key.
+ * @param {string} stack - e.g., "nextjs-supabase"
+ * @returns {string} - e.g., "nextjs-supabase.json"
+ */
+function stackToFilename(stack) {
+  return `${stack}.json`;
+}
+
+// ─── System basics (pre-config) ──────────────────────────────────────────────
+
+/**
+ * Get system-level basics that must be checked before any configuration.
+ * These are Homebrew (macOS), Git, Node.js, and Claude Code.
+ * @returns {Array<object>}
+ */
+function getSystemBasics() {
+  const platform = os.platform() === "darwin" ? "darwin" : "linux";
+  const basics = [];
+
+  // Homebrew (macOS only)
+  if (platform === "darwin") {
+    basics.push({
+      key: "brew",
+      bin: "brew",
+      displayName: "Homebrew",
+      category: "system",
+      why: "Package manager for macOS — needed to install other tools",
+      priority: 0,
+      autoInstall: true,
+      install: {
+        darwin:
+          '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+      },
+      check: "brew --version",
+    });
+  }
+
+  // Git
+  basics.push({
+    key: "git",
+    bin: "git",
+    displayName: "Git",
+    category: "system",
+    why: "Version control — required for all projects",
+    priority: 0,
+    autoInstall: true,
+    install: {
+      darwin: "xcode-select --install",
+      linux: "sudo apt install -y git",
+    },
+    check: "git --version",
+  });
+
+  // Node.js
+  basics.push({
+    key: "node",
+    bin: "node",
+    displayName: "Node.js",
+    category: "system",
+    why: "JavaScript runtime — required for Claude Code and npm tools",
+    priority: 0,
+    autoInstall: true,
+    install: {
+      darwin: "brew install node",
+      linux: "sudo apt install -y nodejs npm",
+    },
+    check: "node --version",
+  });
+
+  // Claude Code
+  basics.push({
+    key: "claude",
+    bin: "claude",
+    displayName: "Claude Code",
+    category: "system",
+    why: "AI coding agent — the core of the autonomous workflow",
+    priority: 0,
+    autoInstall: true,
+    install: {
+      all: "npm i -g @anthropic-ai/claude-code",
+    },
+    check: "claude --version",
+  });
+
+  return basics;
+}
+
+// ─── Main loader ─────────────────────────────────────────────────────────────
+
+/**
+ * Load and merge tool definitions for a given stack.
+ *
+ * Merge order (last wins for duplicate keys):
+ *   1. foundation.json (always)
+ *   2. stack-specific.json (if exists)
+ *   3. Community: <targetDir>/.effectum/tools/*.json
+ *   4. Community: ~/.effectum/tools/*.json
+ *
+ * @param {string} stack - stack key (e.g., "nextjs-supabase", "generic")
+ * @param {string} [targetDir] - project directory for local community tools
+ * @returns {Array<object>} - deduplicated, priority-sorted tool list
+ */
+function loadToolDefinitions(stack, targetDir) {
+  const systemDir = getSystemToolsDir();
+  const tools = [];
+
+  // 1. Foundation (always loaded)
+  const foundationPath = path.join(systemDir, "foundation.json");
+  tools.push(...loadJsonTools(foundationPath));
+
+  // 2. Stack-specific
+  if (stack && stack !== "foundation") {
+    const stackPath = path.join(systemDir, stackToFilename(stack));
+    tools.push(...loadJsonTools(stackPath));
+  }
+
+  // 3. Community: local project overrides
+  if (targetDir) {
+    const localToolsDir = path.join(targetDir, ".effectum", "tools");
+    tools.push(...loadToolsFromDir(localToolsDir));
+  }
+
+  // 4. Community: global user overrides
+  const globalToolsDir = path.join(os.homedir(), ".effectum", "tools");
+  tools.push(...loadToolsFromDir(globalToolsDir));
+
+  return deduplicateByKey(tools);
+}
+
+// ─── Deduplication ───────────────────────────────────────────────────────────
+
+/**
+ * Deduplicate tools by key. Last occurrence wins (community overrides bundled).
+ * Result is sorted by priority (ascending).
+ * @param {Array<object>} tools
+ * @returns {Array<object>}
+ */
+function deduplicateByKey(tools) {
+  const map = new Map();
+  for (const tool of tools) {
+    map.set(tool.key, tool);
+  }
+  return Array.from(map.values()).sort(
+    (a, b) => (a.priority ?? 5) - (b.priority ?? 5),
+  );
+}
+
+// ─── List available stacks ───────────────────────────────────────────────────
+
+/**
+ * List all available stack JSON files (excluding foundation and _schema).
+ * @returns {Array<string>} - stack keys (e.g., ["nextjs-supabase", "python-fastapi"])
+ */
+function listAvailableStacks() {
+  const systemDir = getSystemToolsDir();
+  try {
+    return fs
+      .readdirSync(systemDir)
+      .filter(
+        (f) =>
+          f.endsWith(".json") && !f.startsWith("_") && f !== "foundation.json",
+      )
+      .map((f) => f.replace(".json", ""));
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = {
+  loadJsonTools,
+  loadToolsFromDir,
+  getSystemToolsDir,
+  getSystemBasics,
+  loadToolDefinitions,
+  deduplicateByKey,
+  listAvailableStacks,
+};

package/bin/lib/ui.js

@@ -21,10 +21,14 @@ const {
 } = require("./recommendation");
 const {
   checkAllTools,
+  checkSystemBasics,
   formatToolStatus,
   formatInstallInstructions,
+  formatInstallPlan,
+  formatAuthStatus,
   installTool,
-  checkAuth,
+  categorizeForInstall,
+  checkAllAuth,
 } = require("./cli-tools");
 
 /** @type {import("@clack/prompts")} */
@@ -502,103 +506,159 @@ async function askGitBranch() {
   return { create: true, name };
 }
 
-// ─── CLI Tool Check ─────────────────────────────────────────────────────────
+// ─── System Basics Check (Phase 1) ──────────────────────────────────────────
 
 /**
- * Run CLI tool check and offer installation/auth for missing tools.
+ * Check system basics (Homebrew, Git, Node.js, Claude Code) before config.
+ * Offers to install missing basics.
+ * @returns {Promise<void>}
+ */
+async function showSystemCheck() {
+  const result = checkSystemBasics();
+
+  p.note(formatToolStatus(result.tools), "System Basics");
+
+  if (result.missing.length === 0) {
+    p.log.success("All system basics are installed.");
+    return;
+  }
+
+  p.log.warn(`${result.missing.length} system tool(s) not found.`);
+
+  for (const tool of result.missing) {
+    const name = tool.displayName || tool.key;
+    const wantInstall = await p.confirm({
+      message: `Install ${name}? (${tool.why})`,
+      initialValue: true,
+    });
+    handleCancel(wantInstall);
+
+    if (wantInstall) {
+      const s = p.spinner();
+      s.start(`Installing ${name}...`);
+      const installResult = installTool(tool);
+      if (installResult.ok) {
+        tool.installed = true;
+        s.stop(`${name} installed`);
+      } else {
+        s.stop(`${name} failed: ${installResult.error || "unknown error"}`);
+        p.log.warn(`You can install ${name} manually later.`);
+      }
+    }
+  }
+}
+
+// ─── Consolidated Installation Plan (Phase 3) ──────────────────────────────
+
+/**
+ * Show consolidated installation plan for stack tools and install with one confirmation.
  * @param {string} stack - selected stack key
+ * @param {string} [targetDir] - project directory for community overrides
  * @returns {Promise<{ tools: Array<object>, missing: Array<object>, installed: Array<object> }>}
  */
-async function showCliToolCheck(stack) {
-  const result = checkAllTools(stack);
+async function showInstallPlan(stack, targetDir) {
+  const result = checkAllTools(stack, targetDir);
 
-  p.note(formatToolStatus(result.tools), "CLI Tool Check");
+  p.note(formatToolStatus(result.tools), "Stack Tools");
 
   if (result.missing.length === 0) {
-    p.log.success("All CLI tools are installed.");
-  } else {
-    p.log.warn(`${result.missing.length} tool(s) not found.`);
-
-    const action = await p.select({
-      message: "How would you like to handle missing tools?",
-      options: [
-        {
-          value: "install",
-          label: "Install all missing",
-          hint: "Run install commands automatically",
-        },
-        {
-          value: "show",
-          label: "Show commands only",
-          hint: "Display install commands for manual use",
-        },
-        {
-          value: "skip",
-          label: "Skip",
-          hint: "Continue without installing",
-        },
-      ],
-      initialValue: "show",
+    p.log.success("All stack tools are installed.");
+    return result;
+  }
+
+  // Categorize missing tools
+  const plan = categorizeForInstall(result.tools);
+
+  // Show the consolidated plan
+  p.note(formatInstallPlan(plan), "Installation Plan");
+
+  // Auto-install with one confirmation
+  if (plan.autoInstall.length > 0) {
+    const names = plan.autoInstall
+      .map((t) => t.displayName || t.key)
+      .join(", ");
+    const confirm = await p.confirm({
+      message: `Install ${plan.autoInstall.length} tool(s)? (${names})`,
+      initialValue: true,
     });
-    handleCancel(action);
+    handleCancel(confirm);
 
-    if (action === "install") {
-      for (const tool of result.missing) {
+    if (confirm) {
+      for (const tool of plan.autoInstall) {
+        const name = tool.displayName || tool.key;
         const s = p.spinner();
-        s.start(`Installing ${tool.key}...`);
+        s.start(`Installing ${name}...`);
         const installResult = installTool(tool);
         if (installResult.ok) {
-          tool.installed = true;
-          s.stop(`${tool.key} installed`);
+          // Update in result too
+          const match = result.tools.find((t) => t.key === tool.key);
+          if (match) match.installed = true;
+          s.stop(`${name} installed`);
         } else {
-          s.stop(
-            `${tool.key} failed: ${installResult.error || "unknown error"}`,
-          );
+          s.stop(`${name} failed: ${installResult.error || "unknown error"}`);
         }
       }
-    } else if (action === "show") {
-      p.note(formatInstallInstructions(result.missing), "Install Commands");
     }
   }
 
-  // Auth check for installed tools that need auth
-  const authTools = result.tools.filter((t) => t.installed && t.auth);
+  if (plan.manual.length > 0) {
+    p.log.info("Manual setup required for the tools listed above.");
+  }
 
-  if (authTools.length > 0) {
-    const authResults = authTools.map((t) => {
-      const authStatus = checkAuth(t);
-      return { ...t, ...authStatus };
-    });
+  return result;
+}
 
-    const unauthenticated = authResults.filter(
-      (t) => t.needsAuth && !t.authenticated,
-    );
+// ─── Auth Flow (Phase 4) ────────────────────────────────────────────────────
 
-    if (unauthenticated.length > 0) {
-      const authLines = authResults.map((t) => {
-        const icon = t.authenticated ? "\u2705" : "\u274C";
-        return `  ${icon} ${t.key}${!t.authenticated ? ` — run: ${t.authSetup}` : ""}`;
-      });
-      p.note(authLines.join("\n"), "Auth Status");
-
-      const runAuth = await p.confirm({
-        message:
-          "Would you like to run auth commands for unauthenticated tools?",
-        initialValue: false,
-      });
-      handleCancel(runAuth);
-
-      if (runAuth) {
-        p.log.info(
-          "Auth commands require interactive input. Run these manually:\n" +
-            unauthenticated.map((t) => `  ${t.key}: ${t.authSetup}`).join("\n"),
-        );
-      }
-    } else {
-      p.log.success("All tools are authenticated.");
-    }
+/**
+ * Check auth status for installed tools and guide through authentication.
+ * @param {Array<object>} tools - tools with `installed` status
+ * @returns {Promise<void>}
+ */
+async function showAuthCheck(tools) {
+  const authResults = checkAllAuth(tools);
+
+  if (authResults.length === 0) return;
+
+  p.note(formatAuthStatus(authResults), "Auth Status");
+
+  const unauthenticated = authResults.filter((t) => !t.authenticated);
+
+  if (unauthenticated.length === 0) {
+    p.log.success("All tools are authenticated.");
+    return;
+  }
+
+  p.log.warn(`${unauthenticated.length} tool(s) need authentication.`);
+
+  const runAuth = await p.confirm({
+    message: "Show auth commands for unauthenticated tools?",
+    initialValue: true,
+  });
+  handleCancel(runAuth);
+
+  if (runAuth) {
+    const lines = unauthenticated.map((t) => {
+      const name = t.displayName || t.key;
+      let line = `  ${name}: ${t.authSetupCmd}`;
+      if (t.authUrl) line += `\n    Token: ${t.authUrl}`;
+      return line;
+    });
+    p.note(lines.join("\n"), "Run these commands manually");
   }
+}
+
+// ─── Legacy CLI Tool Check (kept for backward compat) ───────────────────────
 
+/**
+ * Run CLI tool check and offer installation/auth for missing tools.
+ * @deprecated Use showSystemCheck + showInstallPlan + showAuthCheck instead.
+ * @param {string} stack - selected stack key
+ * @returns {Promise<{ tools: Array<object>, missing: Array<object>, installed: Array<object> }>}
+ */
+async function showCliToolCheck(stack) {
+  const result = await showInstallPlan(stack);
+  await showAuthCheck(result.tools);
   return result;
 }
 
@@ -668,7 +728,10 @@ module.exports = {
   askSetupMode,
   askCustomize,
   askManual,
-  // CLI tool check
+  // Tool check flow
+  showSystemCheck,
+  showInstallPlan,
+  showAuthCheck,
   showCliToolCheck,
   // Legacy / utility prompts
   askMcpServers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aslomon/effectum",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Autonomous development system for Claude Code \u2014 describe what you want, get production-ready code",
   "bin": {
     "effectum": "bin/effectum.js"

package/system/tools/_schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Effectum Tool Definition",
+  "description": "Schema for tool definition files in system/tools/. Each file defines tools for a specific stack or category.",
+  "type": "object",
+  "required": ["tools"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable name for this tool set (e.g., 'Foundation Tools')"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of when these tools are used"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "key",
+          "bin",
+          "displayName",
+          "category",
+          "why",
+          "priority"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Unique identifier for the tool (e.g., 'git', 'supabase')"
+          },
+          "bin": {
+            "type": "string",
+            "description": "Binary name to check in PATH (e.g., 'git', 'supabase')"
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable name (e.g., 'Supabase CLI')"
+          },
+          "category": {
+            "type": "string",
+            "enum": ["system", "foundation", "stack", "optional"],
+            "description": "Tool category: system (OS-level), foundation (always needed), stack (stack-specific), optional (nice-to-have)"
+          },
+          "why": {
+            "type": "string",
+            "description": "Human-readable reason why this tool is needed"
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10,
+            "description": "Installation priority (0 = highest, 10 = lowest). Determines install order."
+          },
+          "autoInstall": {
+            "type": "boolean",
+            "default": true,
+            "description": "If false, tool is recommended with a link but not auto-installed (e.g., Docker, Xcode)"
+          },
+          "install": {
+            "type": "object",
+            "properties": {
+              "darwin": {
+                "type": "string",
+                "description": "macOS install command"
+              },
+              "linux": {
+                "type": "string",
+                "description": "Linux install command"
+              },
+              "all": {
+                "type": "string",
+                "description": "Cross-platform install command"
+              }
+            },
+            "description": "Platform-specific install commands. 'all' is used as fallback."
+          },
+          "check": {
+            "type": "string",
+            "description": "Command to verify the tool is working (e.g., 'git --version'). Falls back to 'which <bin>'."
+          },
+          "manualUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL for manual installation instructions (used when autoInstall is false)"
+          },
+          "auth": {
+            "type": "object",
+            "properties": {
+              "check": {
+                "type": "string",
+                "description": "Command to check auth status (exit 0 = authenticated)"
+              },
+              "setup": {
+                "type": "string",
+                "description": "Command to set up authentication"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "URL where user can create tokens/credentials"
+              }
+            },
+            "required": ["check", "setup"],
+            "description": "Authentication configuration. Omit if tool needs no auth."
+          }
+        }
+      }
+    }
+  }
+}

package/system/tools/foundation.json

@@ -0,0 +1,56 @@
+{
+  "name": "Foundation Tools",
+  "description": "Always-required tools regardless of stack. Loaded for every project.",
+  "tools": [
+    {
+      "key": "git",
+      "bin": "git",
+      "displayName": "Git",
+      "category": "foundation",
+      "why": "Version control — required for all projects",
+      "priority": 0,
+      "autoInstall": true,
+      "install": {
+        "darwin": "xcode-select --install",
+        "linux": "sudo apt install -y git"
+      },
+      "check": "git --version",
+      "auth": {
+        "check": "git config user.name && git config user.email",
+        "setup": "git config --global user.name \"Your Name\" && git config --global user.email \"you@example.com\""
+      }
+    },
+    {
+      "key": "gh",
+      "bin": "gh",
+      "displayName": "GitHub CLI",
+      "category": "foundation",
+      "why": "GitHub: Issues, PRs, Code Search, CI status",
+      "priority": 1,
+      "autoInstall": true,
+      "install": {
+        "darwin": "brew install gh",
+        "linux": "sudo apt install -y gh"
+      },
+      "check": "gh --version",
+      "auth": {
+        "check": "gh auth status",
+        "setup": "gh auth login",
+        "url": "https://github.com/settings/tokens"
+      }
+    },
+    {
+      "key": "claude",
+      "bin": "claude",
+      "displayName": "Claude Code",
+      "category": "foundation",
+      "why": "AI coding agent — the core of the autonomous workflow",
+      "priority": 0,
+      "autoInstall": true,
+      "install": {
+        "all": "npm i -g @anthropic-ai/claude-code"
+      },
+      "check": "claude --version"
+    }
+  ]
+}