@docsxai/engine 0.2.0

package/dist/doctor-checks.js

@@ -0,0 +1,367 @@
+// `docsxai doctor` — the per-check probe catalogue.
+//
+// One pure(ish) function per row of the doctor checklist, each over injectable inputs (a workspace
+// dir, an env source, a fake backend, a mocked chromium probe) so per-state coverage is cheap.
+// `doctor.ts` orchestrates these into the printed checklist. Pure inspection throughout: no flow
+// runs, no plugin code execution, no browser launch — the only network touch is the opt-in GET of
+// the configured backend's /v1/health.
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { parseAuthStrategyFile } from "./auth.js";
+import { FlowFileError, parseFlowFile } from "./flow-file.js";
+import { chromiumExecutablePath } from "./playwright-driver.js";
+import { resolveViewerBin, VIEWER_BIN_ENV, VIEWER_BIN_NAME, VIEWER_PACKAGE } from "./viewer-bin.js";
+import { resolveWorkspacePath, WORKSPACE_CONFIG_FILE } from "./workspace.js";
+const CHROMIUM_FIX = "npx playwright-core install chromium  (source checkout: pnpm -C packages/engine exec playwright-core install chromium)";
+/** Layer-3 default probe: does playwright-core have a cached Chromium binary?
+ *  Synchronous - the sole work is the sanctioned `chromiumExecutablePath()`
+ *  helper (a sync `executablePath()` + `existsSync`), no IO to await. */
+export function probeChromium() {
+    try {
+        // Goes through playwright-driver's helper — the one sanctioned playwright-core entry point —
+        // so doctor doesn't open a second import site for the SDK.
+        const p = chromiumExecutablePath();
+        if (p)
+            return { ok: true, detail: p };
+        return { ok: false, detail: "playwright-core has no Chromium binary cached" };
+    }
+    catch (e) {
+        return { ok: false, detail: e.message };
+    }
+}
+async function readTextIfExists(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Individual checks (exported for per-state unit tests)
+// ---------------------------------------------------------------------------
+export function checkNode(nodeVersion) {
+    const major = Number(nodeVersion.split(".")[0]);
+    if (Number.isFinite(major) && major >= 20) {
+        return { name: "node", ok: true, detail: `v${nodeVersion} (>= 20 required)` };
+    }
+    return {
+        name: "node",
+        ok: false,
+        detail: `v${nodeVersion} — the engine requires Node >= 20`,
+        fix: "upgrade Node (https://nodejs.org); the engine's `engines` field pins >= 20",
+    };
+}
+export async function checkChromium(probe) {
+    const r = await probe();
+    return r.ok
+        ? { name: "chromium", ok: true, detail: r.detail }
+        : { name: "chromium", ok: false, detail: r.detail, fix: CHROMIUM_FIX };
+}
+export async function checkWorkspace(workspaceDir) {
+    const configPath = path.join(path.resolve(workspaceDir), WORKSPACE_CONFIG_FILE);
+    const text = await readTextIfExists(configPath);
+    const flowsDirExists = existsSync(path.join(path.resolve(workspaceDir), "flows"));
+    if (text === null) {
+        return {
+            check: {
+                name: "workspace",
+                ok: true,
+                info: true,
+                detail: flowsDirExists
+                    ? `flows/ present but no ${WORKSPACE_CONFIG_FILE} at ${workspaceDir} — \`docsxai init\` writes one`
+                    : `no ${WORKSPACE_CONFIG_FILE} at ${workspaceDir} — not a docsxai workspace (pass <workspace-dir> or run doctor from one); workspace checks skipped`,
+            },
+            config: null,
+            present: flowsDirExists,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return {
+            check: {
+                name: "workspace",
+                ok: false,
+                detail: `${configPath} is not valid JSON: ${e.message}`,
+                fix: `fix the JSON (or re-scaffold with \`docsxai init ${workspaceDir} --force\`)`,
+            },
+            config: null,
+            present: true,
+        };
+    }
+    const cfg = raw;
+    if (cfg?.schema !== "docsxai/workspace@1") {
+        return {
+            check: {
+                name: "workspace",
+                ok: false,
+                detail: `${configPath} has schema "${String(cfg?.schema)}" — expected "docsxai/workspace@1"`,
+                fix: `set "schema": "docsxai/workspace@1" (or re-scaffold with \`docsxai init\`)`,
+            },
+            config: null,
+            present: true,
+        };
+    }
+    const appUrl = typeof cfg.app_url === "string" ? cfg.app_url : undefined;
+    return {
+        check: {
+            name: "workspace",
+            ok: true,
+            detail: `${configPath} (docsxai/workspace@1${appUrl ? `, app_url ${appUrl}` : ", no app_url"})`,
+        },
+        config: cfg,
+        present: true,
+    };
+}
+export async function checkFlows(workspaceDir) {
+    const flowsDir = path.join(path.resolve(workspaceDir), "flows");
+    let entries;
+    try {
+        entries = (await fs.readdir(flowsDir)).filter((e) => e.endsWith(".flow.yaml")).sort();
+    }
+    catch {
+        return {
+            name: "flows",
+            ok: false,
+            detail: `no flows/ directory at ${flowsDir}`,
+            fix: `\`docsxai init\` scaffolds it; flows live at flows/<name>.flow.yaml`,
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            name: "flows",
+            ok: true,
+            info: true,
+            detail: "flows/ is empty — calibrate one, or hand-author flows/<name>.flow.yaml",
+        };
+    }
+    for (const entry of entries) {
+        const p = path.join(flowsDir, entry);
+        try {
+            parseFlowFile(await fs.readFile(p, "utf8"), entry);
+        }
+        catch (e) {
+            const msg = e instanceof FlowFileError ? e.message : e.message;
+            return {
+                name: "flows",
+                ok: false,
+                detail: `${entry} does not parse: ${msg}`,
+                fix: `fix the flow-file (then \`docsxai lint ${workspaceDir}\` for the full static report)`,
+            };
+        }
+    }
+    return {
+        name: "flows",
+        ok: true,
+        detail: `${entries.length} flow-file(s) parse`,
+    };
+}
+export async function checkAuth(workspaceDir, now) {
+    const descriptorPath = resolveWorkspacePath(workspaceDir, "auth", "strategy.yaml");
+    const text = await readTextIfExists(descriptorPath);
+    if (text === null) {
+        return [
+            {
+                name: "auth",
+                ok: true,
+                info: true,
+                detail: "no auth/strategy.yaml — flows run with a fresh, unauthenticated context",
+            },
+        ];
+    }
+    let descriptor;
+    try {
+        descriptor = parseAuthStrategyFile(text, descriptorPath);
+    }
+    catch (e) {
+        return [
+            {
+                name: "auth",
+                ok: false,
+                detail: e.message.replace(/\n\s*/g, " "),
+                fix: "fix auth/strategy.yaml against the descriptor schema (docsxai/auth-strategy@1)",
+            },
+        ];
+    }
+    const role = descriptor.default_role;
+    const roles = Object.keys(descriptor.roles).join(", ");
+    const checks = [
+        {
+            name: "auth",
+            ok: true,
+            detail: `auth/strategy.yaml ok — role(s) ${roles} (default "${role}", strategy ${descriptor.roles[role].strategy})`,
+        },
+    ];
+    // Cached-session freshness for the default role (the one `run` loads).
+    const sessionPath = resolveWorkspacePath(workspaceDir, ".auth", `${role}.json`);
+    const sessionText = await readTextIfExists(sessionPath);
+    if (sessionText === null) {
+        checks.push({
+            name: "auth",
+            ok: true,
+            info: true,
+            detail: `no cached session for role "${role}" — \`docsxai capture-auth ${workspaceDir}\` before \`run\``,
+        });
+        return checks;
+    }
+    let expiresAt;
+    try {
+        const parsed = JSON.parse(sessionText);
+        expiresAt = typeof parsed.expiresAt === "number" ? parsed.expiresAt : undefined;
+    }
+    catch {
+        expiresAt = undefined;
+    }
+    if (expiresAt === undefined) {
+        checks.push({
+            name: "auth",
+            ok: false,
+            detail: `cached session ${sessionPath} is corrupt (no expiresAt)`,
+            fix: `re-capture: docsxai capture-auth ${workspaceDir}`,
+        });
+    }
+    else if (expiresAt <= now) {
+        checks.push({
+            name: "auth",
+            ok: false,
+            detail: `cached session for role "${role}" expired ${new Date(expiresAt).toISOString()}`,
+            fix: `re-capture: docsxai capture-auth ${workspaceDir}`,
+        });
+    }
+    else {
+        checks.push({
+            name: "auth",
+            ok: true,
+            detail: `cached session for role "${role}" valid until ${new Date(expiresAt).toISOString()}`,
+        });
+    }
+    return checks;
+}
+export async function checkBackend(workspaceDir, config, env, fetchImpl) {
+    const backendUrl = typeof config?.backend_url === "string" ? config.backend_url : undefined;
+    if (!backendUrl) {
+        return {
+            name: "backend",
+            ok: true,
+            info: true,
+            detail: "no backend_url configured — the workspace operates fully locally",
+        };
+    }
+    // Token presence is a note, not a gate — /v1/health is unauthenticated.
+    const tokenNote = env.DOCSX_TOKEN
+        ? "token: DOCSX_TOKEN set"
+        : existsSync(path.join(path.resolve(workspaceDir), ".auth", "backend-token.json"))
+            ? "token: OAuth tokens at .auth/backend-token.json"
+            : "no token — push/pull need DOCSX_TOKEN or `docsxai login --oauth`";
+    const base = backendUrl.replace(/\/+$/, "");
+    try {
+        const res = await fetchImpl(`${base}/v1/health`, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok) {
+            return {
+                name: "backend",
+                ok: false,
+                detail: `${base}/v1/health → HTTP ${res.status}`,
+                fix: "the backend answered but is unhealthy — check its logs",
+            };
+        }
+        return { name: "backend", ok: true, detail: `${base}/v1/health ok (${tokenNote})` };
+    }
+    catch (e) {
+        return {
+            name: "backend",
+            ok: false,
+            detail: `${base}/v1/health unreachable (${e.message})`,
+            fix: "start the backend (or fix backend_url in .docsxai.json)",
+        };
+    }
+}
+export async function checkViewer(env, resolveFrom) {
+    const resolution = await resolveViewerBin({
+        env: env,
+        ...(resolveFrom ? { resolveFrom } : {}),
+    });
+    if (resolution.source === "env") {
+        return {
+            name: "viewer",
+            ok: true,
+            detail: `$${VIEWER_BIN_ENV} → ${resolution.prefixArgs[0] ?? resolution.command} (layer 1: env override)`,
+        };
+    }
+    if (resolution.source === "package") {
+        return {
+            name: "viewer",
+            ok: true,
+            detail: `${VIEWER_PACKAGE} installed next to the engine → ${resolution.prefixArgs[0]} (layer 2: installed package)`,
+        };
+    }
+    // Layer 3 is "trust PATH" — resolveViewerBin doesn't verify it, so doctor does.
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, VIEWER_BIN_NAME);
+        if (existsSync(candidate)) {
+            return {
+                name: "viewer",
+                ok: true,
+                detail: `\`${VIEWER_BIN_NAME}\` on PATH → ${candidate} (layer 3: PATH)`,
+            };
+        }
+    }
+    return {
+        name: "viewer",
+        ok: false,
+        detail: `\`${VIEWER_BIN_NAME}\` not resolvable — tried $${VIEWER_BIN_ENV}, the installed ${VIEWER_PACKAGE} package, and PATH`,
+        fix: `install ${VIEWER_PACKAGE} next to the engine (a global \`docsxai\` install ships it), or point ${VIEWER_BIN_ENV} at its bin script`,
+    };
+}
+/** DOCSX_* env vars the docsxai packages read (engine + backend). */
+export const KNOWN_DOCSX_ENV_VARS = [
+    "DOCSX_TOKEN",
+    "DOCSX_CACHE_KEY",
+    "DOCSX_VIEWER_BIN",
+    "DOCSX_ENGINE_BIN",
+    "DOCSX_DATA_DIR",
+    "DOCSX_OAUTH_AUTO_APPROVE",
+    "DOCSX_WEBHOOK_SECRET",
+];
+export function checkEnv(env) {
+    const set = Object.keys(env)
+        .filter((k) => k.startsWith("DOCSX_"))
+        .sort();
+    if (set.length === 0) {
+        return [
+            { name: "env", ok: true, info: true, detail: "no DOCSX_* variables set (defaults apply)" },
+        ];
+    }
+    const checks = [];
+    const known = set.filter((k) => KNOWN_DOCSX_ENV_VARS.includes(k));
+    if (known.length > 0) {
+        checks.push({ name: "env", ok: true, detail: `set: ${known.join(", ")}` });
+    }
+    const cacheKey = env.DOCSX_CACHE_KEY;
+    if (cacheKey) {
+        const decoded = Buffer.from(cacheKey, "base64");
+        if (decoded.length !== 32) {
+            checks.push({
+                name: "env",
+                ok: false,
+                detail: `DOCSX_CACHE_KEY must decode to exactly 32 bytes (got ${decoded.length})`,
+                fix: "regenerate: openssl rand -base64 32",
+            });
+        }
+    }
+    for (const k of set) {
+        if (!KNOWN_DOCSX_ENV_VARS.includes(k)) {
+            checks.push({
+                name: "env",
+                ok: false,
+                detail: `${k} is not a DOCSX_* variable any docsxai package reads (typo?)`,
+                fix: `unset it or fix the spelling — known: ${KNOWN_DOCSX_ENV_VARS.join(", ")}`,
+            });
+        }
+    }
+    return checks;
+}

package/dist/doctor.d.ts

@@ -0,0 +1,7 @@
+import { type DoctorCheck, type DoctorOptions } from "./doctor-checks.js";
+export * from "./doctor-checks.js";
+export * from "./doctor-checks-plugins.js";
+export declare function buildDoctorChecks(opts?: DoctorOptions): Promise<DoctorCheck[]>;
+export declare function formatDoctorChecks(checks: DoctorCheck[]): string;
+/** `docsxai doctor [<workspace-dir>]` — returns the process exit code. */
+export declare function runDoctor(args: string[]): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,62 @@
+// `docsxai doctor` — environment + workspace health-check.
+//
+// Prints a ✓/✗ checklist with a one-line fix per failing check (− marks purely
+// informational rows; they never fail doctor). Exits 0 iff everything passes,
+// 1 otherwise. Pure inspection throughout: no flow runs, no plugin code
+// execution, no browser launch — the only network touch is an opt-in GET of
+// the configured backend's /v1/health.
+//
+// The per-check probe catalogue lives in ./doctor-checks.js; this file owns the
+// checklist assembly + CLI entry and re-exports the checks' public surface so
+// every doctor symbol stays importable from ./doctor.js.
+import { checkAuth, checkBackend, checkChromium, checkEnv, checkFlows, checkNode, checkViewer, checkWorkspace, probeChromium, } from "./doctor-checks.js";
+import { checkPlugins } from "./doctor-checks-plugins.js";
+// Re-export the probe catalogue's public surface so importers keep reaching it
+// through ./doctor.js (its original home) — no importer or test changes. The
+// plugin-runtime probe lives in its own sibling but is re-exported here too.
+export * from "./doctor-checks.js";
+export * from "./doctor-checks-plugins.js";
+// ---------------------------------------------------------------------------
+// Assembly + CLI entry
+// ---------------------------------------------------------------------------
+export async function buildDoctorChecks(opts = {}) {
+    const env = opts.env ?? process.env;
+    const now = opts.now ?? Date.now();
+    const workspaceDir = opts.workspaceDir ?? process.cwd();
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const checks = [];
+    checks.push(checkNode(opts.nodeVersion ?? process.versions.node));
+    checks.push(await checkChromium(opts.chromiumProbe ?? probeChromium));
+    const ws = await checkWorkspace(workspaceDir);
+    checks.push(ws.check);
+    if (ws.present) {
+        checks.push(await checkFlows(workspaceDir));
+        checks.push(...(await checkAuth(workspaceDir, now)));
+        checks.push(await checkBackend(workspaceDir, ws.config, env, fetchImpl));
+        checks.push(...(await checkPlugins(workspaceDir)));
+    }
+    checks.push(await checkViewer(env));
+    checks.push(...checkEnv(env));
+    return checks;
+}
+export function formatDoctorChecks(checks) {
+    let out = "docsxai doctor — environment & workspace health\n\n";
+    let allOk = true;
+    for (const c of checks) {
+        if (!c.ok)
+            allOk = false;
+        const glyph = c.info ? "−" : c.ok ? "✓" : "✗";
+        out += `  ${glyph} ${c.name.padEnd(10)} ${c.detail}\n`;
+        if (!c.ok && c.fix)
+            out += `    fix: ${c.fix}\n`;
+    }
+    out += `\n${allOk ? "all checks passed" : "fix the ✗ items above"}\n`;
+    return out;
+}
+/** `docsxai doctor [<workspace-dir>]` — returns the process exit code. */
+export async function runDoctor(args) {
+    const positionals = args.filter((a) => !a.startsWith("--"));
+    const checks = await buildDoctorChecks(positionals[0] ? { workspaceDir: positionals[0] } : {});
+    process.stdout.write(formatDoctorChecks(checks));
+    return checks.every((c) => c.ok) ? 0 : 1;
+}

package/dist/export/adf.d.ts

@@ -0,0 +1,57 @@
+export interface AdfMark {
+    type: string;
+    attrs?: Record<string, unknown>;
+}
+export interface AdfNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    marks?: AdfMark[];
+    content?: AdfNode[];
+    text?: string;
+}
+export interface AdfDoc {
+    version: 1;
+    type: "doc";
+    content: AdfNode[];
+}
+export type AdfExportMode = "single" | "page-tree";
+export interface AdfAttachment {
+    /** Unique-within-document upload name, `<flow>--<step>.png`. */
+    fileName: string;
+    /** Absolute path of the source PNG inside the workspace. */
+    sourcePath: string;
+    /** sha256 (hex) of the source bytes — the publisher's skip-unchanged key. */
+    sha256: string;
+}
+export interface AdfDocument {
+    /** Page-identity key: `project` for the consolidated/parent page, the flow name for children. */
+    section: string;
+    title: string;
+    adf: AdfDoc;
+    attachments: AdfAttachment[];
+}
+export interface AdfProjection {
+    schema: "docsxai/adf-projection@1";
+    mode: AdfExportMode;
+    documents: AdfDocument[];
+    warnings: string[];
+}
+export interface AdfExportOptions {
+    mode?: AdfExportMode;
+    /** Title of the consolidated page (`single`) / the parent page (`page-tree`). Default: "Site documentation". */
+    title?: string;
+}
+/** Inline markdown → ADF text nodes, accumulating marks through nesting (bold inside link, …). */
+export declare function inlineMarkdownToAdf(source: string, marks?: AdfMark[]): AdfNode[];
+/** Block-level markdown (subset) → ADF block nodes. */
+export declare function markdownToAdf(markdown: string): AdfNode[];
+/**
+ * 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 declare function projectDocPackToAdf(opts: {
+    workspaceDir: string;
+    /** Restrict to these flow names (default: every `flows/*.flow.yaml`). Unknown names throw. */
+    flows?: string[];
+    options?: AdfExportOptions;
+}): Promise<AdfProjection>;