@openwop/openwop-conformance 1.18.1 → 1.20.0

package/dist/cli.js

@@ -11,6 +11,7 @@
  *   openwop-conformance --offline                       # server-free subset only
  *   openwop-conformance --filter discovery               # category filter
  *   openwop-conformance --base-url ... --api-key ... --filter "interrupt|cancellation"
+ *   openwop-conformance --base-url ... --api-key ... --certify out.json   # RFC 0089 bundle
  *
  * Environment variables override flags (per the conformance harness's
  * existing convention):
@@ -24,7 +25,14 @@
  */
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve as resolvePath } from 'node:path';
+import { dirname, resolve as resolvePath, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from './lib/paths.js';
+import { deriveProfiles, isCoreStandard, agentPlatformStatus, } from './lib/profiles.js';
 function parseArgs(argv) {
     let baseUrl;
     let apiKey;
@@ -33,6 +41,7 @@ function parseArgs(argv) {
     let help = false;
     let impl;
     let implVersion;
+    let certify;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i] ?? '';
         if (arg === '-h' || arg === '--help') {
@@ -74,13 +83,16 @@ function parseArgs(argv) {
             case '--implementation-version':
                 implVersion = nextValue();
                 break;
+            case '--certify':
+                certify = nextValue();
+                break;
             default:
                 if (arg.startsWith('-')) {
                     // Unknown flag — pass through to vitest by ignoring here.
                 }
         }
     }
-    return { baseUrl, apiKey, offline, filter, help, impl, implVersion };
+    return { baseUrl, apiKey, offline, filter, help, impl, implVersion, certify };
 }
 const HELP_TEXT = `openwop-conformance — run the openwop conformance suite against a server
 
@@ -99,6 +111,14 @@ Implementation labels (cosmetic — surface in failure messages):
   --impl <name>             Implementation name        (env: OPENWOP_IMPLEMENTATION_NAME)
   --impl-version <version>  Implementation version     (env: OPENWOP_IMPLEMENTATION_VERSION)
 
+Certification (RFC 0089):
+  --certify <out.json>  Generate a machine-readable conformance certification
+                        bundle: fetch /.well-known/openwop (captured verbatim +
+                        SHA-256), derive claimedProfiles from it, run the suite
+                        recording each scenario's terminal state, validate the
+                        assembled bundle against the bundle schema, and write it
+                        to <out.json>. Requires --base-url (and --api-key as usual).
+
 Other:
   --help, -h            Show this message
 
@@ -106,8 +126,210 @@ Examples:
   openwop-conformance --offline
   openwop-conformance --base-url https://api.example.com --api-key hk_test_abc
   openwop-conformance --filter "discovery|errors"
+  openwop-conformance --base-url https://api.example.com --api-key hk_test_abc \\
+    --certify certification-bundle.json
 `;
-function main() {
+/** This CLI package's own version — surfaced as `generator.version` + `suite.version`. */
+function suiteVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = resolvePath(here, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+}
+/**
+ * Deterministic canonical-JSON serialization (RFC 8785 spirit): object keys
+ * sorted lexicographically at every level, arrays preserved in order. Used to
+ * compute `discovery.sha256` so a verifier can re-derive the same digest from
+ * a live `/.well-known/openwop` fetch regardless of incidental key order.
+ */
+function canonicalJSON(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJSON).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJSON(obj[k])}`).join(',')}}`;
+}
+/**
+ * The full set of profiles a discovery document derives — the closed
+ * `deriveProfiles` catalog plus the two operational annexes
+ * (`openwop-core-standard`, `openwop-agent-platform`) when their discovery
+ * predicate holds. This is `claimedProfiles`: a generated bundle MUST NOT
+ * claim a profile its own discovery document does not derive (RFC 0089 §B(1)).
+ */
+function claimedProfilesFor(doc) {
+    const profiles = [...deriveProfiles(doc)];
+    if (isCoreStandard(doc))
+        profiles.push('openwop-core-standard');
+    if (agentPlatformStatus(doc) !== 'none')
+        profiles.push('openwop-agent-platform');
+    return profiles;
+}
+/**
+ * Reduce a vitest JSON report into a per-scenario-file terminal state, keyed by
+ * the test-file basename (e.g. `discovery.test.ts`) to align with the basenames
+ * in `PROFILE_FLOOR_SCENARIOS`. A file is `passed` only if it ran AND had ≥1
+ * passing assertion AND zero failures (non-vacuous, per §C); a fully-skipped
+ * file is `skipped`; any failed assertion makes the file `failed`.
+ */
+function scenarioStatesFromReport(report) {
+    const states = new Map();
+    for (const file of report.testResults ?? []) {
+        const name = file.name;
+        if (typeof name !== 'string')
+            continue;
+        const basename = name.split('/').pop() ?? name;
+        const assertions = file.assertionResults ?? [];
+        let passes = 0;
+        let failures = 0;
+        let nonSkipped = 0;
+        for (const a of assertions) {
+            if (a.status === 'passed') {
+                passes++;
+                nonSkipped++;
+            }
+            else if (a.status === 'failed') {
+                failures++;
+                nonSkipped++;
+            }
+            // `skipped` / `todo` / `pending` count toward neither pass nor fail.
+        }
+        let state;
+        if (failures > 0)
+            state = 'failed';
+        else if (passes > 0 && nonSkipped > 0)
+            state = 'passed';
+        else
+            state = 'skipped';
+        states.set(basename, state);
+    }
+    return states;
+}
+/** Generate + validate + write an RFC 0089 conformance certification bundle. */
+async function runCertify(args, baseUrl, apiKey) {
+    const outPath = args.certify;
+    if (outPath === undefined)
+        process.exit(2);
+    // (a) Fetch /.well-known/openwop verbatim + its canonical-JSON SHA-256.
+    const discoveryUrl = `${baseUrl.replace(/\/$/, '')}/.well-known/openwop`;
+    let document;
+    try {
+        const resp = await fetch(discoveryUrl, { headers: { Accept: 'application/json' } });
+        if (!resp.ok) {
+            process.stderr.write(`openwop-conformance --certify: GET ${discoveryUrl} returned HTTP ${resp.status}.\n`);
+            process.exit(2);
+        }
+        document = (await resp.json());
+    }
+    catch (err) {
+        process.stderr.write(`openwop-conformance --certify: failed to fetch ${discoveryUrl}: ${String(err)}\n`);
+        process.exit(2);
+    }
+    const sha256 = createHash('sha256').update(canonicalJSON(document)).digest('hex');
+    // (b) Derive claimedProfiles from the captured document.
+    const claimedProfiles = claimedProfilesFor(document);
+    // (c) Run the suite, capturing per-scenario terminal state via the vitest
+    // JSON reporter. server-targeted scenarios live under src/scenarios/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const conformanceRoot = resolvePath(here, '..');
+    const reportDir = mkdtempSync(join(tmpdir(), 'owp-certify-'));
+    const reportFile = join(reportDir, 'vitest-report.json');
+    const env = { ...process.env };
+    env.OPENWOP_BASE_URL = baseUrl;
+    env.OPENWOP_API_KEY = apiKey;
+    if (args.impl)
+        env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
+    if (args.implVersion)
+        env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
+    const vitestArgs = [
+        'vitest',
+        'run',
+        '--config',
+        resolvePath(conformanceRoot, 'vitest.config.ts'),
+        '--reporter=json',
+        `--outputFile=${reportFile}`,
+    ];
+    const runResult = spawnSync('npx', vitestArgs, { cwd: conformanceRoot, env, stdio: 'inherit' });
+    if (runResult.error) {
+        process.stderr.write(`openwop-conformance --certify: failed to spawn vitest: ${String(runResult.error)}\n`);
+        process.exit(2);
+    }
+    let report;
+    try {
+        report = JSON.parse(readFileSync(reportFile, 'utf8'));
+    }
+    catch (err) {
+        process.stderr.write(`openwop-conformance --certify: could not read vitest JSON report at ${reportFile}: ${String(err)}\n`);
+        process.exit(2);
+    }
+    finally {
+        rmSync(reportDir, { recursive: true, force: true });
+    }
+    const states = scenarioStatesFromReport(report);
+    const passed = [];
+    const failed = [];
+    const skipped = [];
+    for (const [basename, state] of [...states.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        if (state === 'passed')
+            passed.push(basename);
+        else if (state === 'failed')
+            failed.push(basename);
+        else
+            skipped.push(basename);
+    }
+    // (d) Assemble the bundle.
+    const version = suiteVersion();
+    const impl = document
+        .implementation;
+    const hostName = args.impl ?? (typeof impl?.name === 'string' ? impl.name : 'unknown-host');
+    const hostVersion = args.implVersion ?? (typeof impl?.version === 'string' ? impl.version : '0.0.0');
+    const host = {
+        name: hostName,
+        version: hostVersion,
+    };
+    if (typeof impl?.vendor === 'string')
+        host.vendor = impl.vendor;
+    const bundle = {
+        bundleVersion: '1',
+        generatedAt: new Date().toISOString(),
+        generator: { name: '@openwop/openwop-conformance --certify', version },
+        suite: { package: '@openwop/openwop-conformance', version },
+        host,
+        discovery: { url: discoveryUrl, sha256, document },
+        claimedProfiles,
+        results: {
+            totals: {
+                passed: passed.length,
+                failed: failed.length,
+                skipped: skipped.length,
+                total: passed.length + failed.length + skipped.length,
+            },
+            passed,
+            failed,
+            skipped,
+        },
+    };
+    // (e) Validate against the bundle schema BEFORE writing.
+    const schema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json'), 'utf8'));
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(schema);
+    if (!validate(bundle)) {
+        process.stderr.write('openwop-conformance --certify: assembled bundle FAILED schema validation:\n' +
+            `${JSON.stringify(validate.errors, null, 2)}\n`);
+        process.exit(2);
+    }
+    writeFileSync(outPath, `${JSON.stringify(bundle, null, 2)}\n`);
+    process.stdout.write(`openwop-conformance --certify: wrote certification bundle to ${outPath}\n` +
+        `  host: ${host.name}@${host.version}\n` +
+        `  claimedProfiles: ${claimedProfiles.length > 0 ? claimedProfiles.join(', ') : '(none)'}\n` +
+        `  results: ${passed.length} passed / ${failed.length} failed / ${skipped.length} skipped\n`);
+    // Exit code mirrors the suite outcome: a failing run still produces a bundle
+    // (the failures are recorded), but the process exit reflects pass/fail.
+    process.exit(failed.length > 0 ? 1 : 0);
+}
+async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
         process.stdout.write(HELP_TEXT);
@@ -124,6 +346,15 @@ function main() {
         env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
     if (args.implVersion)
         env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
+    // RFC 0089 — certification-bundle generation requires a live host.
+    if (args.certify !== undefined) {
+        if (!env.OPENWOP_BASE_URL || !env.OPENWOP_API_KEY) {
+            process.stderr.write('openwop-conformance --certify: --base-url and --api-key are required.\n' +
+                'Run `openwop-conformance --help` for usage.\n');
+            process.exit(2);
+        }
+        return runCertify(args, env.OPENWOP_BASE_URL, env.OPENWOP_API_KEY);
+    }
     if (!args.offline && (!env.OPENWOP_BASE_URL || !env.OPENWOP_API_KEY)) {
         process.stderr.write('openwop-conformance: --base-url and --api-key are required (or use --offline).\n' +
             'Run `openwop-conformance --help` for usage.\n');
@@ -158,4 +389,4 @@ function main() {
     }
     process.exit(result.status ?? 1);
 }
-main();
+void main();

package/dist/lib/paths.js

@@ -0,0 +1,160 @@
+/**
+ * Layout-aware path resolver for the offline subset.
+ *
+ * The same suite source runs in two layouts:
+ *
+ *   1. Repo checkout — `openwop/conformance/src/scenarios/X.test.ts`. Schemas,
+ *      api/, and prose docs live one level above the conformance package
+ *      at the repo root.
+ *
+ *   2. Published tarball — `node_modules/@openwop/openwop-conformance/src/...`.
+ *      The `prepack` script vendors `api/` and `schemas/` INTO the package,
+ *      so they resolve relative to the package root instead of a parent.
+ *      Spec prose (`spec/v1/*.md`) is NOT bundled — those tests skip.
+ *
+ * Earlier offline scenarios computed `__dirname/../../..` to find
+ * the repo root. That works in a checkout but lands in `node_modules/@openwop/`
+ * after npx-style install, breaking `npx -y @openwop/openwop-conformance --offline`
+ * with `ENOENT: ... node_modules/@openwop/schemas/workflow-definition.schema.json`.
+ *
+ * This module centralises the resolution. Strategy:
+ *
+ *   - If `OPENWOP_CONFORMANCE_ROOT` is set, treat its value as the layout root
+ *     (the directory that contains `schemas/`, `api/`, and either
+ *     `conformance/fixtures/` (repo) or `fixtures/` directly (vendored)).
+ *     Used by integrators who put the suite in an unusual location.
+ *
+ *   - Otherwise compute the package root from `import.meta.url` (= the
+ *     directory containing `package.json`) and probe whether the schemas
+ *     are vendored at the package root (published) or at the parent (repo).
+ *
+ * Exported paths are non-null for the materials always present in both
+ * layouts; the prose-doc and fixtures.md catalog dirs may resolve to
+ * `null` under the published layout, in which case the corresponding
+ * scenarios skip cleanly (see `spec-corpus-validity.test.ts`).
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+// `dirname(fileURLToPath(import.meta.url))` for an ESM module compiled or
+// run from `src/lib/paths.ts` returns `<pkg>/src/lib/`. The conformance
+// package root is therefore two directories above this file in BOTH the
+// repo checkout and the published tarball — the source layout is
+// identical between the two; only the parent of `<pkg>` differs.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = pathResolve(HERE, '..', '..');
+function resolveFromRoot(root, layout) {
+    // Two on-disk shapes for the layout root:
+    //   - Repo: <root>/schemas, <root>/api, <root>/conformance/fixtures,
+    //           <root>/conformance/{fixtures.md,coverage.md}, <root>/spec/v1/*.md
+    //     (Where `<root>` = the repo root, e.g. `openwop/`.)
+    //   - Vendored / published: <root>/schemas, <root>/api, <root>/fixtures,
+    //           <root>/fixtures.md (when bundled), no spec/v1.
+    // Probe by checking whether `schemas/` lives at the conformance pkg root
+    // (vendored) vs one level up (repo).
+    const schemasDir = join(root, 'schemas');
+    const apiDir = join(root, 'api');
+    const repoFixturesDir = join(root, 'conformance', 'fixtures');
+    const vendoredFixturesDir = join(root, 'fixtures');
+    const fixturesDir = existsSync(repoFixturesDir) ? repoFixturesDir : vendoredFixturesDir;
+    const repoScenariosDir = join(root, 'conformance', 'src', 'scenarios');
+    const vendoredScenariosDir = join(PKG_ROOT, 'src', 'scenarios');
+    const scenariosDir = existsSync(repoScenariosDir)
+        ? repoScenariosDir
+        : existsSync(vendoredScenariosDir)
+            ? vendoredScenariosDir
+            : null;
+    const repoConformanceReadme = join(root, 'conformance', 'README.md');
+    const vendoredConformanceReadme = join(PKG_ROOT, 'README.md');
+    const conformanceReadmePath = existsSync(repoConformanceReadme)
+        ? repoConformanceReadme
+        : existsSync(vendoredConformanceReadme)
+            ? vendoredConformanceReadme
+            : null;
+    const repoFixturesDoc = join(root, 'conformance', 'fixtures.md');
+    const vendoredFixturesDoc = join(root, 'fixtures.md');
+    const fixturesDocPath = existsSync(repoFixturesDoc)
+        ? repoFixturesDoc
+        : existsSync(vendoredFixturesDoc)
+            ? vendoredFixturesDoc
+            : null;
+    const repoCoverageDoc = join(root, 'conformance', 'coverage.md');
+    const vendoredCoverageDoc = join(root, 'coverage.md');
+    const coverageDocPath = existsSync(repoCoverageDoc)
+        ? repoCoverageDoc
+        : existsSync(vendoredCoverageDoc)
+            ? vendoredCoverageDoc
+            : null;
+    const v1Probe = join(root, 'spec', 'v1');
+    const v1Dir = existsSync(v1Probe) ? v1Probe : null;
+    const readmeProbe = join(root, 'README.md');
+    const readmePath = existsSync(readmeProbe) ? readmeProbe : null;
+    const typescriptRunHelpersProbe = join(root, 'sdk', 'typescript', 'src', 'run-helpers.ts');
+    const typescriptRunHelpersPath = existsSync(typescriptRunHelpersProbe) ? typescriptRunHelpersProbe : null;
+    const pythonTypesProbe = join(root, 'sdk', 'python', 'src', 'openwop_client', 'types.py');
+    const pythonTypesPath = existsSync(pythonTypesProbe) ? pythonTypesProbe : null;
+    const goTypesProbe = join(root, 'sdk', 'go', 'types.go');
+    const goTypesPath = existsSync(goTypesProbe) ? goTypesProbe : null;
+    return {
+        pkgRoot: PKG_ROOT,
+        schemasDir,
+        apiDir,
+        fixturesDir,
+        scenariosDir,
+        conformanceReadmePath,
+        fixturesDocPath,
+        coverageDocPath,
+        v1Dir,
+        readmePath,
+        typescriptRunHelpersPath,
+        pythonTypesPath,
+        goTypesPath,
+        layout,
+    };
+}
+function resolveLayout() {
+    const override = process.env.OPENWOP_CONFORMANCE_ROOT?.trim();
+    if (override && override.length > 0) {
+        return resolveFromRoot(pathResolve(override), 'env-override');
+    }
+    // Vendored / published-tarball layout: `prepack` copies `schemas/` +
+    // `api/` to the package root. Repo layout: schemas live one level
+    // above the conformance package.
+    //
+    // Edge case: a developer running `npm pack` locally without a
+    // postpack cleanup leaves schemas/ in BOTH places transiently. When
+    // both exist, prefer the parent (repo layout) so prose-doc tests
+    // continue to run — the parent is the canonical source.
+    const parent = pathResolve(PKG_ROOT, '..');
+    const parentHasSchemas = existsSync(join(parent, 'schemas'));
+    const pkgHasSchemas = existsSync(join(PKG_ROOT, 'schemas'));
+    if (parentHasSchemas) {
+        return resolveFromRoot(parent, 'repo');
+    }
+    if (pkgHasSchemas) {
+        return resolveFromRoot(PKG_ROOT, 'published');
+    }
+    // Neither — return the published-style resolution rooted at PKG_ROOT
+    // so error messages name a concrete directory rather than a
+    // computed-from-undefined path.
+    return resolveFromRoot(PKG_ROOT, 'published');
+}
+const _layout = resolveLayout();
+export const PKG_ROOT_PATH = _layout.pkgRoot;
+export const SCHEMAS_DIR = _layout.schemasDir;
+export const API_DIR = _layout.apiDir;
+export const FIXTURES_DIR = _layout.fixturesDir;
+export const SCENARIOS_DIR = _layout.scenariosDir;
+export const CONFORMANCE_README_PATH = _layout.conformanceReadmePath;
+export const FIXTURES_DOC_PATH = _layout.fixturesDocPath;
+export const COVERAGE_DOC_PATH = _layout.coverageDocPath;
+export const V1_DIR = _layout.v1Dir;
+export const README_PATH = _layout.readmePath;
+export const TYPESCRIPT_RUN_HELPERS_PATH = _layout.typescriptRunHelpersPath;
+export const PYTHON_TYPES_PATH = _layout.pythonTypesPath;
+export const GO_TYPES_PATH = _layout.goTypesPath;
+export const LAYOUT = _layout.layout;
+/** Test-only — re-resolve in case env var or filesystem changed. */
+export function __resolveLayoutForTests() {
+    return resolveLayout();
+}