@aslomon/effectum 0.1.5 → 0.2.0

package/bin/lib/ui.js

@@ -0,0 +1,221 @@
+/**
+ * Shared @clack/prompts helpers and display utilities.
+ */
+"use strict";
+
+const p = require("@clack/prompts");
+const {
+  STACK_CHOICES,
+  LANGUAGE_CHOICES,
+  AUTONOMY_CHOICES,
+  MCP_SERVERS,
+} = require("./constants");
+
+/**
+ * Print the Effectum banner via clack intro.
+ */
+function printBanner() {
+  p.intro("EFFECTUM — Autonomous development system for Claude Code");
+}
+
+/**
+ * Check if the user cancelled a prompt (Ctrl+C).
+ * @param {*} value
+ */
+function handleCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+}
+
+/**
+ * Ask for project name with a detected default.
+ * @param {string} detected
+ * @returns {Promise<string>}
+ */
+async function askProjectName(detected) {
+  const value = await p.text({
+    message: "Project name",
+    placeholder: detected,
+    initialValue: detected,
+    validate: (v) => {
+      if (!v.trim()) return "Project name is required";
+    },
+  });
+  handleCancel(value);
+  return value;
+}
+
+/**
+ * Ask for tech stack selection.
+ * @param {string|null} detected - auto-detected stack key
+ * @returns {Promise<string>}
+ */
+async function askStack(detected) {
+  const value = await p.select({
+    message: "Tech stack",
+    options: STACK_CHOICES.map((c) => ({
+      value: c.value,
+      label: c.label,
+      hint: c.hint,
+    })),
+    initialValue: detected || "generic",
+  });
+  handleCancel(value);
+  return value;
+}
+
+/**
+ * Ask for communication language.
+ * @returns {Promise<{ language: string, customLanguage?: string }>}
+ */
+async function askLanguage() {
+  const value = await p.select({
+    message: "Communication language",
+    options: LANGUAGE_CHOICES.map((c) => ({
+      value: c.value,
+      label: c.label,
+      hint: c.hint,
+    })),
+    initialValue: "english",
+  });
+  handleCancel(value);
+
+  if (value === "custom") {
+    const custom = await p.text({
+      message: "Enter your language instruction",
+      placeholder: 'e.g. "Speak French with the user"',
+      validate: (v) => {
+        if (!v.trim()) return "Language instruction is required";
+      },
+    });
+    handleCancel(custom);
+    return { language: "custom", customLanguage: custom };
+  }
+
+  return { language: value };
+}
+
+/**
+ * Ask for autonomy level.
+ * @returns {Promise<string>}
+ */
+async function askAutonomy() {
+  const value = await p.select({
+    message: "Autonomy level",
+    options: AUTONOMY_CHOICES.map((c) => ({
+      value: c.value,
+      label: c.label,
+      hint: c.hint,
+    })),
+    initialValue: "standard",
+  });
+  handleCancel(value);
+  return value;
+}
+
+/**
+ * Ask which MCP servers to install via multi-select.
+ * @returns {Promise<string[]>}
+ */
+async function askMcpServers() {
+  const value = await p.multiselect({
+    message: "MCP servers (space to toggle, enter to confirm)",
+    options: MCP_SERVERS.map((s) => ({
+      value: s.key,
+      label: s.label,
+      hint: s.desc,
+    })),
+    initialValues: MCP_SERVERS.map((s) => s.key),
+    required: false,
+  });
+  handleCancel(value);
+  return value;
+}
+
+/**
+ * Ask whether to install Playwright browsers.
+ * @returns {Promise<boolean>}
+ */
+async function askPlaywright() {
+  const value = await p.confirm({
+    message: "Install Playwright browsers? (required for /e2e)",
+    initialValue: true,
+  });
+  handleCancel(value);
+  return value;
+}
+
+/**
+ * Ask whether to create a new git branch.
+ * @returns {Promise<{ create: boolean, name?: string }>}
+ */
+async function askGitBranch() {
+  const create = await p.confirm({
+    message: "Create a new git branch for this setup?",
+    initialValue: false,
+  });
+  handleCancel(create);
+
+  if (!create) return { create: false };
+
+  const name = await p.text({
+    message: "Branch name",
+    initialValue: "effectum-setup",
+    placeholder: "effectum-setup",
+  });
+  handleCancel(name);
+  return { create: true, name };
+}
+
+/**
+ * Display a summary note.
+ * @param {object} config
+ * @param {string[]} files
+ */
+function showSummary(config, files) {
+  const lines = [
+    `Project:   ${config.projectName}`,
+    `Stack:     ${config.stack}`,
+    `Language:  ${config.language}`,
+    `Autonomy:  ${config.autonomyLevel}`,
+    `Pkg Mgr:   ${config.packageManager}`,
+    `Formatter: ${config.formatter}`,
+    `MCP:       ${(config.mcpServers || []).join(", ") || "none"}`,
+    "",
+    `Files created/updated:`,
+    ...files.map((f) => `  ${f}`),
+  ];
+  p.note(lines.join("\n"), "Configuration Summary");
+}
+
+/**
+ * Show the next-steps outro.
+ * @param {boolean} isGlobal
+ */
+function showOutro(isGlobal) {
+  if (isGlobal) {
+    p.outro(
+      "Effectum ready! In any project, run: npx @aslomon/effectum init",
+    );
+  } else {
+    p.outro(
+      "Effectum ready! Open Claude Code here and start building. Try /plan or /prd:new",
+    );
+  }
+}
+
+module.exports = {
+  printBanner,
+  handleCancel,
+  askProjectName,
+  askStack,
+  askLanguage,
+  askAutonomy,
+  askMcpServers,
+  askPlaywright,
+  askGitBranch,
+  showSummary,
+  showOutro,
+};

package/bin/lib/utils.js

@@ -0,0 +1,56 @@
+/**
+ * Shared utility functions.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Ensure a directory exists (recursive mkdir).
+ * @param {string} dir
+ */
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Deep-merge two plain objects. Source wins on conflicts.
+ * Arrays are NOT merged — source replaces target.
+ * @param {object} target
+ * @param {object} source
+ * @returns {object}
+ */
+function deepMerge(target, source) {
+  const out = Object.assign({}, target);
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === "object" &&
+      !Array.isArray(source[key]) &&
+      out[key] &&
+      typeof out[key] === "object" &&
+      !Array.isArray(out[key])
+    ) {
+      out[key] = deepMerge(out[key], source[key]);
+    } else {
+      out[key] = source[key];
+    }
+  }
+  return out;
+}
+
+/**
+ * Find the Effectum repo root (parent of bin/).
+ * @returns {string}
+ */
+function findRepoRoot() {
+  const binDir = path.dirname(require.main?.filename || __filename);
+  // If we're in bin/lib/, go up two levels; if in bin/, go up one
+  if (path.basename(binDir) === "lib") {
+    return path.resolve(binDir, "..", "..");
+  }
+  return path.resolve(binDir, "..");
+}
+
+module.exports = { ensureDir, deepMerge, findRepoRoot };

package/bin/reconfigure.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Reconfigure — re-apply settings from .effectum.json.
+ * Reads the saved config and regenerates CLAUDE.md, settings.json, guardrails.md.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const p = require("@clack/prompts");
+
+const { readConfig } = require("./lib/config");
+const { loadStackPreset } = require("./lib/stack-parser");
+const {
+  buildSubstitutionMap,
+  renderTemplate,
+  findTemplatePath,
+  findRemainingPlaceholders,
+  substituteAll,
+} = require("./lib/template");
+const { AUTONOMY_MAP, FORMATTER_MAP } = require("./lib/constants");
+const { ensureDir, deepMerge, findRepoRoot } = require("./lib/utils");
+
+// ─── Main ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const targetDir = process.cwd();
+  const repoRoot = findRepoRoot();
+
+  p.intro("EFFECTUM — Reconfigure");
+
+  // Read existing config
+  const config = readConfig(targetDir);
+  if (!config) {
+    p.log.error(
+      "No .effectum.json found in this directory. Run `npx @aslomon/effectum` first.",
+    );
+    process.exit(1);
+  }
+
+  p.log.info(`Reconfiguring "${config.projectName}" (${config.stack})`);
+
+  if (dryRun) {
+    p.note(JSON.stringify(config, null, 2), "Current Configuration");
+    p.log.info("Dry run — files that would be regenerated:");
+    p.log.step("  CLAUDE.md");
+    p.log.step("  .claude/settings.json");
+    p.log.step("  .claude/guardrails.md");
+    p.outro("Dry run complete. No changes made.");
+    process.exit(0);
+  }
+
+  const claudeDir = path.join(targetDir, ".claude");
+
+  // Load stack preset
+  const stackSections = loadStackPreset(config.stack, targetDir, repoRoot);
+  const vars = buildSubstitutionMap(config, stackSections);
+
+  const s = p.spinner();
+  s.start("Regenerating configuration files...");
+
+  // 1. CLAUDE.md
+  const claudeMdTmpl = findTemplatePath("CLAUDE.md.tmpl", targetDir, repoRoot);
+  const { content: claudeMdContent, remaining: claudeMdRemaining } =
+    renderTemplate(claudeMdTmpl, vars);
+  fs.writeFileSync(path.join(targetDir, "CLAUDE.md"), claudeMdContent, "utf8");
+
+  if (claudeMdRemaining.length > 0) {
+    p.log.warn(
+      `CLAUDE.md has remaining placeholders: ${claudeMdRemaining.join(", ")}`,
+    );
+  }
+
+  // 2. settings.json
+  const settingsTmpl = findTemplatePath(
+    "settings.json.tmpl",
+    targetDir,
+    repoRoot,
+  );
+  let settingsObj;
+  try {
+    settingsObj = JSON.parse(fs.readFileSync(settingsTmpl, "utf8"));
+  } catch (e) {
+    throw new Error(`Could not parse settings template: ${e.message}`);
+  }
+
+  const autonomy = AUTONOMY_MAP[config.autonomyLevel] || AUTONOMY_MAP.standard;
+  settingsObj.permissions = {
+    ...settingsObj.permissions,
+    ...autonomy.permissions,
+    defaultMode: autonomy.defaultMode,
+    deny: settingsObj.permissions?.deny || [],
+  };
+
+  const formatter = FORMATTER_MAP[config.stack] || FORMATTER_MAP.generic;
+  if (settingsObj.hooks?.PostToolUse) {
+    for (const group of settingsObj.hooks.PostToolUse) {
+      if (group.matcher === "Edit|Write") {
+        for (const hook of group.hooks) {
+          if (
+            hook.command &&
+            hook.command.includes("formatter-not-configured")
+          ) {
+            if (formatter.command === "echo no-formatter-configured") {
+              hook.command = "echo no-formatter-configured";
+            } else {
+              hook.command = `bash -c 'INPUT=$(cat); FILE=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty"); if [[ "$FILE" =~ \\.(${formatter.glob})$ ]]; then ${formatter.command} "$FILE" 2>/dev/null; fi; exit 0'`;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const settingsDest = path.join(claudeDir, "settings.json");
+  let existing = {};
+  if (fs.existsSync(settingsDest)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(settingsDest, "utf8"));
+    } catch (_) {}
+  }
+  const merged = deepMerge(existing, settingsObj);
+  ensureDir(path.dirname(settingsDest));
+  fs.writeFileSync(
+    settingsDest,
+    JSON.stringify(merged, null, 2) + "\n",
+    "utf8",
+  );
+
+  // 3. guardrails.md
+  const guardrailsTmpl = findTemplatePath(
+    "guardrails.md.tmpl",
+    targetDir,
+    repoRoot,
+  );
+  const guardrailsRaw = fs.readFileSync(guardrailsTmpl, "utf8");
+  let guardrailsContent = guardrailsRaw;
+
+  if (stackSections.STACK_SPECIFIC_GUARDRAILS) {
+    guardrailsContent = guardrailsContent.replace(
+      /No stack-specific guardrails configured yet\. Run \/setup to configure for your stack\./,
+      stackSections.STACK_SPECIFIC_GUARDRAILS,
+    );
+  }
+  if (stackSections.TOOL_SPECIFIC_GUARDRAILS) {
+    guardrailsContent = guardrailsContent.replace(
+      /No tool-specific guardrails configured yet\. Run \/setup to configure\./,
+      stackSections.TOOL_SPECIFIC_GUARDRAILS,
+    );
+  }
+
+  const guardrailsDest = path.join(claudeDir, "guardrails.md");
+  ensureDir(path.dirname(guardrailsDest));
+  fs.writeFileSync(guardrailsDest, guardrailsContent, "utf8");
+
+  s.stop("Configuration files regenerated");
+
+  p.log.success("CLAUDE.md — updated");
+  p.log.success(".claude/settings.json — updated");
+  p.log.success(".claude/guardrails.md — updated");
+
+  p.outro("Reconfiguration complete!");
+}
+
+main().catch((err) => {
+  p.log.error(`Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@aslomon/effectum",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Autonomous development system for Claude Code — describe what you want, get production-ready code",
   "bin": {
-    "effectum": "bin/install.js"
+    "effectum": "bin/effectum.js"
   },
   "files": [
     "bin/",
@@ -25,5 +25,8 @@
   ],
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0"
   }
-}
+}

package/system/commands/setup.md

@@ -12,7 +12,7 @@ Validate:
 - The path exists. If not, ask: "This directory does not exist. Should I create it?"
 - Check for an existing `.claude/` directory at the target path.
   - If found, ask: **"A .claude/ directory already exists. Overwrite, merge, or abort?"**
-    - **Overwrite**: Delete existing `.claude/` and replace with fresh installation.
+    - **Overwrite**: Replace CONFIGURATION files only (`CLAUDE.md`, `.claude/settings.json`, `.claude/guardrails.md`) but **keep all commands** already in `.claude/commands/`.
     - **Merge**: Keep existing files, only add missing ones. Warn about conflicts.
     - **Abort**: Stop the installation.
 
@@ -57,12 +57,24 @@ Options: English, German (du/informal), or specify another.
 
 ## Step 3: Read Templates and Stack Preset
 
-Read these files from the repo root:
+Read the template files — check these locations **in order** and use the first one found:
 
-1. `system/templates/CLAUDE.md.tmpl` — Main configuration template
-2. `system/templates/settings.json.tmpl` — Settings template
-3. `system/templates/guardrails.md.tmpl` — Guardrails template
-4. `system/stacks/{selected-stack}.md` — Stack-specific content (nextjs-supabase.md, python-fastapi.md, swift-ios.md, or generic.md)
+1. `.effectum/templates/` — local install (created by `npx @aslomon/effectum --local`)
+2. `~/.effectum/templates/` — global install (created by `npx @aslomon/effectum --global`)
+3. `system/templates/` — development (running directly from the repo)
+
+Templates to read:
+- `CLAUDE.md.tmpl` — Main configuration template
+- `settings.json.tmpl` — Settings template
+- `guardrails.md.tmpl` — Guardrails template
+
+Read the stack preset file — check these locations **in order** and use the first one found:
+
+1. `.effectum/stacks/{selected-stack}.md`
+2. `~/.effectum/stacks/{selected-stack}.md`
+3. `system/stacks/{selected-stack}.md`
+
+Available stacks: `nextjs-supabase.md`, `python-fastapi.md`, `swift-ios.md`, `generic.md`
 
 The stack preset file contains values for these placeholders: