ac-framework 1.9.1 → 1.9.3

package/src/services/installer.js

@@ -1,4 +1,4 @@
-import { cp, rm, access, readdir } from 'node:fs/promises';
+import { cp, rm, access, readdir, readFile, writeFile } from 'node:fs/promises';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ALWAYS_INSTALL, BUNDLED, HIDDEN_FOLDERS } from '../config/constants.js';
@@ -7,6 +7,100 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 /** Absolute path to the bundled framework/ directory inside this package. */
 export const FRAMEWORK_PATH = resolve(__dirname, '../../framework');
+export const DEFAULT_TEMPLATE = 'new_project';
+export const TEMPLATE_METADATA_FILE = '.acfm-template.json';
+
+function isTemplateDirectory(entry) {
+  return entry.isDirectory() && !entry.name.startsWith('.');
+}
+
+async function hasLegacyModules(frameworkPath) {
+  const entries = await readdir(frameworkPath, { withFileTypes: true });
+  return entries.some((entry) => entry.isDirectory() && entry.name.startsWith('.'));
+}
+
+export async function getAvailableTemplates(frameworkPath = FRAMEWORK_PATH) {
+  const entries = await readdir(frameworkPath, { withFileTypes: true });
+  const templates = entries
+    .filter(isTemplateDirectory)
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+
+  if (templates.length > 0) {
+    return templates;
+  }
+
+  if (await hasLegacyModules(frameworkPath)) {
+    return [DEFAULT_TEMPLATE];
+  }
+
+  return [];
+}
+
+export async function resolveTemplatePath(templateName, frameworkPath = FRAMEWORK_PATH) {
+  const explicitTemplatePath = join(frameworkPath, templateName);
+
+  try {
+    const entries = await readdir(explicitTemplatePath, { withFileTypes: true });
+    if (entries.length >= 0) {
+      return explicitTemplatePath;
+    }
+  } catch {
+    if (templateName === DEFAULT_TEMPLATE && await hasLegacyModules(frameworkPath)) {
+      return frameworkPath;
+    }
+    throw new Error(`Template not found: ${templateName}`);
+  }
+
+  return explicitTemplatePath;
+}
+
+export async function saveTemplateSelection(targetDir, templateName) {
+  const metadataPath = join(targetDir, TEMPLATE_METADATA_FILE);
+  const payload = {
+    template: templateName,
+    savedAt: new Date().toISOString(),
+  };
+
+  await writeFile(metadataPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+
+export async function readTemplateSelection(targetDir) {
+  try {
+    const metadataPath = join(targetDir, TEMPLATE_METADATA_FILE);
+    const raw = await readFile(metadataPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed?.template || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function detectTemplateForModules(modules, frameworkPath = FRAMEWORK_PATH) {
+  const templates = await getAvailableTemplates(frameworkPath);
+  const prioritizedTemplates = [
+    ...templates.filter((template) => template === DEFAULT_TEMPLATE),
+    ...templates.filter((template) => template !== DEFAULT_TEMPLATE),
+  ];
+
+  for (const template of prioritizedTemplates) {
+    const templatePath = await resolveTemplatePath(template, frameworkPath);
+    let matches = true;
+
+    for (const mod of modules) {
+      if (!(await existsInTarget(templatePath, mod))) {
+        matches = false;
+        break;
+      }
+    }
+
+    if (matches) {
+      return template;
+    }
+  }
+
+  return templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0] || null;
+}
 
 /**
  * Returns sorted list of selectable assistant folder names.
@@ -20,6 +114,7 @@ export async function getSelectableModules(frameworkPath = FRAMEWORK_PATH) {
     .filter(
       (e) =>
         e.isDirectory() &&
+        e.name.startsWith('.') &&
         !ALWAYS_INSTALL.includes(e.name) &&
         !HIDDEN_FOLDERS.has(e.name),
     )

package/src/services/mcp-installer.js

@@ -2,12 +2,15 @@
  * mcp-installer.js — MCP config installer for AC Framework
  *
  * Detects installed AI assistants and injects the ac-framework-memory
- * MCP server into their config files.
+ * MCP server into their config files using the CORRECT format for each.
  *
- * Best-practice config format per MCP spec:
- *   { "mcpServers": { "ac-framework-memory": { "command": "node", "args": [<absPath>] } } }
- *
- * Claude Code uses a different top-level key format (mcpServers inside claude.json).
+ * Verified formats (Mar 2026):
+ *   opencode  → ~/.config/opencode/opencode.json  key:"mcp"  type:"local"  command:array
+ *   claude    → ~/.claude.json                     key:"mcpServers"  type:"stdio"
+ *   cursor    → ~/.cursor/mcp.json                 key:"mcpServers"
+ *   windsurf  → ~/.codeium/windsurf/mcp_config.json key:"mcpServers"
+ *   gemini    → ~/.gemini/settings.json            key:"mcpServers"
+ *   codex     → ~/.codex/config.toml               TOML format
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -17,61 +20,149 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Absolute path to the MCP server entry point (ESM, referenced by node)
+/** Absolute path to the MCP server entry point */
 export function getMCPServerPath() {
-  const srcPath = join(__dirname, '../mcp/server.js');
-  return srcPath;
+  return join(__dirname, '../mcp/server.js');
 }
 
-// ── Supported assistants ──────────────────────────────────────────
-
 const home = homedir();
-const IS_WIN = platform() === 'win32';
 
-/**
- * Each assistant entry:
- *   configPath  – absolute path to the JSON config file
- *   configKey   – top-level key that holds server map ("mcpServers" | "servers")
- *   detectDir   – directory whose existence signals the assistant is present
- */
-const ASSISTANTS = [
+// ── Assistant definitions ─────────────────────────────────────────
+//
+// Each entry may have a custom `install` / `uninstall` function if its
+// format differs from the standard JSON mcpServers pattern.
+
+export const ASSISTANTS = [
+  // ── OpenCode ───────────────────────────────────────────────────
+  // Config: ~/.config/opencode/opencode.json
+  // Schema: { "mcp": { "<name>": { "type": "local", "command": ["node", "path"] } } }
   {
     name: 'opencode',
-    configPath: join(home, '.opencode', 'mcp.json'),
-    configKey: 'mcpServers',
-    detectDir: join(home, '.opencode'),
+    configPath: join(home, '.config', 'opencode', 'opencode.json'),
+    detectDir: join(home, '.config', 'opencode'),
+    install(serverPath) {
+      const configDir = dirname(this.configPath);
+      if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+
+      let config = {};
+      if (existsSync(this.configPath)) {
+        try { config = JSON.parse(readFileSync(this.configPath, 'utf8')); } catch { config = {}; }
+      }
+
+      if (!config.mcp) config.mcp = {};
+      config.mcp['ac-framework-memory'] = {
+        type: 'local',
+        command: ['node', serverPath],
+      };
+
+      writeFileSync(this.configPath, JSON.stringify(config, null, 2));
+      return true;
+    },
+    uninstall() {
+      if (!existsSync(this.configPath)) return true;
+      let config = {};
+      try { config = JSON.parse(readFileSync(this.configPath, 'utf8')); } catch { return true; }
+      if (config.mcp?.['ac-framework-memory']) {
+        delete config.mcp['ac-framework-memory'];
+        writeFileSync(this.configPath, JSON.stringify(config, null, 2));
+      }
+      return true;
+    },
   },
+
+  // ── Claude Code CLI ────────────────────────────────────────────
+  // Config: ~/.claude.json  (top-level mcpServers key, merges with existing data)
+  // Schema: { "mcpServers": { "<name>": { "type": "stdio", "command": "node", "args": ["path"] } } }
   {
     name: 'claude',
-    // Claude Code CLI uses ~/.claude.json (mcpServers key)
     configPath: join(home, '.claude.json'),
-    configKey: 'mcpServers',
-    detectDir: home,
     detectFile: join(home, '.claude.json'),
+    install(serverPath) {
+      let config = {};
+      if (existsSync(this.configPath)) {
+        try { config = JSON.parse(readFileSync(this.configPath, 'utf8')); } catch { config = {}; }
+      }
+
+      if (!config.mcpServers) config.mcpServers = {};
+      config.mcpServers['ac-framework-memory'] = {
+        type: 'stdio',
+        command: 'node',
+        args: [serverPath],
+      };
+
+      writeFileSync(this.configPath, JSON.stringify(config, null, 2));
+      return true;
+    },
+    uninstall() {
+      if (!existsSync(this.configPath)) return true;
+      let config = {};
+      try { config = JSON.parse(readFileSync(this.configPath, 'utf8')); } catch { return true; }
+      if (config.mcpServers?.['ac-framework-memory']) {
+        delete config.mcpServers['ac-framework-memory'];
+        writeFileSync(this.configPath, JSON.stringify(config, null, 2));
+      }
+      return true;
+    },
   },
+
+  // ── Cursor IDE ─────────────────────────────────────────────────
+  // Config: ~/.cursor/mcp.json
+  // Schema: { "mcpServers": { "<name>": { "command": "node", "args": ["path"] } } }
   {
     name: 'cursor',
     configPath: join(home, '.cursor', 'mcp.json'),
-    configKey: 'mcpServers',
     detectDir: join(home, '.cursor'),
+    install(serverPath) {
+      return installJsonMcpServers(this.configPath, serverPath);
+    },
+    uninstall() {
+      return uninstallJsonMcpServers(this.configPath);
+    },
   },
+
+  // ── Windsurf IDE ───────────────────────────────────────────────
+  // Config: ~/.codeium/windsurf/mcp_config.json  (NOT ~/.windsurf/mcp.json)
+  // Schema: { "mcpServers": { "<name>": { "command": "node", "args": ["path"] } } }
   {
     name: 'windsurf',
-    configPath: join(home, '.windsurf', 'mcp.json'),
-    configKey: 'mcpServers',
-    detectDir: join(home, '.windsurf'),
+    configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+    detectDir: join(home, '.codeium', 'windsurf'),
+    install(serverPath) {
+      return installJsonMcpServers(this.configPath, serverPath);
+    },
+    uninstall() {
+      return uninstallJsonMcpServers(this.configPath);
+    },
   },
+
+  // ── Google Gemini CLI ──────────────────────────────────────────
+  // Config: ~/.gemini/settings.json  (NOT ~/.gemini/mcp.json)
+  // Schema: { "mcpServers": { "<name>": { "command": "node", "args": ["path"] } } }
   {
     name: 'gemini',
-    configPath: join(home, '.gemini', 'mcp.json'),
-    configKey: 'mcpServers',
+    configPath: join(home, '.gemini', 'settings.json'),
     detectDir: join(home, '.gemini'),
+    install(serverPath) {
+      return installJsonMcpServers(this.configPath, serverPath);
+    },
+    uninstall() {
+      return uninstallJsonMcpServers(this.configPath);
+    },
   },
+
+  // ── OpenAI Codex CLI ───────────────────────────────────────────
+  // Config: ~/.codex/config.toml  (TOML format, NOT JSON)
+  // Schema: [mcp_servers.ac-framework-memory]\ncommand = "node"\nargs = ["/path"]
   {
     name: 'codex',
-    configPath: join(home, '.codex', 'mcp.json'),
-    configKey: 'mcpServers',
+    configPath: join(home, '.codex', 'config.toml'),
     detectDir: join(home, '.codex'),
+    install(serverPath) {
+      return installTomlMcpServer(this.configPath, serverPath);
+    },
+    uninstall() {
+      return uninstallTomlMcpServer(this.configPath);
+    },
   },
 ];
 
@@ -79,7 +170,6 @@ const ASSISTANTS = [
 
 export function isAssistantInstalled(assistant) {
   try {
-    // If a specific file is the detection signal, use that
     if (assistant.detectFile) return existsSync(assistant.detectFile);
     return existsSync(assistant.detectDir);
   } catch {
@@ -87,39 +177,115 @@ export function isAssistantInstalled(assistant) {
   }
 }
 
-// ── Install / Uninstall ───────────────────────────────────────────
+// ── Generic JSON mcpServers helpers ───────────────────────────────
 
-export function installMCPForAssistant(assistant) {
-  try {
-    const configDir = dirname(assistant.configPath);
+function installJsonMcpServers(configPath, serverPath) {
+  const configDir = dirname(configPath);
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
 
-    if (!existsSync(configDir)) {
-      mkdirSync(configDir, { recursive: true });
-    }
+  let config = {};
+  if (existsSync(configPath)) {
+    try { config = JSON.parse(readFileSync(configPath, 'utf8')); } catch { config = {}; }
+  }
 
-    // Read existing config or start fresh
-    let config = {};
-    if (existsSync(assistant.configPath)) {
-      try {
-        config = JSON.parse(readFileSync(assistant.configPath, 'utf8'));
-      } catch {
-        config = {};
-      }
-    }
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers['ac-framework-memory'] = {
+    command: 'node',
+    args: [serverPath],
+  };
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  return true;
+}
 
-    // Ensure the server map key exists
-    if (!config[assistant.configKey]) {
-      config[assistant.configKey] = {};
+function uninstallJsonMcpServers(configPath) {
+  if (!existsSync(configPath)) return true;
+  let config = {};
+  try { config = JSON.parse(readFileSync(configPath, 'utf8')); } catch { return true; }
+  if (config.mcpServers?.['ac-framework-memory']) {
+    delete config.mcpServers['ac-framework-memory'];
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+  }
+  return true;
+}
+
+// ── TOML helpers (Codex) ──────────────────────────────────────────
+//
+// We write TOML manually (no external dep). The section to add/replace:
+//
+//   [mcp_servers.ac-framework-memory]
+//   command = "node"
+//   args = ["/abs/path/to/server.js"]
+
+const TOML_SECTION = 'mcp_servers.ac-framework-memory';
+
+function installTomlMcpServer(configPath, serverPath) {
+  const configDir = dirname(configPath);
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+
+  // Escape backslashes for Windows paths
+  const escapedPath = serverPath.replace(/\\/g, '\\\\');
+  const newBlock = [
+    `[${TOML_SECTION}]`,
+    `command = "node"`,
+    `args = ["${escapedPath}"]`,
+  ].join('\n');
+
+  let existing = '';
+  if (existsSync(configPath)) {
+    try { existing = readFileSync(configPath, 'utf8'); } catch { existing = ''; }
+  }
+
+  if (existing.includes(`[${TOML_SECTION}]`)) {
+    // Replace existing block — remove old section, append new one
+    existing = removeTomlSection(existing, TOML_SECTION);
+  }
+
+  const separator = existing.trim() ? '\n\n' : '';
+  writeFileSync(configPath, existing.trimEnd() + separator + newBlock + '\n');
+  return true;
+}
+
+function uninstallTomlMcpServer(configPath) {
+  if (!existsSync(configPath)) return true;
+  let content = '';
+  try { content = readFileSync(configPath, 'utf8'); } catch { return true; }
+  if (content.includes(`[${TOML_SECTION}]`)) {
+    content = removeTomlSection(content, TOML_SECTION);
+    writeFileSync(configPath, content);
+  }
+  return true;
+}
+
+/**
+ * Removes a TOML section (and its key-value lines) from a TOML string.
+ * Stops at the next [section] header or end of file.
+ */
+function removeTomlSection(toml, sectionKey) {
+  const lines = toml.split('\n');
+  const result = [];
+  let inSection = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === `[${sectionKey}]`) {
+      inSection = true;
+      continue;
     }
+    if (inSection && trimmed.startsWith('[')) {
+      inSection = false;
+    }
+    if (!inSection) result.push(line);
+  }
 
-    // Add / overwrite our server entry
-    config[assistant.configKey]['ac-framework-memory'] = {
-      command: 'node',
-      args: [getMCPServerPath()],
-    };
+  return result.join('\n');
+}
+
+// ── Install / Uninstall per assistant ────────────────────────────
 
-    writeFileSync(assistant.configPath, JSON.stringify(config, null, 2));
-    return true;
+export function installMCPForAssistant(assistant) {
+  try {
+    return assistant.install(getMCPServerPath());
   } catch (error) {
     console.error(`  Failed to install MCP for ${assistant.name}: ${error.message}`);
     return false;
@@ -128,21 +294,7 @@ export function installMCPForAssistant(assistant) {
 
 export function uninstallMCPForAssistant(assistant) {
   try {
-    if (!existsSync(assistant.configPath)) return true;
-
-    let config = {};
-    try {
-      config = JSON.parse(readFileSync(assistant.configPath, 'utf8'));
-    } catch {
-      return true;
-    }
-
-    if (config[assistant.configKey]?.['ac-framework-memory']) {
-      delete config[assistant.configKey]['ac-framework-memory'];
-      writeFileSync(assistant.configPath, JSON.stringify(config, null, 2));
-    }
-
-    return true;
+    return assistant.uninstall();
   } catch (error) {
     console.error(`  Failed to uninstall MCP for ${assistant.name}: ${error.message}`);
     return false;
@@ -190,5 +342,3 @@ export function uninstallAllMCPs() {
   }
   return { success };
 }
-
-export { ASSISTANTS };

package/src/utils/helpers.js

@@ -6,3 +6,11 @@ export function formatFolderName(name) {
   const clean = name.startsWith('.') ? name.slice(1) : name;
   return clean.charAt(0).toUpperCase() + clean.slice(1);
 }
+
+export function formatTemplateName(name) {
+  return name
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}

package/framework/.agent/workflows/ac-lite.md

@@ -1,192 +0,0 @@
-**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
-
----
-
-## Purpose
-
-`ac-lite` keeps the same spec-driven quality bar as `ac.md`, but reduces token usage by:
-
-1. Loading only the core workflow skills by default.
-2. Activating extra skills only when objective risk gates require them.
-3. Enforcing mandatory quality checkpoints before implementation and archive.
-
----
-
-## Default Skill Set (Always Load)
-
-These are the only mandatory skills for every change:
-
-1. `acfm-spec-workflow`
-2. `openspec-new-change` OR `openspec-ff-change`
-3. `openspec-continue-change`
-4. `openspec-apply-change`
-5. `openspec-verify-change`
-6. `openspec-archive-change`
-
----
-
-## Conditional Skills (Load Only If Gate Triggers)
-
-### Security Gate
-
-Load `secure-coding-cybersecurity` if the change touches any of:
-
-- Auth/session/permissions
-- User input handling or validation
-- SQL/ORM queries or dynamic filters
-- File paths/uploads
-- Secrets/tokens/credentials
-- Shell/command execution
-
-### Testing Gate
-
-Load `test-generator` if:
-
-- There are no tests for the changed behavior, or
-- Existing tests do not cover acceptance criteria, or
-- Regression risk is medium/high.
-
-### Consistency Gate
-
-Load `spec-analysis` and `requirement-checklist` if:
-
-- Requirements are ambiguous, or
-- Change spans multiple modules, or
-- Change modifies core domain behavior.
-
-### API Gate
-
-Load `api-design-principles` if API contracts/endpoints/schemas are added or modified.
-
-### UI Gate
-
-Load `interface-design` if dashboard/app UI behavior is introduced or changed.
-
-### Performance Gate
-
-Load `performance-optimizer` if:
-
-- The change affects hot paths, or
-- Latency/throughput targets exist, or
-- A performance regression is detected/suspected.
-
-### Context Scale Gate
-
-Load `project-index` and/or `context-synthesizer` if:
-
-- Codebase is large and discovery cost is high, or
-- Session is long and context drift appears.
-
-### Debug Gate
-
-Load `systematic-debugging` when blocked by non-trivial bugs or unstable behavior.
-
----
-
-## Mandatory Quality Gates
-
-These gates are non-optional in `ac-lite`.
-
-### Gate A: Ready to Implement
-
-Before `openspec-apply-change`, all must be true:
-
-- Change exists and status is valid (`acfm spec status --change <name> --json`)
-- `tasks.md` exists with actionable checkboxes
-- Acceptance criteria are clear in artifacts
-- Required conditional skills (if triggered) were executed
-
-If any item fails: stop, resolve, then continue.
-
-### Gate B: Ready to Archive
-
-Before `openspec-archive-change`, all must be true:
-
-- `openspec-verify-change` completed
-- No CRITICAL findings remain
-- Relevant tests pass for changed behavior
-- Tasks are complete or explicitly accepted by user with warning
-
-If any item fails: stop, fix, re-verify.
-
----
-
-## Lite Workflows
-
-### New Change (Default Path)
-
-1. Run `acfm-spec-workflow` checks (`acfm spec status --json`, init if needed).
-2. Create change with `openspec-new-change` (or `openspec-ff-change` if user requests speed).
-3. Build artifacts with `openspec-continue-change` until apply-ready.
-4. Evaluate conditional gates and load only triggered skills.
-5. Pass Gate A.
-6. Implement with `openspec-apply-change`.
-7. Verify with `openspec-verify-change`.
-8. Pass Gate B.
-9. Archive with `openspec-archive-change`.
-
-### Existing Change (Default Path)
-
-1. Confirm initialization and active changes.
-2. Select target change.
-3. Refresh artifact status.
-4. Evaluate conditional gates (only load what triggers).
-5. Pass Gate A.
-6. Implement.
-7. Verify.
-8. Pass Gate B.
-9. Archive.
-
----
-
-## Operational Rules
-
-1. Do not load broad quality/documentation skills by default.
-2. Do not run optional skills "just in case".
-3. If risk increases during implementation, activate the matching conditional skill immediately.
-4. Prefer deterministic CLI checks over narrative assumptions.
-5. Keep outputs concise but auditable (show which gates passed/failed and why).
-
----
-
-## Suggested Minimal Execution Template
-
-Use this structure in each run:
-
-1. **Change Context**
-   - Change name
-   - Current artifact progress
-
-2. **Triggered Gates**
-   - Security: pass/fail + reason
-   - Testing: pass/fail + reason
-   - Consistency/API/UI/Performance/Context/Debug: pass/fail + reason
-
-3. **Skills Loaded**
-   - Core: always list
-   - Conditional: list only triggered ones
-
-4. **Gate A Status**
-   - Ready to implement: yes/no
-
-5. **Implementation + Verify**
-   - What was implemented
-   - Verify findings summary
-
-6. **Gate B Status**
-   - Ready to archive: yes/no
-
-7. **Archive Result**
-   - Archive path and timestamp
-
----
-
-## Token Strategy Summary
-
-`ac-lite` reduces cost by replacing "load everything first" with:
-
-- Mandatory core workflow only
-- Risk-gated skill expansion
-- Hard quality checkpoints at implementation and archive boundaries
-
-This preserves software quality while avoiding unnecessary instruction/context overhead.