@docsxai/engine 0.2.0

package/dist/plugins/plan.js

@@ -0,0 +1,279 @@
+// Plugin planning — the deterministic, code-free half of the runtime pipeline.
+//
+// Resolves every configured source to a validated manifest, then runs the ordering/rejection
+// stages purely over manifest metadata — NEVER importing or executing plugin code:
+//   1. Resolve each source ({package} via Node resolution, {path} realpath'd) to a manifest.
+//   2. Reject api-version-incompatible manifests (load-error, precise message).
+//   3. Verify plugins-lock.json sha256 of the register-module bytes BEFORE the load half imports.
+//   4. Namespace conflicts: every claimant of a contested namespace is disabled (deterministic).
+//   5. dependsOn presence + version-range checks (fixpoint — a disabled dep disables dependents).
+//   6. Tarjan-SCC cycle rejection: a cycle is refused as a unit, never partially loaded.
+//
+// The output is a plan: the disabled records, plus the surviving candidates in topological load
+// order. The capability subset check and the actual import + register() live in the load half,
+// so `docsxai plugins sync` pins hashes through `resolvePluginSources` without executing anything.
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { isApiVersionCompatible, parsePluginManifest, RUNTIME_API_VERSION, satisfiesRange, } from "./manifest.js";
+import { verifyLock } from "./lock.js";
+function sourceLabel(spec) {
+    return "package" in spec ? `package:${spec.package}` : `path:${spec.path}`;
+}
+function failureRecord(name, source, reason) {
+    return {
+        name,
+        version: "0.0.0",
+        namespace: "",
+        source,
+        trust: "local",
+        status: "load-error",
+        statusReason: reason,
+        artifacts: [],
+    };
+}
+/** Build the PluginRecord for a resolved candidate at a given status. Shared with the load half. */
+export function candidateRecord(c, status, reason) {
+    return {
+        name: c.name,
+        version: c.version,
+        namespace: c.manifest.namespace,
+        source: c.source,
+        trust: c.manifest.trust,
+        status,
+        ...(reason ? { statusReason: reason } : {}),
+        manifest: c.manifest,
+        registerPath: c.registerPath,
+        artifacts: [],
+    };
+}
+/**
+ * Stage 1 only: resolve every source to a validated manifest (or a load-error record). Never
+ * imports plugin code — `docsxai plugins sync` pins hashes through this without executing
+ * anything.
+ */
+export async function resolvePluginSources(workspaceDir, sources) {
+    const require = createRequire(import.meta.url);
+    const out = [];
+    for (const spec of sources) {
+        const label = sourceLabel(spec);
+        let pkgJsonPath;
+        if ("package" in spec) {
+            try {
+                pkgJsonPath = require.resolve(`${spec.package}/package.json`);
+            }
+            catch (e) {
+                out.push({
+                    ok: false,
+                    record: failureRecord(spec.package, label, `cannot resolve package "${spec.package}" — is it installed? (${e.message})`),
+                });
+                continue;
+            }
+        }
+        else {
+            const abs = path.resolve(workspaceDir, spec.path);
+            let real;
+            try {
+                real = await fs.realpath(abs);
+            }
+            catch {
+                out.push({
+                    ok: false,
+                    record: failureRecord(spec.path, label, `plugin path does not exist: ${abs}`),
+                });
+                continue;
+            }
+            pkgJsonPath = path.join(real, "package.json");
+        }
+        let pkg;
+        try {
+            pkg = JSON.parse(await fs.readFile(pkgJsonPath, "utf8"));
+        }
+        catch (e) {
+            out.push({
+                ok: false,
+                record: failureRecord(label, label, `cannot read ${pkgJsonPath}: ${e.message}`),
+            });
+            continue;
+        }
+        const name = typeof pkg.name === "string" && pkg.name ? pkg.name : label;
+        const version = typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+        let manifest;
+        try {
+            manifest = parsePluginManifest(pkg.docsxai, name);
+        }
+        catch (e) {
+            out.push({ ok: false, record: failureRecord(name, label, e.message) });
+            continue;
+        }
+        const dir = path.dirname(pkgJsonPath);
+        out.push({
+            ok: true,
+            candidate: {
+                name,
+                version,
+                dir,
+                registerPath: path.resolve(dir, manifest.register),
+                source: label,
+                manifest,
+            },
+        });
+    }
+    return out;
+}
+/** Tarjan strongly-connected components. Returns SCCs in reverse topological order. */
+function tarjanSccs(nodes, edges) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    function strongconnect(v) {
+        index.set(v, counter);
+        lowlink.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of edges.get(v) ?? []) {
+            if (!index.has(w)) {
+                strongconnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+            }
+            else if (onStack.has(w)) {
+                lowlink.set(v, Math.min(lowlink.get(v), index.get(w)));
+            }
+        }
+        if (lowlink.get(v) === index.get(v)) {
+            const scc = [];
+            for (;;) {
+                const w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+                if (w === v)
+                    break;
+            }
+            sccs.push(scc);
+        }
+    }
+    for (const v of nodes)
+        if (!index.has(v))
+            strongconnect(v);
+    return sccs;
+}
+/**
+ * Run the deterministic planning pipeline (stages 1–6) over the configured sources. Never imports
+ * plugin code; the surviving `loadOrder` is consumed by the load half, which performs the
+ * capability subset check and the actual import + register().
+ */
+export async function planPlugins(opts) {
+    const resolutions = await resolvePluginSources(opts.workspaceDir, opts.sources);
+    const disabled = [];
+    for (const r of resolutions)
+        if (!r.ok)
+            disabled.push(r.record);
+    let candidates = resolutions.filter((r) => r.ok).map((r) => r.candidate);
+    // Duplicate package names break dep-graph identity — refuse both, deterministically.
+    const byName = new Map();
+    for (const c of candidates)
+        byName.set(c.name, [...(byName.get(c.name) ?? []), c]);
+    for (const [name, group] of byName) {
+        if (group.length > 1) {
+            for (const c of group) {
+                disabled.push(candidateRecord(c, "load-error", `plugin package "${name}" is configured more than once (${group.map((g) => g.source).join(", ")}) — remove the duplicate`));
+            }
+        }
+    }
+    candidates = candidates.filter((c) => byName.get(c.name).length === 1);
+    // apiVersion compatibility.
+    candidates = candidates.filter((c) => {
+        if (isApiVersionCompatible(c.manifest.apiVersion))
+            return true;
+        disabled.push(candidateRecord(c, "load-error", `plugin apiVersion "${c.manifest.apiVersion}" is incompatible with the runtime apiVersion "${RUNTIME_API_VERSION}" ` +
+            `(requires same major and minor ≤ runtime) — upgrade the plugin or the engine`));
+        return false;
+    });
+    // Lock verification — BEFORE any import, so unverified bytes never execute.
+    if (opts.lock) {
+        const lock = opts.lock;
+        const verified = [];
+        for (const c of candidates) {
+            let bytes;
+            try {
+                bytes = await fs.readFile(c.registerPath);
+            }
+            catch {
+                bytes = null;
+            }
+            const mismatch = verifyLock(lock, c.manifest.namespace, bytes);
+            if (mismatch)
+                disabled.push(candidateRecord(c, "load-error", mismatch));
+            else
+                verified.push(c);
+        }
+        candidates = verified;
+    }
+    // Namespace conflicts: every claimant disabled — load order must not pick winners.
+    const byNamespace = new Map();
+    for (const c of candidates) {
+        byNamespace.set(c.manifest.namespace, [...(byNamespace.get(c.manifest.namespace) ?? []), c]);
+    }
+    for (const [ns, group] of byNamespace) {
+        if (group.length > 1) {
+            for (const c of group) {
+                disabled.push(candidateRecord(c, "disabled-by-namespace-conflict", `namespace "${ns}" is claimed by ${group.map((g) => `"${g.name}"`).join(" and ")} — namespaces must be unique; rename one`));
+            }
+        }
+    }
+    candidates = candidates.filter((c) => byNamespace.get(c.manifest.namespace).length === 1);
+    // dependsOn presence + version-range fixpoint: a disabled dep disables its dependents too.
+    const live = new Map(candidates.map((c) => [c.name, c]));
+    const dropForDeps = () => {
+        let changed = false;
+        for (const c of [...live.values()]) {
+            for (const dep of c.manifest.dependsOn) {
+                const target = live.get(dep.plugin);
+                let reason;
+                if (!target) {
+                    reason = `dependsOn "${dep.plugin}" is not loadable — configure it in the workspace "plugins" and ensure it resolves`;
+                }
+                else if (!satisfiesRange(target.version, dep.version)) {
+                    reason = `dependsOn "${dep.plugin}" version ${target.version} does not satisfy the declared range "${dep.version}"`;
+                }
+                if (reason) {
+                    disabled.push(candidateRecord(c, "disabled-by-dep-missing", reason));
+                    live.delete(c.name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        return changed;
+    };
+    while (dropForDeps()) {
+        /* fixpoint */
+    }
+    // Tarjan-SCC cycle rejection: refuse every member of a cycle as a unit.
+    const edges = new Map();
+    for (const c of live.values()) {
+        edges.set(c.name, c.manifest.dependsOn.map((d) => d.plugin).filter((n) => live.has(n)));
+    }
+    const sccs = tarjanSccs([...live.keys()], edges);
+    for (const scc of sccs) {
+        const selfLoop = scc.length === 1 && (edges.get(scc[0]) ?? []).includes(scc[0]);
+        if (scc.length > 1 || selfLoop) {
+            const cycle = [...scc].sort();
+            for (const name of scc) {
+                disabled.push(candidateRecord(live.get(name), "disabled-by-cycle", `dependsOn cycle: ${cycle.join(" → ")} → ${cycle[0]} — break the cycle; none of its members load`));
+                live.delete(name);
+            }
+        }
+    }
+    while (dropForDeps()) {
+        /* dependents of cycle members are now dep-missing */
+    }
+    // Tarjan emits SCCs in reverse topological order; for a DAG that IS the load order
+    // (dependencies before dependents).
+    const loadOrder = sccs.map((scc) => scc[0]).filter((name) => live.has(name));
+    return { disabled, live, loadOrder };
+}

package/dist/plugins/registry.d.ts

@@ -0,0 +1,59 @@
+import type { PluginKind, PluginManifest, PluginTrust } from "./manifest.js";
+import type { AuthStrategyPlugin, PluginLintRule, PublisherPlugin, RendererPlugin } from "./types.js";
+export type PluginStatus = "loaded" | "disabled-by-capability-mismatch" | "disabled-by-cycle" | "disabled-by-dep-missing" | "disabled-by-namespace-conflict" | "load-error";
+export interface PluginArtifact {
+    kind: PluginKind;
+    /** Namespace-qualified name, `<ns>:<name>`. */
+    name: string;
+}
+export interface PluginRecord {
+    /** Package name, or the source spec when the package never resolved. */
+    name: string;
+    version: string;
+    /** Empty string when the manifest never validated. */
+    namespace: string;
+    /** `package:<npm-name>` or `path:<absolute-dir>`. */
+    source: string;
+    trust: PluginTrust;
+    status: PluginStatus;
+    statusReason?: string;
+    manifest?: PluginManifest;
+    /** Absolute path of the register module, when the manifest resolved. */
+    registerPath?: string;
+    artifacts: PluginArtifact[];
+}
+/** Artifacts a successfully-registered plugin contributes; committed atomically per plugin. */
+export interface RegisteredArtifacts {
+    publishers: ReadonlyMap<string, PublisherPlugin>;
+    renderers: ReadonlyMap<string, RendererPlugin>;
+    authStrategies: ReadonlyMap<string, AuthStrategyPlugin>;
+    lintRules: ReadonlyArray<{
+        name: string;
+        rules: ReadonlyArray<PluginLintRule>;
+    }>;
+}
+export declare class PluginRegistryError extends Error {
+    constructor(message: string);
+}
+export declare class PluginRegistry {
+    readonly workspaceDir: string;
+    private readonly records;
+    private readonly publishers;
+    private readonly renderers;
+    private readonly authStrategies;
+    private readonly lintRules;
+    constructor(workspaceDir: string);
+    /** Workspace-contained path resolution — the only filesystem root plugins may touch. */
+    workspacePath(...segments: string[]): string;
+    /** Runtime-facing: record a plugin's outcome (and, when loaded, its artifacts) atomically. */
+    commit(record: PluginRecord, artifacts?: RegisteredArtifacts): void;
+    /** Full status table, sorted by namespace (package name as fallback) for deterministic output. */
+    listPlugins(): PluginRecord[];
+    /** Manifest + registered artifact names for one plugin, looked up by namespace or package name. */
+    pluginsInfo(name: string): PluginRecord | undefined;
+    getPublisher(qualifiedName: string): PublisherPlugin;
+    getRenderer(qualifiedName: string): RendererPlugin;
+    getAuthStrategies(): Map<string, AuthStrategyPlugin>;
+    getLintRules(): PluginLintRule[];
+    private unknownArtifact;
+}

package/dist/plugins/registry.js

@@ -0,0 +1,71 @@
+// The composed plugin surface a CLI invocation consumes. The runtime resolves + loads plugins
+// once and commits each one here; consumers retrieve artifacts by their namespace-qualified
+// name (`<ns>:<name>`). All plugin file IO is chokepointed through `workspacePath`, which
+// routes through `resolveWorkspacePath` against the workspace this registry was built for.
+import { resolveWorkspacePath } from "../workspace.js";
+export class PluginRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginRegistryError";
+    }
+}
+export class PluginRegistry {
+    workspaceDir;
+    records = [];
+    publishers = new Map();
+    renderers = new Map();
+    authStrategies = new Map();
+    lintRules = [];
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    /** Workspace-contained path resolution — the only filesystem root plugins may touch. */
+    workspacePath(...segments) {
+        return resolveWorkspacePath(this.workspaceDir, ...segments);
+    }
+    /** Runtime-facing: record a plugin's outcome (and, when loaded, its artifacts) atomically. */
+    commit(record, artifacts) {
+        this.records.push(record);
+        if (!artifacts)
+            return;
+        for (const [name, impl] of artifacts.publishers)
+            this.publishers.set(name, impl);
+        for (const [name, impl] of artifacts.renderers)
+            this.renderers.set(name, impl);
+        for (const [name, impl] of artifacts.authStrategies)
+            this.authStrategies.set(name, impl);
+        for (const set of artifacts.lintRules)
+            this.lintRules.push(...set.rules);
+    }
+    /** Full status table, sorted by namespace (package name as fallback) for deterministic output. */
+    listPlugins() {
+        return [...this.records].sort((a, b) => (a.namespace || a.name).localeCompare(b.namespace || b.name));
+    }
+    /** Manifest + registered artifact names for one plugin, looked up by namespace or package name. */
+    pluginsInfo(name) {
+        return (this.records.find((r) => r.namespace === name) ?? this.records.find((r) => r.name === name));
+    }
+    getPublisher(qualifiedName) {
+        const impl = this.publishers.get(qualifiedName);
+        if (!impl)
+            throw this.unknownArtifact("publisher", qualifiedName, this.publishers.keys());
+        return impl;
+    }
+    getRenderer(qualifiedName) {
+        const impl = this.renderers.get(qualifiedName);
+        if (!impl)
+            throw this.unknownArtifact("renderer", qualifiedName, this.renderers.keys());
+        return impl;
+    }
+    getAuthStrategies() {
+        return new Map(this.authStrategies);
+    }
+    getLintRules() {
+        return [...this.lintRules];
+    }
+    unknownArtifact(kind, qualifiedName, known) {
+        const names = [...known].sort();
+        return new PluginRegistryError(`no ${kind} named "${qualifiedName}" is registered` +
+            (names.length ? ` (registered: ${names.join(", ")})` : " (no plugins registered one)"));
+    }
+}

package/dist/plugins/runtime.d.ts

@@ -0,0 +1,7 @@
+import type { PluginRegistry } from "./registry.js";
+import { type ResolvePluginsOptions } from "./plan.js";
+export type { PluginSourceResolution, ResolvedPluginSource, ResolvePluginsOptions, } from "./plan.js";
+export { resolvePluginSources } from "./plan.js";
+export type { PluginRegisterApi } from "./load.js";
+/** Resolve, verify, and load the configured plugins. Every failure is a status, never a throw. */
+export declare function resolvePlugins(opts: ResolvePluginsOptions): Promise<PluginRegistry>;

package/dist/plugins/runtime.js

@@ -0,0 +1,27 @@
+// Plugin runtime — resolves the configured plugin set once per CLI invocation.
+//
+// This module is the orchestration barrel: it composes the two halves of the pipeline and
+// re-exports their public surface. The split keeps the deterministic, code-free planning half
+// (./plan.ts) apart from the impure load half (./load.ts), which is the SOLE place plugin code
+// is imported and register() runs.
+//
+// Pipeline:
+//   1. Resolve each source ({package} via Node resolution, {path} realpath'd) to a manifest.  ┐
+//   2. Reject api-version-incompatible manifests (load-error, precise message).               │
+//   3. Verify plugins-lock.json sha256 of the register-module bytes BEFORE importing.         │ plan.ts
+//   4. Namespace conflicts: every claimant of a contested namespace is disabled.              │
+//   5. dependsOn presence + version-range checks (fixpoint — a disabled dep disables deps).   │
+//   6. Tarjan-SCC cycle rejection: a cycle is refused as a unit, never partially loaded.      ┘
+//   7. Capability subset check against the operator-enabled set (disables, not fatal).        ┐ load.ts
+//   8. Import each register module in topological order; call register(api) exactly once.     ┘
+//
+// Plugins are in-process Node modules — NOT sandboxed. Trust is a review signal, not a boundary.
+// A register() failure rolls back that plugin's artifacts and lands as a load-error status.
+import { planPlugins } from "./plan.js";
+import { loadPlugins } from "./load.js";
+export { resolvePluginSources } from "./plan.js";
+/** Resolve, verify, and load the configured plugins. Every failure is a status, never a throw. */
+export async function resolvePlugins(opts) {
+    const plan = await planPlugins(opts);
+    return loadPlugins(opts, plan);
+}

package/dist/plugins/types.d.ts

@@ -0,0 +1,58 @@
+import type { LintRule } from "../flow-lint.js";
+/** Plugin-scoped logger. Writes to stderr prefixed `[plugin:<ns>]` — stdout stays clean for CLI output. */
+export interface PluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface PublisherContext {
+    workspaceDir: string;
+    projection: unknown;
+    artifactsDir: string;
+    config: Record<string, unknown>;
+    secretsEnv: Record<string, string>;
+    log: PluginLogger;
+}
+export interface PublishResult {
+    ok: boolean;
+    target: string;
+    /** `section` echoes the projection section a page belongs to, so callers can rebuild their `{ section → pageId }` map from the result. */
+    pages: Array<{
+        id: string;
+        url?: string;
+        action: "created" | "updated" | "unchanged";
+        section?: string;
+    }>;
+    warnings: string[];
+}
+export interface PublisherPlugin {
+    publish(ctx: PublisherContext): Promise<PublishResult>;
+}
+export interface RendererContext {
+    workspaceDir: string;
+    outDir: string;
+    flows: string[];
+    config: Record<string, unknown>;
+    log: PluginLogger;
+}
+export interface RendererResult {
+    ok: boolean;
+    outputs: string[];
+    warnings: string[];
+}
+export interface RendererPlugin {
+    render(ctx: RendererContext): Promise<RendererResult>;
+}
+export interface AuthStrategyPlugin {
+    authenticate(ctx: {
+        creds: Record<string, string>;
+        options: Record<string, unknown>;
+        baseURL: string;
+        workspaceDir: string;
+    }): Promise<{
+        storageState: unknown;
+        expiresAt?: string;
+        contextOptions?: Record<string, unknown>;
+    }>;
+}
+export type PluginLintRule = LintRule;

package/dist/plugins/types.js

@@ -0,0 +1,4 @@
+// Extension-point contracts for the plugin runtime. Publishers, renderers, lint-rules, and
+// auth-strategies code against these shapes; the runtime auto-prefixes registered names with
+// the plugin's namespace (`<ns>:<name>`).
+export {};

package/dist/plugins-cli.d.ts

@@ -0,0 +1 @@
+export declare function pluginsCli(args: string[]): Promise<number>;