agentic-workflow-manager 5.0.2 → 6.0.0

package/dist/src/core/paths.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WINDOWS_KNOWN_GAP = void 0;
 exports.homeDir = homeDir;
 exports.awmHome = awmHome;
+exports.providerConfigHome = providerConfigHome;
 exports.platform = platform;
 exports.isWindowsNative = isWindowsNative;
 exports.platformLabel = platformLabel;
@@ -27,6 +28,25 @@ function homeDir() {
 function awmHome() {
     return process.env.AWM_HOME || path_1.default.join(homeDir(), '.awm');
 }
+/**
+ * Raiz de configuracion de un agente, honrando SU propia variable de entorno.
+ *
+ * AWM honra `AWM_HOME` para si mismo (ver `awmHome` arriba) y durante mucho tiempo le
+ * nego esa misma cortesia a todos los agentes que administra: cada ruta de proveedor se
+ * armaba desde `homeDir()` y punto. En una maquina con `CODEX_HOME` apuntando a otro
+ * lado, AWM escribia el hook en `~/.codex/hooks.json` y Codex lo leia desde
+ * `$CODEX_HOME/hooks.json` — instalacion correcta, en el archivo que nadie mira. El hook
+ * quedaba instalado y mudo, y `doctor` lo reportaba presente porque miraba el mismo
+ * lugar equivocado donde lo habia escrito.
+ *
+ * `envVar` en `null` significa "este proveedor no declara override conocido": se usa el
+ * default y listo. No se inventan variables — una que no exista de verdad seria peor que
+ * ninguna, porque prometeria una configurabilidad que no funciona.
+ */
+function providerConfigHome(envVar, defaultDir) {
+    const override = envVar ? process.env[envVar]?.trim() : undefined;
+    return override || path_1.default.join(homeDir(), defaultDir);
+}
 /** Raw platform string (wrapper over process.platform for testability). */
 function platform() {
     return process.platform;

package/dist/src/providers/index.js

@@ -45,19 +45,42 @@ function unsupportedScopeError(artifactType, scope, providerLabel, reason) {
     return new Error(`${artifactType} ${scope} scope is not supported by ${providerLabel}` +
         (reason ? `: ${reason}` : '.'));
 }
+/** El override declarado por cada agente. Una sola tabla: agregar un proveedor o
+ *  descubrir la variable de otro es una edicion de UNA linea, y el guard estructural
+ *  `provider-paths-honor-config-home` verifica que TODAS sus rutas la respeten. */
+const CONFIG_HOME = {
+    // Confirmada contra el binario real: Codex 0.146.0 lee `$CODEX_HOME/hooks.json`.
+    // Una corrida del playbook en una maquina con CODEX_HOME seteado encontro el hook
+    // instalado donde Codex no mira. Ver docs/decisions.md D-011.
+    codex: { envVar: 'CODEX_HOME', dir: '.codex' },
+    // Los demas usan su directorio por defecto. `null` es una afirmacion honesta —
+    // "no le conocemos override"— y no un "no tiene". Cuando se confirme uno contra su
+    // binario, se cambia aca y el guard obliga a que todas sus rutas lo sigan.
+    'claude-code': { envVar: null, dir: '.claude' },
+    opencode: { envVar: null, dir: '.config/opencode' },
+    cursor: { envVar: null, dir: '.cursor' },
+    copilot: { envVar: null, dir: '.github' },
+    antigravity: { envVar: null, dir: '.gemini/antigravity' },
+};
+function configHomeFor(agent) {
+    const declared = CONFIG_HOME[agent];
+    return { ...declared, resolved: (0, paths_1.providerConfigHome)(declared.envVar, declared.dir) };
+}
 function providers() {
     const home = (0, paths_1.homeDir)();
     const awm = (0, paths_1.awmHome)();
+    const root = (agent) => configHomeFor(agent).resolved;
     return {
         antigravity: {
             label: 'Antigravity',
+            configHome: configHomeFor('antigravity'),
             skill: {
-                global: path_1.default.join(home, '.gemini/antigravity/skills'),
+                global: path_1.default.join(root('antigravity'), 'skills'),
                 local: '.agent/skills',
                 renderer: 'link',
             },
             workflow: {
-                global: path_1.default.join(home, '.gemini/antigravity/global_workflows'),
+                global: path_1.default.join(root('antigravity'), 'global_workflows'),
                 local: '.agent/workflows',
                 renderer: 'link',
             },
@@ -65,6 +88,7 @@ function providers() {
         },
         opencode: {
             label: 'OpenCode',
+            configHome: configHomeFor('opencode'),
             skill: {
                 global: path_1.default.join(home, '.agents/skills'),
                 local: '.agents/skills',
@@ -72,32 +96,33 @@ function providers() {
             },
             workflow: null,
             agent: {
-                global: path_1.default.join(home, '.config/opencode/agents'),
+                global: path_1.default.join(root('opencode'), 'agents'),
                 local: '.agents/profiles',
                 renderer: 'link',
             },
             injection: {
                 type: 'config-instructions',
-                configPath: path_1.default.join(home, '.config/opencode/opencode.json'),
+                configPath: path_1.default.join(root('opencode'), 'opencode.json'),
                 field: 'instructions',
             },
         },
         'claude-code': {
             label: 'Claude Code',
+            configHome: configHomeFor('claude-code'),
             skill: {
-                global: path_1.default.join(home, '.claude/skills'),
+                global: path_1.default.join(root('claude-code'), 'skills'),
                 local: '.claude/skills',
                 renderer: 'link',
             },
             workflow: null,
             agent: {
-                global: path_1.default.join(home, '.claude/agents'),
+                global: path_1.default.join(root('claude-code'), 'agents'),
                 local: '.claude/agents',
                 renderer: 'link',
             },
             hooks: {
                 type: 'cc-settings-merge',
-                settingsPath: path_1.default.join(home, '.claude/settings.json'),
+                settingsPath: path_1.default.join(root('claude-code'), 'settings.json'),
                 scriptsDir: path_1.default.join(awm, 'hooks'),
                 matcher: 'startup|clear|compact',
                 eventName: 'SessionStart',
@@ -106,6 +131,7 @@ function providers() {
         },
         codex: {
             label: 'Codex',
+            configHome: configHomeFor('codex'),
             minimumVersion: '0.145.0',
             versionCommand: { command: 'codex', args: ['--version'], versionPattern: /^codex-cli (\d+\.\d+\.\d+)$/ },
             skill: {
@@ -115,27 +141,28 @@ function providers() {
             },
             workflow: null,
             agent: {
-                global: path_1.default.join(home, '.codex/agents'),
+                global: path_1.default.join(root('codex'), 'agents'),
                 local: '.codex/agents',
                 renderer: 'codex-agent-toml',
             },
             hooks: {
                 type: 'codex-hooks-json',
-                settingsPath: path_1.default.join(home, '.codex/hooks.json'),
+                settingsPath: path_1.default.join(root('codex'), 'hooks.json'),
                 scriptsDir: path_1.default.join(awm, 'hooks/codex'),
                 matcher: 'startup|resume|clear|compact',
                 eventName: 'SessionStart',
             },
             injection: {
                 type: 'managed-agents-md',
-                globalPath: path_1.default.join(home, '.codex/AGENTS.md'),
+                globalPath: path_1.default.join(root('codex'), 'AGENTS.md'),
                 localFile: 'AGENTS.md',
             },
         },
         cursor: {
             label: 'Cursor',
+            configHome: configHomeFor('cursor'),
             skill: {
-                global: path_1.default.join(home, '.cursor/rules'),
+                global: path_1.default.join(root('cursor'), 'rules'),
                 local: '.cursor/rules',
                 renderer: 'cursor-mdc',
             },
@@ -153,6 +180,7 @@ function providers() {
         },
         copilot: {
             label: 'Copilot',
+            configHome: configHomeFor('copilot'),
             skill: {
                 global: null,
                 globalUnsupportedReason: 'GitHub Copilot has no user-level skill discovery mechanism — skills must be installed per-project.',

package/dist/tests/core/context/orchestrator.test.js

@@ -26,7 +26,7 @@ function tmpRegistry() {
 }
 describe('InjectionOrchestrator (claude-code dispatch via HookMergeStrategy)', () => {
     const ccOverride = {
-        label: 'Claude Code', skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
+        label: 'Claude Code', configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
         injection: { type: 'cc-settings-merge' },
         hooks: { type: 'cc-settings-merge', settingsPath: '', scriptsDir: '', matcher: '', eventName: '' },
     };
@@ -64,7 +64,7 @@ describe('InjectionOrchestrator (claude-code dispatch via HookMergeStrategy)', (
     it('throws when providerOverride has no injection (does not fall through to real agent config)', () => {
         const noInjection = {
             label: 'Test',
-            skill: { global: '', local: '', renderer: 'link' },
+            configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' },
             workflow: null,
             agent: null,
         };
@@ -85,7 +85,7 @@ describe('InjectionOrchestrator (opencode, real strategy)', () => {
         registryRoot = tmpRegistry();
         orch = new orchestrator_1.InjectionOrchestrator({
             providerOverride: {
-                label: 'OpenCode', skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
+                label: 'OpenCode', configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
                 injection: { type: 'config-instructions', configPath, field: 'instructions' },
             },
             contextPathOverride: absPath,
@@ -150,7 +150,7 @@ describe('InjectionOrchestrator (codex, managed AGENTS.md strategy)', () => {
         fs_1.default.writeFileSync(agentsPath, '# User rules\n');
         const orch = new orchestrator_1.InjectionOrchestrator({
             providerOverride: {
-                label: 'Codex', skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
+                label: 'Codex', configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
                 injection: { type: 'managed-agents-md', globalPath: agentsPath, localFile: 'AGENTS.md' },
             },
             contextPathOverride: contextPath,
@@ -202,7 +202,7 @@ describe('InjectionOrchestrator (local scope materializes under the project, not
     it('materializes to projectContextPath(projectRoot) for scope local, never to globalContextPath()', () => {
         const orch = new orchestrator_1.InjectionOrchestrator({
             providerOverride: {
-                label: 'Copilot', skill: { global: null, local: '.github/instructions', renderer: 'link' }, workflow: null, agent: null,
+                label: 'Copilot', configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: null, local: '.github/instructions', renderer: 'link' }, workflow: null, agent: null,
                 injection: { type: 'managed-agents-md', globalPath: null, localFile: 'AGENTS.md' },
             },
         });

package/dist/tests/core/context/strategies/codex-agents.test.js

@@ -287,7 +287,7 @@ describe('CodexAgentsStrategy', () => {
 function codexProvider(globalPath) {
     return {
         label: 'Codex',
-        skill: { global: '', local: '', renderer: 'link' },
+        configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' },
         workflow: null,
         agent: null,
         injection: { type: 'managed-agents-md', globalPath, localFile: 'AGENTS.md' },
@@ -296,7 +296,7 @@ function codexProvider(globalPath) {
 function copilotProvider() {
     return {
         label: 'Copilot',
-        skill: { global: null, local: '.github/instructions', renderer: 'link' },
+        configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: null, local: '.github/instructions', renderer: 'link' },
         workflow: null,
         agent: null,
         injection: { type: 'managed-agents-md', globalPath: null, localFile: 'AGENTS.md' },
@@ -305,7 +305,7 @@ function copilotProvider() {
 function cursorProvider() {
     return {
         label: 'Cursor',
-        skill: { global: '', local: '.cursor/rules', renderer: 'link' },
+        configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '.cursor/rules', renderer: 'link' },
         workflow: null,
         agent: null,
         injection: { type: 'managed-agents-md', globalPath: null, localFile: 'AGENTS.md' },

package/dist/tests/core/context/strategies/config-instructions.test.js

@@ -18,7 +18,7 @@ function setup(opencodeJson) {
     fs_1.default.mkdirSync(path_1.default.dirname(absPath), { recursive: true });
     fs_1.default.writeFileSync(absPath, 'CTX');
     const provider = {
-        label: 'OpenCode', skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
+        label: 'OpenCode', configHome: { envVar: null, dir: '.test', resolved: '/tmp/test-config-home' }, skill: { global: '', local: '', renderer: 'link' }, workflow: null, agent: null,
         injection: { type: 'config-instructions', configPath, field: 'instructions' },
     };
     const input = {

package/dist/tests/providers/index.test.js

@@ -55,6 +55,8 @@ describe('Providers Routing', () => {
     it('declares the complete Codex capability metadata', () => {
         expect((0, providers_1.providerFor)('codex')).toEqual({
             label: 'Codex',
+            // El unico proveedor con override confirmado contra su binario real (D-011).
+            configHome: { envVar: 'CODEX_HOME', dir: '.codex', resolved: path_1.default.join(tmpHome, '.codex') },
             minimumVersion: '0.145.0',
             versionCommand: { command: 'codex', args: ['--version'], versionPattern: /^codex-cli (\d+\.\d+\.\d+)$/ },
             skill: {
@@ -86,6 +88,7 @@ describe('Providers Routing', () => {
         const graph = (0, providers_1.providers)();
         expect(graph.antigravity).toEqual({
             label: 'Antigravity',
+            configHome: { envVar: null, dir: '.gemini/antigravity', resolved: path_1.default.join(tmpHome, '.gemini/antigravity') },
             skill: {
                 global: path_1.default.join(tmpHome, '.gemini/antigravity/skills'),
                 local: '.agent/skills',
@@ -100,6 +103,7 @@ describe('Providers Routing', () => {
         });
         expect(graph.opencode).toEqual({
             label: 'OpenCode',
+            configHome: { envVar: null, dir: '.config/opencode', resolved: path_1.default.join(tmpHome, '.config/opencode') },
             skill: {
                 global: path_1.default.join(tmpHome, '.agents/skills'),
                 local: '.agents/skills',
@@ -119,6 +123,7 @@ describe('Providers Routing', () => {
         });
         expect(graph['claude-code']).toEqual({
             label: 'Claude Code',
+            configHome: { envVar: null, dir: '.claude', resolved: path_1.default.join(tmpHome, '.claude') },
             skill: {
                 global: path_1.default.join(tmpHome, '.claude/skills'),
                 local: '.claude/skills',

package/dist/tests/structural/provider-paths-honor-config-home.test.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Un proveedor que declara override de home tiene que respetarlo en TODAS sus rutas.
+//
+// El caso que lo motivo: en una maquina con `CODEX_HOME` apuntando fuera del home, AWM
+// instalaba el hook en `~/.codex/hooks.json` mientras Codex leia
+// `$CODEX_HOME/hooks.json`. Instalacion correcta, en el archivo que nadie mira — el hook
+// quedaba mudo, y `doctor` lo reportaba presente porque miraba el mismo lugar equivocado
+// donde lo habia escrito. Tres rutas afectadas (`hooks.json`, `agents/`, `AGENTS.md`), y
+// arreglar una o dos habria dejado el bug vivo en la tercera.
+//
+// Por eso el guard es una PROPIEDAD sobre la tabla entera y no una lista de rutas: no se
+// puede satisfacer arreglando un sitio, y un proveedor nuevo lo hereda sin que nadie se
+// acuerde de agregarlo. Ver docs/decisions.md D-011.
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../../src/providers");
+/** Toda ruta absoluta que la config de un proveedor declara, con su nombre de campo. */
+function absolutePaths(config) {
+    const out = [];
+    const push = (field, value) => {
+        if (typeof value === 'string' && path_1.default.isAbsolute(value))
+            out.push({ field, value });
+    };
+    push('skill.global', config.skill.global);
+    push('workflow.global', config.workflow?.global);
+    push('agent.global', config.agent?.global);
+    push('hooks.settingsPath', config.hooks?.settingsPath);
+    if (config.injection?.type === 'config-instructions')
+        push('injection.configPath', config.injection.configPath);
+    if (config.injection?.type === 'managed-agents-md')
+        push('injection.globalPath', config.injection.globalPath);
+    return out;
+}
+/** Vuelve a pedir la tabla con `env` aplicado. `providers()` la reconstruye en cada
+ *  llamada leyendo el entorno, asi que no hace falta resetear modulos. */
+function providersWith(env) {
+    const previous = {};
+    for (const [k, v] of Object.entries(env)) {
+        previous[k] = process.env[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+    try {
+        return (0, providers_1.providers)();
+    }
+    finally {
+        for (const [k, v] of Object.entries(previous)) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+    }
+}
+const HOME = path_1.default.join(path_1.default.sep, 'tmp', 'awm-guard-home');
+const ELSEWHERE = path_1.default.join(path_1.default.sep, 'tmp', 'awm-guard-elsewhere');
+describe('a provider that declares a config-home override honors it everywhere', () => {
+    for (const agent of providers_1.AGENT_TARGETS) {
+        const declared = providersWith({ HOME })[agent].configHome;
+        if (!declared.envVar)
+            continue;
+        it(`${agent}: setting ${declared.envVar} moves every path that lives under its own dir`, () => {
+            const base = providersWith({ HOME, [declared.envVar]: undefined })[agent];
+            const moved = providersWith({ HOME, [declared.envVar]: ELSEWHERE })[agent];
+            const defaultRoot = path_1.default.join(HOME, declared.dir);
+            const under = absolutePaths(base).filter((p) => p.value.startsWith(defaultRoot));
+            // Si esto diera 0, el test pasaria sin verificar nada — y ese es exactamente
+            // el modo de falla que hace inutil a un guard.
+            expect(under.length).toBeGreaterThan(0);
+            const movedByField = new Map(absolutePaths(moved).map((p) => [p.field, p.value]));
+            const stragglers = under.filter((p) => !movedByField.get(p.field)?.startsWith(ELSEWHERE));
+            expect(stragglers.map((p) => `${p.field} = ${movedByField.get(p.field)}`)).toEqual([]);
+        });
+        it(`${agent}: an empty or blank ${declared.envVar} falls back to the default, it does not resolve to nothing`, () => {
+            // Una variable exportada vacia es comun en scripts (`export CODEX_HOME=`) y
+            // tomarla al pie de la letra dejaria las rutas colgando de la raiz.
+            for (const blank of ['', '   ']) {
+                const cfg = providersWith({ HOME, [declared.envVar]: blank })[agent];
+                expect(cfg.configHome.resolved).toBe(path_1.default.join(HOME, declared.dir));
+            }
+        });
+    }
+    it('shared, cross-agent conventions are NOT moved by one agent’s override', () => {
+        // `~/.agents/skills` lo comparten Codex y OpenCode: es del ecosistema, no de un
+        // agente. Moverlo con CODEX_HOME desconectaria a OpenCode de sus propias skills.
+        const moved = providersWith({ HOME, CODEX_HOME: ELSEWHERE });
+        expect(moved.codex.skill.global).toBe(path_1.default.join(HOME, '.agents/skills'));
+        expect(moved.opencode.skill.global).toBe(path_1.default.join(HOME, '.agents/skills'));
+    });
+    it('every agent declares a config home, so a new provider cannot skip the question', () => {
+        const table = providersWith({ HOME });
+        for (const agent of providers_1.AGENT_TARGETS) {
+            expect(typeof table[agent].configHome.dir).toBe('string');
+            expect(table[agent].configHome.dir.length).toBeGreaterThan(0);
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "5.0.2",
+  "version": "6.0.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"