@aslomon/effectum 0.3.4 → 0.5.0

package/bin/install.js

@@ -53,6 +53,9 @@ const {
   askLanguage,
   askAutonomy,
   showRecommendation,
+  showSystemCheck,
+  showInstallPlan,
+  showAuthCheck,
   askSetupMode,
   askCustomize,
   askManual,
@@ -61,6 +64,15 @@ const {
   showSummary,
   showOutro,
 } = require("./lib/ui");
+const {
+  checkAllTools,
+  checkSystemBasics,
+  formatToolStatus,
+  categorizeForInstall,
+  formatInstallPlan,
+  checkAllAuth,
+  formatAuthStatus,
+} = require("./lib/cli-tools");
 
 // ─── File helpers ─────────────────────────────────────────────────────────────
 
@@ -343,7 +355,11 @@ function installRecommendedAgents(targetDir, repoRoot, recommendedAgents) {
   const agentsDest = path.join(targetDir, ".claude", "agents");
   const steps = [];
 
-  if (!fs.existsSync(agentsSrc) || !recommendedAgents || recommendedAgents.length === 0) {
+  if (
+    !fs.existsSync(agentsSrc) ||
+    !recommendedAgents ||
+    recommendedAgents.length === 0
+  ) {
     return steps;
   }
 
@@ -592,6 +608,45 @@ Options:
       process.exit(0);
     }
 
+    // System basics check (report only in non-interactive mode)
+    const sysCheck = checkSystemBasics();
+    if (sysCheck.missing.length > 0) {
+      console.log("\n  System Basics:");
+      console.log(formatToolStatus(sysCheck.tools));
+      console.log(
+        `\n  ${sysCheck.missing.length} system tool(s) not installed. Run installer interactively to install.`,
+      );
+    }
+
+    // CLI tool check (report only, no install in non-interactive mode)
+    const toolCheck = checkAllTools(config.stack);
+    if (toolCheck.missing.length > 0) {
+      const plan = categorizeForInstall(toolCheck.tools);
+      console.log("\n  Stack Tools:");
+      console.log(formatToolStatus(toolCheck.tools));
+      if (plan.autoInstall.length > 0 || plan.manual.length > 0) {
+        console.log("\n  Installation Plan:");
+        console.log(formatInstallPlan(plan));
+      }
+      console.log(
+        `\n  ${toolCheck.missing.length} tool(s) not installed. Run installer interactively to install.`,
+      );
+    }
+
+    // Auth check (report only in non-interactive mode)
+    const authResults = checkAllAuth(toolCheck.tools);
+    const unauthenticated = authResults.filter((t) => !t.authenticated);
+    if (unauthenticated.length > 0) {
+      console.log("\n  Auth Status:");
+      console.log(formatAuthStatus(authResults));
+    }
+
+    // Store tool status in config
+    config.detectedTools = [...sysCheck.tools, ...toolCheck.tools].map((t) => ({
+      key: t.key,
+      installed: t.installed,
+    }));
+
     // Install base files
     installBaseFiles(targetDir, repoRoot, isGlobal);
 
@@ -609,9 +664,13 @@ Options:
     }
 
     // MCP servers — always install recommended MCPs (or explicit --with-mcp)
-    const mcpKeys = config.mcpServers || (config.recommended ? config.recommended.mcps : []) || [];
+    const mcpKeys =
+      config.mcpServers ||
+      (config.recommended ? config.recommended.mcps : []) ||
+      [];
     if (mcpKeys.length > 0 || args.withMcp) {
-      const keysToInstall = mcpKeys.length > 0 ? mcpKeys : MCP_SERVERS.map((s) => s.key);
+      const keysToInstall =
+        mcpKeys.length > 0 ? mcpKeys : MCP_SERVERS.map((s) => s.key);
       const mcpResults = installMcpServers(keysToInstall);
       const settingsPath = isGlobal
         ? path.join(homeClaudeDir, "settings.json")
@@ -673,6 +732,9 @@ Options:
     process.exit(0);
   }
 
+  // ── Phase 1: System Basics Check ──────────────────────────────────────────
+  await showSystemCheck();
+
   // ── Step 2: Project Basics ────────────────────────────────────────────────
   const projectName = await askProjectName(detected.projectName);
   const stack = await askStack(detected.stack);
@@ -700,6 +762,9 @@ Options:
 
   showRecommendation(rec);
 
+  // ── Phase 3: Consolidated Tool Plan ───────────────────────────────────────
+  const cliToolResult = await showInstallPlan(stack, installTargetDir);
+
   // ── Step 8: Decision ──────────────────────────────────────────────────────
   const setupMode = await askSetupMode();
 
@@ -733,6 +798,10 @@ Options:
     packageManager: detected.packageManager,
     formatter: formatterDef.name,
     mcpServers: finalSetup.mcps,
+    detectedTools: cliToolResult.tools.map((t) => ({
+      key: t.key,
+      installed: t.installed,
+    })),
     playwrightBrowsers: wantPlaywright,
     installScope: "local",
     recommended: {
@@ -804,7 +873,11 @@ Options:
   if (recAgents.length > 0) {
     const sAgents = p.spinner();
     sAgents.start("Installing agent specializations...");
-    const agentSteps = installRecommendedAgents(installTargetDir, repoRoot, recAgents);
+    const agentSteps = installRecommendedAgents(
+      installTargetDir,
+      repoRoot,
+      recAgents,
+    );
     const agentCount = agentSteps.filter((s) => s.status === "created").length;
     sAgents.stop(`${agentCount} agent specializations installed`);
     configSteps.push(...agentSteps);
@@ -838,7 +911,10 @@ Options:
     );
   }
 
-  // 9e: Save config
+  // 9e: Auth check
+  await showAuthCheck(cliToolResult.tools);
+
+  // 9f: Save config
   const configPath = writeConfig(installTargetDir, config);
   configSteps.push({ status: "created", dest: configPath });
 

package/bin/lib/cli-tools.js

@@ -0,0 +1,371 @@
+/**
+ * CLI tool detection, installation, and auth checking.
+ *
+ * Tool definitions are loaded dynamically from JSON files in system/tools/
+ * via the tool-loader module. This module provides the runtime operations:
+ * check, install, auth, and formatting.
+ */
+"use strict";
+
+const { spawnSync } = require("child_process");
+const os = require("os");
+const { loadToolDefinitions, getSystemBasics } = require("./tool-loader");
+
+// ─── Platform ────────────────────────────────────────────────────────────────
+
+/**
+ * Get the platform key for install commands.
+ * @returns {"darwin"|"linux"}
+ */
+function getPlatform() {
+  const p = os.platform();
+  return p === "darwin" ? "darwin" : "linux";
+}
+
+// ─── Tool check ──────────────────────────────────────────────────────────────
+
+/**
+ * Check if a CLI tool is installed by looking up its binary.
+ * Uses the tool's `check` command if available, otherwise falls back to `which`.
+ * @param {object|string} toolOrBin - tool object or binary name
+ * @returns {boolean}
+ */
+function checkTool(toolOrBin) {
+  const bin = typeof toolOrBin === "string" ? toolOrBin : toolOrBin.bin;
+  const checkCmd =
+    typeof toolOrBin === "object" && toolOrBin.check ? toolOrBin.check : null;
+
+  try {
+    if (checkCmd) {
+      const result = spawnSync("bash", ["-c", checkCmd], {
+        timeout: 5000,
+        stdio: "pipe",
+        encoding: "utf8",
+      });
+      return result.status === 0;
+    }
+    const result = spawnSync("which", [bin], {
+      timeout: 5000,
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    return result.status === 0 && result.stdout.trim().length > 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ─── Tool retrieval ──────────────────────────────────────────────────────────
+
+/**
+ * Get the relevant tools for a given stack, loaded from JSON definitions.
+ * Foundation tools are always included.
+ * @param {string} stack - stack key (e.g., "nextjs-supabase")
+ * @param {string} [targetDir] - project directory for community overrides
+ * @returns {Array<object>}
+ */
+function getToolsForStack(stack, targetDir) {
+  return loadToolDefinitions(stack, targetDir);
+}
+
+/**
+ * Check all relevant tools for a stack and return status.
+ * @param {string} stack
+ * @param {string} [targetDir] - project directory for community overrides
+ * @returns {{ tools: Array<object>, missing: Array<object>, installed: Array<object> }}
+ */
+function checkAllTools(stack, targetDir) {
+  const relevant = getToolsForStack(stack, targetDir);
+  const results = relevant.map((tool) => ({
+    ...tool,
+    installed: checkTool(tool),
+  }));
+
+  return {
+    tools: results,
+    missing: results.filter((t) => !t.installed),
+    installed: results.filter((t) => t.installed),
+  };
+}
+
+/**
+ * Check system basics (Homebrew, Git, Node.js, Claude Code).
+ * @returns {{ tools: Array<object>, missing: Array<object>, installed: Array<object> }}
+ */
+function checkSystemBasics() {
+  const basics = getSystemBasics();
+  const results = basics.map((tool) => ({
+    ...tool,
+    installed: checkTool(tool),
+  }));
+
+  return {
+    tools: results,
+    missing: results.filter((t) => !t.installed),
+    installed: results.filter((t) => t.installed),
+  };
+}
+
+// ─── Tool installation ───────────────────────────────────────────────────────
+
+/**
+ * Get the install command for a tool on the current platform.
+ * @param {object} tool
+ * @returns {string|null}
+ */
+function getInstallCommand(tool) {
+  if (!tool.install) return null;
+  const platform = getPlatform();
+  return tool.install[platform] || tool.install.all || null;
+}
+
+/**
+ * Install a single tool using its platform-appropriate command.
+ * @param {object} tool
+ * @returns {{ ok: boolean, command: string|null, error?: string }}
+ */
+function installTool(tool) {
+  const command = getInstallCommand(tool);
+  if (!command) {
+    return {
+      ok: false,
+      command: null,
+      error: "No install command for this platform",
+    };
+  }
+
+  try {
+    const result = spawnSync("bash", ["-c", command], {
+      timeout: 120000,
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    if (result.status === 0) {
+      return { ok: true, command };
+    }
+    return { ok: false, command, error: result.stderr || "Install failed" };
+  } catch (err) {
+    return { ok: false, command, error: err.message };
+  }
+}
+
+/**
+ * Categorize tools into auto-installable and manual-only groups.
+ * @param {Array<object>} tools - tools with `installed` status
+ * @returns {{ autoInstall: Array<object>, manual: Array<object> }}
+ */
+function categorizeForInstall(tools) {
+  const missing = tools.filter((t) => !t.installed);
+  const platform = getPlatform();
+
+  return {
+    autoInstall: missing.filter((t) => {
+      if (t.autoInstall === false) return false;
+      const cmd = t.install ? t.install[platform] || t.install.all : null;
+      return !!cmd;
+    }),
+    manual: missing.filter((t) => {
+      if (t.autoInstall === false) return true;
+      const cmd = t.install ? t.install[platform] || t.install.all : null;
+      return !cmd;
+    }),
+  };
+}
+
+// ─── Auth checking ───────────────────────────────────────────────────────────
+
+/**
+ * Check if a tool is authenticated.
+ * Supports both legacy format (auth as string) and new format (auth as object).
+ * @param {object} tool
+ * @returns {{ authenticated: boolean, needsAuth: boolean }}
+ */
+function checkAuth(tool) {
+  const authCheck =
+    typeof tool.auth === "object" && tool.auth !== null
+      ? tool.auth.check
+      : typeof tool.auth === "string"
+        ? tool.auth
+        : null;
+
+  if (!authCheck) {
+    return { authenticated: true, needsAuth: false };
+  }
+
+  try {
+    const result = spawnSync("bash", ["-c", authCheck], {
+      timeout: 10000,
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    return {
+      authenticated: result.status === 0,
+      needsAuth: true,
+    };
+  } catch (_) {
+    return { authenticated: false, needsAuth: true };
+  }
+}
+
+/**
+ * Get the auth setup command for a tool.
+ * @param {object} tool
+ * @returns {string|null}
+ */
+function getAuthSetup(tool) {
+  if (typeof tool.auth === "object" && tool.auth !== null) {
+    return tool.auth.setup || null;
+  }
+  return tool.authSetup || null;
+}
+
+/**
+ * Get the auth URL for a tool (for creating tokens).
+ * @param {object} tool
+ * @returns {string|null}
+ */
+function getAuthUrl(tool) {
+  if (typeof tool.auth === "object" && tool.auth !== null) {
+    return tool.auth.url || null;
+  }
+  return null;
+}
+
+/**
+ * Check auth status for all installed tools that need auth.
+ * @param {Array<object>} tools - tools with `installed` status
+ * @returns {Array<object>} - tools with auth status added
+ */
+function checkAllAuth(tools) {
+  return tools
+    .filter((t) => t.installed)
+    .map((tool) => {
+      const authResult = checkAuth(tool);
+      return {
+        ...tool,
+        ...authResult,
+        authSetupCmd: getAuthSetup(tool),
+        authUrl: getAuthUrl(tool),
+      };
+    })
+    .filter((t) => t.needsAuth);
+}
+
+// ─── Formatting helpers ──────────────────────────────────────────────────────
+
+/**
+ * Generate a human-readable tools status summary.
+ * @param {Array<object>} tools - tool check results
+ * @returns {string}
+ */
+function formatToolStatus(tools) {
+  return tools
+    .map((t) => {
+      const icon = t.installed ? "\u2705" : "\u274C";
+      const name = t.displayName || t.key;
+      return `  ${icon} ${name} — ${t.why}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Generate install instructions for missing tools.
+ * @param {Array<object>} missing - missing tools
+ * @returns {string}
+ */
+function formatInstallInstructions(missing) {
+  const platform = getPlatform();
+  return missing
+    .map((t) => {
+      const cmd = t.install
+        ? t.install[platform] || t.install.all || "N/A"
+        : "N/A";
+      const name = t.displayName || t.key;
+      return `  ${name}: ${cmd}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Format a consolidated installation plan.
+ * @param {{ autoInstall: Array<object>, manual: Array<object> }} plan
+ * @returns {string}
+ */
+function formatInstallPlan(plan) {
+  const lines = [];
+
+  if (plan.autoInstall.length > 0) {
+    lines.push("Will install:");
+    for (const tool of plan.autoInstall) {
+      const name = tool.displayName || tool.key;
+      const cmd = getInstallCommand(tool);
+      lines.push(`  ${name} — ${cmd}`);
+    }
+  }
+
+  if (plan.manual.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("Manual setup needed:");
+    for (const tool of plan.manual) {
+      const name = tool.displayName || tool.key;
+      const url = tool.manualUrl || getInstallCommand(tool) || "see docs";
+      lines.push(`  ${name} — ${url}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format auth status for display.
+ * @param {Array<object>} authResults
+ * @returns {string}
+ */
+function formatAuthStatus(authResults) {
+  return authResults
+    .map((t) => {
+      const icon = t.authenticated ? "\u2705" : "\u274C";
+      const name = t.displayName || t.key;
+      let line = `  ${icon} ${name}`;
+      if (!t.authenticated && t.authSetupCmd) {
+        line += ` — run: ${t.authSetupCmd}`;
+        if (t.authUrl) line += ` (${t.authUrl})`;
+      }
+      return line;
+    })
+    .join("\n");
+}
+
+/**
+ * Build the AVAILABLE_TOOLS section content for CLAUDE.md.
+ * @param {Array<object>} tools - tool check results
+ * @returns {string}
+ */
+function buildAvailableToolsSection(tools) {
+  const lines = tools.map((t) => {
+    const status = t.installed ? "installed" : "not installed";
+    const name = t.displayName || t.key;
+    return `- **${name}** (${status}): ${t.why}`;
+  });
+  return lines.join("\n");
+}
+
+module.exports = {
+  checkTool,
+  getToolsForStack,
+  checkAllTools,
+  checkSystemBasics,
+  getPlatform,
+  getInstallCommand,
+  installTool,
+  categorizeForInstall,
+  checkAuth,
+  getAuthSetup,
+  getAuthUrl,
+  checkAllAuth,
+  formatToolStatus,
+  formatInstallInstructions,
+  formatInstallPlan,
+  formatAuthStatus,
+  buildAvailableToolsSection,
+};

package/bin/lib/specializations.js

@@ -94,6 +94,16 @@ const SUBAGENT_SPECS = [
     label: "Code Reviewer",
     tags: ["testing-heavy", "docs-needed"],
   },
+  {
+    key: "mobile-developer",
+    label: "Mobile Developer",
+    tags: ["native-ui", "frontend-heavy", "swift"],
+  },
+  {
+    key: "data-engineer",
+    label: "Data Engineer",
+    tags: ["data-pipeline", "compute-heavy", "analytics"],
+  },
 ];
 
 /**
@@ -116,7 +126,7 @@ const STACK_SUBAGENTS = {
     "test-automator",
     "api-designer",
   ],
-  "swift-ios": ["ui-designer", "test-automator"],
+  "swift-ios": ["ui-designer", "test-automator", "mobile-developer"],
   generic: ["debugger", "test-automator"],
 };
 

package/bin/lib/template.js

@@ -9,6 +9,7 @@ const fs = require("fs");
 const path = require("path");
 const { FORMATTER_MAP } = require("./constants");
 const { LANGUAGE_INSTRUCTIONS } = require("./languages");
+const { getToolsForStack, checkTool } = require("./cli-tools");
 
 /**
  * Build a substitution map from user config and parsed stack sections.
@@ -23,6 +24,18 @@ function buildSubstitutionMap(config, stackSections) {
     config.customLanguage ||
     LANGUAGE_INSTRUCTIONS.english;
 
+  // Build AVAILABLE_TOOLS section from detected CLI tools
+  const tools = getToolsForStack(config.stack);
+  const toolLines = tools.map((t) => {
+    const installed = checkTool(t.bin);
+    const status = installed ? "installed" : "not installed";
+    return `- **${t.key}** (${status}): ${t.why}`;
+  });
+  const availableTools =
+    toolLines.length > 0
+      ? toolLines.join("\n")
+      : "No CLI tools configured. Run the installer to detect and configure tools.";
+
   return {
     PROJECT_NAME: config.projectName,
     LANGUAGE: langInstruction,
@@ -39,6 +52,7 @@ function buildSubstitutionMap(config, stackSections) {
     PACKAGE_MANAGER: config.packageManager,
     TOOL_SPECIFIC_GUARDRAILS:
       stackSections.TOOL_SPECIFIC_GUARDRAILS || "[Not configured]",
+    AVAILABLE_TOOLS: availableTools,
   };
 }