agentic-qe 3.13.3 → 3.13.4

package/dist/init/codex-installer.js

@@ -9,6 +9,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSyn
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { selectCodexSkills } from './codex-skill-manifest.js';
 import { createPlatformConfigGenerator, } from './platform-config-generator.js';
 // ============================================================================
 // Codex Installer Class
@@ -18,6 +19,8 @@ export class CodexInstaller {
     overwrite;
     options;
     generator;
+    static AGENTS_START = '<!-- BEGIN AGENTIC-QE CODEX -->';
+    static AGENTS_END = '<!-- END AGENTIC-QE CODEX -->';
     constructor(options) {
         this.projectRoot = options.projectRoot;
         this.overwrite = options.overwrite ?? false;
@@ -36,13 +39,21 @@ export class CodexInstaller {
             agentsMdPath: '',
             hooksPath: join(this.projectRoot, '.codex', 'hooks.json'),
             skillsPath: join(this.projectRoot, '.agents', 'skills'),
+            components: {
+                mcp: { status: 'skipped' },
+                rules: { status: 'skipped' },
+                hooks: { status: 'unavailable' },
+                skills: { status: 'unavailable' },
+            },
         };
         try {
-            // Generate TOML MCP config
             const mcpConfig = this.generator.generateMcpConfig('codex', { memoryBackend: this.options.memoryBackend });
             const configPath = join(this.projectRoot, mcpConfig.path);
             result.configPath = configPath;
-            if (!existsSync(configPath) || this.overwrite) {
+            // Generate TOML MCP config unless the caller explicitly requested a
+            // platform-only install (rules, hooks, and skills remain useful).
+            const configExists = existsSync(configPath);
+            if (this.options.installMcp !== false && (!configExists || this.overwrite)) {
                 const configDir = dirname(configPath);
                 if (!existsSync(configDir)) {
                     mkdirSync(configDir, { recursive: true });
@@ -55,30 +66,61 @@ export class CodexInstaller {
                     writeFileSync(configPath, mcpConfig.content);
                 }
                 result.mcpConfigured = true;
+                result.components.mcp.status = configExists ? 'updated' : 'installed';
+            }
+            else if (this.options.installMcp !== false && configExists) {
+                result.components.mcp.status = 'preserved';
             }
+        }
+        catch (error) {
+            this.recordComponentFailure(result, 'mcp', error);
+        }
+        try {
             // Generate AGENTS.md behavioral rules
             const rules = this.generator.generateBehavioralRules('codex');
             const agentsMdPath = join(this.projectRoot, rules.path);
             result.agentsMdPath = agentsMdPath;
-            if (!existsSync(agentsMdPath) || this.overwrite) {
-                if (existsSync(agentsMdPath) && this.overwrite) {
+            const rulesExist = existsSync(agentsMdPath);
+            if (!rulesExist || this.overwrite) {
+                if (rulesExist && this.overwrite) {
                     const merged = this.mergeExistingAgentsMd(agentsMdPath, rules.content);
                     writeFileSync(agentsMdPath, merged);
                 }
                 else {
-                    writeFileSync(agentsMdPath, rules.content);
+                    writeFileSync(agentsMdPath, this.markAgentsSection(rules.content));
                 }
                 result.agentsMdInstalled = true;
+                result.components.rules.status = rulesExist ? 'updated' : 'installed';
+            }
+            else {
+                result.components.rules.status = 'preserved';
             }
-            this.installCodexHooks(result);
-            result.skillsInstalled = this.installCodexSkills();
         }
         catch (error) {
-            result.success = false;
-            result.errors.push(`Codex installation failed: ${toErrorMessage(error)}`);
+            this.recordComponentFailure(result, 'rules', error);
         }
+        try {
+            result.components.hooks.status = this.installCodexHooks(result);
+        }
+        catch (error) {
+            this.recordComponentFailure(result, 'hooks', error);
+        }
+        try {
+            const skills = this.installCodexSkills();
+            result.skillsInstalled = skills.count;
+            result.components.skills.status = skills.status;
+        }
+        catch (error) {
+            this.recordComponentFailure(result, 'skills', error);
+        }
+        result.success = result.errors.length === 0;
         return result;
     }
+    recordComponentFailure(result, component, error) {
+        const message = toErrorMessage(error);
+        result.components[component] = { status: 'failed', error: message };
+        result.errors.push(`Codex ${component} installation failed: ${message}`);
+    }
     /**
      * Install Codex-native lifecycle adapters and merge AQE/ruflo hook groups
      * without removing user-defined hooks.
@@ -86,15 +128,17 @@ export class CodexInstaller {
     installCodexHooks(result) {
         const sourceRoot = this.resolvePackageRoot();
         if (!sourceRoot)
-            return;
+            return 'unavailable';
         const sourceConfig = join(sourceRoot, '.codex', 'hooks.json');
         const sourceScripts = join(sourceRoot, '.codex', 'hooks');
         if (!existsSync(sourceConfig) || !existsSync(sourceScripts))
-            return;
+            return 'unavailable';
         const targetCodexDir = join(this.projectRoot, '.codex');
         const targetScripts = join(targetCodexDir, 'hooks');
         mkdirSync(targetScripts, { recursive: true });
         for (const file of readdirSync(sourceScripts)) {
+            if (!this.options.includeRuflo && file === 'ruflo-codex-hook.cjs')
+                continue;
             const source = join(sourceScripts, file);
             if (!statSync(source).isFile())
                 continue;
@@ -108,25 +152,31 @@ export class CodexInstaller {
                 source: join(sourceRoot, '.claude', 'hooks', 'aqe-hook.cjs'),
                 target: join(targetScripts, 'aqe-runtime.cjs'),
             },
-            {
-                source: join(sourceRoot, '.claude', 'helpers', 'ruflo-hook.cjs'),
-                target: join(targetScripts, 'ruflo-runtime.cjs'),
-            },
+            ...(this.options.includeRuflo ? [{
+                    source: join(sourceRoot, '.claude', 'helpers', 'ruflo-hook.cjs'),
+                    target: join(targetScripts, 'ruflo-runtime.cjs'),
+                }] : []),
         ];
         for (const runtime of runtimes) {
             if (existsSync(runtime.source) && (!existsSync(runtime.target) || this.overwrite)) {
                 copyFileSync(runtime.source, runtime.target);
             }
         }
-        const generated = JSON.parse(readFileSync(sourceConfig, 'utf-8'));
+        const generatedSource = JSON.parse(readFileSync(sourceConfig, 'utf-8'));
+        const isRufloGroup = (value) => JSON.stringify(value).includes('ruflo-codex-hook.cjs');
+        const generated = {
+            ...generatedSource,
+            hooks: Object.fromEntries(Object.entries(generatedSource.hooks || {}).map(([event, groups]) => [
+                event,
+                this.options.includeRuflo ? groups : groups.filter((group) => !isRufloGroup(group)),
+            ])),
+        };
         const targetConfig = join(targetCodexDir, 'hooks.json');
         if (!existsSync(targetConfig)) {
             writeFileSync(targetConfig, JSON.stringify(generated, null, 2) + '\n');
             result.hooksConfigured = true;
-            return;
+            return 'installed';
         }
-        if (!this.overwrite)
-            return;
         const existing = JSON.parse(readFileSync(targetConfig, 'utf-8'));
         const owned = (value) => JSON.stringify(value).includes('/.codex/hooks/aqe-codex-hook.cjs')
             || JSON.stringify(value).includes('/.codex/hooks/ruflo-codex-hook.cjs');
@@ -141,31 +191,54 @@ export class CodexInstaller {
         }
         writeFileSync(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
         result.hooksConfigured = true;
+        return 'updated';
     }
     /** Install the curated repo-scoped AQE skills Codex discovers automatically. */
     installCodexSkills() {
         const sourceRoot = this.resolvePackageRoot();
         if (!sourceRoot)
-            return 0;
+            return { count: 0, status: 'unavailable' };
         const sourceSkills = join(sourceRoot, '.agents', 'skills');
         if (!existsSync(sourceSkills))
-            return 0;
+            return { count: 0, status: 'unavailable' };
         const targetSkills = join(this.projectRoot, '.agents', 'skills');
         mkdirSync(targetSkills, { recursive: true });
         let installed = 0;
-        for (const skill of readdirSync(sourceSkills)) {
-            if (!skill.startsWith('aqe-'))
-                continue;
-            const source = join(sourceSkills, skill);
-            if (!statSync(source).isDirectory())
-                continue;
-            const target = join(targetSkills, skill);
+        let updated = 0;
+        for (const skill of selectCodexSkills({ includeRuflo: this.options.includeRuflo })) {
+            const source = join(sourceSkills, skill.name);
+            if (!existsSync(source) || !statSync(source).isDirectory()) {
+                throw new Error(`Missing packaged Codex skill directory: ${skill.name}`);
+            }
+            const target = join(targetSkills, skill.name);
             if (existsSync(target) && !this.overwrite)
                 continue;
-            this.copyDirectory(source, target);
-            installed++;
+            const targetExisted = existsSync(target);
+            if (skill.files) {
+                mkdirSync(target, { recursive: true });
+                for (const relativeFile of skill.files) {
+                    const from = join(source, relativeFile);
+                    if (!existsSync(from) || !statSync(from).isFile()) {
+                        throw new Error(`Missing packaged Codex skill file: ${skill.name}/${relativeFile}`);
+                    }
+                    const to = join(target, relativeFile);
+                    mkdirSync(dirname(to), { recursive: true });
+                    copyFileSync(from, to);
+                }
+            }
+            else {
+                this.copyDirectory(source, target);
+            }
+            if (targetExisted)
+                updated++;
+            else
+                installed++;
         }
-        return installed;
+        const count = installed + updated;
+        return {
+            count,
+            status: updated > 0 ? 'updated' : installed > 0 ? 'installed' : 'preserved',
+        };
     }
     copyDirectory(source, target) {
         mkdirSync(target, { recursive: true });
@@ -195,40 +268,45 @@ export class CodexInstaller {
     }
     /**
      * Merge AQE MCP server config into existing TOML.
-     * Simple approach: if [mcp_servers.agentic-qe] already exists, skip.
-     * Otherwise, append the AQE block at the end.
+     * Replace only AQE-owned TOML tables, preserving every user-owned table and
+     * setting. AQE owns the exact `mcp_servers.agentic-qe` table prefix.
      */
     mergeExistingTomlConfig(configPath, newContent) {
-        try {
-            const existing = readFileSync(configPath, 'utf-8');
-            // If AQE server already configured, return as-is
-            if (existing.includes('[mcp_servers.agentic-qe]')) {
-                return existing;
+        const existing = readFileSync(configPath, 'utf-8');
+        const aqeTable = /^\s*\[mcp_servers\.(?:agentic-qe|"agentic-qe")(?:\.(?:[^\]]+))?\]\s*(?:#.*)?$/;
+        const lines = existing.split(/\r?\n/);
+        const kept = [];
+        let inOwnedTable = false;
+        for (const line of lines) {
+            if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(line)) {
+                inOwnedTable = aqeTable.test(line);
             }
-            // Append AQE config block
-            return existing.trimEnd() + '\n\n' + newContent;
-        }
-        catch {
-            return newContent;
+            if (!inOwnedTable)
+                kept.push(line);
         }
+        return kept.join('\n').trimEnd() + '\n\n' + newContent.trim() + '\n';
     }
     /**
      * Merge AQE section into existing AGENTS.md.
-     * Appends the AQE section if not already present.
+     * Replaces a previously marked AQE section or appends a new marked section.
      */
     mergeExistingAgentsMd(agentsMdPath, newContent) {
-        try {
-            const existing = readFileSync(agentsMdPath, 'utf-8');
-            // If AQE section already present, return as-is
-            if (existing.includes('Agentic QE') || existing.includes('fleet_init')) {
-                return existing;
+        const existing = readFileSync(agentsMdPath, 'utf-8');
+        const marked = this.markAgentsSection(newContent);
+        const start = CodexInstaller.AGENTS_START;
+        const end = CodexInstaller.AGENTS_END;
+        const startIndex = existing.indexOf(start);
+        if (startIndex >= 0) {
+            const endIndex = existing.indexOf(end, startIndex);
+            if (endIndex >= 0) {
+                return existing.slice(0, startIndex) + marked
+                    + existing.slice(endIndex + end.length);
             }
-            // Append AQE section
-            return existing.trimEnd() + '\n\n---\n\n' + newContent;
-        }
-        catch {
-            return newContent;
         }
+        return existing.trimEnd() + '\n\n---\n\n' + marked;
+    }
+    markAgentsSection(content) {
+        return `${CodexInstaller.AGENTS_START}\n${content.trim()}\n${CodexInstaller.AGENTS_END}\n`;
     }
 }
 // ============================================================================

package/dist/init/codex-skill-manifest.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Skills shipped for repository-scoped Codex installs.
+ *
+ * Keep this list explicit: discovering skills by directory prefix makes the
+ * public package surface depend on unrelated files in a development checkout.
+ * Ruflo remains an opt-in, development-time integration and only its skill
+ * instructions are packaged; no Ruflo runtime code or dependency is shipped.
+ */
+export interface CodexSkillManifestEntry {
+    /** Directory name below `.agents/skills`. */
+    readonly name: string;
+    /** Install in every Codex configuration. */
+    readonly default: boolean;
+    /** Optional file allowlist relative to the skill directory. */
+    readonly files?: readonly string[];
+}
+export declare const CODEX_SKILL_MANIFEST: readonly [{
+    readonly name: "aqe-plan-quality";
+    readonly default: true;
+}, {
+    readonly name: "aqe-plan-work";
+    readonly default: true;
+}, {
+    readonly name: "aqe-research";
+    readonly default: true;
+}, {
+    readonly name: "aqe-review-quality";
+    readonly default: true;
+}, {
+    readonly name: "aqe-test-change";
+    readonly default: true;
+}, {
+    readonly name: "aqe-ruflo";
+    readonly default: false;
+    readonly files: readonly ["SKILL.md"];
+}];
+export interface SelectCodexSkillsOptions {
+    /** Include the Ruflo orchestration guidance without installing Ruflo itself. */
+    includeRuflo?: boolean;
+}
+/** Return the deterministic install set for a Codex project. */
+export declare function selectCodexSkills(options?: SelectCodexSkillsOptions): readonly CodexSkillManifestEntry[];
+//# sourceMappingURL=codex-skill-manifest.d.ts.map

package/dist/init/codex-skill-manifest.js

@@ -0,0 +1,21 @@
+/**
+ * Skills shipped for repository-scoped Codex installs.
+ *
+ * Keep this list explicit: discovering skills by directory prefix makes the
+ * public package surface depend on unrelated files in a development checkout.
+ * Ruflo remains an opt-in, development-time integration and only its skill
+ * instructions are packaged; no Ruflo runtime code or dependency is shipped.
+ */
+export const CODEX_SKILL_MANIFEST = [
+    { name: 'aqe-plan-quality', default: true },
+    { name: 'aqe-plan-work', default: true },
+    { name: 'aqe-research', default: true },
+    { name: 'aqe-review-quality', default: true },
+    { name: 'aqe-test-change', default: true },
+    { name: 'aqe-ruflo', default: false, files: ['SKILL.md'] },
+];
+/** Return the deterministic install set for a Codex project. */
+export function selectCodexSkills(options = {}) {
+    return CODEX_SKILL_MANIFEST.filter((skill) => skill.default || (skill.name === 'aqe-ruflo' && options.includeRuflo === true));
+}
+//# sourceMappingURL=codex-skill-manifest.js.map

package/dist/init/orchestrator.js

@@ -42,6 +42,7 @@ export class ModularInitOrchestrator {
                 withKiloCode: options.withKiloCode || allPlatforms,
                 withRooCode: options.withRooCode || allPlatforms,
                 withCodex: options.withCodex || allPlatforms,
+                withRuflo: options.withRuflo,
                 withWindsurf: options.withWindsurf || allPlatforms,
                 withContinueDev: options.withContinueDev || allPlatforms,
                 withAllPlatforms: options.withAllPlatforms,

package/dist/init/phases/09-assets.js

@@ -293,7 +293,13 @@ export class AssetsPhase extends BasePhase {
         // P2 platforms: Codex (TOML), Windsurf (JSON), Continue.dev (YAML)
         if (options.withCodex || (options.autoMode && existsSync(join(projectRoot, '.codex')))) {
             const { createCodexInstaller } = await import('../codex-installer.js');
-            const installer = createCodexInstaller({ projectRoot, overwrite: shouldOverwrite, memoryBackend: options.memoryBackend === 'memory' ? 'memory' : undefined });
+            const installer = createCodexInstaller({
+                projectRoot,
+                overwrite: shouldOverwrite,
+                installMcp: !options.noMcp,
+                includeRuflo: options.withRuflo,
+                memoryBackend: options.memoryBackend === 'memory' ? 'memory' : undefined,
+            });
             const res = await installer.install();
             if (res.mcpConfigured)
                 platformsConfigured.push('codex');
@@ -307,6 +313,9 @@ export class AssetsPhase extends BasePhase {
                 context.services.log(`  Codex hooks: ${res.hooksPath}`);
             if (res.skillsInstalled > 0)
                 context.services.log(`  Codex skills: ${res.skillsInstalled} installed`);
+            context.services.log(options.withRuflo
+                ? '  Codex Ruflo integration: enabled'
+                : '  Codex Ruflo integration: not installed (opt in with --with-ruflo)');
         }
         if (options.withWindsurf || (options.autoMode && existsSync(join(projectRoot, '.windsurf')))) {
             const { createWindsurfInstaller } = await import('../windsurf-installer.js');

package/dist/init/phases/phase-interface.d.ts

@@ -121,6 +121,8 @@ export interface InitOptions {
     withRooCode?: boolean;
     /** Install OpenAI Codex CLI MCP, AGENTS.md, hooks, and QE skills */
     withCodex?: boolean;
+    /** Include optional Ruflo guidance and Codex lifecycle integration */
+    withRuflo?: boolean;
     /** Install Windsurf MCP config and rules */
     withWindsurf?: boolean;
     /** Install Continue.dev MCP config and rules */