@docsxai/engine 0.2.0

package/dist/backend-client-transport.js

@@ -0,0 +1,181 @@
+// REST transport for `@docsxai/backend`: the {@link BackendClient} HTTP surface, plus the
+// token-resolving {@link createBackendClient} factory and the `docsxai run` history relay. Used by
+// `docsxai push` / `pull` / `login` / `run`. Re-exported from `./backend-client.js`.
+import { API_VERSION, API_VERSION_HEADER, BackendClientError, } from "./backend-client-contracts.js";
+import { resolveBackendToken } from "./backend-client-token.js";
+export class BackendClient {
+    baseUrl;
+    token;
+    doFetch;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new BackendClientError("baseUrl is required");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.token = opts.token ?? process.env.DOCSX_TOKEN ?? "";
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+        if (!this.token) {
+            throw new BackendClientError("no bearer token — set DOCSX_TOKEN env var or pass `token`. Run `docsxai login` to validate.");
+        }
+    }
+    headers(extra) {
+        return {
+            authorization: `Bearer ${this.token}`,
+            [API_VERSION_HEADER]: API_VERSION,
+            "content-type": "application/json",
+            ...(extra ?? {}),
+        };
+    }
+    async req(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await this.doFetch(url, {
+            method,
+            headers: this.headers(),
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let parsed = text;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                /* leave as text */
+            }
+            throw new BackendClientError(`${method} ${path} → ${res.status}: ${text.slice(0, 200)}`, res.status, parsed);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    health() {
+        // /v1/health is the only no-auth endpoint; bypass the bearer here in case caller's token is bad.
+        return this.doFetch(`${this.baseUrl}/v1/health`).then((r) => {
+            if (!r.ok)
+                throw new BackendClientError(`health → ${r.status}`);
+            return r.json();
+        });
+    }
+    // --- workspaces ---
+    listWorkspaces() {
+        return this.req("GET", "/v1/workspaces");
+    }
+    createWorkspace(name) {
+        return this.req("POST", "/v1/workspaces", { name });
+    }
+    getWorkspace(id) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(id)}`);
+    }
+    // --- projects ---
+    listProjects(wsId) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects`);
+    }
+    createProject(wsId, name) {
+        return this.req("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/projects`, { name });
+    }
+    getProject(wsId, projectId) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}`);
+    }
+    // --- revisions ---
+    listRevisions(wsId, projectId) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions`);
+    }
+    createRevision(wsId, projectId, body) {
+        return this.req("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions`, body);
+    }
+    getRevision(wsId, projectId, rev) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(rev)}`);
+    }
+    /** Finalize a revision (idempotent). Artifact PUTs afterwards are rejected with 409. */
+    finalizeRevision(wsId, projectId, rev) {
+        return this.req("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(rev)}/finalize`);
+    }
+    /** PUT an artifact's payload on a revision. The backend treats the payload as opaque JSON. */
+    putArtifact(wsId, projectId, rev, artifact, payload) {
+        return this.req("PUT", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(rev)}/${artifact}`, payload);
+    }
+    getArtifact(wsId, projectId, rev, artifact) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/revisions/${encodeURIComponent(rev)}/${artifact}`);
+    }
+    // --- run history ---
+    appendRun(wsId, projectId, rec) {
+        return this.req("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/run-history`, rec);
+    }
+    listRuns(wsId, projectId) {
+        return this.req("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/projects/${encodeURIComponent(projectId)}/run-history`);
+    }
+    // --- content-addressed blobs ---
+    /** Upload raw bytes; the backend stores them under their sha256. Idempotent. */
+    async putBlob(data) {
+        const res = await this.doFetch(`${this.baseUrl}/v1/blobs`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/octet-stream" }),
+            body: data,
+        });
+        if (!res.ok) {
+            throw new BackendClientError(`POST /v1/blobs → ${res.status}`, res.status);
+        }
+        return (await res.json());
+    }
+    /** HEAD-probe a blob — true when the backend already has these bytes. */
+    async hasBlob(sha256) {
+        const res = await this.doFetch(`${this.baseUrl}/v1/blobs/${encodeURIComponent(sha256)}`, {
+            method: "HEAD",
+            headers: this.headers(),
+        });
+        if (res.status === 404)
+            return false;
+        if (!res.ok)
+            throw new BackendClientError(`HEAD /v1/blobs/${sha256} → ${res.status}`, res.status);
+        return true;
+    }
+    async getBlob(sha256) {
+        const res = await this.doFetch(`${this.baseUrl}/v1/blobs/${encodeURIComponent(sha256)}`, {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new BackendClientError(`GET /v1/blobs/${sha256} → ${res.status}`, res.status);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+}
+/** Build a {@link BackendClient} with the token resolved via {@link resolveBackendToken}. */
+export async function createBackendClient(opts) {
+    const token = await resolveBackendToken({
+        baseUrl: opts.baseUrl,
+        ...(opts.token !== undefined ? { token: opts.token } : {}),
+        ...(opts.workspaceDir !== undefined ? { workspaceDir: opts.workspaceDir } : {}),
+        ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+    });
+    return new BackendClient({
+        baseUrl: opts.baseUrl,
+        token,
+        ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+    });
+}
+// --- run-history wiring (`docsxai run`) -------------------------------------
+/**
+ * Append an execution-run record for a backend-bound workspace. A no-op when the workspace config
+ * lacks the backend binding; never throws — `docsxai run` must stay offline-tolerant, so failures
+ * come back as a warning string for the caller to surface.
+ */
+export async function recordRunHistory(opts) {
+    const { backend_url, backend_workspace_id, backend_project_id } = opts.config;
+    if (!backend_url || !backend_workspace_id || !backend_project_id)
+        return { recorded: false };
+    try {
+        const client = await createBackendClient({
+            baseUrl: backend_url,
+            workspaceDir: opts.workspaceDir,
+            ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+        });
+        await client.appendRun(backend_workspace_id, backend_project_id, {
+            rev: "head",
+            ok: opts.ok,
+            duration_ms: opts.durationMs,
+            summary: opts.summary,
+        });
+        return { recorded: true };
+    }
+    catch (e) {
+        return { recorded: false, warning: `failed to record run history: ${e.message}` };
+    }
+}

package/dist/backend-client.d.ts

@@ -0,0 +1,5 @@
+export * from "./backend-client-contracts.js";
+export * from "./backend-client-transport.js";
+export * from "./backend-client-token.js";
+export * from "./backend-client-oauth-login.js";
+export * from "./backend-client-state-cache.js";

package/dist/backend-client.js

@@ -0,0 +1,18 @@
+// HTTP client for `@docsxai/backend`. Used by `docsxai push` / `pull` / `login` / `run`.
+//
+// Barrel: the implementation lives in flat siblings, split by reason-to-change. This file preserves
+// the original public surface so `./backend-client.js` importers (and colocated tests) don't move.
+//   • backend-client-contracts.ts   — wire DTOs / payloads / error class / option shapes (the leaf)
+//   • backend-client-transport.ts    — the REST `BackendClient` + `createBackendClient` + run history
+//   • backend-client-token.ts        — stored-token file + bearer-token resolution / refresh
+//   • backend-client-oauth-login.ts  — the OAuth 2.1 + PKCE login flow
+//   • backend-client-state-cache.ts  — the AES-256-GCM `BackendStateCache` relay
+//
+// The contract types are *redeclared* in the contracts leaf (not imported from the backend package)
+// so the engine stays decoupled at the package level — there's no runtime nor build-time dep on the
+// backend. Drift is caught by the round-trip integration test that spins up a real stub.
+export * from "./backend-client-contracts.js";
+export * from "./backend-client-transport.js";
+export * from "./backend-client-token.js";
+export * from "./backend-client-oauth-login.js";
+export * from "./backend-client-state-cache.js";

package/dist/calibrate.d.ts

@@ -0,0 +1,31 @@
+import { type FlowFile } from "./doc-pack.js";
+export declare class CalibrateError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Extract a flow-file from a structured flow-guide. Accepts: the YAML of a flow-file directly, or a Markdown
+ * doc whose first ```yaml fenced block parses as one. Throws {@link CalibrateError} if neither works (which is
+ * the signal that the input is loose prose → use the calibrate skill / agent path instead).
+ */
+export declare function extractFlowFile(text: string, source?: string): FlowFile;
+export interface CalibrateOptions {
+    workspaceDir: string;
+    /** The flow-guide text. */
+    fromText: string;
+    /** Where it came from (for error messages). */
+    fromSource?: string;
+    /** Override the flow name (default: the flow-file's `name`). */
+    flowName?: string;
+}
+export interface CalibrateResult {
+    flow: FlowFile;
+    /** Path the flow-file was written to. */
+    flowFilePath: string;
+    /** Path of the style artifact (whether newly written or pre-existing). */
+    stylePath: string;
+    /** True if the style artifact was newly written (false if it already existed and was left alone). */
+    wroteStyle: boolean;
+}
+/** Run the deterministic calibration step: extract the flow-file from a structured guide, write it + a default style. */
+export declare function calibrate(opts: CalibrateOptions): Promise<CalibrateResult>;

package/dist/calibrate.js

@@ -0,0 +1,68 @@
+// Calibration — the deterministic, structured-input path.
+//
+// `docsxai calibrate <workspace> --from <flow.md|.yaml>` takes a *structured flow-guide* — a flow-file in
+// YAML, or a Markdown doc containing a ```yaml fenced block that parses as one (the the first-consumer testing guide
+// shape: prerequisites + locators reference + per-step actions + success criteria) — and writes it as
+// `<workspace>/flows/<name>.flow.yaml`, plus a default `docs/style.yaml` if absent. Then `docsxai run`
+// exercises it against the live app to fill in screenshots + bounding boxes + the real `annotations.json`.
+//
+// Loose-prose flow descriptions (and live element-picking / ambiguity resolution) need the host agent —
+// that's the `/docsxai:calibrate` *skill* (see packages/plugin/skills/calibrate/SKILL.md); ambiguity
+// signalling lives at the MCP/skill layer. This module covers only the part that's deterministic.
+import { promises as fs } from "node:fs";
+import { FlowFileError, parseFlowFile, serializeFlowFile } from "./flow-file.js";
+import { initStyleIfAbsent } from "./style.js";
+import { resolveWorkspacePath, resolveWorkspacePathReal } from "./workspace.js";
+export class CalibrateError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "CalibrateError";
+    }
+}
+const YAML_FENCE = /```ya?ml\s*\n([\s\S]*?)\n```/i;
+/**
+ * Extract a flow-file from a structured flow-guide. Accepts: the YAML of a flow-file directly, or a Markdown
+ * doc whose first ```yaml fenced block parses as one. Throws {@link CalibrateError} if neither works (which is
+ * the signal that the input is loose prose → use the calibrate skill / agent path instead).
+ */
+export function extractFlowFile(text, source = "<flow-guide>") {
+    // 1. The whole text as flow-file YAML.
+    try {
+        return parseFlowFile(text, source);
+    }
+    catch (e) {
+        if (!(e instanceof FlowFileError))
+            throw e;
+    }
+    // 2. A ```yaml fenced block.
+    const m = YAML_FENCE.exec(text);
+    if (m) {
+        try {
+            return parseFlowFile(m[1], `${source} (yaml block)`);
+        }
+        catch (e) {
+            if (e instanceof FlowFileError) {
+                throw new CalibrateError(`${source}: found a yaml block but it isn't a valid flow-file:\n${e.message}`, e);
+            }
+            throw e;
+        }
+    }
+    throw new CalibrateError(`${source}: not a structured flow-guide (no parseable flow-file YAML found).\n` +
+        `\`calibrate --from\` only takes a flow-file in YAML, or a Markdown doc with a \`\`\`yaml fenced block that *is* one.\n` +
+        `Loose prose — e.g. a hand-written test guide whose fenced blocks are numbered prose pseudo-steps for an agent\n` +
+        `to *test* rather than flow-file YAML — must be turned into a flow-file by hand: follow the /docsxai:calibrate skill\n` +
+        `(walk the live app via Claude in Chrome, pin one canonical locator per step), then \`calibrate --from\` it or just \`run\`.`);
+}
+/** Run the deterministic calibration step: extract the flow-file from a structured guide, write it + a default style. */
+export async function calibrate(opts) {
+    const flow = extractFlowFile(opts.fromText, opts.fromSource ?? "<flow-guide>");
+    const name = opts.flowName ?? flow.name;
+    await fs.mkdir(resolveWorkspacePath(opts.workspaceDir, "flows"), { recursive: true });
+    // The flow name is guide-supplied — resolve with the symlink-aware variant before writing.
+    const flowFilePath = await resolveWorkspacePathReal(opts.workspaceDir, "flows", `${name}.flow.yaml`);
+    await fs.writeFile(flowFilePath, serializeFlowFile(flow), "utf8");
+    const { paths, created } = await initStyleIfAbsent(opts.workspaceDir);
+    return { flow, flowFilePath, stylePath: paths.yamlPath, wroteStyle: created };
+}

package/dist/cli-commands-authoring.d.ts

@@ -0,0 +1,5 @@
+export declare function cmdInspect(args: string[]): Promise<number>;
+export declare function cmdLint(args: string[]): Promise<number>;
+export declare function cmdFlowTree(args: string[]): Promise<number>;
+export declare function cmdDiagnose(args: string[]): Promise<number>;
+export declare function cmdStyle(args: string[]): Promise<number>;