@docsxai/engine 0.2.0

package/dist/export/adf.js

@@ -0,0 +1,323 @@
+// ADF (Atlassian Document Format) projection of a doc pack — pure, deterministic, zero HTTP.
+//
+// The engine emits projections only; all Confluence egress lives in the capability-declared
+// publisher plugin (`@docsxai/plugin-confluence`). This module turns a workspace's
+// doc pack (flow-files + step write-ups + burned screenshots) into Confluence Cloud REST v2
+// `atlas_doc_format` documents plus an attachments manifest, in one of two shapes:
+//
+//   - `single` (default): ONE consolidated document for the whole project — every flow is an
+//     anchored H2 section, every step an H3 — published as one page.
+//   - `page-tree`: a parent overview document (section "project") plus one child document per
+//     flow (section = flow name).
+//
+// Media nodes reference attachments by `alt` file name with empty `id`/`collection` — the
+// publisher (or a host agent handing the projection to the Atlassian MCP) fills the file ids
+// in after upload. Attachment file names are `<flow>--<step>.png`, unique per document and
+// stable across modes.
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { parseFlowFile, resolveFlowExtends } from "../flow-file.js";
+import { resolveWorkspacePath } from "../workspace.js";
+// ---------------------------------------------------------------------------
+// markdown → ADF (subset converter)
+// ---------------------------------------------------------------------------
+// Supported: paragraphs, fenced code blocks, bullet/ordered lists, `code`, **bold**, *em* /
+// _em_, [links](url). Anything else — raw HTML included — stays literal text inside an ADF
+// text node (ADF text is plain text, so markup can never be smuggled through).
+function text(value, marks) {
+    return marks.length > 0 ? { type: "text", text: value, marks } : { type: "text", text: value };
+}
+/** Earliest inline token in `s`, or null. Order of tie-breaks: leftmost, then longest opener. */
+function findInlineToken(s) {
+    let best = null;
+    const consider = (m) => {
+        if (m && (best === null || m.start < best.start))
+            best = m;
+    };
+    const code = /`([^`]+)`/.exec(s);
+    if (code) {
+        consider({
+            start: code.index,
+            end: code.index + code[0].length,
+            kind: "code",
+            inner: code[1],
+        });
+    }
+    const strong = /\*\*([^*]+)\*\*/.exec(s);
+    if (strong) {
+        consider({
+            start: strong.index,
+            end: strong.index + strong[0].length,
+            kind: "strong",
+            inner: strong[1],
+        });
+    }
+    const em = /(^|[^*])\*([^*]+)\*/.exec(s);
+    if (em) {
+        const start = em.index + em[1].length;
+        consider({ start, end: start + em[2].length + 2, kind: "em", inner: em[2] });
+    }
+    const emU = /_([^_]+)_/.exec(s);
+    if (emU) {
+        consider({ start: emU.index, end: emU.index + emU[0].length, kind: "em", inner: emU[1] });
+    }
+    const link = /\[([^\]]+)\]\(([^)\s]+)\)/.exec(s);
+    if (link) {
+        consider({
+            start: link.index,
+            end: link.index + link[0].length,
+            kind: "link",
+            inner: link[1],
+            href: link[2],
+        });
+    }
+    return best;
+}
+/** Inline markdown → ADF text nodes, accumulating marks through nesting (bold inside link, …). */
+export function inlineMarkdownToAdf(source, marks = []) {
+    const out = [];
+    let rest = source;
+    for (;;) {
+        const token = findInlineToken(rest);
+        if (!token) {
+            if (rest.length > 0)
+                out.push(text(rest, marks));
+            return out;
+        }
+        if (token.start > 0)
+            out.push(text(rest.slice(0, token.start), marks));
+        if (token.kind === "code") {
+            // Code spans take no nested marks — literal content.
+            out.push(text(token.inner, [...marks, { type: "code" }]));
+        }
+        else if (token.kind === "link") {
+            out.push(...inlineMarkdownToAdf(token.inner, [
+                ...marks,
+                { type: "link", attrs: { href: token.href } },
+            ]));
+        }
+        else {
+            out.push(...inlineMarkdownToAdf(token.inner, [...marks, { type: token.kind }]));
+        }
+        rest = rest.slice(token.end);
+    }
+}
+function paragraph(lines) {
+    return { type: "paragraph", content: inlineMarkdownToAdf(lines.join(" ")) };
+}
+function listItem(line) {
+    return { type: "listItem", content: [{ type: "paragraph", content: inlineMarkdownToAdf(line) }] };
+}
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const ORDERED = /^\s*\d+\.\s+(.*)$/;
+/** Block-level markdown (subset) → ADF block nodes. */
+export function markdownToAdf(markdown) {
+    const out = [];
+    const lines = markdown.replaceAll("\r\n", "\n").split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i++;
+            continue;
+        }
+        if (line.trimStart().startsWith("```")) {
+            const code = [];
+            i++;
+            while (i < lines.length && !lines[i].trimStart().startsWith("```")) {
+                code.push(lines[i]);
+                i++;
+            }
+            i++; // closing fence (or EOF)
+            out.push({
+                type: "codeBlock",
+                attrs: {},
+                content: code.length > 0 ? [{ type: "text", text: code.join("\n") }] : [],
+            });
+            continue;
+        }
+        if (BULLET.test(line)) {
+            const items = [];
+            while (i < lines.length && BULLET.test(lines[i])) {
+                items.push(listItem(BULLET.exec(lines[i])[1]));
+                i++;
+            }
+            out.push({ type: "bulletList", content: items });
+            continue;
+        }
+        if (ORDERED.test(line)) {
+            const items = [];
+            while (i < lines.length && ORDERED.test(lines[i])) {
+                items.push(listItem(ORDERED.exec(lines[i])[1]));
+                i++;
+            }
+            out.push({ type: "orderedList", attrs: { order: 1 }, content: items });
+            continue;
+        }
+        // Paragraph: consume consecutive non-blank, non-list, non-fence lines.
+        const para = [];
+        while (i < lines.length &&
+            lines[i].trim() !== "" &&
+            !BULLET.test(lines[i]) &&
+            !ORDERED.test(lines[i]) &&
+            !lines[i].trimStart().startsWith("```")) {
+            para.push(lines[i].trim());
+            i++;
+        }
+        out.push(paragraph(para));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// doc pack → projection
+// ---------------------------------------------------------------------------
+function heading(level, value) {
+    return { type: "heading", attrs: { level }, content: [{ type: "text", text: value }] };
+}
+function mediaSingle(fileName) {
+    return {
+        type: "mediaSingle",
+        attrs: { layout: "center" },
+        content: [
+            // Empty id/collection: the publisher fills these in after attachment upload, matching by `alt`.
+            { type: "media", attrs: { type: "file", id: "", collection: "", alt: fileName } },
+        ],
+    };
+}
+async function readIfExists(p) {
+    try {
+        return await fs.readFile(p);
+    }
+    catch {
+        return null;
+    }
+}
+async function projectFlow(workspaceDir, flowName, flow, warnings) {
+    const nodes = [heading(2, flow.name)];
+    const attachments = [];
+    for (const step of flow.steps) {
+        const mdPath = resolveWorkspacePath(workspaceDir, "docs", flowName, `${step.id}.md`);
+        const md = await readIfExists(mdPath);
+        const burnedPath = resolveWorkspacePath(workspaceDir, "docs", flowName, "burned", `${step.id}.png`);
+        const cleanPath = resolveWorkspacePath(workspaceDir, "docs", flowName, "screenshots", `${step.id}.png`);
+        let shotPath = null;
+        let shot = await readIfExists(burnedPath);
+        if (shot) {
+            shotPath = burnedPath;
+        }
+        else {
+            shot = await readIfExists(cleanPath);
+            if (shot) {
+                shotPath = cleanPath;
+                warnings.push(`flow "${flowName}" step "${step.id}": burned screenshot missing — falling back to the clean screenshot`);
+            }
+        }
+        if (md === null && shot === null)
+            continue; // nothing documented for this step
+        nodes.push(heading(3, step.id));
+        if (md !== null)
+            nodes.push(...markdownToAdf(md.toString("utf8")));
+        if (shot !== null && shotPath !== null) {
+            const fileName = `${flowName}--${step.id}.png`;
+            attachments.push({
+                fileName,
+                sourcePath: shotPath,
+                sha256: createHash("sha256").update(shot).digest("hex"),
+            });
+            nodes.push(mediaSingle(fileName));
+        }
+        else {
+            warnings.push(`flow "${flowName}" step "${step.id}": no screenshot found (burned or clean)`);
+        }
+    }
+    return { flowName, title: flow.name, nodes, attachments };
+}
+async function loadFlows(workspaceDir, only) {
+    const flowsDir = resolveWorkspacePath(workspaceDir, "flows");
+    const entries = await fs.readdir(flowsDir).catch(() => []);
+    const names = entries
+        .filter((e) => e.endsWith(".flow.yaml"))
+        .map((e) => e.slice(0, -".flow.yaml".length))
+        .sort();
+    const wanted = only && only.length > 0 ? names.filter((n) => only.includes(n)) : names;
+    if (only) {
+        for (const o of only) {
+            if (!names.includes(o))
+                throw new Error(`export adf: no flow named "${o}" in ${flowsDir}`);
+        }
+    }
+    const load = async (name) => {
+        const p = resolveWorkspacePath(workspaceDir, "flows", `${name}.flow.yaml`);
+        return parseFlowFile(await fs.readFile(p, "utf8"), p);
+    };
+    const out = [];
+    for (const name of wanted) {
+        out.push({ flowName: name, flow: await resolveFlowExtends(await load(name), load) });
+    }
+    return out;
+}
+/**
+ * Project a workspace's doc pack into Confluence-ready ADF documents. Pure file → JSON
+ * transform: deterministic for a given doc pack, performs no HTTP, and never writes.
+ */
+export async function projectDocPackToAdf(opts) {
+    const mode = opts.options?.mode ?? "single";
+    const title = opts.options?.title ?? "Site documentation";
+    const warnings = [];
+    const flows = await loadFlows(opts.workspaceDir, opts.flows);
+    const sections = [];
+    for (const { flowName, flow } of flows) {
+        sections.push(await projectFlow(opts.workspaceDir, flowName, flow, warnings));
+    }
+    if (mode === "page-tree") {
+        const overview = {
+            version: 1,
+            type: "doc",
+            content: [
+                {
+                    type: "paragraph",
+                    content: [{ type: "text", text: "Documentation for the flows below." }],
+                },
+                {
+                    type: "bulletList",
+                    content: sections.map((s) => ({
+                        type: "listItem",
+                        content: [{ type: "paragraph", content: [{ type: "text", text: s.title }] }],
+                    })),
+                },
+            ],
+        };
+        return {
+            schema: "docsxai/adf-projection@1",
+            mode,
+            documents: [
+                { section: "project", title, adf: overview, attachments: [] },
+                ...sections.map((s) => ({
+                    section: s.flowName,
+                    title: s.title,
+                    adf: { version: 1, type: "doc", content: s.nodes },
+                    attachments: s.attachments,
+                })),
+            ],
+            warnings,
+        };
+    }
+    // single: stitch every flow's section into one consolidated document.
+    return {
+        schema: "docsxai/adf-projection@1",
+        mode,
+        documents: [
+            {
+                section: "project",
+                title,
+                adf: {
+                    version: 1,
+                    type: "doc",
+                    content: sections.flatMap((s) => s.nodes),
+                },
+                attachments: sections.flatMap((s) => s.attachments),
+            },
+        ],
+        warnings,
+    };
+}

package/dist/export/playwright-test.d.ts

@@ -0,0 +1,26 @@
+import { type FlowFile } from "../doc-pack.js";
+export interface PlaywrightExportOptions {
+    /** Flow-file base name for the header comment (default: the flow's `name`). */
+    flowFileName?: string;
+}
+/**
+ * Render a flow as a self-contained Playwright `.spec.ts`. The flow must have its `extends`
+ * chain resolved first (see `resolveFlowExtends`) so the emitted spec carries the merged steps.
+ * Pure string transform — deterministic for a given flow.
+ */
+export declare function exportFlowAsPlaywrightTest(flow: FlowFile, options?: PlaywrightExportOptions): string;
+export interface ExportedSpec {
+    flowName: string;
+    /** `<flow>.spec.ts` */
+    fileName: string;
+    content: string;
+}
+/**
+ * Export a workspace's flows (default: all of `flows/*.flow.yaml`, sorted) as Playwright specs.
+ * `extends` chains are resolved before generation. Reads only; the caller writes the files.
+ */
+export declare function exportWorkspaceFlowsAsPlaywrightTests(opts: {
+    workspaceDir: string;
+    /** Restrict to these flow names. Unknown names throw. */
+    flows?: string[];
+}): Promise<ExportedSpec[]>;

package/dist/export/playwright-test.js

@@ -0,0 +1,221 @@
+// Flow-file → Playwright test export — pure, deterministic, zero HTTP.
+//
+// Each flow becomes one self-contained `.spec.ts`: locator const declarations from the flow's
+// `locators` map, steps translated to Playwright actions, `wait_for` to waits, `success` to
+// `expect(...)` assertions, the `environment` block to `test.use({...})` (+ `page.clock` for a
+// frozen clock), and `optional: true` steps wrapped in try/catch (conditionally-present UI — a
+// miss is tolerated, mirroring the runtime). The flow-file stays the source of truth: generated
+// specs carry a "regenerate, don't hand-edit" header and are meant to live in the consumer's
+// Playwright suite as a drift tripwire between docs and reality.
+import { promises as fs } from "node:fs";
+import { VIEWPORT_PRESETS, } from "../doc-pack.js";
+import { locatorRefName, parseFlowFile, resolveFlowExtends } from "../flow-file.js";
+import { resolveWorkspacePath } from "../workspace.js";
+const RESERVED = new Set([
+    // ES reserved words + the identifiers the generated scaffold itself uses.
+    ...`await break case catch class const continue debugger default delete do else enum export
+  extends false finally for function if import in instanceof let new null return static super
+  switch this throw true try typeof var void while with yield`.split(/\s+/),
+    "page",
+    "test",
+    "expect",
+]);
+/** Deterministic flow-locator-name → JS identifier mapping (sanitized, collision-free). */
+function locatorIdentifiers(flow) {
+    const taken = new Set(RESERVED);
+    const ids = new Map();
+    for (const name of Object.keys(flow.locators)) {
+        let id = name.replace(/[^A-Za-z0-9_$]/g, "_");
+        if (!/^[A-Za-z_$]/.test(id))
+            id = `_${id}`;
+        while (taken.has(id))
+            id = `${id}_`;
+        taken.add(id);
+        ids.set(name, id);
+    }
+    return ids;
+}
+/** Render a step `target` / locator-ref-or-inline-selector as a Playwright locator expression. */
+function locatorExpr(value, ids) {
+    const ref = locatorRefName(value);
+    if (ref !== null) {
+        const id = ids.get(ref);
+        if (id)
+            return id;
+    }
+    return `page.locator(${JSON.stringify(value)})`;
+}
+function environmentUse(env) {
+    const entries = [];
+    if (env.viewport !== undefined) {
+        const v = typeof env.viewport === "string" ? VIEWPORT_PRESETS[env.viewport] : env.viewport;
+        entries.push(`viewport: { width: ${v.width}, height: ${v.height} }`);
+    }
+    if (env.locale !== undefined)
+        entries.push(`locale: ${JSON.stringify(env.locale)}`);
+    if (env.timezone !== undefined)
+        entries.push(`timezoneId: ${JSON.stringify(env.timezone)}`);
+    if (env.color_scheme !== undefined)
+        entries.push(`colorScheme: ${JSON.stringify(env.color_scheme)}`);
+    if (env.reduced_motion)
+        entries.push(`reducedMotion: "reduce"`);
+    if (entries.length === 0)
+        return [];
+    return ["test.use({", ...entries.map((e) => `  ${e},`), "});", ""];
+}
+function actionLines(step, ids) {
+    const target = step.target !== undefined ? locatorExpr(step.target, ids) : null;
+    const value = step.value;
+    const missing = (what) => [
+        `// step "${step.id}": ${step.action} without ${what} — nothing to emit`,
+    ];
+    switch (step.action) {
+        case "navigate":
+            return value === undefined
+                ? missing("a value")
+                : [`await page.goto(${JSON.stringify(value)});`];
+        case "click":
+            return target === null ? missing("a target") : [`await ${target}.click();`];
+        case "fill":
+            return target === null
+                ? missing("a target")
+                : [`await ${target}.fill(${JSON.stringify(value ?? "")});`];
+        case "select":
+            return target === null || value === undefined
+                ? missing("a target/value")
+                : [`await ${target}.selectOption(${JSON.stringify(value)});`];
+        case "check":
+            return target === null ? missing("a target") : [`await ${target}.check();`];
+        case "uncheck":
+            return target === null ? missing("a target") : [`await ${target}.uncheck();`];
+        case "hover":
+            return target === null ? missing("a target") : [`await ${target}.hover();`];
+        case "press":
+            if (value === undefined)
+                return missing("a key value");
+            return target === null
+                ? [`await page.keyboard.press(${JSON.stringify(value)});`]
+                : [`await ${target}.press(${JSON.stringify(value)});`];
+        case "upload":
+            return target === null || value === undefined
+                ? missing("a target/value")
+                : [`await ${target}.setInputFiles(${JSON.stringify(value)});`];
+        case "wait":
+            return []; // the step's wait_for carries the semantics
+    }
+}
+function waitLines(wait, step, ids) {
+    if (wait === "network_idle")
+        return [`await page.waitForLoadState("networkidle");`];
+    if (wait === "load")
+        return [`await page.waitForLoadState("load");`];
+    if (wait === "element_stable") {
+        // Playwright actions auto-wait for element stability; approximate the standalone wait with a
+        // visibility wait on the step target when there is one.
+        return step.target !== undefined
+            ? [`await ${locatorExpr(step.target, ids)}.waitFor({ state: "visible" }); // element_stable`]
+            : [`// wait_for: element_stable — Playwright auto-waits on the next action`];
+    }
+    if ("selector" in wait) {
+        const opts = wait.timeout_ms !== undefined
+            ? `{ state: "visible", timeout: ${wait.timeout_ms} }`
+            : `{ state: "visible" }`;
+        return [`await ${locatorExpr(wait.selector, ids)}.waitFor(${opts});`];
+    }
+    return [`await page.waitForTimeout(${wait.timeout_ms});`];
+}
+function successLines(success, ids) {
+    if ("visible" in success)
+        return [`await expect(${locatorExpr(success.visible, ids)}).toBeVisible();`];
+    if ("hidden" in success)
+        return [`await expect(${locatorExpr(success.hidden, ids)}).toBeHidden();`];
+    if ("url_matches" in success)
+        return [`await expect(page).toHaveURL(new RegExp(${JSON.stringify(success.url_matches)}));`];
+    return [
+        `await expect(${locatorExpr(success.text_contains.selector, ids)})` +
+            `.toContainText(${JSON.stringify(success.text_contains.text)});`,
+    ];
+}
+function stepLines(step, ids) {
+    const body = [
+        ...actionLines(step, ids),
+        ...(step.wait_for !== undefined ? waitLines(step.wait_for, step, ids) : []),
+        ...(step.success !== undefined ? successLines(step.success, ids) : []),
+    ];
+    const header = `// step: ${step.id} (${step.action}${step.optional ? ", optional" : ""})`;
+    if (!step.optional)
+        return [header, ...body];
+    return [
+        header,
+        "try {",
+        ...body.map((l) => `  ${l}`),
+        "} catch {",
+        "  // optional step — conditionally-present UI; a miss is tolerated",
+        "}",
+    ];
+}
+/**
+ * Render a flow as a self-contained Playwright `.spec.ts`. The flow must have its `extends`
+ * chain resolved first (see `resolveFlowExtends`) so the emitted spec carries the merged steps.
+ * Pure string transform — deterministic for a given flow.
+ */
+export function exportFlowAsPlaywrightTest(flow, options = {}) {
+    if (flow.extends) {
+        throw new Error(`flow "${flow.name}": resolve \`extends\` before exporting (resolveFlowExtends)`);
+    }
+    const fileName = options.flowFileName ?? flow.name;
+    const ids = locatorIdentifiers(flow);
+    const lines = [
+        `// generated from ${fileName}.flow.yaml — regenerate, don't hand-edit`,
+        `import { expect, test } from "@playwright/test";`,
+        "",
+    ];
+    if (flow.environment)
+        lines.push(...environmentUse(flow.environment));
+    lines.push(`test(${JSON.stringify(flow.name)}, async ({ page }) => {`);
+    const body = [];
+    if (flow.environment?.clock !== undefined) {
+        body.push(`await page.clock.setFixedTime(new Date(${JSON.stringify(flow.environment.clock)}));`, "");
+    }
+    const locatorDecls = [...ids.entries()].map(([name, id]) => `const ${id} = page.locator(${JSON.stringify(flow.locators[name])});`);
+    if (locatorDecls.length > 0)
+        body.push(...locatorDecls, "");
+    flow.steps.forEach((step, i) => {
+        body.push(...stepLines(step, ids));
+        if (i < flow.steps.length - 1)
+            body.push("");
+    });
+    lines.push(...body.map((l) => (l === "" ? "" : `  ${l}`)), "});", "");
+    return lines.join("\n");
+}
+/**
+ * Export a workspace's flows (default: all of `flows/*.flow.yaml`, sorted) as Playwright specs.
+ * `extends` chains are resolved before generation. Reads only; the caller writes the files.
+ */
+export async function exportWorkspaceFlowsAsPlaywrightTests(opts) {
+    const flowsDir = resolveWorkspacePath(opts.workspaceDir, "flows");
+    const entries = await fs.readdir(flowsDir).catch(() => []);
+    const names = entries
+        .filter((e) => e.endsWith(".flow.yaml"))
+        .map((e) => e.slice(0, -".flow.yaml".length))
+        .sort();
+    const wanted = opts.flows && opts.flows.length > 0 ? opts.flows : names;
+    for (const w of wanted) {
+        if (!names.includes(w))
+            throw new Error(`export playwright: no flow named "${w}" in ${flowsDir}`);
+    }
+    const load = async (name) => {
+        const p = resolveWorkspacePath(opts.workspaceDir, "flows", `${name}.flow.yaml`);
+        return parseFlowFile(await fs.readFile(p, "utf8"), p);
+    };
+    const out = [];
+    for (const name of wanted) {
+        const flow = await resolveFlowExtends(await load(name), load);
+        out.push({
+            flowName: name,
+            fileName: `${name}.spec.ts`,
+            content: exportFlowAsPlaywrightTest(flow, { flowFileName: name }),
+        });
+    }
+    return out;
+}

package/dist/flow-file.d.ts

@@ -0,0 +1,21 @@
+import { FlowFile } from "./doc-pack.js";
+export declare class FlowFileError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Parse + validate a flow-file from YAML text. Throws {@link FlowFileError} with a readable message on failure. */
+export declare function parseFlowFile(yamlText: string, source?: string): FlowFile;
+/** Serialize a {@link FlowFile} back to canonical YAML. */
+export declare function serializeFlowFile(flow: FlowFile): string;
+/** Returns the locator name if `value` is a `$name` reference, else `null` (it's an inline selector). */
+export declare function locatorRefName(value: string): string | null;
+/** Locator names referenced anywhere in `flow` (steps + flow-level redactions); inline selectors excluded. */
+export declare function referencedLocatorNames(flow: FlowFile): Set<string>;
+/**
+ * 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 declare function resolveFlowExtends(flow: FlowFile, loadFlowFile: (name: string) => Promise<FlowFile> | FlowFile, visited?: Set<string>): Promise<FlowFile>;