@docsxai/engine 0.2.0

package/dist/doc-pack.js

@@ -0,0 +1,328 @@
+// Doc-pack schema — the artifacts a calibration run produces and an execution run consumes.
+//
+// Layout on disk:
+//   <project>/flows/<flow>.flow.yaml          — flow-file (source of truth for execution)
+//   <project>/docs/<flow>/<step>.md           — step write-ups (user-facing prose)
+//   <project>/docs/<flow>/screenshots/<step>.png
+//   <project>/docs/<flow>/annotations.json    — per-step annotation records (this module's AnnotationsFile)
+//   <project>/docs/style.yaml + style.json    — style artifact (canonical + derived)
+//   <project>/docs/locators.yaml              — locator manifest (one canonical locator per step)
+//   <project>/auth/strategy.yaml              — target-site auth-strategy descriptor
+//
+// Runtime validation is done with zod; the exported TS types are inferred from the schemas
+// so the two never drift.
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
+export const ArrowStyle = z.enum([
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+    "top",
+    "bottom",
+    "left",
+    "right",
+]);
+/** A locator reference (`$play_button`) resolved against a flow-file's `locators` map, or an inline selector. */
+export const LocatorRef = z.string().min(1);
+// ---------------------------------------------------------------------------
+// Flow-file (`<flow>.flow.yaml`)
+// ---------------------------------------------------------------------------
+export const ActionType = z.enum([
+    "navigate",
+    "click",
+    "fill",
+    "upload",
+    "press",
+    "hover",
+    "select",
+    "check",
+    "uncheck",
+    "wait",
+]);
+/**
+ * What to wait for after a step's action settles. `network_idle` / `element_stable` / `load` are named
+ * primitives; `{ selector }` waits for an element to appear (Playwright's default timeout, ~30s) — give it
+ * `timeout_ms` to override that (e.g. waiting on a multi-minute backend op that mounts a "done" element);
+ * `{ timeout_ms }` alone is a blind sleep (last resort — for animations, not state).
+ */
+export const WaitSpec = z.union([
+    z.enum(["network_idle", "element_stable", "load"]),
+    z.object({ timeout_ms: z.number().int().positive() }).strict(),
+    z.object({ selector: LocatorRef, timeout_ms: z.number().int().positive().optional() }).strict(),
+]);
+/** Post-step success criterion. Execution halts if it fails (no selector fallbacks — drift is a signal). */
+export const SuccessSpec = z.union([
+    z.object({ visible: LocatorRef }).strict(),
+    z.object({ hidden: LocatorRef }).strict(),
+    z.object({ url_matches: z.string().min(1) }).strict(),
+    z
+        .object({ text_contains: z.object({ selector: LocatorRef, text: z.string() }).strict() })
+        .strict(),
+]);
+export const NudgeOffset = z.object({ x: z.number(), y: z.number() }).strict();
+// ---------------------------------------------------------------------------
+// Execution environment (`environment:` block)
+// ---------------------------------------------------------------------------
+export const ViewportSize = z
+    .object({ width: z.number().int().positive(), height: z.number().int().positive() })
+    .strict();
+export const ViewportPreset = z.enum(["desktop", "tablet", "mobile"]);
+/** Named viewport presets — `desktop` 1440×900, `tablet` 834×1112, `mobile` 390×844. */
+export const VIEWPORT_PRESETS = {
+    desktop: { width: 1440, height: 900 },
+    tablet: { width: 834, height: 1112 },
+    mobile: { width: 390, height: 844 },
+};
+/**
+ * Deterministic execution environment for a flow. All fields optional; applied at browser-context
+ * creation (so the whole flow runs under them). With `extends`, the child flow's `environment`
+ * wins per-key over the parent's (a child can pin just `viewport` and inherit the parent's clock).
+ */
+export const EnvironmentSpec = z
+    .object({
+    /** ISO-8601 instant the page clock is frozen at — `new Date()` etc. return this for the whole run. */
+    clock: z.string().datetime({ offset: true, local: true }).optional(),
+    /** BCP-47 language tag (e.g. `en-GB`). */
+    locale: z
+        .string()
+        .regex(/^[A-Za-z]{2,3}(-[A-Za-z0-9]+)*$/, "must be a BCP-47 language tag (e.g. en-GB)")
+        .optional(),
+    /** IANA timezone (e.g. `Europe/Amsterdam`). */
+    timezone: z.string().min(1).optional(),
+    /** `{ width, height }` in CSS pixels, or a named preset — see {@link VIEWPORT_PRESETS}. */
+    viewport: z.union([ViewportPreset, ViewportSize]).optional(),
+    color_scheme: z.enum(["light", "dark"]).optional(),
+    reduced_motion: z.boolean().optional(),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Redactions (`redactions:` — flow-level and per-step)
+// ---------------------------------------------------------------------------
+export const RedactionStyle = z.enum(["box", "pixelate"]);
+/** A fixed rectangle in CSS pixels (viewport coordinates), scaled to device pixels at capture time. */
+export const RedactionRegion = z
+    .object({
+    x: z.number().min(0),
+    y: z.number().min(0),
+    width: z.number().positive(),
+    height: z.number().positive(),
+})
+    .strict();
+/**
+ * One area to mask on every screenshot it applies to (step shots *and* halt shots): either an
+ * element (locator ref / inline selector, resolved to its bounding box at capture time) or a fixed
+ * `region`. Default `style` is `box` (solid #000 fill); `pixelate` is a 16-px mosaic. A selector
+ * that matches nothing at capture time is skipped with a stderr warning — redacting an absent
+ * element is vacuously satisfied, never a halt. Flow-level `redactions` apply to every step;
+ * per-step `redactions` are additive.
+ */
+export const RedactionSpec = z.union([
+    z.object({ selector: LocatorRef, style: RedactionStyle.optional() }).strict(),
+    z.object({ region: RedactionRegion, style: RedactionStyle.optional() }).strict(),
+]);
+export const StepAnnotation = z
+    .object({
+    copy: z.string().min(1),
+    arrow: ArrowStyle.optional(),
+    /**
+     * Optional pixel offset applied to the callout + arrow after Popper-like placement. The halo (which
+     * highlights the target element) stays on the target. Use this when two annotations on the same
+     * screenshot would otherwise overlap each other — nudge one aside so both are readable.
+     * Image-space pixels; small values (5–40 px in either direction) typically suffice.
+     */
+    nudge: NudgeOffset.optional(),
+    /**
+     * Optional override: the locator to anchor the halo/arrow to. Default = the step's `target`. Use this on
+     * a step whose action *transitions the UI* — the action target vanishes (gets unmounted / replaced) and
+     * a *different* element is what you want to highlight in the resulting state. Point this at the
+     * surviving / appearing element.
+     */
+    target: LocatorRef.optional(),
+})
+    .strict();
+export const Step = z
+    .object({
+    id: z.string().min(1),
+    action: ActionType,
+    /**
+     * Best-effort step: if the action / `wait_for` / `success` check throws (target absent, wait timed
+     * out, etc.), **skip this step and continue** instead of halting the flow. For conditionally-present
+     * UI — a confirmation modal that sometimes appears, a first-run tooltip, a cookie banner. A skipped
+     * optional step emits no screenshot / annotation (same as a step skipped by `--start-from`). Prefer
+     * this over a permissive comma-selector that no-ops on one branch.
+     */
+    optional: z.boolean().optional(),
+    /** Locator ref (`$name`) or inline selector. Optional for actions like `navigate` (uses `value`) or `wait`. */
+    target: LocatorRef.optional(),
+    /** Action payload: text for `fill`, file path for `upload`, key for `press`, path/URL for `navigate`, option for `select`. */
+    value: z.string().optional(),
+    wait_for: WaitSpec.optional(),
+    success: SuccessSpec.optional(),
+    /** Single call-out on this step's screenshot. Shorthand for a one-element `annotations` array. */
+    annotation: StepAnnotation.optional(),
+    /**
+     * Multiple call-outs on the same screenshot — rendered as numbered badges (1, 2, …) so the reader sees
+     * up front that there's more than one thing to look at without having to hover everything. Each entry
+     * has its own `target` (defaults to the step's `target`) and `copy` / `arrow` — see {@link StepAnnotation}.
+     * Mutually exclusive with `annotation`.
+     */
+    annotations: z.array(StepAnnotation).min(1).optional(),
+    /** Extra redactions for this step's screenshots, additive on top of the flow-level list. */
+    redactions: z.array(RedactionSpec).min(1).optional(),
+})
+    .strict()
+    .refine((s) => !(s.annotation && s.annotations), {
+    message: "step has both `annotation` and `annotations`; use one (`annotations: [...]` for the multi-callout form)",
+    path: ["annotations"],
+});
+/** A precondition the flow assumes (e.g. `{ logged_in_as: "editor" }`, `{ feature_flag: "recap.enabled" }`). */
+export const Prerequisite = z.record(z.string(), z.union([z.string(), z.boolean()]));
+export const FlowFile = z
+    .object({
+    name: z.string().min(1),
+    /**
+     * Name of another flow whose steps run *first* (composition). The parent's `locators` + `prerequisites`
+     * are merged in (this flow wins on collisions); step ids must be unique across the merge. Chains allowed
+     * (A extends B extends C); cycles are rejected. Resolved at run time against `flows/<name>.flow.yaml`.
+     * Typical use: factor out a shared preamble (Library → open a video → editor) so dependent flows don't
+     * re-walk it every run. (`run --stop-after` operates on the merged step list.)
+     */
+    extends: z.string().min(1).optional(),
+    /**
+     * Deterministic execution environment (frozen clock, locale, timezone, viewport, color scheme,
+     * reduced motion). With `extends`, merged per-key — this flow's keys win over the parent's.
+     */
+    environment: EnvironmentSpec.optional(),
+    /** Areas masked on every screenshot this flow produces (incl. halt shots). See {@link RedactionSpec}. */
+    redactions: z.array(RedactionSpec).min(1).optional(),
+    prerequisites: z.array(Prerequisite).default([]),
+    /** Named canonical locators referenced from steps as `$name`. One per name; no fallback lists. */
+    locators: z.record(z.string(), z.string()).default({}),
+    steps: z.array(Step).min(1),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Annotations (`<flow>/annotations.json`)
+// ---------------------------------------------------------------------------
+export const BoundingBox = z
+    .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+    .strict();
+export const AnnotationRecord = z
+    .object({
+    step: z.string().min(1),
+    selector: z.string().min(1),
+    bounding_box: BoundingBox.optional(),
+    copy: z.string().min(1),
+    arrow_style: ArrowStyle.optional(),
+    /** Optional pixel offset applied to the callout + arrow at render time — see {@link NudgeOffset}. */
+    nudge: NudgeOffset.optional(),
+    /** 1-based index of this annotation *within its step's screenshot* — set only when the step has > 1 annotation, so the viewer can render a numbered badge. Absent → render as a plain (un-numbered) halo. */
+    index: z.number().int().positive().optional(),
+})
+    .strict();
+export const AnnotationsFile = z
+    .object({
+    schema: z.literal("docsxai/annotations@1"),
+    flow: z.string().min(1),
+    annotations: z.array(AnnotationRecord),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Style artifact (`style.yaml` canonical → `style.json` derived)
+// ---------------------------------------------------------------------------
+export const StyleArtifact = z
+    .object({
+    schema: z.literal("docsxai/style@1"),
+    voice: z.record(z.string(), z.unknown()).optional(),
+    structure: z.record(z.string(), z.unknown()).optional(),
+    terminology: z.record(z.string(), z.string()).optional(),
+    visual: z.record(z.string(), z.unknown()).optional(),
+    localisation: z.record(z.string(), z.unknown()).optional(),
+    /** Categories of testing-jargon the commit stage must strip from user-facing prose. */
+    pruning_rules: z.array(z.string()).optional(),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Locator manifest (`locators.yaml`)
+// ---------------------------------------------------------------------------
+export const LocatorManifest = z
+    .object({
+    schema: z.literal("docsxai/locators@1"),
+    /** flow name → locator name → canonical selector. One per name; no fallbacks. */
+    flows: z.record(z.string(), z.record(z.string(), z.string())),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Auth-strategy descriptor (`auth/strategy.yaml`)
+// ---------------------------------------------------------------------------
+export const StrategyName = z.enum([
+    "api-login",
+    "jwt-injection",
+    "ui-form",
+    "http-basic",
+    "mtls",
+    "pat-header",
+    "email-otp",
+    "totp",
+    "webauthn",
+    "manual-capture",
+    "test-backdoor",
+]);
+/** `session` = use the captured session's own lifetime; otherwise a duration string (`30m`, `1h`) or ms number. */
+export const CacheTtl = z.union([
+    z.literal("session"),
+    z.string().regex(/^\d+(ms|s|m|h)$/),
+    z.number().int().positive(),
+]);
+export const RoleAuth = z
+    .object({
+    strategy: StrategyName,
+    /** Env-var *names* holding credentials — never the values. May be `{}` (e.g. `manual-capture` needs none). */
+    creds_env: z.record(z.string(), z.string()).default({}),
+    options: z.record(z.string(), z.unknown()).default({}),
+    cache: z
+        .object({
+        enabled: z.boolean().default(false),
+        store: z.enum(["local", "backend"]).default("local"),
+        /** Fallback expiry when no `auth_cookie` is set/found: a duration, or `session` (→ a 1h default). */
+        ttl: CacheTtl.default("session"),
+        /**
+         * Name of the app's actual auth/session cookie. When set, the cached session's `expiresAt` is *that*
+         * cookie's expiry — the real bound — rather than the `ttl` guess. Identify it from the captured jar
+         * (`capture-auth` prints it): it's on the app's domain, long-lived (not an ephemeral IdP scratch
+         * cookie), e.g. `AppSession.Production` / `.AspNetCore.Cookies` / `session`. Optional.
+         */
+        auth_cookie: z.string().min(1).optional(),
+    })
+        .strict()
+        .default({ enabled: false, store: "local", ttl: "session" }),
+})
+    .strict();
+export const AuthStrategyDescriptor = z
+    .object({
+    schema: z.literal("docsxai/auth-strategy@1"),
+    default_role: z.string().min(1),
+    roles: z.record(z.string(), RoleAuth),
+})
+    .strict()
+    .refine((d) => d.default_role in d.roles, {
+    message: "default_role must be one of the keys in roles",
+    path: ["default_role"],
+});
+// ---------------------------------------------------------------------------
+// Revision metadata (linear immutable revisions per project)
+// ---------------------------------------------------------------------------
+export const RevisionKind = z.enum(["calibrate", "run", "edit"]);
+export const RevisionMeta = z
+    .object({
+    rev_id: z.string().min(1),
+    parent_rev_id: z.string().min(1).nullable(),
+    kind: RevisionKind,
+    author: z.string().min(1),
+    /** ISO-8601 timestamp. */
+    timestamp: z.string().min(1),
+})
+    .strict();

package/dist/doctor-checks-plugins.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "./doctor-checks.js";
+export declare function checkPlugins(workspaceDir: string): Promise<DoctorCheck[]>;

package/dist/doctor-checks-plugins.js

@@ -0,0 +1,136 @@
+// docsxai doctor - the plugin-runtime probe. Split out of doctor-checks.ts: the
+// plugin config / lock / manifest checking is a distinct, sizeable concern from
+// the environment and workspace-content probes, with its own dependency set
+// (the plugin runtime + lock + manifest domain).
+import { promises as fs } from "node:fs";
+import { isApiVersionCompatible, RUNTIME_API_VERSION } from "./plugins/manifest.js";
+import { PLUGINS_LOCK_FILE, PluginsConfigError, PluginsLockError, readPluginsLock, readWorkspacePluginsConfig, verifyLock, } from "./plugins/lock.js";
+import { resolvePluginSources } from "./plugins/runtime.js";
+import { WORKSPACE_CONFIG_FILE } from "./workspace.js";
+export async function checkPlugins(workspaceDir) {
+    let cfg;
+    try {
+        cfg = await readWorkspacePluginsConfig(workspaceDir);
+    }
+    catch (e) {
+        if (e instanceof PluginsConfigError) {
+            return [
+                {
+                    name: "plugins",
+                    ok: false,
+                    detail: e.message,
+                    fix: `fix the "plugins" / "plugin_capabilities" keys in ${WORKSPACE_CONFIG_FILE}`,
+                },
+            ];
+        }
+        throw e;
+    }
+    if (cfg.sources.length === 0) {
+        return [
+            {
+                name: "plugins",
+                ok: true,
+                info: true,
+                detail: `no plugins configured (add a "plugins" array to ${WORKSPACE_CONFIG_FILE})`,
+            },
+        ];
+    }
+    let lock;
+    try {
+        lock = await readPluginsLock(workspaceDir);
+    }
+    catch (e) {
+        if (e instanceof PluginsLockError) {
+            return [
+                {
+                    name: "plugins",
+                    ok: false,
+                    detail: e.message,
+                    fix: `re-pin: docsxai plugins sync ${workspaceDir}`,
+                },
+            ];
+        }
+        throw e;
+    }
+    const checks = [];
+    if (!lock) {
+        checks.push({
+            name: "plugins",
+            ok: false,
+            detail: `${PLUGINS_LOCK_FILE} missing (${cfg.sources.length} plugin(s) configured — no reproducibility pin)`,
+            fix: `docsxai plugins sync ${workspaceDir}`,
+        });
+    }
+    const resolutions = await resolvePluginSources(workspaceDir, cfg.sources);
+    const enabled = new Set(cfg.capabilities);
+    const namespaceOwner = new Map();
+    for (const r of resolutions) {
+        if (!r.ok) {
+            checks.push({
+                name: "plugins",
+                ok: false,
+                detail: `${r.record.name}: ${r.record.statusReason ?? "unresolvable"}`,
+                fix: `fix the source entry in ${WORKSPACE_CONFIG_FILE} (or install the package), then \`docsxai plugins sync\``,
+            });
+            continue;
+        }
+        const c = r.candidate;
+        const ns = c.manifest.namespace;
+        const issues = [];
+        if (!isApiVersionCompatible(c.manifest.apiVersion)) {
+            issues.push({
+                detail: `${c.name} apiVersion "${c.manifest.apiVersion}" incompatible with runtime apiVersion "${RUNTIME_API_VERSION}"`,
+                fix: "upgrade the plugin or the engine (same major, plugin minor ≤ runtime)",
+            });
+        }
+        const prior = namespaceOwner.get(ns);
+        if (prior) {
+            issues.push({
+                detail: `${c.name} namespace "${ns}" already claimed by ${prior} — neither will load`,
+                fix: "namespaces are unique across the configured set; rename one",
+            });
+        }
+        else {
+            namespaceOwner.set(ns, c.name);
+        }
+        let lockNote = "no lock";
+        if (lock) {
+            let bytes;
+            try {
+                bytes = await fs.readFile(c.registerPath);
+            }
+            catch {
+                bytes = null;
+            }
+            const mismatch = verifyLock(lock, ns, bytes);
+            if (mismatch) {
+                issues.push({
+                    detail: mismatch,
+                    fix: `after auditing the change: docsxai plugins sync ${workspaceDir}`,
+                });
+            }
+            else {
+                lockNote = "lock ok";
+            }
+        }
+        const missingCaps = c.manifest.capabilities.filter((cap) => !enabled.has(cap));
+        if (missingCaps.length > 0) {
+            issues.push({
+                detail: `${c.name} declares capability(ies) [${missingCaps.join(", ")}] not enabled for this workspace`,
+                fix: `opt in via "plugin_capabilities" in ${WORKSPACE_CONFIG_FILE}`,
+            });
+        }
+        if (issues.length > 0) {
+            for (const i of issues)
+                checks.push({ name: "plugins", ok: false, ...i });
+        }
+        else {
+            checks.push({
+                name: "plugins",
+                ok: true,
+                detail: `${c.name}@${c.version} (ns=${ns}, ${c.manifest.kinds.join(",")}, ${lockNote})`,
+            });
+        }
+    }
+    return checks;
+}

package/dist/doctor-checks.d.ts

@@ -0,0 +1,56 @@
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    fix?: string;
+    /** Informational row — printed with − instead of ✓/✗; never fails doctor. */
+    info?: boolean;
+}
+export interface DoctorOptions {
+    /** Workspace dir to inspect. Default: the current working directory. */
+    workspaceDir?: string;
+    /** Env source (tests inject). Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Node version under test (tests inject). Default `process.versions.node`. */
+    nodeVersion?: string;
+    /** Chromium probe override (tests inject; the real probe asks playwright-core). */
+    chromiumProbe?: () => Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** fetch override for the backend health probe (tests inject). */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Clock override for session-freshness checks (tests inject). */
+    now?: number;
+}
+/** Layer-3 default probe: does playwright-core have a cached Chromium binary?
+ *  Synchronous - the sole work is the sanctioned `chromiumExecutablePath()`
+ *  helper (a sync `executablePath()` + `existsSync`), no IO to await. */
+export declare function probeChromium(): {
+    ok: boolean;
+    detail: string;
+};
+export declare function checkNode(nodeVersion: string): DoctorCheck;
+export declare function checkChromium(probe: () => {
+    ok: boolean;
+    detail: string;
+} | Promise<{
+    ok: boolean;
+    detail: string;
+}>): Promise<DoctorCheck>;
+interface WorkspaceProbe {
+    check: DoctorCheck;
+    /** Parsed `.docsxai.json` when valid (doctor reads the raw JSON — schema-checked here). */
+    config: Record<string, unknown> | null;
+    /** True when the dir looks like a workspace at all (config file or flows/ present). */
+    present: boolean;
+}
+export declare function checkWorkspace(workspaceDir: string): Promise<WorkspaceProbe>;
+export declare function checkFlows(workspaceDir: string): Promise<DoctorCheck>;
+export declare function checkAuth(workspaceDir: string, now: number): Promise<DoctorCheck[]>;
+export declare function checkBackend(workspaceDir: string, config: Record<string, unknown> | null, env: NodeJS.ProcessEnv, fetchImpl: typeof globalThis.fetch): Promise<DoctorCheck>;
+export declare function checkViewer(env: NodeJS.ProcessEnv, resolveFrom?: string[]): Promise<DoctorCheck>;
+/** DOCSX_* env vars the docsxai packages read (engine + backend). */
+export declare const KNOWN_DOCSX_ENV_VARS: ReadonlyArray<string>;
+export declare function checkEnv(env: NodeJS.ProcessEnv): DoctorCheck[];
+export {};