@hover-dev/core 0.18.0 → 0.19.0

package/dist/engine.d.ts

@@ -15,6 +15,8 @@
 export { writeSpec } from './specs/writeSpec.js';
 export type { WriteSpecOptions, WriteSpecResult, Redaction } from './specs/writeSpec.js';
 export type { SkillStep } from './specs/specStep.js';
+export { writeApiSpec } from './specs/writeApiSpec.js';
+export type { ApiCheck, WriteApiSpecOptions, WriteApiSpecResult } from './specs/writeApiSpec.js';
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
 export type { ReplayResult, ReplayFailure, ReplayStep, GroundedTarget } from './specs/replayGrounded.js';
 export { launchDebugChrome, closeDebugChrome, findChromeBinary } from './playwright/launchChrome.js';

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGzG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACjH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGzG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrG,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACrG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzG,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/engine.js

@@ -14,6 +14,8 @@
  */
 // ── crystallization + grounded replay ────────────────────────────────────────
 export { writeSpec } from './specs/writeSpec.js';
+// API-layer crystallizer — observed/replayed requests → *.api-test.spec.ts.
+export { writeApiSpec } from './specs/writeApiSpec.js';
 // Creation-verification: replay a flow's grounded steps over CDP (no playwright test).
 export { replayGroundedSteps, replayOnPage, applyGroundedStep, groundedLocate } from './specs/replayGrounded.js';
 // ── debug-Chrome lifecycle ───────────────────────────────────────────────────

package/dist/specs/writeApiSpec.d.ts

@@ -0,0 +1,36 @@
+/** One asserted API call — a contract, shape, or authz check. */
+export interface ApiCheck {
+    /** Short imperative title → the `test()` name (e.g. "GET /api/cart returns the cart"). */
+    title: string;
+    /** HTTP method. */
+    method: string;
+    /** URL as captured. Same-origin URLs are relativized to a path so the spec
+     *  rides the config's baseURL; cross-origin URLs are emitted in full. */
+    url: string;
+    /** Request body to send (objects are emitted as a JSON literal via `data`). */
+    requestBody?: unknown;
+    /** Headers to send. For an authz check the agent omits/alters the auth header. */
+    headers?: Record<string, string>;
+    /** Expected status — observed for a contract check, or expected-after-mutation
+     *  for an authz check (verified with replay_request before crystallizing). */
+    expectStatus?: number;
+    /** Top-level response keys to assert present (a light shape contract). */
+    expectBodyKeys?: string[];
+    /** Optional human note → emitted as a leading comment (e.g. "authz: no session → 401"). */
+    note?: string;
+}
+export interface WriteApiSpecOptions {
+    devRoot: string;
+    name: string;
+    description?: string;
+    checks: ApiCheck[];
+    /** Run target origin — same-origin URLs are relativized against it. */
+    startUrl?: string;
+    overwrite?: boolean;
+}
+export interface WriteApiSpecResult {
+    path: string;
+    slug: string;
+}
+export declare function writeApiSpec(opts: WriteApiSpecOptions): Promise<WriteApiSpecResult>;
+//# sourceMappingURL=writeApiSpec.d.ts.map

package/dist/specs/writeApiSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeApiSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeApiSpec.ts"],"names":[],"mappings":"AAgBA,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf;6EACyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;kFAC8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AA0DD,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAyBzF"}

package/dist/specs/writeApiSpec.js

@@ -0,0 +1,94 @@
+/**
+ * Deterministic API-spec crystallizer — the API-layer sibling of writeSpec.
+ *
+ * Writes a `<devRoot>/__vibe_tests__/<slug>.api-test.spec.ts` from a list of
+ * `ApiCheck`s the agent assembled (observed via CDP capture, optionally with a
+ * mutation it verified with replay_request). Pure `@playwright/test`
+ * `APIRequestContext` — `request.get/post(...)` + status / shape / authz
+ * assertions. No LLM in the codegen path: a 1:1 string-template translation, so
+ * record == replay holds for the API layer too (the call that was captured is
+ * the call that's asserted).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { slugify, firstSentence } from './text.js';
+const KNOWN_METHODS = new Set(['get', 'post', 'put', 'delete', 'patch', 'head']);
+function q(s) {
+    return `'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/** Same-origin → path (rides baseURL); cross-origin → full URL. */
+function toRequestUrl(url, startUrl) {
+    try {
+        const u = new URL(url);
+        if (startUrl) {
+            const base = new URL(startUrl);
+            if (u.origin === base.origin)
+                return (u.pathname + u.search) || '/';
+        }
+        return url;
+    }
+    catch {
+        return url; // already a path, or unparseable — emit as-is
+    }
+}
+function renderCheck(check, startUrl) {
+    const m = check.method.toLowerCase();
+    const useFetch = !KNOWN_METHODS.has(m);
+    const fn = useFetch ? 'fetch' : m;
+    const url = toRequestUrl(check.url, startUrl);
+    // Build the options object (data / headers / method-for-fetch).
+    const opts = [];
+    if (useFetch)
+        opts.push(`method: ${q(check.method.toUpperCase())}`);
+    if (check.requestBody !== undefined && m !== 'get' && m !== 'head') {
+        opts.push(`data: ${JSON.stringify(check.requestBody)}`);
+    }
+    if (check.headers && Object.keys(check.headers).length) {
+        opts.push(`headers: ${JSON.stringify(check.headers)}`);
+    }
+    const callArgs = opts.length ? `${q(url)}, { ${opts.join(', ')} }` : q(url);
+    const body = [];
+    if (check.note)
+        body.push(`    // ${check.note}`);
+    body.push(`    const res = await request.${fn}(${callArgs});`);
+    if (typeof check.expectStatus === 'number') {
+        body.push(`    expect(res.status()).toBe(${check.expectStatus});`);
+    }
+    else {
+        body.push(`    expect(res.ok()).toBeTruthy();`);
+    }
+    if (check.expectBodyKeys && check.expectBodyKeys.length) {
+        body.push(`    const body = await res.json();`);
+        for (const k of check.expectBodyKeys) {
+            body.push(`    expect(body).toHaveProperty(${q(k)});`);
+        }
+    }
+    const title = check.title.replace(/'/g, "\\'");
+    return [`  test('${title}', async ({ request }) => {`, ...body, `  });`].join('\n');
+}
+export async function writeApiSpec(opts) {
+    const slug = slugify(opts.name);
+    if (!slug)
+        throw new Error('api spec name must contain at least one alphanumeric character');
+    if (!opts.checks.length)
+        throw new Error('api spec needs at least one check');
+    const dir = join(opts.devRoot, '__vibe_tests__');
+    const path = join(dir, `${slug}.api-test.spec.ts`);
+    if (existsSync(path) && !opts.overwrite) {
+        throw new Error(`${path} already exists (pass overwrite to replace)`);
+    }
+    const header = opts.description ? `// ${firstSentence(opts.description)}` : null;
+    const lines = [
+        ...(header ? [header] : []),
+        `import { test, expect } from '@playwright/test';`,
+        ``,
+        `test.describe(${q(opts.name)}, () => {`,
+        opts.checks.map(c => renderCheck(c, opts.startUrl)).join('\n\n'),
+        `});`,
+        ``,
+    ];
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, lines.join('\n'), 'utf-8');
+    return { path, slug };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",