@docsxai/engine 0.2.0

package/dist/plugins-cli.js

@@ -0,0 +1,191 @@
+// `docsxai plugins <list|info|sync>` — the operator surface over the plugin runtime.
+//
+//   list  — resolve + load the workspace's plugins; print the full status table.
+//   info  — manifest + registered artifact names for one plugin (by namespace).
+//   sync  — (re)write plugins-lock.json from the resolved manifests. Never executes plugin code.
+//
+// All three honour `--format json` for tooling.
+import { promises as fs } from "node:fs";
+import { PLUGINS_LOCK_FILE, PLUGINS_LOCK_SCHEMA, PluginsConfigError, PluginsLockError, readPluginsLock, readWorkspacePluginsConfig, sha256Hex, writePluginsLock, } from "./plugins/lock.js";
+import { parseFlags } from "./cli-shared.js";
+import { resolvePlugins, resolvePluginSources } from "./plugins/runtime.js";
+const PLUGINS_USAGE = `docsxai plugins — workspace plugin runtime
+
+Usage:
+  docsxai plugins list <workspace-dir> [--format text|json]
+  docsxai plugins info <workspace-dir> <namespace> [--format text|json]
+  docsxai plugins sync <workspace-dir> [--format text|json]
+
+Notes:
+  • Plugins are declared in the workspace's .docsxai.json:
+      "plugins":             [{ "package": "<npm-name>" } | { "path": "<dir>" }, …]
+      "plugin_capabilities": ["egress:<host-glob>", …]
+  • list resolves and loads the declared set, then prints every plugin's status (loaded, or the
+    disabled/error reason). Exit 1 if any declared plugin is not loaded.
+  • sync pins each plugin's register-module sha256 into ${PLUGINS_LOCK_FILE} next to the config.
+    When the lock exists, every resolve verifies the bytes before importing — a changed module
+    fails closed until you re-run sync. sync itself never executes plugin code.
+`;
+function parseFormat(flags) {
+    const format = typeof flags.get("format") === "string" ? flags.get("format") : "text";
+    return format === "text" || format === "json" ? format : null;
+}
+function formatRecordText(r, indent = "  ") {
+    const id = r.namespace || r.name;
+    const kinds = r.manifest ? r.manifest.kinds.join(",") : "-";
+    let out = `${indent}${id}  ${r.status}  v${r.version}  ${r.trust}  ${kinds}  ${r.source}\n`;
+    if (r.statusReason)
+        out += `${indent}    ↳ ${r.statusReason}\n`;
+    return out;
+}
+async function loadRegistry(workspaceDir) {
+    const cfg = await readWorkspacePluginsConfig(workspaceDir);
+    const lock = await readPluginsLock(workspaceDir);
+    const registry = await resolvePlugins({
+        workspaceDir,
+        sources: cfg.sources,
+        enabledCapabilities: cfg.capabilities,
+        lock,
+    });
+    return { cfg, registry };
+}
+async function cmdList(workspaceDir, format) {
+    const { registry } = await loadRegistry(workspaceDir);
+    const records = registry.listPlugins();
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(records, null, 2) + "\n");
+    }
+    else if (records.length === 0) {
+        process.stdout.write('plugins: none configured (add a "plugins" array to .docsxai.json)\n');
+    }
+    else {
+        const loaded = records.filter((r) => r.status === "loaded").length;
+        process.stdout.write(`plugins (${records.length} configured, ${loaded} loaded):\n`);
+        for (const r of records)
+            process.stdout.write(formatRecordText(r));
+    }
+    return records.every((r) => r.status === "loaded") ? 0 : 1;
+}
+async function cmdInfo(workspaceDir, namespace, format) {
+    const { registry } = await loadRegistry(workspaceDir);
+    const record = registry.pluginsInfo(namespace);
+    if (!record) {
+        const known = registry
+            .listPlugins()
+            .map((r) => r.namespace || r.name)
+            .join(", ");
+        process.stderr.write(`plugins info: no plugin "${namespace}"${known ? ` (configured: ${known})` : " (none configured)"}\n`);
+        return 1;
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(record, null, 2) + "\n");
+        return record.status === "loaded" ? 0 : 1;
+    }
+    process.stdout.write(formatRecordText(record, ""));
+    if (record.manifest) {
+        process.stdout.write(`  apiVersion: ${record.manifest.apiVersion}\n`);
+        process.stdout.write(`  capabilities: ${record.manifest.capabilities.join(", ") || "(none)"}\n`);
+        process.stdout.write(`  dependsOn: ${record.manifest.dependsOn.map((d) => `${d.plugin}@${d.version}`).join(", ") || "(none)"}\n`);
+    }
+    process.stdout.write(`  artifacts (${record.artifacts.length}):\n`);
+    for (const a of record.artifacts)
+        process.stdout.write(`    ${a.kind}  ${a.name}\n`);
+    return record.status === "loaded" ? 0 : 1;
+}
+async function cmdSync(workspaceDir, format) {
+    const cfg = await readWorkspacePluginsConfig(workspaceDir);
+    const resolutions = await resolvePluginSources(workspaceDir, cfg.sources);
+    const failures = [];
+    const lock = { schema: PLUGINS_LOCK_SCHEMA, plugins: {} };
+    for (const r of resolutions) {
+        if (!r.ok) {
+            failures.push({ source: r.record.source, reason: r.record.statusReason ?? "unresolvable" });
+            continue;
+        }
+        const ns = r.candidate.manifest.namespace;
+        if (lock.plugins[ns]) {
+            failures.push({
+                source: r.candidate.source,
+                reason: `namespace "${ns}" is claimed by more than one configured plugin — cannot lock`,
+            });
+            delete lock.plugins[ns];
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = await fs.readFile(r.candidate.registerPath);
+        }
+        catch {
+            failures.push({
+                source: r.candidate.source,
+                reason: `register module not found at ${r.candidate.registerPath}`,
+            });
+            continue;
+        }
+        lock.plugins[ns] = {
+            source: r.candidate.source,
+            version: r.candidate.version,
+            sha256: sha256Hex(bytes),
+        };
+    }
+    const lockPath = await writePluginsLock(workspaceDir, lock);
+    const entryCount = Object.keys(lock.plugins).length;
+    if (format === "json") {
+        process.stdout.write(JSON.stringify({ lockPath, lock, failures }, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(`plugins sync: wrote ${lockPath} (${entryCount} plugin(s))\n`);
+        for (const [ns, entry] of Object.entries(lock.plugins)) {
+            process.stdout.write(`  ${ns}  v${entry.version}  ${entry.sha256.slice(0, 12)}…  ${entry.source}\n`);
+        }
+        for (const f of failures) {
+            process.stderr.write(`plugins sync: NOT locked ${f.source} — ${f.reason}\n`);
+        }
+    }
+    return failures.length > 0 ? 1 : 0;
+}
+export async function pluginsCli(args) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help") {
+        process.stdout.write(PLUGINS_USAGE);
+        return sub === undefined ? 2 : 0;
+    }
+    if (sub !== "list" && sub !== "info" && sub !== "sync") {
+        process.stderr.write(`plugins: unknown subcommand "${sub}"\n\n${PLUGINS_USAGE}`);
+        return 2;
+    }
+    const { positionals, flags } = parseFlags(rest);
+    const workspaceDir = positionals[0];
+    if (!workspaceDir) {
+        process.stderr.write(`plugins ${sub}: missing <workspace-dir>\n\n${PLUGINS_USAGE}`);
+        return 2;
+    }
+    const format = parseFormat(flags);
+    if (!format) {
+        process.stderr.write(`plugins ${sub}: --format must be "text" or "json"\n`);
+        return 2;
+    }
+    try {
+        switch (sub) {
+            case "list":
+                return await cmdList(workspaceDir, format);
+            case "info": {
+                const namespace = positionals[1];
+                if (!namespace) {
+                    process.stderr.write(`plugins info: missing <namespace>\n\n${PLUGINS_USAGE}`);
+                    return 2;
+                }
+                return await cmdInfo(workspaceDir, namespace, format);
+            }
+            case "sync":
+                return await cmdSync(workspaceDir, format);
+        }
+    }
+    catch (e) {
+        if (e instanceof PluginsConfigError || e instanceof PluginsLockError) {
+            process.stderr.write(`plugins ${sub}: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}

package/dist/redact.d.ts

@@ -0,0 +1,16 @@
+import { type RedactionStyle } from "./doc-pack.js";
+/** One rectangle to mask, in the PNG's own pixel space. */
+export interface RedactionBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    style: RedactionStyle;
+}
+/**
+ * Apply redaction boxes to a PNG. `box` fills the rect with solid opaque black; `pixelate`
+ * replaces it with a {@link MOSAIC_TILE}-px mosaic (each tile becomes its average colour, tiles
+ * anchored at the box origin). Boxes are clamped to the image; a box that clamps to nothing is a
+ * no-op. Returns a freshly encoded PNG buffer; the input is not mutated.
+ */
+export declare function applyRedactions(png: Buffer, boxes: RedactionBox[]): Buffer;

package/dist/redact.js

@@ -0,0 +1,72 @@
+// Deterministic screenshot redaction — pure pixel transforms over decoded PNGs.
+//
+// Boxes arrive in the screenshot's own pixel space (device pixels — selector bounding boxes are
+// already devicePixelRatio-scaled by the driver; fixed regions are scaled the same way at capture
+// time). Same PNG + same boxes → byte-identical output, which is what keeps redacted doc packs
+// reproducible run-over-run.
+import { PNG } from "pngjs";
+const MOSAIC_TILE = 16;
+/**
+ * Apply redaction boxes to a PNG. `box` fills the rect with solid opaque black; `pixelate`
+ * replaces it with a {@link MOSAIC_TILE}-px mosaic (each tile becomes its average colour, tiles
+ * anchored at the box origin). Boxes are clamped to the image; a box that clamps to nothing is a
+ * no-op. Returns a freshly encoded PNG buffer; the input is not mutated.
+ */
+export function applyRedactions(png, boxes) {
+    if (boxes.length === 0)
+        return png;
+    const img = PNG.sync.read(png);
+    for (const box of boxes) {
+        const x0 = Math.max(0, Math.floor(box.x));
+        const y0 = Math.max(0, Math.floor(box.y));
+        const x1 = Math.min(img.width, Math.ceil(box.x + box.width));
+        const y1 = Math.min(img.height, Math.ceil(box.y + box.height));
+        if (x1 <= x0 || y1 <= y0)
+            continue;
+        if (box.style === "pixelate")
+            pixelate(img, x0, y0, x1, y1);
+        else
+            fillBlack(img, x0, y0, x1, y1);
+    }
+    return PNG.sync.write(img);
+}
+function fillBlack(img, x0, y0, x1, y1) {
+    for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+            const i = (y * img.width + x) * 4;
+            img.data[i] = 0;
+            img.data[i + 1] = 0;
+            img.data[i + 2] = 0;
+            img.data[i + 3] = 255;
+        }
+    }
+}
+function pixelate(img, x0, y0, x1, y1) {
+    for (let ty = y0; ty < y1; ty += MOSAIC_TILE) {
+        for (let tx = x0; tx < x1; tx += MOSAIC_TILE) {
+            const tx1 = Math.min(tx + MOSAIC_TILE, x1);
+            const ty1 = Math.min(ty + MOSAIC_TILE, y1);
+            let r = 0, g = 0, b = 0, a = 0;
+            const n = (tx1 - tx) * (ty1 - ty);
+            for (let y = ty; y < ty1; y++) {
+                for (let x = tx; x < tx1; x++) {
+                    const i = (y * img.width + x) * 4;
+                    r += img.data[i];
+                    g += img.data[i + 1];
+                    b += img.data[i + 2];
+                    a += img.data[i + 3];
+                }
+            }
+            const avg = [Math.round(r / n), Math.round(g / n), Math.round(b / n), Math.round(a / n)];
+            for (let y = ty; y < ty1; y++) {
+                for (let x = tx; x < tx1; x++) {
+                    const i = (y * img.width + x) * 4;
+                    img.data[i] = avg[0];
+                    img.data[i + 1] = avg[1];
+                    img.data[i + 2] = avg[2];
+                    img.data[i + 3] = avg[3];
+                }
+            }
+        }
+    }
+}

package/dist/style.d.ts

@@ -0,0 +1,46 @@
+import { StyleArtifact } from "./doc-pack.js";
+export declare class StyleError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** The seed style every workspace starts with — overwritable by the agent during calibration. */
+export declare const DEFAULT_STYLE: StyleArtifact;
+/**
+ * Regex patterns keyed by the pruning-rule category string. The style artifact's `pruning_rules`
+ * names categories from this catalogue; the lint reports any match.
+ *
+ * Each pattern is multiline-friendly. Add new categories here and reference them by string in
+ * `style.yaml`'s `pruning_rules:` — the engine reads the array, picks the matching patterns,
+ * and scans `docs/**\/*.md` for leaks.
+ */
+export declare const JARGON_PATTERNS: Record<string, RegExp>;
+export interface JargonHit {
+    /** Path of the offending file, workspace-relative. */
+    file: string;
+    /** 1-based line number where the match starts. */
+    line: number;
+    /** The pruning-rule category that matched. */
+    category: string;
+    /** The literal substring that matched. */
+    snippet: string;
+}
+export interface StylePaths {
+    workspace: string;
+    yamlPath: string;
+    jsonPath: string;
+}
+export declare function stylePathsFor(workspace: string): StylePaths;
+/** Read + parse + validate `docs/style.yaml`. Returns null when the file doesn't exist. Throws on invalid YAML or schema mismatch. */
+export declare function loadStyle(workspace: string): Promise<StyleArtifact | null>;
+/** Write `docs/style.yaml` + derived `docs/style.json`. Creates `docs/` if missing. */
+export declare function writeStyle(workspace: string, style: StyleArtifact): Promise<StylePaths>;
+/** Init the style artifact with `DEFAULT_STYLE` if it doesn't already exist. */
+export declare function initStyleIfAbsent(workspace: string): Promise<{
+    paths: StylePaths;
+    created: boolean;
+}>;
+/** Scan a single text body against the named jargon categories. Returns hits with line numbers. */
+export declare function scanTextForJargon(text: string, file: string, categories: string[]): JargonHit[];
+/** Scan every `<workspace>/docs/<flow>/<step>.md` user-facing write-up for jargon leakage. */
+export declare function scanWorkspaceForJargon(workspace: string, style: StyleArtifact): Promise<JargonHit[]>;
+export declare function formatJargonHitsText(hits: JargonHit[]): string;

package/dist/style.js

@@ -0,0 +1,151 @@
+// Style artifact — load/write/derive `docs/style.yaml` + derived `docs/style.json`, plus the
+// jargon-leak scanner that backs the semantic-reshape exit criterion (testing-jargon absent
+// from user-facing step write-ups). The engine never re-shapes prose itself (LLM-agnostic) —
+// the agent does that during calibration. This module is the engine's contribution: validate
+// the schema, persist the artifact, and report when jargon leaks through.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { StyleArtifact } from "./doc-pack.js";
+import { resolveWorkspacePath } from "./workspace.js";
+export class StyleError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "StyleError";
+    }
+}
+/** The seed style every workspace starts with — overwritable by the agent during calibration. */
+export const DEFAULT_STYLE = {
+    schema: "docsxai/style@1",
+    voice: {
+        tone: "concise, instructional, second-person ('you')",
+        audience: "end users (not engineers)",
+    },
+    structure: { per_step: "one short imperative sentence + a screenshot; no internal jargon" },
+    terminology: {},
+    pruning_rules: [
+        "VERIFY/EXPECT/ASSERT directives",
+        "WAIT directives",
+        "internal locator names",
+        "network-verification blocks",
+    ],
+};
+/**
+ * Regex patterns keyed by the pruning-rule category string. The style artifact's `pruning_rules`
+ * names categories from this catalogue; the lint reports any match.
+ *
+ * Each pattern is multiline-friendly. Add new categories here and reference them by string in
+ * `style.yaml`'s `pruning_rules:` — the engine reads the array, picks the matching patterns,
+ * and scans `docs/**\/*.md` for leaks.
+ */
+export const JARGON_PATTERNS = {
+    "VERIFY/EXPECT/ASSERT directives": /\b(VERIFY|EXPECT|ASSERT)\b/g,
+    "WAIT directives": /\bWAIT(?:\s+FOR)?\b/g,
+    "internal locator names": /\b(data-testid|data-test|data-cy|data-qa|querySelector|getByRole|getByText)\b/g,
+    "network-verification blocks": /\b(GET|POST|PUT|DELETE|PATCH)\s+\/(?:api|v\d)\/\S+|\bstatus[:\s]+[1-5]\d{2}\b/g,
+};
+export function stylePathsFor(workspace) {
+    return {
+        workspace,
+        yamlPath: resolveWorkspacePath(workspace, "docs", "style.yaml"),
+        jsonPath: resolveWorkspacePath(workspace, "docs", "style.json"),
+    };
+}
+/** Read + parse + validate `docs/style.yaml`. Returns null when the file doesn't exist. Throws on invalid YAML or schema mismatch. */
+export async function loadStyle(workspace) {
+    const { yamlPath } = stylePathsFor(workspace);
+    let text;
+    try {
+        text = await fs.readFile(yamlPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (e) {
+        throw new StyleError(`${yamlPath}: invalid YAML — ${e.message}`, e);
+    }
+    const parsed = StyleArtifact.safeParse(raw);
+    if (!parsed.success) {
+        throw new StyleError(`${yamlPath}: schema validation failed — ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+/** Write `docs/style.yaml` + derived `docs/style.json`. Creates `docs/` if missing. */
+export async function writeStyle(workspace, style) {
+    const paths = stylePathsFor(workspace);
+    await fs.mkdir(path.dirname(paths.yamlPath), { recursive: true });
+    await fs.writeFile(paths.yamlPath, stringifyYaml(style, { lineWidth: 100 }), "utf8");
+    await fs.writeFile(paths.jsonPath, JSON.stringify(style, null, 2) + "\n", "utf8");
+    return paths;
+}
+/** Init the style artifact with `DEFAULT_STYLE` if it doesn't already exist. */
+export async function initStyleIfAbsent(workspace) {
+    const paths = stylePathsFor(workspace);
+    try {
+        await fs.access(paths.yamlPath);
+        return { paths, created: false };
+    }
+    catch {
+        await writeStyle(workspace, DEFAULT_STYLE);
+        return { paths, created: true };
+    }
+}
+/** Scan a single text body against the named jargon categories. Returns hits with line numbers. */
+export function scanTextForJargon(text, file, categories) {
+    const hits = [];
+    const lines = text.split(/\n/);
+    for (const category of categories) {
+        const pattern = JARGON_PATTERNS[category];
+        if (!pattern)
+            continue;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // reset stateful flag-`g` regex each pass
+            const re = new RegExp(pattern.source, pattern.flags.replace(/g/g, "") + "g");
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                hits.push({ file, line: i + 1, category, snippet: m[0] });
+            }
+        }
+    }
+    return hits;
+}
+/** Scan every `<workspace>/docs/<flow>/<step>.md` user-facing write-up for jargon leakage. */
+export async function scanWorkspaceForJargon(workspace, style) {
+    const docsRoot = resolveWorkspacePath(workspace, "docs");
+    const flows = await fs.readdir(docsRoot, { withFileTypes: true }).catch(() => []);
+    const categories = style.pruning_rules ?? [];
+    if (categories.length === 0)
+        return [];
+    const hits = [];
+    for (const ent of flows) {
+        if (!ent.isDirectory())
+            continue;
+        const flowDir = resolveWorkspacePath(workspace, "docs", ent.name);
+        const files = await fs.readdir(flowDir).catch(() => []);
+        for (const f of files) {
+            if (!f.endsWith(".md"))
+                continue;
+            const abs = resolveWorkspacePath(workspace, "docs", ent.name, f);
+            const rel = path.relative(path.resolve(workspace), abs);
+            const text = await fs.readFile(abs, "utf8").catch(() => "");
+            hits.push(...scanTextForJargon(text, rel, categories));
+        }
+    }
+    return hits;
+}
+export function formatJargonHitsText(hits) {
+    if (hits.length === 0)
+        return "✓ no jargon leaks\n";
+    let out = `${hits.length} jargon leak${hits.length !== 1 ? "s" : ""}:\n`;
+    for (const h of hits) {
+        out += `  ${h.file}:${h.line}  [${h.category}]  ${h.snippet}\n`;
+    }
+    return out;
+}

package/dist/viewer-bin.d.ts

@@ -0,0 +1,20 @@
+export declare const VIEWER_BIN_ENV = "DOCSX_VIEWER_BIN";
+export declare const VIEWER_PACKAGE = "@docsxai/viewer";
+export declare const VIEWER_BIN_NAME = "docsxai-viewer";
+export interface ViewerBinResolution {
+    /** Command to spawn. */
+    command: string;
+    /** Args to pass before the caller's own (the bin script path when `command` is the Node binary). */
+    prefixArgs: string[];
+    source: "env" | "package" | "path";
+    /** Human-readable description of every resolution step tried, ending with the one that resolved. */
+    attempts: string[];
+}
+export interface ResolveViewerBinOptions {
+    env?: Record<string, string | undefined>;
+    /** Directories whose `node_modules` to search for the viewer package. Defaults to the engine's own resolution chain. */
+    resolveFrom?: string[];
+}
+export declare function resolveViewerBin(opts?: ResolveViewerBinOptions): Promise<ViewerBinResolution>;
+/** Failure message for when the resolved command could not be launched (spawn ENOENT). */
+export declare function formatViewerBinFailure(resolution: ViewerBinResolution): string;

package/dist/viewer-bin.js

@@ -0,0 +1,97 @@
+// Resolution of the `docsxai-viewer` bin for `docsxai render`. The viewer is its own package and
+// the engine doesn't depend on it at build time, so the bin is located at run time, in order:
+//
+//   1. `DOCSX_VIEWER_BIN` — explicit operator override; a path to the viewer's bin script
+//      (run with the current Node when it's a `.js`/`.mjs`/`.cjs` file) or to an executable.
+//   2. The `@docsxai/viewer` package installed next to the engine: its `package.json` is
+//      looked up along the engine's node_modules ancestor chain and the `bin` entry is run with
+//      the current Node — covers installs where the package is present but no PATH shim is.
+//      (A direct manifest read, not `require.resolve("…/package.json")` — the viewer's `exports`
+//      map doesn't export its package.json. The chain is walked explicitly rather than via
+//      `require.resolve.paths()`, which test runners extend with extra lookup dirs.)
+//   3. `docsxai-viewer` on PATH (the npm bin shim) — the legacy behavior, kept as the fallback.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export const VIEWER_BIN_ENV = "DOCSX_VIEWER_BIN";
+export const VIEWER_PACKAGE = "@docsxai/viewer";
+export const VIEWER_BIN_NAME = "docsxai-viewer";
+async function isFile(p) {
+    try {
+        return (await fs.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findViewerManifest(searchDirs) {
+    for (const dir of searchDirs) {
+        const manifest = path.join(dir, VIEWER_PACKAGE, "package.json");
+        if (await isFile(manifest))
+            return manifest;
+    }
+    return undefined;
+}
+/** The `node_modules` dirs Node itself would search from this module's location. */
+function defaultSearchDirs() {
+    const dirs = [];
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        if (path.basename(dir) !== "node_modules")
+            dirs.push(path.join(dir, "node_modules"));
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return dirs;
+        dir = parent;
+    }
+}
+export async function resolveViewerBin(opts = {}) {
+    const env = opts.env ?? process.env;
+    const attempts = [];
+    const envBin = env[VIEWER_BIN_ENV];
+    if (envBin) {
+        if (await isFile(envBin)) {
+            attempts.push(`$${VIEWER_BIN_ENV} → ${envBin}`);
+            return /\.(c|m)?js$/.test(envBin)
+                ? { command: process.execPath, prefixArgs: [envBin], source: "env", attempts }
+                : { command: envBin, prefixArgs: [], source: "env", attempts };
+        }
+        attempts.push(`$${VIEWER_BIN_ENV} → ${envBin} (no such file)`);
+    }
+    else {
+        attempts.push(`$${VIEWER_BIN_ENV} — not set`);
+    }
+    const searchDirs = opts.resolveFrom
+        ? opts.resolveFrom.map((d) => path.join(d, "node_modules"))
+        : defaultSearchDirs();
+    const manifestPath = await findViewerManifest(searchDirs);
+    if (manifestPath) {
+        const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+        const binRel = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[VIEWER_BIN_NAME];
+        if (binRel) {
+            const binAbs = path.resolve(path.dirname(manifestPath), binRel);
+            if (await isFile(binAbs)) {
+                attempts.push(`${VIEWER_PACKAGE} (installed package) → ${binAbs}`);
+                return { command: process.execPath, prefixArgs: [binAbs], source: "package", attempts };
+            }
+            attempts.push(`${VIEWER_PACKAGE} (installed package) → ${binAbs} (bin file missing — is the package built?)`);
+        }
+        else {
+            attempts.push(`${VIEWER_PACKAGE} (installed package) → ${manifestPath} (no "${VIEWER_BIN_NAME}" bin entry)`);
+        }
+    }
+    else {
+        attempts.push(`${VIEWER_PACKAGE} (installed package) — not found next to the engine`);
+    }
+    attempts.push(`\`${VIEWER_BIN_NAME}\` on PATH`);
+    return { command: VIEWER_BIN_NAME, prefixArgs: [], source: "path", attempts };
+}
+/** Failure message for when the resolved command could not be launched (spawn ENOENT). */
+export function formatViewerBinFailure(resolution) {
+    const lines = resolution.attempts.map((a, i, all) => `  ${i + 1}. ${a}${i === all.length - 1 ? " — not found" : ""}`);
+    return [
+        `\`${VIEWER_BIN_NAME}\` could not be launched. Tried, in order:`,
+        ...lines,
+        `Install ${VIEWER_PACKAGE} next to the engine (or globally), or point ${VIEWER_BIN_ENV} at its bin script.`,
+    ].join("\n");
+}

package/dist/workspace.d.ts

@@ -0,0 +1,60 @@
+export declare const WORKSPACE_CONFIG_FILE = ".docsxai.json";
+/** Thrown when a workspace-relative path resolves outside the workspace root. */
+export declare class WorkspacePathEscapeError extends Error {
+    readonly workspaceDir: string;
+    readonly resolvedPath: string;
+    constructor(workspaceDir: string, resolvedPath: string);
+}
+/** Resolve path segments against a workspace root, guaranteeing containment. */
+export declare function resolveWorkspacePath(workspaceDir: string, ...segments: string[]): string;
+/**
+ * Like {@link resolveWorkspacePath}, but additionally defends against symlink escape: the deepest
+ * existing ancestor of the resolved path is realpath'd and containment re-verified against the
+ * realpath'd workspace root. Use before writing to a path whose segments are user-influenced
+ * (flow names, step ids, role names) — a symlink inside the workspace pointing outside must throw.
+ */
+export declare function resolveWorkspacePathReal(workspaceDir: string, ...segments: string[]): Promise<string>;
+export interface WorkspaceConfig {
+    schema: "docsxai/workspace@1";
+    /** Base URL of the running app this workspace documents. Used as the default for `run`/`capture-auth`. */
+    app_url?: string;
+    /** Accept self-signed/invalid TLS for `app_url` (e.g. a local HTTPS dev cert). */
+    ignore_https_errors?: boolean;
+    /** Backend stub/service URL for `push`/`pull` (e.g. `http://localhost:4477`). Optional — workspaces operate fully locally without it. */
+    backend_url?: string;
+    /** Backend workspace ID, set by `push` after first round-trip. */
+    backend_workspace_id?: string;
+    /** Backend project ID, set by `push` after first round-trip. */
+    backend_project_id?: string;
+    created_at: string;
+}
+export interface InitWorkspaceOptions {
+    /** Target directory. Ignored (a temp dir is used) when `persistTmp` is true; otherwise required. */
+    dir?: string;
+    /** Create the workspace in a throwaway temp dir instead of `dir`. */
+    persistTmp?: boolean;
+    appUrl?: string;
+    /** `manual-capture` (default) writes an `auth/strategy.yaml`; `none` skips it. */
+    auth?: "manual-capture" | "none";
+    role?: string;
+    /** Cache TTL for the captured session (`session`, or a duration like `1h`/`30m`). Default `1h` — a *fallback* used only when `authCookie` isn't set/found. */
+    ttl?: string;
+    /** Name of the app's auth/session cookie — when set, the cached session's expiry tracks this cookie, not `ttl`. */
+    authCookie?: string;
+    captureTrigger?: "console" | "button";
+    ignoreHttpsErrors?: boolean;
+    /** Allow scaffolding into a non-empty directory. */
+    force?: boolean;
+}
+export interface InitWorkspaceResult {
+    /** The (possibly temp) directory the workspace was created in. */
+    dir: string;
+    /** Paths created, relative to `dir`. */
+    created: string[];
+    /** True if `dir` is a throwaway temp dir (from `--persist tmp`). */
+    ephemeral: boolean;
+}
+/** Scaffold a workspace. Returns where it landed + what was created. */
+export declare function initWorkspace(opts: InitWorkspaceOptions): Promise<InitWorkspaceResult>;
+/** Read `<dir>/.docsxai.json` if present. Returns `null` if absent or unreadable. */
+export declare function loadWorkspaceConfig(dir: string): Promise<WorkspaceConfig | null>;