agentic-workflow-manager 9.17.0 → 9.18.0

package/dist/src/core/facts/catalog.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VOLATILE_TTL_SECONDS = void 0;
+exports.parseFactsCatalog = parseFactsCatalog;
+const fs_1 = __importDefault(require("fs"));
+const registries_1 = require("../registries");
+const types_1 = require("./types");
+const VALUE_TYPES = ['string', 'path', 'enum'];
+const RESOLUTIONS = ['prompt'];
+const DURABILITIES = ['durable', 'volatile'];
+const INJECTS = ['reference', 'context'];
+/** Max volatile ttl (seconds) so updatedMs + ttl*1000 stays in a safe Date range. */
+exports.MAX_VOLATILE_TTL_SECONDS = 365 * 24 * 3600;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseFactEntry(id, raw) {
+    if (!types_1.FACT_ID_RE.test(id)) {
+        throw new types_1.FactsCatalogError(`Invalid fact id ${JSON.stringify(id)}: must match ${types_1.FACT_ID_RE}`);
+    }
+    if (!isRecord(raw)) {
+        throw new types_1.FactsCatalogError(`facts.${id} must be an object`);
+    }
+    if (typeof raw.valueType !== 'string' || !VALUE_TYPES.includes(raw.valueType)) {
+        throw new types_1.FactsCatalogError(`facts.${id}.valueType must be one of ${VALUE_TYPES.join(', ')}`);
+    }
+    const valueType = raw.valueType;
+    if (raw.resolution === 'command') {
+        throw new types_1.FactsCatalogError(`facts.${id}: resolution: command is not supported in v1 (use prompt / --value / editable store)`);
+    }
+    if (raw.resolution !== undefined) {
+        if (typeof raw.resolution !== 'string' || !RESOLUTIONS.includes(raw.resolution)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.resolution must be "prompt" in v1`);
+        }
+    }
+    if (raw.durability !== undefined) {
+        if (typeof raw.durability !== 'string' || !DURABILITIES.includes(raw.durability)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.durability must be durable|volatile`);
+        }
+    }
+    if (raw.inject !== undefined) {
+        if (typeof raw.inject !== 'string' || !INJECTS.includes(raw.inject)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.inject must be reference|context`);
+        }
+    }
+    const def = {
+        valueType,
+        resolution: raw.resolution ?? 'prompt',
+        durability: raw.durability ?? 'durable',
+        inject: raw.inject ?? 'reference',
+    };
+    if (raw.description !== undefined) {
+        if (typeof raw.description !== 'string') {
+            throw new types_1.FactsCatalogError(`facts.${id}.description must be a string`);
+        }
+        def.description = raw.description;
+    }
+    if (valueType === 'enum') {
+        if (!Array.isArray(raw.values) || raw.values.length === 0 || raw.values.some((v) => typeof v !== 'string')) {
+            throw new types_1.FactsCatalogError(`facts.${id}.values must be a non-empty string array when valueType is enum`);
+        }
+        def.values = raw.values;
+    }
+    else if (raw.values !== undefined) {
+        throw new types_1.FactsCatalogError(`facts.${id}.values is only allowed when valueType is enum`);
+    }
+    if (raw.ttl !== undefined) {
+        if (typeof raw.ttl !== 'number' || !Number.isFinite(raw.ttl) || raw.ttl < 0) {
+            throw new types_1.FactsCatalogError(`facts.${id}.ttl must be a non-negative number`);
+        }
+        def.ttl = raw.ttl;
+    }
+    if (def.durability === 'volatile') {
+        if (typeof def.ttl !== 'number' ||
+            !Number.isFinite(def.ttl) ||
+            def.ttl <= 0 ||
+            def.ttl > exports.MAX_VOLATILE_TTL_SECONDS) {
+            throw new types_1.FactsCatalogError(`facts.${id}: durability volatile requires finite ttl in (0, ${exports.MAX_VOLATILE_TTL_SECONDS}] seconds`);
+        }
+    }
+    return def;
+}
+function parseObject(raw) {
+    if (!isRecord(raw)) {
+        throw new types_1.FactsCatalogError('facts catalog must be a JSON object');
+    }
+    if (raw.schemaVersion !== 1) {
+        throw new types_1.FactsCatalogError(`facts catalog schemaVersion must be 1, got ${JSON.stringify(raw.schemaVersion)}`);
+    }
+    if (!isRecord(raw.facts)) {
+        throw new types_1.FactsCatalogError('facts catalog must include a facts object');
+    }
+    const facts = {};
+    for (const [id, entry] of Object.entries(raw.facts)) {
+        if (id === '') {
+            throw new types_1.FactsCatalogError('fact id must be non-empty');
+        }
+        facts[id] = parseFactEntry(id, entry);
+    }
+    return { schemaVersion: 1, facts };
+}
+/**
+ * Parse a facts catalog from an in-memory object or from a file path string.
+ * Named errors: {@link FactsCatalogError}.
+ */
+function parseFactsCatalog(rawOrPath) {
+    if (typeof rawOrPath === 'string') {
+        try {
+            if (!(0, registries_1.assertRegularRegistryFile)(rawOrPath)) {
+                throw new types_1.FactsCatalogError(`facts catalog not found at ${rawOrPath}`);
+            }
+        }
+        catch (e) {
+            if (e instanceof types_1.FactsCatalogError)
+                throw e;
+            throw new types_1.FactsCatalogError(e instanceof Error ? e.message : `Cannot inspect facts catalog at ${rawOrPath}: ${String(e)}`);
+        }
+        let text;
+        try {
+            text = fs_1.default.readFileSync(rawOrPath, 'utf-8');
+        }
+        catch (e) {
+            throw new types_1.FactsCatalogError(`Cannot read facts catalog at ${rawOrPath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (e) {
+            throw new types_1.FactsCatalogError(`Invalid JSON in facts catalog at ${rawOrPath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return parseObject(parsed);
+    }
+    return parseObject(rawOrPath);
+}

package/dist/src/core/facts/needs.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillNeeds = readSkillNeeds;
+exports.findOrphanNeeds = findOrphanNeeds;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const frontmatter_1 = require("../frontmatter");
+const types_1 = require("./types");
+/**
+ * Read the `needs` list from a skill SKILL.md frontmatter.
+ * Absent → `[]`. Invalid shape → {@link SkillNeedsError}.
+ */
+function readSkillNeeds(skillMdPath) {
+    let raw;
+    try {
+        const stat = fs_1.default.lstatSync(skillMdPath);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new types_1.SkillNeedsError(`Skill path ${skillMdPath} must be a regular file`);
+        }
+        raw = fs_1.default.readFileSync(skillMdPath, 'utf-8');
+    }
+    catch (e) {
+        if (e instanceof types_1.SkillNeedsError)
+            throw e;
+        throw new types_1.SkillNeedsError(`Cannot read skill at ${skillMdPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const block = (0, frontmatter_1.matchFrontmatterBlock)(raw);
+    if (block === null)
+        return [];
+    let parsed;
+    try {
+        parsed = js_yaml_1.default.load(block);
+    }
+    catch (e) {
+        throw new types_1.SkillNeedsError(`Invalid skill frontmatter at ${skillMdPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return [];
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new types_1.SkillNeedsError(`Invalid skill frontmatter at ${skillMdPath}: expected a mapping`);
+    }
+    const needs = parsed.needs;
+    if (needs === undefined)
+        return [];
+    if (!Array.isArray(needs) || needs.some((n) => typeof n !== 'string' || n === '')) {
+        throw new types_1.SkillNeedsError(`Invalid needs at ${skillMdPath}: needs must be a YAML list of non-empty strings`);
+    }
+    return needs;
+}
+/** Ids in `needs` that are absent from the catalog (fail-closed; never invent). */
+function findOrphanNeeds(needs, catalog) {
+    // Own keys only — `in` would treat Object.prototype (toString, …) as catalog facts.
+    return needs.filter((id) => !Object.hasOwn(catalog.facts, id));
+}

package/dist/src/core/facts/types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillNeedsError = exports.FactsCatalogError = exports.FACT_ID_RE = exports.FACTS_MIN_CLI_VERSION = void 0;
+/** First CLI version that understands registry facts / needs. Bump only with intentional release. */
+exports.FACTS_MIN_CLI_VERSION = '9.18.0';
+/** Dotted fact ids: `repos.root`, `aws.profile.dev`. */
+exports.FACT_ID_RE = /^[a-z][a-z0-9]*(\.[a-z0-9]+)+$/;
+class FactsCatalogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FactsCatalogError';
+    }
+}
+exports.FactsCatalogError = FactsCatalogError;
+class SkillNeedsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SkillNeedsError';
+    }
+}
+exports.SkillNeedsError = SkillNeedsError;

package/dist/src/index.js

@@ -37,6 +37,7 @@ const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
 const registry_1 = require("./commands/registry");
+const env_1 = require("./commands/env");
 const pin_1 = require("./commands/pin");
 const export_1 = require("./commands/export");
 const agent_1 = require("./commands/agent");
@@ -743,6 +744,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, backup_1.registerBackupCommand)(exports.program);
 (0, init_1.registerInitCommand)(exports.program);
 (0, registry_1.registerRegistryCommand)(exports.program);
+(0, env_1.registerEnvCommand)(exports.program);
 (0, pin_1.registerPinCommands)(exports.program);
 (0, export_1.registerExportCommand)(exports.program);
 (0, agent_1.registerAgentCommand)(exports.program);

package/dist/tests/commands/env/index.test.js

@@ -0,0 +1,261 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const env_1 = require("../../../src/commands/env");
+const store_1 = require("../../../src/core/environments/store");
+const catalog = {
+    schemaVersion: 1,
+    facts: {
+        'repos.root': {
+            valueType: 'path',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        },
+        'aws.profile': {
+            valueType: 'string',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        },
+        'env.kind': {
+            valueType: 'enum',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+            values: ['dev', 'prod'],
+        },
+        'aws.token': {
+            valueType: 'string',
+            resolution: 'prompt',
+            durability: 'volatile',
+            inject: 'reference',
+            ttl: 1,
+        },
+    },
+};
+function isolateHome() {
+    const tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-env-cmd-'));
+    process.env.AWM_HOME = path_1.default.join(tmp, '.awm');
+    process.env.HOME = tmp;
+    return tmp;
+}
+async function run(argv, loadCatalog = () => catalog, extraDeps = {}) {
+    const prog = new commander_1.Command();
+    prog.exitOverride();
+    prog.configureOutput({ writeErr: () => undefined });
+    (0, env_1.registerEnvCommand)(prog, {
+        loadCatalog,
+        consultedRoots: () => ['/tmp/test-registry'],
+        stdinIsTTY: () => false,
+        ...extraDeps,
+    });
+    const outSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    const errSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+        await prog.parseAsync(['node', 'awm', 'env', ...argv]);
+    }
+    finally {
+        // keep spies until we collect
+    }
+    const out = outSpy.mock.calls.map((c) => String(c[0])).join('') +
+        logSpy.mock.calls.map((c) => c.map(String).join(' ')).join('\n');
+    const err = errSpy.mock.calls.map((c) => String(c[0])).join('') +
+        errorSpy.mock.calls.map((c) => c.map(String).join(' ')).join('\n');
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+    return { out, err };
+}
+describe('awm env commands (RF-2, RF-3.3)', () => {
+    let tmp;
+    let prevHome;
+    let prevAwm;
+    beforeEach(() => {
+        prevHome = process.env.HOME;
+        prevAwm = process.env.AWM_HOME;
+        tmp = isolateHome();
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+        if (prevHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prevHome;
+        if (prevAwm === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = prevAwm;
+    });
+    it('set --value writes under environments/default/values.json without shelling out (RF-2.1, RF-3.3)', async () => {
+        const spawn = jest.spyOn(require('child_process'), 'spawnSync');
+        const execFile = jest.spyOn(require('child_process'), 'execFileSync');
+        await run(['set', 'repos.root', '--value', '/machine/repos']);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/machine/repos');
+        expect(fs_1.default.existsSync((0, store_1.valuesPath)('default'))).toBe(true);
+        expect((0, store_1.valuesPath)('default')).toContain(path_1.default.join('.awm', 'environments', 'default', 'values.json'));
+        expect(spawn).not.toHaveBeenCalled();
+        expect(execFile).not.toHaveBeenCalled();
+        spawn.mockRestore();
+        execFile.mockRestore();
+    });
+    it('status reports missing for unset facts and fresh after set (RF-2.5)', async () => {
+        let { out } = await run(['status']);
+        expect(out).toMatch(/repos\.root:\s*missing/);
+        expect(out).toMatch(/aws\.profile:\s*missing/);
+        await run(['set', 'repos.root', '--value', '/r']);
+        ({ out } = await run(['status']));
+        expect(out).toMatch(/repos\.root:\s*fresh/);
+        // Unset sibling stays missing — no silent default invent for other ids.
+        expect(out).toMatch(/aws\.profile:\s*missing/);
+        expect(out).not.toMatch(/aws\.profile:\s*fresh/);
+    });
+    it('status reports stale for expired volatile fact (RF-2.5)', async () => {
+        (0, store_1.writeFact)('default', 'aws.token', {
+            value: 'tok',
+            status: 'fresh',
+            updatedAt: '2026-10-12T00:00:00.000Z',
+        }, { definition: catalog.facts['aws.token'] });
+        const { out } = await run(['status'], () => catalog, {
+            now: () => new Date('2026-10-12T00:00:02.000Z'),
+        });
+        expect(out).toMatch(/aws\.token:\s*stale/);
+    });
+    it('edit prints absolute store path', async () => {
+        const { out } = await run(['edit']);
+        expect(out).toContain((0, store_1.valuesPath)((0, store_1.getActiveEnvironmentName)()));
+        expect(path_1.default.isAbsolute(out.trim().split(/\s+/).find((t) => t.includes('values.json')) || (0, store_1.valuesPath)('default'))).toBe(true);
+    });
+    it('refresh --value updates an existing fact without shell (RF-3.3)', async () => {
+        await run(['set', 'aws.profile', '--value', 'old']);
+        await run(['refresh', 'aws.profile', '--value', 'new-profile']);
+        expect((0, store_1.readValues)('default')['aws.profile'].value).toBe('new-profile');
+    });
+    it('refresh without --value in non-interactive mode errors', async () => {
+        await run(['set', 'aws.profile', '--value', 'old']);
+        await expect(run(['refresh', 'aws.profile'])).rejects.toThrow(/--value|value/i);
+    });
+    it('use switches active environment (RF-2.2)', async () => {
+        await run(['use', 'staging']);
+        expect((0, store_1.getActiveEnvironmentName)()).toBe('staging');
+        await run(['set', 'repos.root', '--value', '/staging/repos']);
+        expect((0, store_1.valuesPath)('staging')).toContain(`${path_1.default.sep}staging${path_1.default.sep}values.json`);
+        expect((0, store_1.readValues)('staging')['repos.root'].value).toBe('/staging/repos');
+    });
+    it('set unknown id errors listing consulted roots', async () => {
+        await expect(run(['set', 'no.such.fact', '--value', 'x'])).rejects.toThrow(/no\.such\.fact/);
+        await expect(run(['set', 'no.such.fact', '--value', 'x'])).rejects.toThrow(/test-registry/);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set rejects empty path and leaves store unchanged', async () => {
+        await expect(run(['set', 'repos.root', '--value', ''])).rejects.toThrow(/path|empty|value/i);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set rejects invalid enum value', async () => {
+        await expect(run(['set', 'env.kind', '--value', 'qa'])).rejects.toThrow(/enum|dev|prod/i);
+        expect((0, store_1.readValues)('default')).toEqual({});
+    });
+    it('set never imports child_process for resolution (RF-3.3)', () => {
+        const src = fs_1.default.readFileSync(path_1.default.join(__dirname, '../../../src/commands/env/index.ts'), 'utf-8');
+        expect(src).not.toMatch(/child_process/);
+        expect(src).not.toMatch(/\bexecSync\b|\bspawnSync\b|\bexecFileSync\b/);
+    });
+    it('set without --value on TTY uses promptFn (RF-3.3)', async () => {
+        const prompts = [];
+        await run(['set', 'repos.root'], () => catalog, {
+            stdinIsTTY: () => true,
+            promptValue: (q) => {
+                prompts.push(q);
+                return '/prompted/repos';
+            },
+        });
+        expect(prompts.length).toBeGreaterThanOrEqual(1);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/prompted/repos');
+    });
+    it('set without --value when not TTY keeps requireValue error (RF-3.3)', async () => {
+        await expect(run(['set', 'repos.root'], () => catalog, { stdinIsTTY: () => false })).rejects.toThrow(/--value|value/i);
+    });
+    it('refresh --all on TTY prompts each store id via promptFn', async () => {
+        await run(['set', 'repos.root', '--value', '/old']);
+        await run(['set', 'aws.profile', '--value', 'old-profile']);
+        const seen = [];
+        const answers = {
+            'repos.root': '/new',
+            'aws.profile': 'new-profile',
+        };
+        await run(['refresh', '--all'], () => catalog, {
+            stdinIsTTY: () => true,
+            promptValue: (q) => {
+                const id = Object.keys(answers).find((k) => q.includes(k));
+                if (!id)
+                    throw new Error(`unexpected prompt: ${q}`);
+                seen.push(id);
+                return answers[id];
+            },
+        });
+        expect(seen.sort()).toEqual(['aws.profile', 'repos.root']);
+        expect((0, store_1.readValues)('default')['repos.root'].value).toBe('/new');
+        expect((0, store_1.readValues)('default')['aws.profile'].value).toBe('new-profile');
+    });
+    it('refresh --all when not TTY keeps clear error', async () => {
+        await run(['set', 'repos.root', '--value', '/old']);
+        await expect(run(['refresh', '--all'], () => catalog, { stdinIsTTY: () => false })).rejects.toThrow(/--all|interactive|factId|--value|TTY/i);
+    });
+    it('inject prints buildInjection JSON (default reference)', async () => {
+        await run(['set', 'repos.root', '--value', '/r']);
+        const { out } = await run(['inject']);
+        const parsed = JSON.parse(out.trim());
+        expect(parsed.mode).toBe('reference');
+        expect(parsed.storePath).toContain('values.json');
+        expect(parsed.factIds).toEqual(expect.arrayContaining(['repos.root']));
+        expect(parsed.values).toBeUndefined();
+    });
+    it('inject --mode context includes fresh context values when catalog allows', async () => {
+        const contextCatalog = {
+            schemaVersion: 1,
+            facts: {
+                'team.color': {
+                    valueType: 'string',
+                    resolution: 'prompt',
+                    durability: 'durable',
+                    inject: 'context',
+                },
+            },
+        };
+        await run(['set', 'team.color', '--value', 'blue'], () => contextCatalog);
+        const { out } = await run(['inject', '--mode', 'context'], () => contextCatalog);
+        const parsed = JSON.parse(out.trim());
+        expect(parsed.mode).toBe('context');
+        expect(parsed.values).toEqual({ 'team.color': 'blue' });
+    });
+    it('mergeFactDefinitions refuses to weaken volatile → durable (secret revive)', () => {
+        const into = {
+            'aws.token': {
+                valueType: 'string',
+                resolution: 'prompt',
+                durability: 'volatile',
+                inject: 'context',
+                ttl: 60,
+            },
+        };
+        (0, env_1.mergeFactDefinitions)(into, {
+            'aws.token': {
+                valueType: 'string',
+                resolution: 'prompt',
+                durability: 'durable',
+                inject: 'context',
+            },
+        });
+        expect(into['aws.token'].durability).toBe('volatile');
+        expect(into['aws.token'].ttl).toBe(60);
+    });
+});