agentic-qe 3.10.7 → 3.10.9

package/dist/init/opencode-installer.js

@@ -2,13 +2,39 @@
  * OpenCode Platform Installer
  * ADR-025: Enhanced Init with Self-Configuration
  *
- * Installs OpenCode agents, skills, tools, and permissions to user projects
- * when --with-opencode flag is used. Follows the N8n installer pattern.
+ * Installs OpenCode agents and skills to user projects in OpenCode's NATIVE
+ * on-disk format (validated against OpenCode CLI v1.17.x):
+ *   - agents -> .opencode/agent/<name>.md   (markdown + YAML frontmatter; body = system prompt)
+ *   - skills -> .opencode/skills/<name>/SKILL.md  (frontmatter name+description; body = instructions)
+ *   - MCP    -> opencode.json (mcp.agentic-qe local server)
+ *
+ * The shipped source assets under <pkg>/.opencode/{agents,skills} use AQE's own
+ * YAML schema (name/description/model/systemPrompt/tools/permissions). OpenCode
+ * does NOT load that schema, so this installer CONVERTS them at install time.
+ *
+ * Tools are intentionally NOT installed: AQE's .opencode/tools/*.ts use a custom
+ * `{name, parameters, execute}` shape and call ctx.callTool('mcp:agentic-qe:*'),
+ * which is incompatible with OpenCode's `tool()` API and redundant once the MCP
+ * server is connected (the underlying tools are exposed directly).
  */
-import { existsSync, mkdirSync, readdirSync, writeFileSync, copyFileSync, } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'fs';
 import { join } from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { findPackageRoot } from './find-package-root.js';
+// OpenCode-valid per-agent permission keys. AQE keys outside this set are dropped
+// or remapped (see PERM_KEY_MAP). In particular `mcp:agentic-qe:*` patterns are
+// dropped — OpenCode does not interpret MCP tool patterns in the permission block.
+const VALID_PERMISSION_KEYS = new Set([
+    'read', 'edit', 'glob', 'grep', 'list', 'bash', 'task',
+    'external_directory', 'todowrite', 'webfetch', 'websearch',
+    'lsp', 'skill', 'question', 'doom_loop',
+]);
+// Remap AQE permission keys to OpenCode equivalents.
+const PERM_KEY_MAP = {
+    fetch: 'webfetch',
+    write: 'edit', // OpenCode has no separate 'write' permission; file writes are 'edit'
+};
 // ============================================================================
 // OpenCode Installer Class
 // ============================================================================
@@ -21,7 +47,7 @@ export class OpenCodeInstaller {
         this.options = {
             installAgents: true,
             installSkills: true,
-            installTools: true,
+            installTools: false,
             overwrite: false,
             ...options,
         };
@@ -31,7 +57,7 @@ export class OpenCodeInstaller {
     // Source Directory Detection
     // ==========================================================================
     /**
-     * Find the source .opencode/ directory containing agents/skills/tools to install.
+     * Find the source .opencode/ directory containing agents/skills to install.
      * Resolves relative to the package installation directory (not CWD) so that
      * globally-installed and bundled CLI paths all work correctly (#361).
      */
@@ -40,20 +66,16 @@ export class OpenCodeInstaller {
         const pkgRoot = findPackageRoot(import.meta.url);
         const possiblePaths = [];
         if (pkgRoot) {
-            // OpenCode assets live at the package root .opencode/ directory
             possiblePaths.push(join(pkgRoot, '.opencode'));
         }
-        // Local install: in node_modules
         possiblePaths.push(join(this.projectRoot, 'node_modules/agentic-qe/.opencode'));
         for (const path of possiblePaths) {
-            // Never use the target directory as the source
             if (path === targetDir)
                 continue;
             if (this.isValidSourceDir(path)) {
                 return path;
             }
         }
-        // Return the first package path even if not found — install() will report the error
         return possiblePaths[0] ?? join(this.projectRoot, 'node_modules/agentic-qe/.opencode');
     }
     /**
@@ -69,7 +91,7 @@ export class OpenCodeInstaller {
     // Installation
     // ==========================================================================
     /**
-     * Install OpenCode agents, skills, tools, and permissions
+     * Install OpenCode agents, skills, and MCP config (native OpenCode format).
      */
     async install() {
         const targetDir = join(this.projectRoot, '.opencode');
@@ -88,29 +110,22 @@ export class OpenCodeInstaller {
                 result.success = false;
                 return result;
             }
-            // Install agents
+            // Per-agent permission overrides shipped in permissions.yaml (defaults +
+            // per-agent). Merged with each agent's own `permissions` field.
+            const permissionsYaml = this.loadPermissionsYaml();
             if (this.options.installAgents) {
-                const agentResult = this.installAgents(targetDir);
+                const agentResult = this.installAgents(targetDir, permissionsYaml);
                 result.agentsInstalled = agentResult.installed;
                 result.errors.push(...agentResult.errors);
+                // Per-agent permissions are folded into each agent's frontmatter.
+                result.permissionsInstalled = result.agentsInstalled.length > 0;
             }
-            // Install skills
             if (this.options.installSkills) {
                 const skillResult = this.installSkills(targetDir);
                 result.skillsInstalled = skillResult.installed;
                 result.errors.push(...skillResult.errors);
             }
-            // Install tools
-            if (this.options.installTools) {
-                const toolResult = this.installTools(targetDir);
-                result.toolsInstalled = toolResult.installed;
-                result.errors.push(...toolResult.errors);
-            }
-            // Install permissions
-            const permResult = this.installPermissions(targetDir);
-            result.permissionsInstalled = permResult.installed;
-            result.errors.push(...permResult.errors);
-            // Generate opencode.json MCP config if not exists
+            // Generate opencode.json MCP config if not present.
             this.generateOpenCodeConfig();
         }
         catch (error) {
@@ -119,14 +134,58 @@ export class OpenCodeInstaller {
         }
         return result;
     }
+    // ==========================================================================
+    // Permission helpers
+    // ==========================================================================
     /**
-     * Install agent YAML files from .opencode/agents/
+     * Load the shipped permissions.yaml (defaults + per-agent overrides). Returns
+     * { defaults, agents } or empty maps if the file is missing/unparseable.
      */
-    installAgents(targetDir) {
+    loadPermissionsYaml() {
+        const empty = { defaults: {}, agents: {} };
+        const file = join(this.sourceDir, 'permissions.yaml');
+        if (!existsSync(file))
+            return empty;
+        try {
+            const parsed = parseYaml(readFileSync(file, 'utf-8'));
+            return { defaults: parsed?.defaults ?? {}, agents: parsed?.agents ?? {} };
+        }
+        catch {
+            return empty;
+        }
+    }
+    /**
+     * Build an OpenCode-valid `permission` frontmatter object by merging
+     * defaults -> agent.permissions (from agent yaml) -> permissions.yaml override,
+     * remapping keys and dropping anything OpenCode does not understand.
+     */
+    buildPermission(agentName, agentPerms, permissionsYaml) {
+        const merged = {
+            ...permissionsYaml.defaults,
+            ...(agentPerms ?? {}),
+            ...(permissionsYaml.agents[agentName] ?? {}),
+        };
+        const out = {};
+        for (const [rawKey, value] of Object.entries(merged)) {
+            // Drop MCP tool patterns and any other unsupported key.
+            if (rawKey.includes(':'))
+                continue;
+            const key = PERM_KEY_MAP[rawKey] ?? rawKey;
+            if (!VALID_PERMISSION_KEYS.has(key))
+                continue;
+            // 'allow' | 'ask' | 'deny' (string) or object map for bash etc.
+            out[key] = value;
+        }
+        return out;
+    }
+    // ==========================================================================
+    // Agents: <name>.yaml -> .opencode/agent/<name>.md
+    // ==========================================================================
+    installAgents(targetDir, permissionsYaml) {
         const installed = [];
         const errors = [];
         const sourceAgentsDir = join(this.sourceDir, 'agents');
-        const targetAgentsDir = join(targetDir, 'agents');
+        const targetAgentsDir = join(targetDir, 'agent'); // OpenCode native: singular 'agent'
         if (!existsSync(sourceAgentsDir)) {
             errors.push(`Source agents directory not found: ${sourceAgentsDir}`);
             return { installed, errors };
@@ -134,26 +193,37 @@ export class OpenCodeInstaller {
         if (!existsSync(targetAgentsDir)) {
             mkdirSync(targetAgentsDir, { recursive: true });
         }
-        const files = readdirSync(sourceAgentsDir).filter(f => f.endsWith('.yaml'));
-        for (const file of files) {
-            const sourceFile = join(sourceAgentsDir, file);
-            const targetFile = join(targetAgentsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
+        for (const file of readdirSync(sourceAgentsDir).filter(f => f.endsWith('.yaml'))) {
             try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.yaml', ''));
+                const data = parseYaml(readFileSync(join(sourceAgentsDir, file), 'utf-8'));
+                const name = data.name || file.replace(/\.yaml$/, '');
+                const targetFile = join(targetAgentsDir, `${name}.md`);
+                if (existsSync(targetFile) && !this.options.overwrite)
+                    continue;
+                const frontmatter = {
+                    description: (data.description || name).replace(/\s+/g, ' ').trim(),
+                    mode: 'subagent',
+                };
+                // NOTE: `model` is intentionally omitted so agents inherit the user's
+                // default OpenCode model. AQE ships model "claude-sonnet-4-6" which may
+                // not resolve in OpenCode's provider registry; inheriting avoids
+                // hard-failing the agent at invocation time.
+                const permission = this.buildPermission(name, data.permissions, permissionsYaml);
+                if (Object.keys(permission).length > 0)
+                    frontmatter.permission = permission;
+                const body = (data.systemPrompt || '').trimEnd() + '\n';
+                writeFileSync(targetFile, this.renderFrontmatter(frontmatter) + '\n' + body);
+                installed.push(name);
             }
             catch (error) {
-                errors.push(`Failed to install agent ${file}: ${toErrorMessage(error)}`);
+                errors.push(`Failed to convert agent ${file}: ${toErrorMessage(error)}`);
             }
         }
         return { installed, errors };
     }
-    /**
-     * Install skill YAML files from .opencode/skills/
-     */
+    // ==========================================================================
+    // Skills: <name>.yaml -> .opencode/skills/<name>/SKILL.md
+    // ==========================================================================
     installSkills(targetDir) {
         const installed = [];
         const errors = [];
@@ -166,97 +236,79 @@ export class OpenCodeInstaller {
         if (!existsSync(targetSkillsDir)) {
             mkdirSync(targetSkillsDir, { recursive: true });
         }
-        const files = readdirSync(sourceSkillsDir).filter(f => f.endsWith('.yaml'));
-        for (const file of files) {
-            const sourceFile = join(sourceSkillsDir, file);
-            const targetFile = join(targetSkillsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
+        for (const file of readdirSync(sourceSkillsDir).filter(f => f.endsWith('.yaml'))) {
             try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.yaml', ''));
+                const data = parseYaml(readFileSync(join(sourceSkillsDir, file), 'utf-8'));
+                const name = (data.name || file.replace(/\.yaml$/, '')).toLowerCase();
+                // OpenCode requires: ^[a-z0-9]+(-[a-z0-9]+)*$ and name === directory.
+                if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+                    errors.push(`Skipped skill with non-conforming name: ${name}`);
+                    continue;
+                }
+                const skillDir = join(targetSkillsDir, name);
+                const targetFile = join(skillDir, 'SKILL.md');
+                if (existsSync(targetFile) && !this.options.overwrite)
+                    continue;
+                if (!existsSync(skillDir))
+                    mkdirSync(skillDir, { recursive: true });
+                let description = (data.description || name).replace(/\s+/g, ' ').trim();
+                if (description.length > 1024)
+                    description = description.slice(0, 1021) + '...';
+                let body = '';
+                for (const step of data.steps ?? []) {
+                    body += `## ${step.name || 'step'}\n\n`;
+                    const text = (step.prompt || step.description || '').trimEnd();
+                    if (text)
+                        body += `${text}\n\n`;
+                }
+                if (!body.trim())
+                    body = `${data.description || name}\n`;
+                writeFileSync(targetFile, this.renderFrontmatter({ name, description }) + '\n' + body.trimEnd() + '\n');
+                installed.push(name);
             }
             catch (error) {
-                errors.push(`Failed to install skill ${file}: ${toErrorMessage(error)}`);
+                errors.push(`Failed to convert skill ${file}: ${toErrorMessage(error)}`);
             }
         }
         return { installed, errors };
     }
-    /**
-     * Install tool wrapper files from .opencode/tools/
-     */
-    installTools(targetDir) {
-        const installed = [];
-        const errors = [];
-        const sourceToolsDir = join(this.sourceDir, 'tools');
-        const targetToolsDir = join(targetDir, 'tools');
-        if (!existsSync(sourceToolsDir)) {
-            errors.push(`Source tools directory not found: ${sourceToolsDir}`);
-            return { installed, errors };
-        }
-        if (!existsSync(targetToolsDir)) {
-            mkdirSync(targetToolsDir, { recursive: true });
-        }
-        const files = readdirSync(sourceToolsDir).filter(f => f.endsWith('.ts'));
-        for (const file of files) {
-            const sourceFile = join(sourceToolsDir, file);
-            const targetFile = join(targetToolsDir, file);
-            if (existsSync(targetFile) && !this.options.overwrite) {
-                continue;
-            }
-            try {
-                copyFileSync(sourceFile, targetFile);
-                installed.push(file.replace('.ts', ''));
-            }
-            catch (error) {
-                errors.push(`Failed to install tool ${file}: ${toErrorMessage(error)}`);
-            }
-        }
-        return { installed, errors };
-    }
-    /**
-     * Install permissions.yaml to target .opencode/ directory
-     */
-    installPermissions(targetDir) {
-        const errors = [];
-        const sourceFile = join(this.sourceDir, 'permissions.yaml');
-        const targetFile = join(targetDir, 'permissions.yaml');
-        if (!existsSync(sourceFile)) {
-            return { installed: false, errors: [] };
-        }
-        if (existsSync(targetFile) && !this.options.overwrite) {
-            return { installed: false, errors: [] };
-        }
-        try {
-            if (!existsSync(targetDir)) {
-                mkdirSync(targetDir, { recursive: true });
-            }
-            copyFileSync(sourceFile, targetFile);
-            return { installed: true, errors: [] };
-        }
-        catch (error) {
-            errors.push(`Failed to install permissions.yaml: ${toErrorMessage(error)}`);
-            return { installed: false, errors };
-        }
+    // ==========================================================================
+    // Frontmatter rendering
+    // ==========================================================================
+    /** Render a frontmatter object as a `---`-delimited YAML block. */
+    renderFrontmatter(obj) {
+        return `---\n${stringifyYaml(obj).trimEnd()}\n---\n`;
     }
+    // ==========================================================================
+    // opencode.json MCP config
+    // ==========================================================================
     /**
-     * Generate opencode.json MCP config if it does not already exist
+     * Generate opencode.json MCP config if it does not already exist.
      */
     generateOpenCodeConfig() {
         const configPath = join(this.projectRoot, 'opencode.json');
-        if (existsSync(configPath)) {
+        if (existsSync(configPath))
             return;
-        }
+        // Database-free install: in-memory backend => no AQE_MEMORY_PATH, set
+        // AQE_MEMORY_BACKEND=memory so the MCP server writes nothing to disk.
+        // Otherwise preserve the historical persistent SQLite path.
+        const environment = this.options.memoryBackend === 'memory'
+            ? { AQE_MEMORY_BACKEND: 'memory', AQE_V3_MODE: 'true' }
+            : { AQE_MEMORY_PATH: '.agentic-qe/memory.db', AQE_V3_MODE: 'true' };
         const config = {
+            $schema: 'https://opencode.ai/config.json',
             mcp: {
                 'agentic-qe': {
                     type: 'local',
-                    command: ['npx', 'agentic-qe', 'mcp'],
-                    environment: {
-                        AQE_MEMORY_PATH: '.agentic-qe/memory.db',
-                        AQE_V3_MODE: 'true',
-                    },
+                    // Use the dedicated `aqe-mcp` bin, which runs the MCP server bundle
+                    // directly. The `agentic-qe mcp` subcommand instead double-spawns the
+                    // server (stdio:'inherit'), which corrupts stdin delivery and makes
+                    // OpenCode's client fail with "Failed to get tools". A higher timeout
+                    // accommodates the server's subsystem boot.
+                    command: ['aqe-mcp'],
+                    environment,
+                    enabled: true,
+                    timeout: 60000,
                 },
             },
         };

package/dist/init/orchestrator.js

@@ -49,6 +49,8 @@ export class ModularInitOrchestrator {
                 wizardAnswers: options.wizardAnswers,
                 noGovernance: options.noGovernance,
                 noMcp: options.noMcp,
+                noClaude: options.noClaude,
+                memoryBackend: options.memoryBackend,
             },
             config: {},
             enhancements: {

package/dist/init/phases/04-database.d.ts

@@ -29,6 +29,11 @@ export declare class DatabasePhase extends BasePhase<DatabaseResult> {
     readonly order = 40;
     readonly critical = true;
     readonly requiresPhases: readonly ["configuration"];
+    /**
+     * Database-free mode (`--no-database` / memoryBackend: 'memory'): skip the
+     * SQLite database entirely. Nothing is written under .agentic-qe/.
+     */
+    shouldRun(context: InitContext): Promise<boolean>;
     protected run(context: InitContext): Promise<DatabaseResult>;
 }
 //# sourceMappingURL=04-database.d.ts.map

package/dist/init/phases/04-database.js

@@ -26,6 +26,13 @@ export class DatabasePhase extends BasePhase {
     order = 40;
     critical = true;
     requiresPhases = ['configuration'];
+    /**
+     * Database-free mode (`--no-database` / memoryBackend: 'memory'): skip the
+     * SQLite database entirely. Nothing is written under .agentic-qe/.
+     */
+    async shouldRun(context) {
+        return context.options.memoryBackend !== 'memory';
+    }
     async run(context) {
         const { projectRoot } = context;
         // Issue #399 / ADR-090: warn on stale ./vectors.db cruft.

package/dist/init/phases/05-learning.js

@@ -16,6 +16,9 @@ export class LearningPhase extends BasePhase {
     critical = false;
     requiresPhases = ['database', 'configuration'];
     async shouldRun(context) {
+        // Database-free mode has no persistent store to seed patterns into.
+        if (context.options.memoryBackend === 'memory')
+            return false;
         const config = context.config;
         return config?.learning?.enabled ?? true;
     }

package/dist/init/phases/06-code-intelligence.js

@@ -84,6 +84,12 @@ export class CodeIntelligencePhase extends BasePhase {
      *     for the case where the corpus misses something in the wild.
      */
     async shouldRun(context) {
+        // Database-free mode: the knowledge graph is persisted to the SQLite DB,
+        // which does not exist here. Build it later with `aqe code index`.
+        if (context.options.memoryBackend === 'memory') {
+            context.services.log('  Code intelligence skipped (database-free mode)');
+            return false;
+        }
         const envSkip = process.env.AQE_SKIP_CODE_INDEX;
         if (envSkip === '1' || envSkip === 'true') {
             context.services.log('  Code intelligence skipped (AQE_SKIP_CODE_INDEX=1)');

package/dist/init/phases/07-hooks.js

@@ -25,6 +25,11 @@ export class HooksPhase extends BasePhase {
     critical = false;
     requiresPhases = ['configuration'];
     async shouldRun(context) {
+        // #532: hooks write into .claude/ — part of the Claude Code surface.
+        if (context.options.noClaude) {
+            context.services.log('  Hooks skipped (--no-claude)');
+            return false;
+        }
         const config = context.config;
         return config?.hooks?.claudeCode ?? true;
     }

package/dist/init/phases/08-mcp.js

@@ -26,6 +26,11 @@ export class MCPPhase extends BasePhase {
     requiresPhases = ['configuration', 'database'];
     async run(context) {
         const { projectRoot } = context;
+        // #532: --no-claude suppresses the Claude Code surface, including .mcp.json.
+        if (context.options.noClaude) {
+            context.services.log('  MCP: skipped (--no-claude — .mcp.json is the Claude Code surface)');
+            return { configured: false, mcpPath: '', serverName: '' };
+        }
         // MCP is enabled by default — skip only with --no-mcp
         if (context.options.noMcp) {
             context.services.log('  MCP: skipped (--no-mcp)');
@@ -39,14 +44,29 @@ export class MCPPhase extends BasePhase {
         // AQE MCP server configuration
         // AQE_PROJECT_ROOT omitted — runtime discovery via findProjectRoot() is
         // portable across machines, devcontainers, and CI (#321)
-        const aqeServerConfig = {
-            command: 'aqe-mcp',
-            args: [],
-            env: {
+        //
+        // Issue #533: in database-free mode (--no-database / memoryBackend:'memory')
+        // the server must run in-memory and must not have learning/workers forced
+        // on (those persist to SQLite, recreating .agentic-qe/memory.db at runtime
+        // and defeating the db-free install). Those phases are already skipped at
+        // install time; mirror that in the generated env.
+        const dbFree = context.options.memoryBackend === 'memory';
+        const env = dbFree
+            ? {
+                AQE_MEMORY_BACKEND: 'memory',
+                AQE_LEARNING_ENABLED: 'false',
+                AQE_WORKERS_ENABLED: 'false',
+                NODE_ENV: 'production',
+            }
+            : {
                 AQE_LEARNING_ENABLED: 'true',
                 AQE_WORKERS_ENABLED: 'true',
                 NODE_ENV: 'production',
-            },
+            };
+        const aqeServerConfig = {
+            command: 'aqe-mcp',
+            args: [],
+            env,
         };
         // Write to .mcp.json at project root (the only location Claude Code reads)
         const rootMcpPath = join(projectRoot, '.mcp.json');
@@ -68,8 +88,15 @@ export class MCPPhase extends BasePhase {
         writeFileSync(rootMcpPath, JSON.stringify(rootMcpConfig, null, 2), 'utf-8');
         context.services.log(`  MCP config: ${rootMcpPath}`);
         context.services.log(`  Server: agentic-qe`);
-        context.services.log(`  Learning: enabled`);
-        context.services.log(`  Workers: enabled`);
+        if (dbFree) {
+            context.services.log(`  Memory backend: in-memory (database-free)`);
+            context.services.log(`  Learning: disabled (db-free)`);
+            context.services.log(`  Workers: disabled (db-free)`);
+        }
+        else {
+            context.services.log(`  Learning: enabled`);
+            context.services.log(`  Workers: enabled`);
+        }
         return {
             configured: true,
             mcpPath: rootMcpPath,