agentic-workflow-manager 9.17.0 → 9.19.0

package/dist/tests/core/facts/catalog.test.js

@@ -0,0 +1,179 @@
+"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 types_1 = require("../../../src/core/facts/types");
+const catalog_1 = require("../../../src/core/facts/catalog");
+const validRepos = {
+    schemaVersion: 1,
+    facts: {
+        'repos.root': {
+            description: 'Local root for team clones',
+            valueType: 'path',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        },
+    },
+};
+describe('parseFactsCatalog (RF-1.1)', () => {
+    it('exports FACTS_MIN_CLI_VERSION as 9.18.0', () => {
+        expect(types_1.FACTS_MIN_CLI_VERSION).toBe('9.18.0');
+    });
+    it('parses a valid schemaVersion 1 catalog with path/prompt/durable/reference', () => {
+        const catalog = (0, catalog_1.parseFactsCatalog)(validRepos);
+        expect(catalog.schemaVersion).toBe(1);
+        expect(catalog.facts['repos.root']).toEqual({
+            description: 'Local root for team clones',
+            valueType: 'path',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        });
+    });
+    it('applies defaults durability durable, inject reference, resolution prompt', () => {
+        const catalog = (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: {
+                'aws.profile': { valueType: 'string' },
+            },
+        });
+        expect(catalog.facts['aws.profile']).toMatchObject({
+            valueType: 'string',
+            resolution: 'prompt',
+            durability: 'durable',
+            inject: 'reference',
+        });
+    });
+    it('accepts empty facts object', () => {
+        expect((0, catalog_1.parseFactsCatalog)({ schemaVersion: 1, facts: {} }).facts).toEqual({});
+    });
+    it('rejects bad schemaVersion with FactsCatalogError', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({ schemaVersion: 2, facts: {} })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({ schemaVersion: 2, facts: {} })).toThrow(/schemaVersion/);
+    });
+    it('rejects missing facts object with FactsCatalogError', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({ schemaVersion: 1 })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({ schemaVersion: 1 })).toThrow(/facts/);
+    });
+    it('rejects unknown valueType with FactsCatalogError', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'repos.root': { valueType: 'blob' } },
+        })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'repos.root': { valueType: 'blob' } },
+        })).toThrow(/valueType/);
+    });
+    it('rejects resolution: command with message containing those words and v1 (RF-3.3 catalog)', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: {
+                'repos.root': { valueType: 'path', resolution: 'command' },
+            },
+        })).toThrow(types_1.FactsCatalogError);
+        try {
+            (0, catalog_1.parseFactsCatalog)({
+                schemaVersion: 1,
+                facts: {
+                    'repos.root': { valueType: 'path', resolution: 'command' },
+                },
+            });
+            fail('expected throw');
+        }
+        catch (e) {
+            const msg = e.message;
+            expect(msg).toMatch(/resolution:\s*command/i);
+            expect(msg).toMatch(/v1/i);
+        }
+    });
+    it('rejects non-dotted fact ids', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { root: { valueType: 'path' } },
+        })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'Repos.Root': { valueType: 'path' } },
+        })).toThrow(types_1.FactsCatalogError);
+    });
+    it('parses from a file path', () => {
+        const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-facts-'));
+        try {
+            const file = path_1.default.join(dir, 'facts.json');
+            fs_1.default.writeFileSync(file, JSON.stringify(validRepos));
+            const catalog = (0, catalog_1.parseFactsCatalog)(file);
+            expect(catalog.facts['repos.root'].valueType).toBe('path');
+        }
+        finally {
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('rejects symlink facts.json (regular-file guard)', () => {
+        const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-facts-'));
+        try {
+            const real = path_1.default.join(dir, 'real-facts.json');
+            fs_1.default.writeFileSync(real, JSON.stringify(validRepos));
+            const link = path_1.default.join(dir, 'facts.json');
+            fs_1.default.symlinkSync(real, link);
+            expect(() => (0, catalog_1.parseFactsCatalog)(link)).toThrow(types_1.FactsCatalogError);
+            expect(() => (0, catalog_1.parseFactsCatalog)(link)).toThrow(/symbolic link|regular file/i);
+        }
+        finally {
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('requires enum values[] when valueType is enum', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'env.tier': { valueType: 'enum' } },
+        })).toThrow(types_1.FactsCatalogError);
+        const ok = (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'env.tier': { valueType: 'enum', values: ['dev', 'prod'] } },
+        });
+        expect(ok.facts['env.tier'].values).toEqual(['dev', 'prod']);
+    });
+    it('rejects volatile without finite ttl in (0, MAX] (RF-2.4 catalog)', () => {
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'aws.token': { valueType: 'string', durability: 'volatile' } },
+        })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'aws.token': { valueType: 'string', durability: 'volatile', ttl: 0 } },
+        })).toThrow(types_1.FactsCatalogError);
+        expect(() => (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: {
+                'aws.token': {
+                    valueType: 'string',
+                    durability: 'volatile',
+                    ttl: 365 * 24 * 3600 + 1,
+                },
+            },
+        })).toThrow(types_1.FactsCatalogError);
+        const ok = (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'aws.token': { valueType: 'string', durability: 'volatile', ttl: 60 } },
+        });
+        expect(ok.facts['aws.token'].ttl).toBe(60);
+    });
+    it('rejects invalid JSON file with named FactsCatalogError (RF-1.1)', () => {
+        const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-facts-bad-'));
+        try {
+            const file = path_1.default.join(dir, 'facts.json');
+            fs_1.default.writeFileSync(file, '{not-json');
+            expect(() => (0, catalog_1.parseFactsCatalog)(file)).toThrow(types_1.FactsCatalogError);
+            expect(() => (0, catalog_1.parseFactsCatalog)(file)).toThrow(/Invalid JSON/i);
+        }
+        finally {
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/core/facts/needs.test.js

@@ -0,0 +1,88 @@
+"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 catalog_1 = require("../../../src/core/facts/catalog");
+const needs_1 = require("../../../src/core/facts/needs");
+const types_1 = require("../../../src/core/facts/types");
+describe('readSkillNeeds / findOrphanNeeds (RF-1.2, RF-1.3, RF-1.4)', () => {
+    let tmp;
+    beforeEach(() => {
+        tmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-needs-'));
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmp, { recursive: true, force: true });
+    });
+    function writeSkill(body) {
+        const dir = path_1.default.join(tmp, 'skills', 'demo');
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        const skillPath = path_1.default.join(dir, 'SKILL.md');
+        fs_1.default.writeFileSync(skillPath, body);
+        return skillPath;
+    }
+    it('resolves needs: [repos.root] from frontmatter (RF-1.2)', () => {
+        const skillPath = writeSkill(`---
+name: demo
+description: d
+needs:
+  - repos.root
+---
+# Demo
+`);
+        expect((0, needs_1.readSkillNeeds)(skillPath)).toEqual(['repos.root']);
+    });
+    it('accepts flow-style needs list', () => {
+        const skillPath = writeSkill(`---
+name: demo
+description: d
+needs: [repos.root, aws.profile.dev]
+---
+# Demo
+`);
+        expect((0, needs_1.readSkillNeeds)(skillPath)).toEqual(['repos.root', 'aws.profile.dev']);
+    });
+    it('returns empty when needs omitted (RF-1.4)', () => {
+        const skillPath = writeSkill(`---
+name: demo
+description: d
+---
+# Demo
+`);
+        expect((0, needs_1.readSkillNeeds)(skillPath)).toEqual([]);
+    });
+    it('throws SkillNeedsError for invalid needs shape', () => {
+        const skillPath = writeSkill(`---
+name: demo
+description: d
+needs: repos.root
+---
+# Demo
+`);
+        expect(() => (0, needs_1.readSkillNeeds)(skillPath)).toThrow(types_1.SkillNeedsError);
+    });
+    it('lists unknown ids as orphans without inventing facts (RF-1.3)', () => {
+        const catalog = (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'repos.root': { valueType: 'path' } },
+        });
+        expect((0, needs_1.findOrphanNeeds)(['repos.root', 'ghost.fact'], catalog)).toEqual(['ghost.fact']);
+        expect((0, needs_1.findOrphanNeeds)(['repos.root'], catalog)).toEqual([]);
+        expect((0, needs_1.findOrphanNeeds)([], catalog)).toEqual([]);
+    });
+    it('treats Object.prototype keys as orphans (not catalog facts)', () => {
+        const catalog = (0, catalog_1.parseFactsCatalog)({
+            schemaVersion: 1,
+            facts: { 'repos.root': { valueType: 'path' } },
+        });
+        // `in` would match prototype; Object.hasOwn must not.
+        expect((0, needs_1.findOrphanNeeds)(['toString'], catalog)).toEqual(['toString']);
+        expect((0, needs_1.findOrphanNeeds)(['__proto__', 'constructor'], catalog)).toEqual([
+            '__proto__',
+            'constructor',
+        ]);
+    });
+});

package/dist/tests/structural/cloud-admission-docs-contract.test.js

@@ -0,0 +1,54 @@
+"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 path_1 = __importDefault(require("path"));
+/** CMD-DOCS — V-R4 (issue #215 documentation). */
+const repoRoot = path_1.default.resolve(__dirname, '../../..');
+/** Whitespace-normalized so re-wrapping the prose never breaks a pinned phrase. */
+const read = (relative) => fs_1.default.readFileSync(path_1.default.join(repoRoot, ...relative.split('/')), 'utf8').replace(/\s+/g, ' ');
+describe('issue #215 documentation contract (V-R4)', () => {
+    const configuration = read('docs/configuration.md');
+    it('documents .awm/admission.json with defaults, the git rule and the accepted risk', () => {
+        expect(configuration).toContain('## Read-only admission observation (`.awm/admission.json`)');
+        for (const name of ['node_modules', '.next', '.turbo', 'dist', 'build', 'coverage', '.venv', 'target'])
+            expect(configuration).toContain(`\`${name}\``);
+        expect(configuration).toContain('git-ignored and contains no tracked file');
+        expect(configuration).toContain('**Accepted risk:**');
+        expect(configuration).toContain('`admission-config-invalid`');
+        expect(configuration).toContain('`readOnlyObservation`');
+        expect(configuration).toContain('`awm plan admit` does not print it');
+    });
+    it.each([
+        '250000',
+        '1 GiB',
+        '`read-only-mutation-detected`',
+        '`read-only-observation-unavailable`',
+        '`not-ignored`',
+        '`contains-tracked`',
+        '`git-unavailable`',
+        '`.git` or `.awm`',
+        'never skipped',
+        'including any `.awm` or `.git` nested',
+        'regular file',
+        '65536 bytes',
+    ])('documents the observation limit, reason code or reserved-name rule %s', literal => {
+        expect(configuration).toContain(literal);
+    });
+    it('points --verify-sensors in the CLI reference at the observation rules', () => {
+        const doc = read('docs/cli-reference.md');
+        expect(doc).toContain('configuration.md#read-only-admission-observation-awmadmissionjson');
+        expect(doc).toContain('`ADMISSION_SENSORS_BLOCKED`');
+    });
+    it('states that the D-7 insteadOf recipe passes strict currentness', () => {
+        const doc = read('docs/operations/cloud-and-platforms.md');
+        expect(doc).toContain('`awm preflight --require-current`');
+        expect(doc).toContain('`remote.origin.url`');
+        expect(doc).toContain('--local');
+    });
+    it('describes the snapshot exclusions in the plan admit help', () => {
+        expect(read('cli/src/commands/plan/index.ts')).toContain("'require an empirical sensor pass; read-only observation skips git-ignored build output (see .awm/admission.json)'");
+    });
+});

package/dist/tests/structural/operator-environments-docs-contract.test.js

@@ -0,0 +1,70 @@
+"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 path_1 = __importDefault(require("path"));
+/**
+ * CMD-SCAFFOLD-DOCS — RF-5.2 operator-environments documentation contract.
+ * Asserts runbook + cli-reference document scaffold/doctor/env and state that
+ * awm-cenco-infra-registry migration is out of scope (RF-5.2).
+ */
+const repoRoot = path_1.default.resolve(__dirname, '../../..');
+const runbookPath = path_1.default.join(repoRoot, 'docs', 'runbook.md');
+const cliReferencePath = path_1.default.join(repoRoot, 'docs', 'cli-reference.md');
+const designPath = 'docs/plans/2026-10-12-operator-environments-design.md';
+function teamRegistriesSection(runbook) {
+    const start = runbook.indexOf('## Team registries');
+    expect(start).toBeGreaterThanOrEqual(0);
+    const rest = runbook.slice(start);
+    const nextH2 = rest.search(/\n## (?!Team)/);
+    return nextH2 === -1 ? rest : rest.slice(0, nextH2);
+}
+function registriesSection(cliRef) {
+    const start = cliRef.indexOf('## Registries & pinning');
+    expect(start).toBeGreaterThanOrEqual(0);
+    const rest = cliRef.slice(start);
+    const nextH2 = rest.search(/\n## (?!Registries)/);
+    return nextH2 === -1 ? rest : rest.slice(0, nextH2);
+}
+describe('operator-environments docs contract (RF-5.2)', () => {
+    it('runbook team-registries leads with scaffold and mentions doctor + design RF-5.2 out-of-scope', () => {
+        const runbook = fs_1.default.readFileSync(runbookPath, 'utf-8');
+        const section = teamRegistriesSection(runbook);
+        const scaffoldIdx = section.indexOf('awm registry scaffold');
+        const addIdx = section.indexOf('awm registry add');
+        expect(scaffoldIdx).toBeGreaterThanOrEqual(0);
+        expect(addIdx).toBeGreaterThan(scaffoldIdx);
+        expect(section).toContain('awm registry doctor');
+        // RF-5.2: Cenco infra registry is out of scope — require the out-of-scope
+        // phrase near the cenco mention (same paragraph/window), not a loose
+        // match elsewhere in the section.
+        expect(section).toMatch(/RF-5\.2/);
+        expect(section).toContain(designPath);
+        const cencoIdx = section.search(/awm-cenco-infra-registry/);
+        expect(cencoIdx).toBeGreaterThanOrEqual(0);
+        const windowStart = Math.max(0, cencoIdx - 120);
+        const windowEnd = Math.min(section.length, cencoIdx + 160);
+        const nearCenco = section.slice(windowStart, windowEnd);
+        expect(nearCenco).toMatch(/out of scope|out-of-scope|does not modify|SHALL NOT modify/i);
+    });
+    it('cli-reference documents registry scaffold, registry doctor, and awm env', () => {
+        const cliRef = fs_1.default.readFileSync(cliReferencePath, 'utf-8');
+        const registries = registriesSection(cliRef);
+        expect(registries).toMatch(/###\s+`awm registry scaffold/);
+        expect(registries).toMatch(/###\s+`awm registry doctor/);
+        // env lives as its own H2; require the three command strings in the file
+        // with scoped checks so headings cannot be satisfied by a stray mention.
+        expect(cliRef).toContain('awm registry scaffold');
+        expect(cliRef).toContain('awm registry doctor');
+        const envStart = cliRef.search(/^##\s+.*\benv\b/im);
+        expect(envStart).toBeGreaterThanOrEqual(0);
+        const envRest = cliRef.slice(envStart);
+        const envNext = envRest.search(/\n## /);
+        const envSection = envNext === -1 ? envRest : envRest.slice(0, envNext);
+        expect(envSection).toMatch(/awm env/);
+        expect(envSection).toMatch(/env set|`awm env set`/i);
+        expect(envSection).toMatch(/env status|`awm env status`/i);
+    });
+});

package/package.json

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