@docsxai/engine 0.2.0

package/dist/workspace.js

@@ -0,0 +1,172 @@
+// Workspace scaffolding & config.
+//
+// A *workspace* is the directory docsxai reads/writes for a project: `flows/`, `docs/`, `auth/`, plus
+// (gitignored) `.auth/` and `.viewer/`, plus a small `.docsxai.json` config so `run`/`render`/`capture-auth`
+// don't need `--base-url` / `--ignore-https-errors` on every call. **It must live outside the app repo** — docsxai
+// operates *on* a running app from outside; it never writes into the app's source tree.
+//
+// `docsxai init <dir> --app-url <url>` scaffolds one; `--persist tmp` puts it in a throwaway temp dir.
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+export const WORKSPACE_CONFIG_FILE = ".docsxai.json";
+/** Thrown when a workspace-relative path resolves outside the workspace root. */
+export class WorkspacePathEscapeError extends Error {
+    workspaceDir;
+    resolvedPath;
+    constructor(workspaceDir, resolvedPath) {
+        super(`path escapes workspace root ${workspaceDir}: ${resolvedPath}`);
+        this.workspaceDir = workspaceDir;
+        this.resolvedPath = resolvedPath;
+        this.name = "WorkspacePathEscapeError";
+    }
+}
+function assertContained(root, candidate) {
+    // Prefix check on a path-separator boundary: `/ws/docs-evil` must not pass for root `/ws/docs`.
+    if (candidate !== root && !candidate.startsWith(root + path.sep)) {
+        throw new WorkspacePathEscapeError(root, candidate);
+    }
+}
+/** Resolve path segments against a workspace root, guaranteeing containment. */
+export function resolveWorkspacePath(workspaceDir, ...segments) {
+    const root = path.resolve(workspaceDir);
+    const resolved = path.resolve(root, ...segments);
+    assertContained(root, resolved);
+    return resolved;
+}
+/** Realpath of the deepest existing ancestor of `p`, with the non-existing suffix re-appended. */
+async function realpathDeepestExisting(p) {
+    let probe = p;
+    let suffix = "";
+    for (;;) {
+        try {
+            const real = await fs.realpath(probe);
+            return suffix ? path.join(real, suffix) : real;
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                return p; // not even the filesystem root resolves — give up lexically
+            suffix = suffix ? path.join(path.basename(probe), suffix) : path.basename(probe);
+            probe = parent;
+        }
+    }
+}
+/**
+ * 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 async function resolveWorkspacePathReal(workspaceDir, ...segments) {
+    const resolved = resolveWorkspacePath(workspaceDir, ...segments);
+    const rootReal = await realpathDeepestExisting(path.resolve(workspaceDir));
+    const resolvedReal = await realpathDeepestExisting(resolved);
+    assertContained(rootReal, resolvedReal);
+    return resolved;
+}
+const README = (cfg) => `# docsxai workspace
+
+This directory is a **docsxai workspace** — it holds the doc pack for one running app:
+
+- \`flows/<flow>.flow.yaml\` — hand-editable flow-files (the source of truth for execution)
+- \`docs/<flow>/{annotations.json, screenshots/, <step>.md}\`, \`docs/{style.yaml, locators.yaml}\` — the generated docs
+- \`auth/strategy.yaml\` — how execution authenticates to the app
+- \`.auth/<role>.json\` — captured session(s) (gitignored; never committed; never leaves this machine)
+- \`.viewer/\` — the generated interactive viewer (gitignored)
+- \`${WORKSPACE_CONFIG_FILE}\` — workspace config (\`app_url${cfg.app_url ? ` = ${cfg.app_url}` : ""}\`, \`ignore_https_errors = ${!!cfg.ignore_https_errors}\`)
+
+**Do NOT place this directory inside the app's source repo.** docsxai documents the *running* app from outside;
+keeping the workspace separate is what guarantees zero traces in the app repo.
+
+Usage (from this directory):
+
+\`\`\`
+docsxai capture-auth .     # if auth is manual-capture: opens an instrumented browser; log in, then run window.__docsxai.capture()
+docsxai calibrate . --description path/to/flow.md   # (when the calibration stages land) produce/refresh flow-files
+docsxai run .              # replay the flow-files headlessly; refresh annotations + screenshots
+docsxai render . && open .viewer/index.html
+\`\`\`
+`;
+async function isNonEmptyDir(p) {
+    try {
+        const entries = await fs.readdir(p);
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Scaffold a workspace. Returns where it landed + what was created. */
+export async function initWorkspace(opts) {
+    let dir;
+    let ephemeral = false;
+    if (opts.persistTmp) {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), "docsxai-workspace-"));
+        ephemeral = true;
+    }
+    else {
+        if (!opts.dir)
+            throw new Error("init: a target directory is required (or use --persist tmp)");
+        dir = path.resolve(opts.dir);
+        if (!opts.force && (await isNonEmptyDir(dir))) {
+            throw new Error(`init: ${dir} exists and is not empty — pick another dir or pass --force`);
+        }
+    }
+    const role = opts.role ?? "editor";
+    const ttl = opts.ttl ?? "1h";
+    const trigger = opts.captureTrigger ?? "console";
+    const auth = opts.auth ?? "manual-capture";
+    const created = [];
+    for (const sub of ["flows", "docs", "auth", ".auth", ".viewer"]) {
+        await fs.mkdir(resolveWorkspacePath(dir, sub), { recursive: true });
+    }
+    created.push("flows/", "docs/", "auth/", ".auth/", ".viewer/");
+    await fs.writeFile(resolveWorkspacePath(dir, ".gitignore"), ".auth/\n.viewer/\n", "utf8");
+    created.push(".gitignore");
+    const cfg = {
+        schema: "docsxai/workspace@1",
+        ...(opts.appUrl ? { app_url: opts.appUrl } : {}),
+        ...(opts.ignoreHttpsErrors ? { ignore_https_errors: true } : {}),
+        created_at: new Date().toISOString(),
+    };
+    await fs.writeFile(resolveWorkspacePath(dir, WORKSPACE_CONFIG_FILE), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    created.push(WORKSPACE_CONFIG_FILE);
+    if (auth === "manual-capture") {
+        const descriptor = {
+            schema: "docsxai/auth-strategy@1",
+            default_role: role,
+            roles: {
+                [role]: {
+                    strategy: "manual-capture",
+                    options: { capture_trigger: trigger },
+                    cache: {
+                        enabled: true,
+                        store: "local",
+                        ttl,
+                        ...(opts.authCookie ? { auth_cookie: opts.authCookie } : {}),
+                    },
+                },
+            },
+        };
+        await fs.writeFile(resolveWorkspacePath(dir, "auth", "strategy.yaml"), stringifyYaml(descriptor, { lineWidth: 100 }), "utf8");
+        created.push("auth/strategy.yaml");
+    }
+    await fs.writeFile(resolveWorkspacePath(dir, "README.md"), README(cfg), "utf8");
+    created.push("README.md");
+    return { dir, created, ephemeral };
+}
+/** Read `<dir>/.docsxai.json` if present. Returns `null` if absent or unreadable. */
+export async function loadWorkspaceConfig(dir) {
+    try {
+        const text = await fs.readFile(resolveWorkspacePath(dir, WORKSPACE_CONFIG_FILE), "utf8");
+        const parsed = JSON.parse(text);
+        if (parsed && parsed.schema === "docsxai/workspace@1")
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zip.d.ts

@@ -0,0 +1,17 @@
+export interface ZipOptions {
+    workspace: string;
+    output: string;
+    /** Include the rendered viewer (`.viewer/`) in the archive. Default false — viewers are derived from the doc pack and re-rendering is cheap. */
+    includeViewer?: boolean;
+}
+export interface ZipResult {
+    output: string;
+    bytes: number;
+    /** Workspace-relative archive entries, in the (sorted) order they appear in the zip. */
+    entries: string[];
+}
+export declare class ZipError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function zipDocPack(opts: ZipOptions): Promise<ZipResult>;

package/dist/zip.js

@@ -0,0 +1,113 @@
+// Package a workspace's doc pack into a single archive for hand-off. Zips in-process (fflate) —
+// no system `zip` binary required. Excludes operator-local state (`.auth/`, halt screenshots, the
+// rendered `.viewer/` by default) so the archive is reviewer-ready without manual cleanup.
+//
+// Archives are deterministic: entries are sorted, every entry carries a fixed mtime (the zip
+// format's 1980-01-01 epoch, built from local wall-clock fields so the stored bytes don't vary
+// with the machine's timezone), and the compression level is pinned. Same tree → same bytes.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { zipSync } from "fflate";
+import { resolveWorkspacePath, resolveWorkspacePathReal, WorkspacePathEscapeError, } from "./workspace.js";
+export class ZipError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "ZipError";
+    }
+}
+const DEFAULT_INCLUDES = ["flows/", "docs/", ".docsxai.json", "auth/strategy.yaml", "README.md"];
+const FIXED_MTIME = new Date(1980, 0, 1);
+const FIXED_LEVEL = 6;
+function isExcluded(relPath, includeViewer) {
+    const segments = relPath.split("/");
+    if (segments.includes(".auth") || segments.includes("halts"))
+        return true;
+    if (!includeViewer && segments[0] === ".viewer")
+        return true;
+    const base = segments[segments.length - 1];
+    return base === ".DS_Store" || base.endsWith(".tmp");
+}
+async function collectFiles(workspace, relDir, includeViewer, out) {
+    const entries = await fs.readdir(resolveWorkspacePath(workspace, relDir), {
+        withFileTypes: true,
+    });
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        if (isExcluded(rel, includeViewer))
+            continue;
+        if (entry.isDirectory()) {
+            await collectFiles(workspace, rel, includeViewer, out);
+        }
+        else if (entry.isFile()) {
+            out.push(rel);
+        }
+        else if (entry.isSymbolicLink()) {
+            // The archive is a hand-off artifact: follow a symlink only if its target stays inside the
+            // workspace — a link escaping the root must not exfiltrate whatever it points at.
+            let stat;
+            try {
+                await resolveWorkspacePathReal(workspace, rel);
+                stat = await fs.stat(resolveWorkspacePath(workspace, rel));
+            }
+            catch (e) {
+                if (e instanceof WorkspacePathEscapeError)
+                    continue;
+                continue; // broken symlink — nothing to archive
+            }
+            if (stat.isDirectory())
+                await collectFiles(workspace, rel, includeViewer, out);
+            else if (stat.isFile())
+                out.push(rel);
+        }
+    }
+}
+export async function zipDocPack(opts) {
+    const { workspace, output, includeViewer = false } = opts;
+    try {
+        await fs.access(workspace);
+    }
+    catch {
+        throw new ZipError(`workspace doesn't exist: ${workspace}`);
+    }
+    const outAbs = path.resolve(output);
+    await fs.mkdir(path.dirname(outAbs), { recursive: true });
+    const includesAll = includeViewer ? [...DEFAULT_INCLUDES, ".viewer/"] : DEFAULT_INCLUDES;
+    const files = [];
+    let anyIncludePresent = false;
+    for (const inc of includesAll) {
+        const rel = inc.endsWith("/") ? inc.slice(0, -1) : inc;
+        let stat;
+        try {
+            stat = await fs.stat(resolveWorkspacePath(workspace, rel));
+        }
+        catch {
+            continue; // skip absent
+        }
+        anyIncludePresent = true;
+        if (stat.isDirectory())
+            await collectFiles(workspace, rel, includeViewer, files);
+        else
+            files.push(rel);
+    }
+    if (!anyIncludePresent) {
+        throw new ZipError(`workspace ${workspace} has nothing to zip (no flows/ or docs/ found)`);
+    }
+    files.sort();
+    const zippable = {};
+    for (const rel of files) {
+        const data = await fs.readFile(resolveWorkspacePath(workspace, rel));
+        zippable[rel] = [new Uint8Array(data), { level: FIXED_LEVEL, mtime: FIXED_MTIME }];
+    }
+    let bytes;
+    try {
+        bytes = zipSync(zippable, { level: FIXED_LEVEL, mtime: FIXED_MTIME });
+    }
+    catch (e) {
+        throw new ZipError(`failed to build archive: ${e.message}`, e);
+    }
+    await fs.writeFile(outAbs, bytes);
+    return { output: outAbs, bytes: bytes.length, entries: files };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@docsxai/engine",
+  "version": "0.2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "LLM-agnostic engine: flow-file parser + deterministic runtime + the docsxai CLI + the target-site auth-strategy layer.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalebteccom/docsxai.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/kalebteccom/docsxai#readme",
+  "bugs": "https://github.com/kalebteccom/docsxai/issues",
+  "keywords": [
+    "docsxai",
+    "documentation",
+    "playwright",
+    "claude-code",
+    "agent"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "docsxai": "./dist/cli.js"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "playwright-core": "^1.61.0",
+    "pngjs": "^7.0.0",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/pngjs": "^6.0.5",
+    "vitest": "^2.0.0",
+    "@docsxai/backend": "0.2.0"
+  },
+  "author": "Kalebtec <security@kalebtec.com>",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -b tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}