@pellux/goodvibes-contracts 1.6.0 → 1.7.0

package/dist/testing/conformance.d.ts

@@ -0,0 +1,56 @@
+/**
+ * testing/conformance.ts — the descriptor/handler drift gate, shipped from the
+ * contracts package so every consuming front-end (terminal-shell, the tui and
+ * agent forks, the webui) runs the SAME gate against its own composition rather
+ * than keeping a divergent local copy.
+ *
+ * A gateway method catalog registers DESCRIPTORS (the contract surface) and,
+ * separately, HANDLERS (what actually answers an invoke). A descriptor with no
+ * attached handler answers 501 "Gateway method is not invokable" over both
+ * websocket and HTTP invoke — a whole verb family can look present in the
+ * contract yet be dead. That is the exact regression this gate catches: run
+ * `assertEveryDescriptorHasHandler` against a FULLY-composed catalog in the
+ * consumer's test suite and it fails loudly the moment any registered
+ * descriptor is left handler-less.
+ *
+ * The catalog is accepted through a narrow structural view, so a consumer can
+ * pass its concrete GatewayMethodCatalog (or any equivalent) without the
+ * contracts package depending on the catalog's full type.
+ */
+/** The minimal catalog surface this gate reads. GatewayMethodCatalog satisfies it structurally. */
+export interface GatewayCatalogConformanceView {
+    /** Every registered method descriptor. Only the `id` field is read here. */
+    list(): ReadonlyArray<{
+        readonly id: string;
+    }>;
+    /** True when the descriptor with this id has a handler attached. */
+    hasHandler(id: string): boolean;
+}
+export interface ConformanceOptions {
+    /**
+     * Restrict the check to these descriptor ids. Use when a catalog carries
+     * builtin descriptors whose handlers are attached by a different layer (host
+     * daemon surfaces) and are legitimately absent in the composition under test.
+     */
+    readonly onlyIds?: readonly string[];
+    /**
+     * Descriptor ids allowed to have no handler — descriptors a given
+     * composition intentionally does not answer. Prefer `onlyIds` for the common
+     * case; use `ignoreIds` to carve out a small known set from a full sweep.
+     */
+    readonly ignoreIds?: readonly string[];
+}
+/**
+ * Return the sorted ids of every registered descriptor that has no attached
+ * handler (the 501 set), honoring `onlyIds` / `ignoreIds`. Empty means every
+ * checked descriptor is invokable.
+ */
+export declare function findMethodsMissingHandlers(catalog: GatewayCatalogConformanceView, options?: ConformanceOptions): string[];
+/**
+ * Assert every registered descriptor (honoring `onlyIds` / `ignoreIds`) has a
+ * handler attached. Throws with the full list of offending ids when any is
+ * handler-less. This is the consumer-facing gate: call it in your CI against
+ * the same catalog your daemon serves.
+ */
+export declare function assertEveryDescriptorHasHandler(catalog: GatewayCatalogConformanceView, options?: ConformanceOptions): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mGAAmG;AACnG,MAAM,WAAW,6BAA6B;IAC5C,4EAA4E;IAC5E,IAAI,IAAI,aAAa,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,oEAAoE;IACpE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,6BAA6B,EACtC,OAAO,GAAE,kBAAuB,GAC/B,MAAM,EAAE,CAUV;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,6BAA6B,EACtC,OAAO,GAAE,kBAAuB,GAC/B,IAAI,CASN"}

package/dist/testing/conformance.js

@@ -0,0 +1,50 @@
+/**
+ * testing/conformance.ts — the descriptor/handler drift gate, shipped from the
+ * contracts package so every consuming front-end (terminal-shell, the tui and
+ * agent forks, the webui) runs the SAME gate against its own composition rather
+ * than keeping a divergent local copy.
+ *
+ * A gateway method catalog registers DESCRIPTORS (the contract surface) and,
+ * separately, HANDLERS (what actually answers an invoke). A descriptor with no
+ * attached handler answers 501 "Gateway method is not invokable" over both
+ * websocket and HTTP invoke — a whole verb family can look present in the
+ * contract yet be dead. That is the exact regression this gate catches: run
+ * `assertEveryDescriptorHasHandler` against a FULLY-composed catalog in the
+ * consumer's test suite and it fails loudly the moment any registered
+ * descriptor is left handler-less.
+ *
+ * The catalog is accepted through a narrow structural view, so a consumer can
+ * pass its concrete GatewayMethodCatalog (or any equivalent) without the
+ * contracts package depending on the catalog's full type.
+ */
+/**
+ * Return the sorted ids of every registered descriptor that has no attached
+ * handler (the 501 set), honoring `onlyIds` / `ignoreIds`. Empty means every
+ * checked descriptor is invokable.
+ */
+export function findMethodsMissingHandlers(catalog, options = {}) {
+    const only = options.onlyIds ? new Set(options.onlyIds) : null;
+    const ignore = options.ignoreIds ? new Set(options.ignoreIds) : null;
+    return catalog
+        .list()
+        .map((descriptor) => descriptor.id)
+        .filter((id) => (only ? only.has(id) : true))
+        .filter((id) => (ignore ? !ignore.has(id) : true))
+        .filter((id) => !catalog.hasHandler(id))
+        .sort();
+}
+/**
+ * Assert every registered descriptor (honoring `onlyIds` / `ignoreIds`) has a
+ * handler attached. Throws with the full list of offending ids when any is
+ * handler-less. This is the consumer-facing gate: call it in your CI against
+ * the same catalog your daemon serves.
+ */
+export function assertEveryDescriptorHasHandler(catalog, options = {}) {
+    const missing = findMethodsMissingHandlers(catalog, options);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Gateway catalog has ${missing.length} descriptor(s) with no attached handler — `
+        + `each answers 501 "Gateway method is not invokable" over websocket and HTTP invoke. `
+        + `Attach handlers together with the descriptors at composition time. Offending ids:\n  `
+        + missing.join('\n  '));
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @pellux/goodvibes-contracts/testing — the shipped conformance kit + mock-daemon
+ * fixture generator, the single source consuming front-ends (terminal-shell, the
+ * tui and agent forks, the webui, the Home Assistant fixtures) run instead of a
+ * divergent local copy.
+ *
+ *   - conformance: assertEveryDescriptorHasHandler / findMethodsMissingHandlers —
+ *     the descriptor/handler drift gate, run against a fully-composed catalog.
+ *   - mock-daemon: buildMockDaemonResponses / buildMockDaemonFixtureMap /
+ *     createMockDaemon / sampleFromSchema — schema-valid sample responses for
+ *     every cataloged method, generated from the contract's own JSON Schemas so
+ *     Playwright/HA mocks are generated rather than hand-written.
+ */
+export { assertEveryDescriptorHasHandler, findMethodsMissingHandlers, type GatewayCatalogConformanceView, type ConformanceOptions, } from './conformance.js';
+export { sampleFromSchema, buildMockDaemonResponses, buildMockDaemonFixtureMap, createMockDaemon, type MockDaemonResponse, type MockDaemonFixtureMap, } from './mock-daemon.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,15 @@
+/**
+ * @pellux/goodvibes-contracts/testing — the shipped conformance kit + mock-daemon
+ * fixture generator, the single source consuming front-ends (terminal-shell, the
+ * tui and agent forks, the webui, the Home Assistant fixtures) run instead of a
+ * divergent local copy.
+ *
+ *   - conformance: assertEveryDescriptorHasHandler / findMethodsMissingHandlers —
+ *     the descriptor/handler drift gate, run against a fully-composed catalog.
+ *   - mock-daemon: buildMockDaemonResponses / buildMockDaemonFixtureMap /
+ *     createMockDaemon / sampleFromSchema — schema-valid sample responses for
+ *     every cataloged method, generated from the contract's own JSON Schemas so
+ *     Playwright/HA mocks are generated rather than hand-written.
+ */
+export { assertEveryDescriptorHasHandler, findMethodsMissingHandlers, } from './conformance.js';
+export { sampleFromSchema, buildMockDaemonResponses, buildMockDaemonFixtureMap, createMockDaemon, } from './mock-daemon.js';

package/dist/testing/mock-daemon.d.ts

@@ -0,0 +1,58 @@
+/**
+ * testing/mock-daemon.ts — generate schema-valid sample responses for every
+ * cataloged operator method, straight from the contract's own JSON Schemas.
+ *
+ * Consumers (the webui Playwright suite, the Home Assistant test fixtures) have
+ * historically hand-written a mock response per method their UI calls, which
+ * drifts silently the moment a method's output schema changes. This generator
+ * removes the hand-authoring: given the operator contract manifest, it walks
+ * each method's `outputSchema` and produces a minimal, deterministic,
+ * schema-valid body — the single source those mocks can be generated from.
+ *
+ * The walk is deterministic (no randomness, no clock) so a regenerated fixture
+ * set is byte-identical unless the contract itself changed — the property that
+ * lets a checked-in fixture artifact carry a drift check.
+ *
+ * Scope: this understands the JSON Schema subset the contract generator emits —
+ * object (properties/required), array (items), string (enum), number/integer,
+ * boolean, null, and anyOf unions. It is a fixture generator, not a full JSON
+ * Schema materializer; an unrecognized shape yields null rather than throwing,
+ * so a new schema keyword degrades to a still-valid (if minimal) sample.
+ */
+import type { JsonSchema, OperatorContractManifest } from '../types.js';
+/**
+ * Produce a minimal, deterministic value that satisfies `schema`. Fills every
+ * declared object property (required and optional) so the sample exercises the
+ * full shape a consumer's mock renders.
+ */
+export declare function sampleFromSchema(schema: JsonSchema | undefined): unknown;
+/** One generated mock response: what a daemon would answer for a method. */
+export interface MockDaemonResponse {
+    readonly methodId: string;
+    readonly http: {
+        readonly method: string;
+        readonly path: string;
+    } | null;
+    readonly status: number;
+    readonly body: unknown;
+}
+/**
+ * Build a schema-valid sample response for every method in the contract, in
+ * catalog order. A method with no `outputSchema` yields a `null` body (honest:
+ * the contract declares no shape to sample).
+ */
+export declare function buildMockDaemonResponses(contract: OperatorContractManifest): MockDaemonResponse[];
+/** A methodId -> sample response map, the fixture shape most consumers want. */
+export type MockDaemonFixtureMap = Readonly<Record<string, MockDaemonResponse>>;
+/** Reduce the response list to a methodId-keyed map. */
+export declare function buildMockDaemonFixtureMap(contract: OperatorContractManifest): MockDaemonFixtureMap;
+/**
+ * A tiny in-memory mock daemon over the generated fixtures: answer by methodId
+ * or by HTTP method+path. Returns null for an unknown method/route so a caller
+ * can fall through to its own 404, exactly like a real dispatcher.
+ */
+export declare function createMockDaemon(contract: OperatorContractManifest): {
+    answer(methodId: string): MockDaemonResponse | null;
+    answerHttp(method: string, path: string): MockDaemonResponse | null;
+};
+//# sourceMappingURL=mock-daemon.d.ts.map

package/dist/testing/mock-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-daemon.d.ts","sourceRoot":"","sources":["../../src/testing/mock-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAQxE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAoDxE;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,kBAAkB,EAAE,CAOjG;AAED,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEhF,wDAAwD;AACxD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,oBAAoB,CAMlG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,GAAG;IACpE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACpD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;CACrE,CAYA"}

package/dist/testing/mock-daemon.js

@@ -0,0 +1,96 @@
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Produce a minimal, deterministic value that satisfies `schema`. Fills every
+ * declared object property (required and optional) so the sample exercises the
+ * full shape a consumer's mock renders.
+ */
+export function sampleFromSchema(schema) {
+    if (!schema)
+        return null;
+    const record = asRecord(schema);
+    if (!record)
+        return null;
+    // anyOf union: take the first branch that is not a bare `null` type, so the
+    // sample carries a representative value rather than degenerating to null.
+    const anyOf = record['anyOf'];
+    if (Array.isArray(anyOf) && anyOf.length > 0) {
+        const branches = anyOf;
+        const preferred = branches.find((branch) => asRecord(branch)?.['type'] !== 'null') ?? branches[0];
+        return sampleFromSchema(preferred);
+    }
+    const enumValues = record['enum'];
+    if (Array.isArray(enumValues) && enumValues.length > 0) {
+        return enumValues[0];
+    }
+    const type = record['type'];
+    if (type === 'object' || (type === undefined && asRecord(record['properties']))) {
+        const properties = asRecord(record['properties']) ?? {};
+        const out = {};
+        for (const [key, propSchema] of Object.entries(properties)) {
+            out[key] = sampleFromSchema(propSchema);
+        }
+        return out;
+    }
+    if (type === 'array') {
+        const items = record['items'];
+        if (items && !Array.isArray(items)) {
+            return [sampleFromSchema(items)];
+        }
+        return [];
+    }
+    switch (type) {
+        case 'string':
+            return 'sample';
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'null':
+            return null;
+        default:
+            // Unknown / absent type with no properties: JSON Schema's "accept anything".
+            return null;
+    }
+}
+/**
+ * Build a schema-valid sample response for every method in the contract, in
+ * catalog order. A method with no `outputSchema` yields a `null` body (honest:
+ * the contract declares no shape to sample).
+ */
+export function buildMockDaemonResponses(contract) {
+    return contract.operator.methods.map((method) => ({
+        methodId: method.id,
+        http: method.http ? { method: method.http.method, path: method.http.path } : null,
+        status: 200,
+        body: sampleFromSchema(method.outputSchema),
+    }));
+}
+/** Reduce the response list to a methodId-keyed map. */
+export function buildMockDaemonFixtureMap(contract) {
+    const map = {};
+    for (const response of buildMockDaemonResponses(contract)) {
+        map[response.methodId] = response;
+    }
+    return map;
+}
+/**
+ * A tiny in-memory mock daemon over the generated fixtures: answer by methodId
+ * or by HTTP method+path. Returns null for an unknown method/route so a caller
+ * can fall through to its own 404, exactly like a real dispatcher.
+ */
+export function createMockDaemon(contract) {
+    const responses = buildMockDaemonResponses(contract);
+    const byId = new Map(responses.map((response) => [response.methodId, response]));
+    const byHttp = new Map(responses
+        .filter((response) => response.http)
+        .map((response) => [`${response.http.method} ${response.http.path}`, response]));
+    return {
+        answer: (methodId) => byId.get(methodId) ?? null,
+        answerHttp: (method, path) => byHttp.get(`${method.toUpperCase()} ${path}`) ?? null,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-contracts",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "engines": {
     "bun": "1.3.10",
     "node": ">=22.0.0"
@@ -14,10 +14,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
     "./generated/foundation-client-types": {
       "types": "./dist/generated/foundation-client-types.d.ts",
       "import": "./dist/generated/foundation-client-types.js"
     },
+    "./generated/mock-daemon-fixtures": {
+      "types": "./dist/generated/mock-daemon-fixtures.d.ts",
+      "import": "./dist/generated/mock-daemon-fixtures.js"
+    },
     "./generated/foundation-metadata": {
       "types": "./dist/generated/foundation-metadata.d.ts",
       "import": "./dist/generated/foundation-metadata.js"
@@ -42,6 +50,10 @@
       "types": "./dist/generated/runtime-event-domains.d.ts",
       "import": "./dist/generated/runtime-event-domains.js"
     },
+    "./generated/webui-facade": {
+      "types": "./dist/generated/webui-facade.d.ts",
+      "import": "./dist/generated/webui-facade.js"
+    },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -71,6 +83,7 @@
       "import": "./dist/zod-schemas/session.js"
     },
     "./operator-contract.json": "./artifacts/operator-contract.json",
+    "./operator-openapi.json": "./artifacts/operator-openapi.json",
     "./peer-contract.json": "./artifacts/peer-contract.json",
     "./package.json": "./package.json"
   },