@docsxai/engine 0.2.0

package/dist/cli-commands-authoring.js

@@ -0,0 +1,403 @@
+// Calibration-aid commands — the static / inspection tools an engineer leans on while hand-authoring
+// or fixing a flow-file. None of them mutate the doc pack; they read, check, and report:
+//   inspect    — open the app (cached session loaded) and dump [data-testid]s for pinning locators
+//   lint       — pure-static flow-file checks (R001…R004 + plugin-contributed rules)
+//   flow-tree  — the extends graph, orphans, and resolution issues
+//   diagnose   — halt context + recommendations for one step (optional live --cdp probe)
+//   style      — init/validate docs/style.yaml; --check scans prose for jargon leaks
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { LocalStorageStateCache, parseAuthStrategyFile } from "./auth.js";
+import { FlowFileError, parseFlowFile, resolveFlowExtends } from "./flow-file.js";
+import { buildDiagnoseReport, formatReportText, probeLive, } from "./diagnose.js";
+import { formatIssuesText, lintFlow } from "./flow-lint.js";
+import { buildFlowTree, formatTreeText } from "./flow-tree.js";
+import { formatJargonHitsText, initStyleIfAbsent, loadStyle, scanWorkspaceForJargon, StyleError, writeStyle, } from "./style.js";
+import { readPluginsLock, readWorkspacePluginsConfig } from "./plugins/lock.js";
+import { resolvePlugins } from "./plugins/runtime.js";
+import { launchPlaywrightSession } from "./playwright-driver.js";
+import { loadWorkspaceConfig, resolveWorkspacePath } from "./workspace.js";
+import { listFlowFiles, parseFlags } from "./cli-shared.js";
+import { USAGE } from "./cli-usage.js";
+export async function cmdInspect(args) {
+    const { positionals, flags } = parseFlags(args);
+    const workspaceDir = positionals[0];
+    if (!workspaceDir) {
+        process.stderr.write("inspect: missing <workspace-dir>\n\n" + USAGE + "\n");
+        return 2;
+    }
+    const wsCfg = await loadWorkspaceConfig(workspaceDir);
+    const cdp = typeof flags.get("cdp") === "string" ? flags.get("cdp") : undefined;
+    const explicitUrl = typeof flags.get("url") === "string" ? flags.get("url") : undefined;
+    const url = explicitUrl ?? wsCfg?.app_url;
+    if (!cdp && !url) {
+        process.stderr.write("inspect: no URL — pass --url <url>, set app_url in .docsxai.json, or use --cdp <endpoint>\n");
+        return 2;
+    }
+    const selector = typeof flags.get("selector") === "string" ? flags.get("selector") : undefined;
+    const headed = flags.get("headed") === true;
+    const ignoreHTTPSErrors = flags.get("ignore-https-errors") === true || !!wsCfg?.ignore_https_errors;
+    const waitForSel = typeof flags.get("wait-for") === "string" ? flags.get("wait-for") : undefined;
+    const waitMs = typeof flags.get("wait") === "string" ? Math.max(0, Number(flags.get("wait")) || 0) : 800;
+    let storageState;
+    if (!cdp) {
+        let role = typeof flags.get("role") === "string" ? flags.get("role") : undefined;
+        if (!role) {
+            try {
+                role = parseAuthStrategyFile(await fs.readFile(resolveWorkspacePath(workspaceDir, "auth", "strategy.yaml"), "utf8")).default_role;
+            }
+            catch {
+                role = "editor";
+            }
+        }
+        storageState =
+            (await new LocalStorageStateCache(resolveWorkspacePath(workspaceDir, ".auth")).load(role)) ??
+                undefined;
+        if (!storageState) {
+            process.stderr.write(`inspect: no valid cached session for role "${role}" — inspecting unauthenticated (\`docsxai capture-auth\` first if the app needs login)\n`);
+        }
+    }
+    let session;
+    try {
+        session = await launchPlaywrightSession({
+            ...(cdp
+                ? { connectOverCdp: cdp }
+                : {
+                    ...(url ? { baseURL: url } : {}),
+                    headed,
+                    ignoreHTTPSErrors,
+                    ...(storageState ? { storageState } : {}),
+                }),
+            docPackRoot: workspaceDir,
+        });
+    }
+    catch (e) {
+        const msg = e.message;
+        if (/Executable doesn't exist|playwright install/i.test(msg)) {
+            process.stderr.write("inspect: no Chromium binary — `npx playwright-core install chromium` (source checkout: `pnpm -C packages/engine exec playwright-core install chromium`)\n");
+            return 1;
+        }
+        process.stderr.write(`inspect: failed to launch browser: ${msg}\n`);
+        return 1;
+    }
+    try {
+        // In CDP-attach mode without an explicit --url, inspect whatever the attached browser already has open.
+        if (url && (!cdp || explicitUrl))
+            await session.page.goto(url, { waitUntil: "domcontentloaded" }).catch(() => undefined);
+        if (waitForSel)
+            await session.page.waitForSelector(waitForSel, { timeout: 30_000 }).catch(() => undefined);
+        else if (waitMs > 0)
+            await session.page.waitForTimeout(waitMs);
+        process.stdout.write(`inspect: ${session.page.url()}\n  title: ${await session.page.title().catch(() => "(?)")}\n`);
+        if (selector) {
+            const els = await session.page.locator(selector).all();
+            process.stdout.write(`  ${els.length} element(s) matching ${selector} (first 20):\n`);
+            for (const el of els.slice(0, 20)) {
+                const html = (await el.evaluate((e) => e.outerHTML).catch(() => ""))
+                    .replace(/\s+/g, " ")
+                    .slice(0, 400);
+                process.stdout.write(`    ${html}\n`);
+            }
+        }
+        else {
+            const items = await session.page
+                .$$eval("[data-testid]", (els) => els.map((e) => ({
+                testid: e.getAttribute("data-testid") ?? "",
+                tag: e.tagName.toLowerCase(),
+                text: (e.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 60),
+                visible: typeof e.checkVisibility ===
+                    "function"
+                    ? e.checkVisibility()
+                    : e.offsetParent != null,
+            })))
+                .catch(() => []);
+            process.stdout.write(`  ${items.length} [data-testid] element(s) (✓ = visible) — pin these as locators:\n`);
+            for (const it of items) {
+                process.stdout.write(`    ${it.visible ? "✓" : " "} [data-testid="${it.testid}"]  <${it.tag}>  ${it.text ? `"${it.text}"` : ""}\n`);
+            }
+            process.stdout.write(`  (--selector '<css>' dumps matching elements' HTML; --url <url> for a sub-page; --wait <ms> / --wait-for '<css>' to settle a slow SPA before snapshot; --cdp <endpoint> to attach to a running Chrome instead of launching; --headed to open it)\n`);
+        }
+        if (headed && !cdp) {
+            process.stdout.write("inspect: browser is open — close it to exit.\n");
+            await new Promise((resolve) => session.browser.on("disconnected", () => resolve()));
+        }
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`inspect: ${e.message}\n`);
+        return 1;
+    }
+    finally {
+        if (!headed)
+            await session.close();
+    }
+}
+export async function cmdLint(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`lint: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const flowFilter = typeof flags.get("flow") === "string" ? flags.get("flow") : undefined;
+    const format = typeof flags.get("format") === "string" ? flags.get("format") : "text";
+    if (format !== "text" && format !== "json") {
+        process.stderr.write(`lint: --format must be "text" or "json"\n`);
+        return 2;
+    }
+    let flowPaths;
+    try {
+        flowPaths = await listFlowFiles(projectDir);
+    }
+    catch (e) {
+        process.stderr.write(`lint: ${e.message}\n`);
+        return 2;
+    }
+    const flowsByName = new Map();
+    for (const p of flowPaths) {
+        try {
+            const text = await fs.readFile(p, "utf8");
+            const flow = parseFlowFile(text, path.basename(p));
+            flowsByName.set(flow.name, flow);
+        }
+        catch (e) {
+            const msg = e instanceof FlowFileError ? e.message : e.message;
+            process.stderr.write(`lint: parse error in ${p}: ${msg}\n`);
+            return 1;
+        }
+    }
+    const targets = flowFilter
+        ? flowsByName.has(flowFilter)
+            ? [flowsByName.get(flowFilter)]
+            : []
+        : Array.from(flowsByName.values());
+    if (flowFilter && targets.length === 0) {
+        process.stderr.write(`lint: flow not found: ${flowFilter}\n`);
+        return 2;
+    }
+    const loadFlow = (name) => {
+        const f = flowsByName.get(name);
+        if (!f)
+            throw new Error(`extends target not found: ${name}`);
+        return f;
+    };
+    // Lint-rule plugins: resolve the workspace's plugin registry and feed registered
+    // rules through lintFlow's extraRules. A plugin-resolution failure degrades to
+    // core rules with a warning — lint must stay usable while a plugin is broken.
+    let extraRules = [];
+    try {
+        const cfg = await readWorkspacePluginsConfig(projectDir);
+        if (cfg.sources.length > 0) {
+            const lock = await readPluginsLock(projectDir);
+            const registry = await resolvePlugins({
+                workspaceDir: projectDir,
+                sources: cfg.sources,
+                enabledCapabilities: cfg.capabilities,
+                lock,
+            });
+            extraRules = registry.getLintRules();
+        }
+    }
+    catch (e) {
+        process.stderr.write(`lint: plugin rules skipped — ${e.message}\n`);
+    }
+    const issues = [];
+    for (const flow of targets) {
+        const result = await lintFlow(flow, { loadFlow, extraRules });
+        issues.push(...result);
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(issues, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatIssuesText(issues));
+    }
+    return issues.some((i) => i.severity === "error" || i.severity === "warning") ? 1 : 0;
+}
+export async function cmdFlowTree(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`flow-tree: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const format = typeof flags.get("format") === "string" ? flags.get("format") : "text";
+    if (format !== "text" && format !== "json") {
+        process.stderr.write(`flow-tree: --format must be "text" or "json"\n`);
+        return 2;
+    }
+    let flowPaths;
+    try {
+        flowPaths = await listFlowFiles(projectDir);
+    }
+    catch (e) {
+        process.stderr.write(`flow-tree: ${e.message}\n`);
+        return 2;
+    }
+    const flowsByName = new Map();
+    for (const p of flowPaths) {
+        try {
+            const text = await fs.readFile(p, "utf8");
+            const flow = parseFlowFile(text, path.basename(p));
+            flowsByName.set(flow.name, flow);
+        }
+        catch (e) {
+            const msg = e instanceof FlowFileError ? e.message : e.message;
+            process.stderr.write(`flow-tree: parse error in ${p}: ${msg}\n`);
+            return 1;
+        }
+    }
+    const tree = await buildFlowTree(flowsByName);
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(tree, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatTreeText(tree));
+    }
+    return tree.issues.length > 0 || tree.orphans.length > 0 ? 1 : 0;
+}
+export async function cmdDiagnose(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`diagnose: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const flowName = typeof flags.get("flow") === "string" ? flags.get("flow") : undefined;
+    const stepId = typeof flags.get("step") === "string" ? flags.get("step") : undefined;
+    const cdpEndpoint = typeof flags.get("cdp") === "string" ? flags.get("cdp") : undefined;
+    const format = typeof flags.get("format") === "string" ? flags.get("format") : "text";
+    if (!flowName) {
+        process.stderr.write(`diagnose: --flow <name> required\n`);
+        return 2;
+    }
+    if (!stepId) {
+        process.stderr.write(`diagnose: --step <step-id> required\n`);
+        return 2;
+    }
+    if (format !== "text" && format !== "json") {
+        process.stderr.write(`diagnose: --format must be "text" or "json"\n`);
+        return 2;
+    }
+    // Load the flow (resolving `extends` so step lookup works against the merged step list).
+    const loadFlowFile = async (name) => {
+        const fp = resolveWorkspacePath(projectDir, "flows", `${name}.flow.yaml`);
+        let text;
+        try {
+            text = await fs.readFile(fp, "utf8");
+        }
+        catch {
+            throw new FlowFileError(`no flow named "${name}" at ${fp}`);
+        }
+        return parseFlowFile(text, fp);
+    };
+    let flow;
+    try {
+        const parsed = await loadFlowFile(flowName);
+        flow = parsed.extends ? await resolveFlowExtends(parsed, loadFlowFile) : parsed;
+    }
+    catch (e) {
+        const msg = e instanceof FlowFileError ? e.message : e.message;
+        process.stderr.write(`diagnose: ${msg}\n`);
+        return 1;
+    }
+    const step = flow.steps.find((s) => s.id === stepId);
+    if (!step) {
+        process.stderr.write(`diagnose: no step "${stepId}" in flow "${flowName}" (merged step list: ${flow.steps.map((s) => s.id).join(", ")})\n`);
+        return 1;
+    }
+    const resolvedSelector = step.target
+        ? step.target.startsWith("$")
+            ? (flow.locators[step.target.slice(1)] ?? step.target)
+            : step.target
+        : undefined;
+    const haltScreenshotAbsPath = resolveWorkspacePath(projectDir, "docs", flowName, "halts", `${stepId}.png`);
+    // Optional live probe via --cdp.
+    let liveProbe;
+    let liveSession;
+    if (cdpEndpoint && resolvedSelector) {
+        liveProbe = async () => {
+            liveSession = await launchPlaywrightSession({
+                connectOverCdp: cdpEndpoint,
+                docPackRoot: projectDir,
+            });
+            return probeLive(liveSession.driver, resolvedSelector, cdpEndpoint);
+        };
+    }
+    let report;
+    try {
+        report = await buildDiagnoseReport({
+            workspace: projectDir,
+            flow,
+            step,
+            ...(resolvedSelector ? { resolvedSelector } : {}),
+            haltScreenshotAbsPath,
+            ...(liveProbe ? { liveProbe } : {}),
+        });
+    }
+    catch (e) {
+        process.stderr.write(`diagnose: live probe failed: ${e.message}\n`);
+        return 1;
+    }
+    finally {
+        if (liveSession)
+            await liveSession.close();
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatReportText(report));
+    }
+    return 0;
+}
+export async function cmdStyle(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`style: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const check = flags.get("check") === true;
+    const format = typeof flags.get("format") === "string" ? flags.get("format") : "text";
+    if (format !== "text" && format !== "json") {
+        process.stderr.write(`style: --format must be "text" or "json"\n`);
+        return 2;
+    }
+    // init-if-absent (idempotent); then load + validate; then rederive JSON; then optional jargon check.
+    const { created } = await initStyleIfAbsent(projectDir);
+    let style;
+    try {
+        style = await loadStyle(projectDir);
+    }
+    catch (e) {
+        if (e instanceof StyleError) {
+            process.stderr.write(`style: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    if (!style) {
+        // Shouldn't happen after initStyleIfAbsent, but defensive.
+        process.stderr.write(`style: failed to initialise style.yaml in ${projectDir}\n`);
+        return 1;
+    }
+    // Always rewrite to ensure derived JSON stays in sync with YAML (idempotent).
+    const paths = await writeStyle(projectDir, style);
+    let hits = [];
+    if (check) {
+        hits = await scanWorkspaceForJargon(projectDir, style);
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify({ style, paths, created, jargonLeaks: check ? hits : undefined }, null, 2) +
+            "\n");
+    }
+    else {
+        process.stdout.write(`style: ${created ? "created" : "validated"} ${path.relative(projectDir, paths.yamlPath)}; rederived ${path.relative(projectDir, paths.jsonPath)}\n`);
+        if (check) {
+            process.stdout.write("\n");
+            process.stdout.write(formatJargonHitsText(hits));
+        }
+    }
+    return check && hits.length > 0 ? 1 : 0;
+}

package/dist/cli-commands-backend.d.ts

@@ -0,0 +1,5 @@
+export declare function cmdLogin(args: string[]): Promise<number>;
+export declare function cmdPush(args: string[]): Promise<number>;
+export declare function cmdPull(args: string[]): Promise<number>;
+/** `docsxai plugins …` — forwards to the plugin-runtime CLI verbatim. */
+export declare function cmdPlugins(args: string[]): Promise<number>;

package/dist/cli-commands-backend.js

@@ -0,0 +1,211 @@
+// Backend / sync commands — everything that talks to `@docsxai/backend` over HTTP, plus the plugins
+// subcommand delegation:
+//   login    — validate a bearer token (or run the OAuth 2.1 + PKCE flow with --oauth)
+//   push     — serialise the doc pack and POST it as a new revision (binds the workspace on first push)
+//   pull     — fetch a revision's artifacts back into the workspace files
+//   plugins  — forwards to plugins-cli (list | info | sync over the plugin runtime; no plugin code runs)
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { BackendClient, BackendClientError, createBackendClient, oauthLogin, saveBackendTokenFile, } from "./backend-client.js";
+import { fetchScreenshotBlobs, readDocPack, uploadScreenshotBlobs, writeDocPack, } from "./doc-pack-io.js";
+import { pluginsCli } from "./plugins-cli.js";
+import { loadWorkspaceConfig, resolveWorkspacePath } from "./workspace.js";
+import { parseFlags } from "./cli-shared.js";
+export async function cmdLogin(args) {
+    const { positionals, flags } = parseFlags(args);
+    const backendUrl = typeof flags.get("backend-url") === "string" ? flags.get("backend-url") : undefined;
+    if (!backendUrl) {
+        process.stderr.write(`login: --backend-url <url> required\n`);
+        return 2;
+    }
+    const oauthFlag = flags.get("oauth");
+    if (oauthFlag !== undefined) {
+        // OAuth 2.1 authorization-code + PKCE against the backend's authorization server. Tokens land
+        // at <workspace>/.auth/backend-token.json (mode 0600); push/pull/run pick them up from there.
+        // The flag parser hands `--oauth <dir>` the dir as the flag value; bare `--oauth` reads it
+        // from the positional.
+        const workspaceDir = typeof oauthFlag === "string" ? oauthFlag : positionals[0];
+        if (!workspaceDir) {
+            process.stderr.write(`login: --oauth requires a <workspace-dir> (tokens are stored at <workspace>/.auth/backend-token.json)\n`);
+            return 2;
+        }
+        try {
+            const tokens = await oauthLogin({
+                backendUrl,
+                onAuthorizeUrl: (u) => {
+                    process.stdout.write(`login: open this URL in your browser to authorize:\n  ${u}\n`);
+                },
+            });
+            const storedAt = await saveBackendTokenFile(workspaceDir, tokens);
+            process.stdout.write(`login: ok. tokens stored at ${storedAt} (access token expires ${new Date(tokens.expires_at).toISOString()})\n`);
+            return 0;
+        }
+        catch (e) {
+            process.stderr.write(`login: ${e.message}\n`);
+            return 1;
+        }
+    }
+    if (!process.env.DOCSX_TOKEN) {
+        process.stderr.write(`login: DOCSX_TOKEN env var not set. Export it before running: DOCSX_TOKEN=<token> docsxai login --backend-url ${backendUrl}\n`);
+        return 2;
+    }
+    let client;
+    try {
+        client = new BackendClient({ baseUrl: backendUrl });
+    }
+    catch (e) {
+        process.stderr.write(`login: ${e.message}\n`);
+        return 1;
+    }
+    try {
+        const h = await client.health();
+        if (!h.ok) {
+            process.stderr.write(`login: backend health-check returned ok=false\n`);
+            return 1;
+        }
+        const wss = await client.listWorkspaces();
+        process.stdout.write(`login: ok. ${wss.length} workspace${wss.length !== 1 ? "s" : ""} visible at ${backendUrl}\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof BackendClientError) {
+            process.stderr.write(`login: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+/** Ensure the workspace has a backend workspace + project to push to; create them on first push. */
+async function ensureBackendBinding(client, projectDir, cfg, workspaceName) {
+    let wsId = cfg.backend_workspace_id;
+    let projectId = cfg.backend_project_id;
+    let createdAny = false;
+    if (!wsId) {
+        const ws = await client.createWorkspace(workspaceName);
+        wsId = ws.id;
+        createdAny = true;
+    }
+    if (!projectId) {
+        const proj = await client.createProject(wsId, workspaceName);
+        projectId = proj.id;
+        createdAny = true;
+    }
+    return { wsId, projectId, createdAny };
+}
+export async function cmdPush(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`push: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const wsCfg = await loadWorkspaceConfig(projectDir);
+    if (!wsCfg?.backend_url) {
+        process.stderr.write(`push: no backend_url in ${path.join(projectDir, ".docsxai.json")}. Set it before pushing.\n`);
+        return 2;
+    }
+    const kindArg = typeof flags.get("kind") === "string" ? flags.get("kind") : "calibrate";
+    if (kindArg !== "calibrate" && kindArg !== "run" && kindArg !== "edit") {
+        process.stderr.write(`push: --kind must be calibrate | run | edit (got "${kindArg}")\n`);
+        return 2;
+    }
+    const author = (typeof flags.get("author") === "string" ? flags.get("author") : null) ??
+        process.env.USER ??
+        "unknown";
+    let client;
+    try {
+        client = await createBackendClient({ baseUrl: wsCfg.backend_url, workspaceDir: projectDir });
+    }
+    catch (e) {
+        process.stderr.write(`push: ${e.message}\n`);
+        return 1;
+    }
+    try {
+        const binding = await ensureBackendBinding(client, projectDir, wsCfg, path.basename(path.resolve(projectDir)));
+        if (binding.createdAny) {
+            // Persist the new IDs back to .docsxai.json so subsequent push/pull don't re-create.
+            const updated = {
+                ...wsCfg,
+                backend_workspace_id: binding.wsId,
+                backend_project_id: binding.projectId,
+            };
+            await fs.writeFile(resolveWorkspacePath(projectDir, ".docsxai.json"), JSON.stringify(updated, null, 2) + "\n", "utf8");
+        }
+        const rev = await client.createRevision(binding.wsId, binding.projectId, {
+            kind: kindArg,
+            author,
+        });
+        const payloads = await readDocPack(projectDir);
+        if (payloads.screenshots) {
+            // Screenshot bytes go up as content-addressed blobs (HEAD-probed, so unchanged PNGs are
+            // skipped); the artifact slot carries only the sha256 manifest.
+            const { uploaded, skipped } = await uploadScreenshotBlobs(projectDir, payloads.screenshots, client);
+            process.stdout.write(`push: screenshots — ${uploaded} blob(s) uploaded, ${skipped} already on the backend\n`);
+        }
+        let pushed = 0;
+        for (const [key, p] of Object.entries(payloads)) {
+            if (p === null)
+                continue;
+            await client.putArtifact(binding.wsId, binding.projectId, rev.id, key, p);
+            pushed++;
+        }
+        await client.finalizeRevision(binding.wsId, binding.projectId, rev.id);
+        process.stdout.write(`push: revision ${rev.id} (${kindArg}, ${author}) — ${pushed} artifact slot${pushed !== 1 ? "s" : ""} uploaded, finalized\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof BackendClientError) {
+            process.stderr.write(`push: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+export async function cmdPull(args) {
+    const { positionals, flags } = parseFlags(args);
+    if (!positionals[0]) {
+        process.stderr.write(`pull: missing <workspace-dir>\n`);
+        return 2;
+    }
+    const projectDir = positionals[0];
+    const wsCfg = await loadWorkspaceConfig(projectDir);
+    if (!wsCfg?.backend_url || !wsCfg.backend_workspace_id || !wsCfg.backend_project_id) {
+        process.stderr.write(`pull: workspace isn't bound to a backend yet. Run \`push\` first (or hand-edit .docsxai.json's backend_workspace_id / backend_project_id).\n`);
+        return 2;
+    }
+    const revArg = typeof flags.get("rev") === "string" ? flags.get("rev") : "head";
+    let client;
+    try {
+        client = await createBackendClient({ baseUrl: wsCfg.backend_url, workspaceDir: projectDir });
+    }
+    catch (e) {
+        process.stderr.write(`pull: ${e.message}\n`);
+        return 1;
+    }
+    try {
+        const rev = await client.getRevision(wsCfg.backend_workspace_id, wsCfg.backend_project_id, revArg);
+        const payloads = {};
+        for (const artifact of rev.artifacts) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            payloads[artifact] = await client.getArtifact(wsCfg.backend_workspace_id, wsCfg.backend_project_id, rev.id, artifact);
+        }
+        // The screenshots artifact is a sha256 manifest — fetch the bytes behind it (integrity-checked).
+        const screenshotBytes = payloads.screenshots
+            ? await fetchScreenshotBlobs(payloads.screenshots, client)
+            : undefined;
+        const r = await writeDocPack(projectDir, payloads, screenshotBytes ? { screenshotBytes } : {});
+        process.stdout.write(`pull: revision ${rev.id} (${rev.kind}, ${rev.author}) — wrote ${r.filesWritten} file(s)\n`);
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof BackendClientError) {
+            process.stderr.write(`pull: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+/** `docsxai plugins …` — forwards to the plugin-runtime CLI verbatim. */
+export async function cmdPlugins(args) {
+    return pluginsCli(args);
+}

package/dist/cli-commands-docpack.d.ts

@@ -0,0 +1,5 @@
+export declare function cmdRender(args: string[]): Promise<number>;
+export declare function cmdZip(args: string[]): Promise<number>;
+export declare function cmdExport(args: string[]): Promise<number>;
+export declare function cmdBaseline(args: string[]): Promise<number>;
+export declare function cmdDiff(args: string[]): Promise<number>;