@docsxai/engine 0.2.0

package/dist/flow-file.js

@@ -0,0 +1,180 @@
+// Flow-file (`.flow.yaml`) parsing, validation, and serialization.
+//
+// A flow-file is the source of truth for execution: declarative YAML, hand-editable,
+// translated to Playwright at run time (see flow-runtime, to come). This module is the
+// parse/validate/serialize boundary — everything downstream works with the validated
+// `FlowFile` value, never raw YAML.
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { FlowFile } from "./doc-pack.js";
+export class FlowFileError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "FlowFileError";
+    }
+}
+function formatZodIssues(err) {
+    return err.issues
+        .map((i) => {
+        const path = i.path.length ? i.path.join(".") : "(root)";
+        return `  • ${path}: ${i.message}`;
+    })
+        .join("\n");
+}
+/** Parse + validate a flow-file from YAML text. Throws {@link FlowFileError} with a readable message on failure. */
+export function parseFlowFile(yamlText, source = "<flow-file>") {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (e) {
+        throw new FlowFileError(`${source}: not valid YAML — ${e.message}`, e);
+    }
+    const result = FlowFile.safeParse(raw);
+    if (!result.success) {
+        throw new FlowFileError(`${source}: invalid flow-file:\n${formatZodIssues(result.error)}`, result.error);
+    }
+    const flow = result.data;
+    // A flow with `extends` may reference locators it inherits from the parent — defer the ref check to
+    // `resolveFlowExtends`, which runs it on the merged flow.
+    if (!flow.extends)
+        assertLocatorRefsResolve(flow, source);
+    assertStepIdsUnique(flow, source);
+    return flow;
+}
+/** Serialize a {@link FlowFile} back to canonical YAML. */
+export function serializeFlowFile(flow) {
+    // Validate on the way out too, so we never write a malformed file.
+    const checked = FlowFile.parse(flow);
+    return stringifyYaml(checked, { lineWidth: 100 });
+}
+const LOCATOR_REF = /^\$([A-Za-z_][A-Za-z0-9_]*)$/;
+/** Returns the locator name if `value` is a `$name` reference, else `null` (it's an inline selector). */
+export function locatorRefName(value) {
+    const m = LOCATOR_REF.exec(value);
+    return m ? m[1] : null;
+}
+function collectLocatorRefs(step) {
+    const refs = [];
+    const push = (v) => {
+        if (v) {
+            const name = locatorRefName(v);
+            if (name)
+                refs.push(name);
+        }
+    };
+    push(step.target);
+    if (step.wait_for && typeof step.wait_for === "object" && "selector" in step.wait_for)
+        push(step.wait_for.selector);
+    if (step.success) {
+        if ("visible" in step.success)
+            push(step.success.visible);
+        else if ("hidden" in step.success)
+            push(step.success.hidden);
+        else if ("text_contains" in step.success)
+            push(step.success.text_contains.selector);
+    }
+    if (step.annotation?.target)
+        push(step.annotation.target);
+    if (step.annotations)
+        for (const a of step.annotations)
+            if (a.target)
+                push(a.target);
+    if (step.redactions)
+        for (const r of step.redactions)
+            if ("selector" in r)
+                push(r.selector);
+    return refs;
+}
+/** Locator names referenced anywhere in `flow` (steps + flow-level redactions); inline selectors excluded. */
+export function referencedLocatorNames(flow) {
+    const refs = new Set();
+    for (const step of flow.steps)
+        for (const ref of collectLocatorRefs(step))
+            refs.add(ref);
+    for (const r of flow.redactions ?? []) {
+        if ("selector" in r) {
+            const name = locatorRefName(r.selector);
+            if (name)
+                refs.add(name);
+        }
+    }
+    return refs;
+}
+function assertLocatorRefsResolve(flow, source) {
+    const known = new Set(Object.keys(flow.locators));
+    const missing = [];
+    for (const step of flow.steps) {
+        for (const ref of collectLocatorRefs(step)) {
+            if (!known.has(ref))
+                missing.push(`step "${step.id}" → $${ref}`);
+        }
+    }
+    for (const r of flow.redactions ?? []) {
+        if ("selector" in r) {
+            const name = locatorRefName(r.selector);
+            if (name && !known.has(name))
+                missing.push(`redactions → $${name}`);
+        }
+    }
+    if (missing.length) {
+        throw new FlowFileError(`${source}: unresolved locator references (not in \`locators\`):\n${missing.map((m) => `  • ${m}`).join("\n")}`);
+    }
+}
+function assertStepIdsUnique(flow, source) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const step of flow.steps) {
+        if (seen.has(step.id))
+            dupes.add(step.id);
+        seen.add(step.id);
+    }
+    if (dupes.size) {
+        throw new FlowFileError(`${source}: duplicate step ids: ${[...dupes].map((d) => `"${d}"`).join(", ")}`);
+    }
+}
+/**
+ * Resolve a flow's `extends` chain into a single flow: parent's steps first, then this flow's. `locators` and
+ * `prerequisites` are merged (this flow wins on locator-name collisions); `environment` merges per-key with
+ * this flow's keys winning; `redactions` concatenate (parent's first); step ids must be unique across the
+ * merge. Chains are followed recursively; cycles throw. `loadFlowFile(name)` parses `flows/<name>.flow.yaml`
+ * (a flow with its own `extends` un-resolved — this function recurses). The result has no `extends`.
+ */
+export async function resolveFlowExtends(flow, loadFlowFile, visited = new Set()) {
+    if (!flow.extends)
+        return flow;
+    if (visited.has(flow.name)) {
+        throw new FlowFileError(`flow "${flow.name}": \`extends\` cycle (chain: ${[...visited, flow.name].join(" → ")})`);
+    }
+    visited.add(flow.name);
+    let parentRaw;
+    try {
+        parentRaw = await loadFlowFile(flow.extends);
+    }
+    catch (e) {
+        throw e instanceof FlowFileError
+            ? e
+            : new FlowFileError(`flow "${flow.name}": cannot load \`extends\` target "${flow.extends}": ${e.message}`, e);
+    }
+    const parent = await resolveFlowExtends(parentRaw, loadFlowFile, visited);
+    const parentStepIds = new Set(parent.steps.map((s) => s.id));
+    for (const s of flow.steps) {
+        if (parentStepIds.has(s.id)) {
+            throw new FlowFileError(`flow "${flow.name}": step id "${s.id}" collides with a step inherited via \`extends\` from "${flow.extends}"`);
+        }
+    }
+    // `environment` merges per-key (this flow wins); `redactions` are additive, parent's first.
+    const environment = { ...parent.environment, ...flow.environment };
+    const redactions = [...(parent.redactions ?? []), ...(flow.redactions ?? [])];
+    const merged = {
+        name: flow.name,
+        ...(Object.keys(environment).length ? { environment } : {}),
+        ...(redactions.length ? { redactions } : {}),
+        prerequisites: [...parent.prerequisites, ...flow.prerequisites],
+        locators: { ...parent.locators, ...flow.locators },
+        steps: [...parent.steps, ...flow.steps],
+    };
+    assertLocatorRefsResolve(merged, `<resolved flow "${flow.name}">`);
+    return merged;
+}

package/dist/flow-lint.d.ts

@@ -0,0 +1,24 @@
+import type { FlowFile } from "./doc-pack.js";
+export type LintSeverity = "error" | "warning" | "info";
+export type LintIssue = {
+    code: string;
+    severity: LintSeverity;
+    flow: string;
+    stepId?: string;
+    message: string;
+    suggestion?: string;
+};
+/** An injectable lint rule — the open hinge for the plugins runtime. Runs after the built-ins. */
+export type LintRule = {
+    /** Stable diagnostic code (the built-ins use `RNNN`; injected rules should pick another prefix). */
+    code: string;
+    run: (flow: FlowFile, opts: LintOptions) => Promise<LintIssue[]> | LintIssue[];
+};
+export type LintOptions = {
+    /** Resolver for `extends` (used by R001/R005). If omitted, inter-flow rules are skipped. */
+    loadFlow?: (name: string) => Promise<FlowFile> | FlowFile;
+    /** Additional rules run after the built-ins (same flow, same options). */
+    extraRules?: LintRule[];
+};
+export declare function lintFlow(flow: FlowFile, opts?: LintOptions): Promise<LintIssue[]>;
+export declare function formatIssuesText(issues: LintIssue[]): string;

package/dist/flow-lint.js

@@ -0,0 +1,203 @@
+// Static analysis of flow-files. Catches common authoring mistakes at write-time, before a run.
+// Pure-static — no Playwright, no live page. Run via `docsxai lint`.
+import { locatorRefName, referencedLocatorNames } from "./flow-file.js";
+/** Heuristic — names that suggest a step kicks off a multi-minute backend op. */
+const LONG_ASYNC = /generate|create|process|submit|upload|translate|render|publish|export/i;
+/** A "bare" data-attribute selector like `[data-foo="x"]` with no further qualifier. */
+const BARE_DATA_ATTR = /^\[data-[a-z][a-z0-9-]*="[^"]+"\]$/;
+const DEEP_CHAIN_THRESHOLD = 4;
+export async function lintFlow(flow, opts = {}) {
+    const issues = [];
+    // R001 — extends chain depth; R005 — extends target missing
+    if (opts.loadFlow && flow.extends) {
+        const chain = await walkChain(flow, opts.loadFlow);
+        if (chain.missing !== undefined) {
+            issues.push({
+                code: "R005",
+                severity: "error",
+                flow: flow.name,
+                message: `\`extends: ${chain.missing}\` names a flow that doesn't exist in the workspace`,
+                suggestion: "fix the name, or create flows/" + chain.missing + ".flow.yaml",
+            });
+        }
+        else if (chain.depth >= DEEP_CHAIN_THRESHOLD) {
+            issues.push({
+                code: "R001",
+                severity: "info",
+                flow: flow.name,
+                message: `extends chain depth is ${chain.depth}`,
+                suggestion: "consider flattening — deep chains add per-run setup cost and obscure the step order",
+            });
+        }
+    }
+    // R006 — locator defined but never referenced
+    const referenced = referencedLocatorNames(flow);
+    for (const name of Object.keys(flow.locators)) {
+        if (!referenced.has(name)) {
+            issues.push({
+                code: "R006",
+                severity: "info",
+                flow: flow.name,
+                message: `locator \`${name}\` is defined but never referenced by any step, wait, success, annotation, or redaction`,
+                suggestion: "remove it — unless a child flow references it via `extends` (references in children count only in the child)",
+            });
+        }
+    }
+    // R007 — terminal step lacks `success` (with `extends`, this flow's steps run last, so its
+    // final step IS the merged flow's terminal step)
+    const lastStep = flow.steps[flow.steps.length - 1];
+    if (lastStep && !lastStep.success) {
+        issues.push({
+            code: "R007",
+            severity: "warning",
+            flow: flow.name,
+            stepId: lastStep.id,
+            message: "the flow's terminal step has no `success` criterion — the run can end without verifying the end state",
+            suggestion: "add `success: { visible: $… }` (or url_matches / text_contains) to the last step",
+        });
+    }
+    // Resolve a `$ref` to its selector for same-element comparison; an un-resolvable ref (e.g.
+    // inherited from an `extends` parent) compares by its raw `$name`, which still matches itself.
+    const resolveMaybe = (v) => {
+        const name = locatorRefName(v);
+        return name ? (flow.locators[name] ?? v) : v;
+    };
+    const flowRedactionSelectors = new Set((flow.redactions ?? []).flatMap((r) => ("selector" in r ? [resolveMaybe(r.selector)] : [])));
+    for (const step of flow.steps) {
+        const anns = step.annotation ? [step.annotation] : (step.annotations ?? []);
+        // R002 — annotation anchored to a likely-unmounting action target
+        if (anns.length && (step.action === "click" || step.action === "navigate") && step.target) {
+            const anyWithoutOverride = anns.some((a) => !a.target);
+            if (anyWithoutOverride) {
+                issues.push({
+                    code: "R002",
+                    severity: "warning",
+                    flow: flow.name,
+                    stepId: step.id,
+                    message: `annotation has no \`target\` override on a \`${step.action}\` action; if the action unmounts its target, the halo will have nothing to anchor to`,
+                    suggestion: "set `annotation.target` (or `annotations[].target`) to an element that exists in the resulting state",
+                });
+            }
+        }
+        // R003 — wait_for object form without timeout_ms on a long-async-looking step
+        const w = step.wait_for;
+        if (w && typeof w === "object" && !Array.isArray(w) && "selector" in w && !w.timeout_ms) {
+            const targetText = step.target ? (locatorRefName(step.target) ?? step.target) : "";
+            if (LONG_ASYNC.test(step.id) || LONG_ASYNC.test(targetText)) {
+                issues.push({
+                    code: "R003",
+                    severity: "warning",
+                    flow: flow.name,
+                    stepId: step.id,
+                    message: `wait_for has no timeout_ms but the step looks long-async (keyword match)`,
+                    suggestion: "add `timeout_ms: 180000` (or higher for multi-minute backend ops)",
+                });
+            }
+        }
+        // R004 — bare `[data-*=…]` selector — may have hidden duplicates
+        if (step.target) {
+            const sel = step.target.startsWith("$")
+                ? flow.locators[locatorRefName(step.target) ?? ""]
+                : step.target;
+            if (sel && BARE_DATA_ATTR.test(sel)) {
+                issues.push({
+                    code: "R004",
+                    severity: "info",
+                    flow: flow.name,
+                    stepId: step.id,
+                    message: `selector \`${sel}\` is a bare \`[data-*=…]\` match — may resolve to multiple DOM nodes (visible + hidden duplicate)`,
+                    suggestion: "if duplicates exist, scope with `:visible` or add a `:has-text(...)` qualifier",
+                });
+            }
+        }
+        // R008 — un-guarded optional step
+        if (step.optional && !step.wait_for && !step.success) {
+            issues.push({
+                code: "R008",
+                severity: "warning",
+                flow: flow.name,
+                stepId: step.id,
+                message: "`optional: true` with no `wait_for` or `success` — every failure is silently swallowed, so a real regression on this step would be masked",
+                suggestion: "add a `wait_for: { selector: … }` or a `success:` check to make the presence test explicit",
+            });
+        }
+        // R009 — element_stable with no selector context (a no-op)
+        if (step.wait_for === "element_stable" && !step.target) {
+            issues.push({
+                code: "R009",
+                severity: "warning",
+                flow: flow.name,
+                stepId: step.id,
+                message: "`wait_for: element_stable` has no selector context (the step has no `target`) — it waits on nothing",
+                suggestion: "give the step a `target`, or wait on a concrete element with `wait_for: { selector: $x }`",
+            });
+        }
+        // R010 — annotation anchored to a redacted element (the call-out would point at a black box)
+        const stepRedactionSelectors = new Set([
+            ...flowRedactionSelectors,
+            ...(step.redactions ?? []).flatMap((r) => "selector" in r ? [resolveMaybe(r.selector)] : []),
+        ]);
+        if (stepRedactionSelectors.size) {
+            for (const ann of anns) {
+                const anchor = ann.target ?? step.target;
+                if (anchor && stepRedactionSelectors.has(resolveMaybe(anchor))) {
+                    issues.push({
+                        code: "R010",
+                        severity: "warning",
+                        flow: flow.name,
+                        stepId: step.id,
+                        message: `annotation is anchored to \`${anchor}\`, which a redaction on this step masks — the call-out would point at a black box`,
+                        suggestion: "anchor the annotation to a different element, or drop the redaction",
+                    });
+                }
+            }
+        }
+    }
+    for (const rule of opts.extraRules ?? []) {
+        issues.push(...(await rule.run(flow, opts)));
+    }
+    return issues;
+}
+async function walkChain(flow, load) {
+    let depth = 1;
+    let cur = flow;
+    const seen = new Set([flow.name]);
+    while (cur.extends) {
+        if (seen.has(cur.extends))
+            return { depth };
+        seen.add(cur.extends);
+        try {
+            cur = await load(cur.extends);
+        }
+        catch {
+            return { depth, missing: cur.extends };
+        }
+        depth++;
+    }
+    return { depth };
+}
+export function formatIssuesText(issues) {
+    if (issues.length === 0)
+        return "✓ no issues\n";
+    const byFlow = new Map();
+    for (const i of issues) {
+        const list = byFlow.get(i.flow) ?? [];
+        list.push(i);
+        byFlow.set(i.flow, list);
+    }
+    let out = "";
+    for (const [flow, list] of byFlow) {
+        out += `flow ${flow}\n`;
+        for (const i of list) {
+            const where = i.stepId ? `step '${i.stepId}': ` : "";
+            out += `  ${i.code} [${i.severity}] ${where}${i.message}\n`;
+            if (i.suggestion)
+                out += `    → ${i.suggestion}\n`;
+        }
+    }
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+    const infos = issues.filter((i) => i.severity === "info").length;
+    out += `\n${errors} error${errors !== 1 ? "s" : ""}, ${warnings} warning${warnings !== 1 ? "s" : ""}, ${infos} info\n`;
+    return out;
+}

package/dist/flow-runtime.d.ts

@@ -0,0 +1,113 @@
+import { type AnnotationsFile, type BoundingBox, type FlowFile, type RedactionRegion, type RedactionStyle, type Step } from "./doc-pack.js";
+/**
+ * A redaction with its locator ref already resolved to a concrete selector. `selector` entries are
+ * turned into bounding boxes by the driver at capture time (absent/zero-box selectors are skipped
+ * with a stderr warning — never a halt); `region` rects are in CSS pixels and the driver scales
+ * them to the screenshot's device-pixel space.
+ */
+export type ResolvedRedaction = {
+    selector: string;
+    style: RedactionStyle;
+} | {
+    region: RedactionRegion;
+    style: RedactionStyle;
+};
+/** What the runtime needs from a browser. Selectors passed here are already resolved (no `$ref`). */
+export interface BrowserDriver {
+    goto(url: string): Promise<void>;
+    click(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    upload(selector: string, filePath: string): Promise<void>;
+    press(selector: string | null, key: string): Promise<void>;
+    hover(selector: string): Promise<void>;
+    selectOption(selector: string, value: string): Promise<void>;
+    setChecked(selector: string, checked: boolean): Promise<void>;
+    waitForNetworkIdle(): Promise<void>;
+    waitForLoad(): Promise<void>;
+    waitForElementStable(selector: string): Promise<void>;
+    /** Wait for `selector` to appear. `timeoutMs` overrides the driver's default (use for slow backend ops). */
+    waitForSelector(selector: string, timeoutMs?: number): Promise<void>;
+    waitForTimeout(ms: number): Promise<void>;
+    isVisible(selector: string): Promise<boolean>;
+    urlMatches(pattern: string): Promise<boolean>;
+    textContains(selector: string, text: string): Promise<boolean>;
+    /** Current page URL. */
+    currentUrl(): Promise<string>;
+    /** How many elements `selector` matches (so a halt can say "0" vs "8 stale ones"). */
+    count(selector: string): Promise<number>;
+    /** Text content of the first match of `selector`, or `null`. */
+    textOf(selector: string): Promise<string | null>;
+    /** Bounding box of an element, in page pixels. Pass `timeoutMs` (default = driver default) so this fails fast when the target has vanished. Returns `null` on miss. */
+    boundingBox(selector: string, timeoutMs?: number): Promise<BoundingBox | null>;
+    /** Capture a clean screenshot (no baked annotations), applying any `redactions` before it hits disk. */
+    screenshot(relPath: string, redactions?: ResolvedRedaction[]): Promise<void>;
+    /**
+     * Probe the actionability state of `selector` at write-time / calibration-time, without trying
+     * to act on it. Returns one of {@link ActionableState}. Designed to mirror the same Playwright
+     * actionability checks the runtime would hit at execution-time — so a calibration agent (or an
+     * MCP browser bridge consuming this driver's contract) can decide "no point fill'ing a disabled
+     * input" or "scope this selector with `:visible` — it matches multiple" *before* the step is
+     * written into a flow-file. `timeoutMs` is the *budget per check*, not a wait — keep small
+     * (≤500 ms) to avoid stalling calibration. The runtime itself doesn't call this on every step
+     * (Playwright's per-action actionability already covers that); it's an exposed contract for
+     * consumers that want to read the state without acting.
+     */
+    actionable(selector: string, timeoutMs?: number): Promise<ActionableState>;
+}
+/**
+ * The contract `actionable()` returns. Mirrors Playwright's per-action actionability checks
+ * + a couple of states Playwright either throws on (multiple matches) or surfaces awkwardly
+ * (off-screen, covered). Listed in the order calibration usually cares about them.
+ */
+export type ActionableState = "actionable" | "not-found" | "multiple-matches" | "detached" | "not-visible" | "off-screen" | "covered" | "disabled";
+export declare class FlowExecutionError extends Error {
+    readonly stepId: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, stepId: string, cause?: unknown | undefined);
+}
+/**
+ * Best-effort 1-line cause extracted from a Playwright actionability log (or similar driver
+ * error). Returns undefined when nothing matches — keeps the halt message short rather than
+ * guessing. Surfaced as a `[cause]` prefix on the halt message so the agent doesn't have to
+ * scan the multi-line actionability log.
+ */
+export declare function inferHaltCause(rawError: string): string | undefined;
+export interface RunFlowOptions {
+    /** Resolve a locator name → selector. Defaults to the flow-file's own `locators` map. */
+    resolveLocator?: (name: string) => string | undefined;
+    /** Where screenshots are written, relative to the doc pack root. Default: `docs/<flow>/screenshots/<step>.png`. */
+    screenshotPath?: (flow: string, stepId: string) => string;
+    /** If false, skip screenshot/annotation capture (pure flow validation). Default: true. */
+    captureDocs?: boolean;
+    /** If set, stop after executing the step with this id — run only a prefix of the flow (for calibration). */
+    stopAfter?: string;
+    /**
+     * If set, **skip** every step *before* the one with this id — start executing from this step onward.
+     * Assumes the browser is already in the state the prior steps would have produced (typical use:
+     * paired with `connectOverCdp` to attach to a Chrome that's already been driven there manually or
+     * by an earlier partial run). The skipped steps emit no annotations / screenshots / executed records;
+     * the caller is responsible for preserving the previous run's artifacts for them.
+     */
+    startFrom?: string;
+}
+export interface ExecutedStep {
+    id: string;
+    action: Step["action"];
+    /** Resolved selector the action targeted, if any. */
+    selector?: string;
+    /** Screenshot path (relative to the doc pack), if one was captured for this step. */
+    screenshot?: string;
+}
+export interface RunFlowResult {
+    flow: string;
+    steps: ExecutedStep[];
+    annotations: AnnotationsFile;
+}
+/** Resolve a `target` value (`$name` ref or inline selector) using the flow-file's locators (or a custom resolver). */
+export declare function resolveTarget(value: string, flow: FlowFile, resolver?: RunFlowOptions["resolveLocator"]): string;
+/**
+ * Execute a flow-file against a {@link BrowserDriver}, re-capturing screenshots and emitting annotation records.
+ * Deterministic: given the same site state and driver behaviour, produces the same result. Halts on the first
+ * locator / success-criterion failure.
+ */
+export declare function runFlow(flow: FlowFile, driver: BrowserDriver, opts?: RunFlowOptions): Promise<RunFlowResult>;