@aslomon/effectum 0.1.5 → 0.2.0

package/bin/lib/config.js

@@ -0,0 +1,55 @@
+/**
+ * Read/write .effectum.json configuration file.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CONFIG_FILENAME = ".effectum.json";
+
+/**
+ * Read .effectum.json from a directory.
+ * @param {string} dir
+ * @returns {object|null} parsed config or null if not found
+ */
+function readConfig(dir) {
+  const filePath = path.join(dir, CONFIG_FILENAME);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Write .effectum.json to a directory.
+ * @param {string} dir
+ * @param {object} config
+ */
+function writeConfig(dir, config) {
+  const filePath = path.join(dir, CONFIG_FILENAME);
+  const now = new Date().toISOString();
+  const data = {
+    version: "0.2.0",
+    ...config,
+    updatedAt: now,
+  };
+  if (!data.createdAt) {
+    data.createdAt = now;
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+  return filePath;
+}
+
+/**
+ * Check if .effectum.json exists in a directory.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function configExists(dir) {
+  return fs.existsSync(path.join(dir, CONFIG_FILENAME));
+}
+
+module.exports = { readConfig, writeConfig, configExists, CONFIG_FILENAME };

package/bin/lib/constants.js

@@ -0,0 +1,197 @@
+/**
+ * Shared constants for the Effectum CLI.
+ * Autonomy levels, formatter mappings, MCP server definitions, stack choices, language choices.
+ */
+"use strict";
+
+/** @type {Record<string, { defaultMode: string, permissions: { allow: string[] } }>} */
+const AUTONOMY_MAP = {
+  conservative: {
+    defaultMode: "default",
+    permissions: {
+      allow: ["Read(*)", "Glob(*)", "Grep(*)", "WebFetch(*)", "WebSearch(*)"],
+    },
+  },
+  standard: {
+    defaultMode: "default",
+    permissions: {
+      allow: [
+        "Bash(*)",
+        "Read(*)",
+        "Write(*)",
+        "Edit(*)",
+        "Glob(*)",
+        "Grep(*)",
+        "WebFetch(*)",
+        "WebSearch(*)",
+        "Task(*)",
+        "NotebookEdit(*)",
+      ],
+    },
+  },
+  full: {
+    defaultMode: "bypassPermissions",
+    permissions: {
+      allow: [
+        "Bash(*)",
+        "Read(*)",
+        "Write(*)",
+        "Edit(*)",
+        "Glob(*)",
+        "Grep(*)",
+        "WebFetch(*)",
+        "WebSearch(*)",
+        "Task(*)",
+        "NotebookEdit(*)",
+      ],
+    },
+  },
+};
+
+/** @type {Record<string, { command: string, name: string, glob: string }>} */
+const FORMATTER_MAP = {
+  "nextjs-supabase": {
+    command: "npx prettier --write",
+    name: "Prettier",
+    glob: "ts|tsx|js|jsx|json|css|md",
+  },
+  "python-fastapi": {
+    command: "ruff format",
+    name: "Ruff",
+    glob: "py",
+  },
+  "swift-ios": {
+    command: "swift-format format -i",
+    name: "swift-format",
+    glob: "swift",
+  },
+  generic: {
+    command: "echo no-formatter-configured",
+    name: "None",
+    glob: "*",
+  },
+};
+
+/** @type {Array<{ key: string, label: string, package: string, desc: string, config: object }>} */
+const MCP_SERVERS = [
+  {
+    key: "context7",
+    label: "Context7",
+    package: "@upstash/context7-mcp",
+    desc: "Up-to-date library docs for Claude",
+    config: {
+      command: "npx",
+      args: ["-y", "@upstash/context7-mcp"],
+    },
+  },
+  {
+    key: "playwright",
+    label: "Playwright MCP",
+    package: "@playwright/mcp",
+    desc: "E2E browser automation — required for /e2e",
+    config: {
+      command: "npx",
+      args: ["-y", "@playwright/mcp"],
+    },
+  },
+  {
+    key: "sequential-thinking",
+    label: "Sequential Thinking",
+    package: "@modelcontextprotocol/server-sequential-thinking",
+    desc: "Complex planning and multi-step reasoning",
+    config: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    },
+  },
+  {
+    key: "filesystem",
+    label: "Filesystem",
+    package: "@modelcontextprotocol/server-filesystem",
+    desc: "File operations (read/write/search)",
+    configFn: (cwd) => ({
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", cwd],
+    }),
+  },
+];
+
+/** @type {Array<{ value: string, label: string, hint: string }>} */
+const STACK_CHOICES = [
+  {
+    value: "nextjs-supabase",
+    label: "Next.js + Supabase",
+    hint: "Full-stack TypeScript with Tailwind, Shadcn, Supabase",
+  },
+  {
+    value: "python-fastapi",
+    label: "Python + FastAPI",
+    hint: "Backend APIs with Pydantic, SQLAlchemy, Alembic",
+  },
+  {
+    value: "swift-ios",
+    label: "Swift / SwiftUI",
+    hint: "Native Apple apps with SwiftData, SPM",
+  },
+  {
+    value: "generic",
+    label: "Generic",
+    hint: "Stack-agnostic baseline — customize after setup",
+  },
+];
+
+/** @type {Array<{ value: string, label: string, hint: string }>} */
+const LANGUAGE_CHOICES = [
+  {
+    value: "english",
+    label: "English",
+    hint: "Communicate in English",
+  },
+  {
+    value: "german",
+    label: "Deutsch (du/informal)",
+    hint: "German, informal",
+  },
+  {
+    value: "custom",
+    label: "Custom",
+    hint: "Enter your own language instruction",
+  },
+];
+
+/** @type {Record<string, string>} */
+const LANGUAGE_INSTRUCTIONS = {
+  english:
+    "Speak English with the user. All code, comments, commits, and docs in English.",
+  german:
+    "Speak German (du/informal) with the user. All code, comments, commits, and docs in English.",
+};
+
+/** @type {Array<{ value: string, label: string, hint: string }>} */
+const AUTONOMY_CHOICES = [
+  {
+    value: "conservative",
+    label: "Conservative",
+    hint: "Read-only tools allowed, ask before write/execute",
+  },
+  {
+    value: "standard",
+    label: "Standard",
+    hint: "Read + Write + Bash allowed, ask for dangerous ops",
+  },
+  {
+    value: "full",
+    label: "Full Autonomy",
+    hint: "Bypass all permission prompts — trust Claude fully",
+  },
+];
+
+module.exports = {
+  AUTONOMY_MAP,
+  FORMATTER_MAP,
+  MCP_SERVERS,
+  STACK_CHOICES,
+  LANGUAGE_CHOICES,
+  LANGUAGE_INSTRUCTIONS,
+  AUTONOMY_CHOICES,
+};

package/bin/lib/detect.js

@@ -0,0 +1,98 @@
+/**
+ * Auto-detection: project name, tech stack, package manager.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Detect project name from directory name.
+ * @param {string} dir
+ * @returns {string}
+ */
+function detectProjectName(dir) {
+  return path.basename(path.resolve(dir));
+}
+
+/**
+ * Detect tech stack from project files.
+ * @param {string} dir
+ * @returns {string|null} stack key or null
+ */
+function detectStack(dir) {
+  const packageJsonPath = path.join(dir, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      const allDeps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+      };
+      if (allDeps["next"] && allDeps["@supabase/supabase-js"]) {
+        return "nextjs-supabase";
+      }
+      if (allDeps["next"]) {
+        return "nextjs-supabase";
+      }
+    } catch (_) {
+      // ignore parse errors
+    }
+  }
+
+  const pyprojectPath = path.join(dir, "pyproject.toml");
+  const requirementsPath = path.join(dir, "requirements.txt");
+  if (fs.existsSync(pyprojectPath) || fs.existsSync(requirementsPath)) {
+    return "python-fastapi";
+  }
+
+  const packageSwiftPath = path.join(dir, "Package.swift");
+  const xcodeprojExists = fs
+    .readdirSync(dir)
+    .some((f) => f.endsWith(".xcodeproj") || f.endsWith(".xcworkspace"));
+  if (fs.existsSync(packageSwiftPath) || xcodeprojExists) {
+    return "swift-ios";
+  }
+
+  return null;
+}
+
+/**
+ * Detect package manager from lock files.
+ * @param {string} dir
+ * @returns {string}
+ */
+function detectPackageManager(dir) {
+  if (fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(dir, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(dir, "bun.lockb"))) return "bun";
+  if (fs.existsSync(path.join(dir, "package-lock.json"))) return "npm";
+  if (fs.existsSync(path.join(dir, "Pipfile.lock"))) return "pipenv";
+  if (fs.existsSync(path.join(dir, "poetry.lock"))) return "poetry";
+  if (fs.existsSync(path.join(dir, "uv.lock"))) return "uv";
+  if (fs.existsSync(path.join(dir, "pyproject.toml"))) return "uv";
+  if (fs.existsSync(path.join(dir, "Package.swift")))
+    return "swift package (SPM)";
+  if (fs.existsSync(path.join(dir, "package.json"))) return "npm";
+  return "npm";
+}
+
+/**
+ * Run all detections and return a summary.
+ * @param {string} dir
+ * @returns {{ projectName: string, stack: string|null, packageManager: string }}
+ */
+function detectAll(dir) {
+  return {
+    projectName: detectProjectName(dir),
+    stack: detectStack(dir),
+    packageManager: detectPackageManager(dir),
+  };
+}
+
+module.exports = {
+  detectProjectName,
+  detectStack,
+  detectPackageManager,
+  detectAll,
+};

package/bin/lib/stack-parser.js

@@ -0,0 +1,56 @@
+/**
+ * Parse stack preset .md files into key-value maps.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Parse a stack preset markdown file into a sections map.
+ * Extracts content from sections like:
+ * ## KEY_NAME
+ * ```
+ * value content
+ * ```
+ * @param {string} content - markdown content
+ * @returns {Record<string, string>}
+ */
+function parseStackPreset(content) {
+  const sections = {};
+  const regex = /^## (\w+)\s*\n+`{3,4}\n([\s\S]*?)`{3,4}/gm;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    sections[match[1]] = match[2].trim();
+  }
+  return sections;
+}
+
+/**
+ * Load and parse a stack preset file by stack key.
+ * Looks in the .effectum/stacks/ directory first (installed copy),
+ * then falls back to system/stacks/ (repo source).
+ * @param {string} stackKey - e.g. 'nextjs-supabase'
+ * @param {string} targetDir - project directory
+ * @param {string} repoRoot - effectum repo root
+ * @returns {Record<string, string>}
+ */
+function loadStackPreset(stackKey, targetDir, repoRoot) {
+  const candidates = [
+    path.join(targetDir, ".effectum", "stacks", `${stackKey}.md`),
+    path.join(repoRoot, "system", "stacks", `${stackKey}.md`),
+  ];
+
+  for (const filePath of candidates) {
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, "utf8");
+      return parseStackPreset(content);
+    }
+  }
+
+  throw new Error(
+    `Stack preset "${stackKey}" not found. Searched:\n  ${candidates.join("\n  ")}`,
+  );
+}
+
+module.exports = { parseStackPreset, loadStackPreset };

package/bin/lib/template.js

@@ -0,0 +1,108 @@
+/**
+ * Template substitution engine.
+ * Reads template files, replaces all {{PLACEHOLDER}} tokens with values
+ * from the stack preset and user config.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { FORMATTER_MAP, LANGUAGE_INSTRUCTIONS } = require("./constants");
+
+/**
+ * Build a substitution map from user config and parsed stack sections.
+ * @param {object} config - user config from .effectum.json
+ * @param {Record<string, string>} stackSections - parsed stack preset
+ * @returns {Record<string, string>}
+ */
+function buildSubstitutionMap(config, stackSections) {
+  const formatter = FORMATTER_MAP[config.stack] || FORMATTER_MAP.generic;
+  const langInstruction =
+    LANGUAGE_INSTRUCTIONS[config.language] ||
+    config.customLanguage ||
+    LANGUAGE_INSTRUCTIONS.english;
+
+  return {
+    PROJECT_NAME: config.projectName,
+    LANGUAGE: langInstruction,
+    TECH_STACK: stackSections.TECH_STACK || "[Not configured]",
+    ARCHITECTURE_PRINCIPLES:
+      stackSections.ARCHITECTURE_PRINCIPLES || "[Not configured]",
+    PROJECT_STRUCTURE: stackSections.PROJECT_STRUCTURE || "[Not configured]",
+    QUALITY_GATES: stackSections.QUALITY_GATES || "[Not configured]",
+    STACK_SPECIFIC_GUARDRAILS:
+      stackSections.STACK_SPECIFIC_GUARDRAILS || "[Not configured]",
+    FORMATTER: formatter.command,
+    FORMATTER_NAME: formatter.name,
+    FORMATTER_GLOB: formatter.glob,
+    PACKAGE_MANAGER: config.packageManager,
+    TOOL_SPECIFIC_GUARDRAILS:
+      stackSections.TOOL_SPECIFIC_GUARDRAILS || "[Not configured]",
+  };
+}
+
+/**
+ * Replace all {{KEY}} placeholders in a string.
+ * @param {string} content
+ * @param {Record<string, string>} vars
+ * @returns {string}
+ */
+function substituteAll(content, vars) {
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, "g");
+    result = result.replace(pattern, value);
+  }
+  return result;
+}
+
+/**
+ * Check if any {{...}} placeholders remain.
+ * @param {string} content
+ * @returns {string[]} list of remaining placeholder names
+ */
+function findRemainingPlaceholders(content) {
+  const matches = content.match(/\{\{(\w+)\}\}/g) || [];
+  return [...new Set(matches)];
+}
+
+/**
+ * Read a template file, substitute all placeholders, return result.
+ * @param {string} templatePath
+ * @param {Record<string, string>} vars
+ * @returns {{ content: string, remaining: string[] }}
+ */
+function renderTemplate(templatePath, vars) {
+  const raw = fs.readFileSync(templatePath, "utf8");
+  const content = substituteAll(raw, vars);
+  const remaining = findRemainingPlaceholders(content);
+  return { content, remaining };
+}
+
+/**
+ * Find template file path. Checks .effectum/templates/ first, then system/templates/.
+ * @param {string} filename - e.g. 'CLAUDE.md.tmpl'
+ * @param {string} targetDir
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function findTemplatePath(filename, targetDir, repoRoot) {
+  const candidates = [
+    path.join(targetDir, ".effectum", "templates", filename),
+    path.join(repoRoot, "system", "templates", filename),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  throw new Error(
+    `Template "${filename}" not found. Searched:\n  ${candidates.join("\n  ")}`,
+  );
+}
+
+module.exports = {
+  buildSubstitutionMap,
+  substituteAll,
+  findRemainingPlaceholders,
+  renderTemplate,
+  findTemplatePath,
+};