@docsxai/engine 0.2.0

package/dist/plugins/load.js

@@ -0,0 +1,99 @@
+// Plugin loading — the impure half of the runtime pipeline, and the SOLE place plugin code runs.
+//
+// Given a plan (survivors in topological order), this:
+//   7. Capability subset check against the operator-enabled set (disables, not fatal).
+//   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.
+// This is the only module that dynamically imports plugin modules and invokes register().
+import { pathToFileURL } from "node:url";
+import { resolveWorkspacePath } from "../workspace.js";
+import { PluginRegistry } from "./registry.js";
+import { candidateRecord } from "./plan.js";
+/**
+ * Commit the plan's disabled records, then import + register the surviving plugins in load order.
+ * Every failure is a status, never a throw. This is the only place plugin code is imported.
+ */
+export async function loadPlugins(opts, plan) {
+    const registry = new PluginRegistry(opts.workspaceDir);
+    const enabled = new Set(opts.enabledCapabilities ?? []);
+    const { disabled, live, loadOrder } = plan;
+    for (const record of disabled)
+        registry.commit(record);
+    for (const name of loadOrder) {
+        const c = live.get(name);
+        const missing = c.manifest.capabilities.filter((cap) => !enabled.has(cap));
+        if (missing.length > 0) {
+            registry.commit(candidateRecord(c, "disabled-by-capability-mismatch", `plugin declares capabilities [${missing.join(", ")}] not enabled for this workspace — ` +
+                `add them to "plugin_capabilities" in .docsxai.json to opt in`));
+            continue;
+        }
+        const ns = c.manifest.namespace;
+        const publishers = new Map();
+        const renderers = new Map();
+        const authStrategies = new Map();
+        const lintRules = [];
+        const artifacts = [];
+        const ARTIFACT_NAME = /^[a-z][a-z0-9-]*$/;
+        const qualify = (kind, bare, taken) => {
+            if (!c.manifest.kinds.includes(kind)) {
+                throw new Error(`plugin "${c.name}": registered a "${kind}" but the manifest's kinds are [${c.manifest.kinds.join(", ")}] — declare every extension point the plugin registers`);
+            }
+            if (!ARTIFACT_NAME.test(bare)) {
+                throw new Error(`plugin "${c.name}": artifact name "${bare}" must be bare kebab-case (the runtime prefixes "${ns}:")`);
+            }
+            const qualified = `${ns}:${bare}`;
+            if (taken.has(qualified)) {
+                throw new Error(`plugin "${c.name}": ${kind} "${qualified}" is already registered`);
+            }
+            artifacts.push({ kind, name: qualified });
+            return qualified;
+        };
+        const log = {
+            info: (message) => process.stderr.write(`[plugin:${ns}] ${message}\n`),
+            warn: (message) => process.stderr.write(`[plugin:${ns}] warn: ${message}\n`),
+            error: (message) => process.stderr.write(`[plugin:${ns}] error: ${message}\n`),
+        };
+        const lintRuleNames = new Set();
+        const api = {
+            namespace: ns,
+            declaredKinds: c.manifest.kinds,
+            declaredCapabilities: c.manifest.capabilities,
+            registerPublisher: (bare, impl) => {
+                publishers.set(qualify("publisher", bare, publishers), impl);
+            },
+            registerRenderer: (bare, impl) => {
+                renderers.set(qualify("renderer", bare, renderers), impl);
+            },
+            registerLintRules: (bare, rules) => {
+                const qualified = qualify("lint-rules", bare, lintRuleNames);
+                lintRuleNames.add(qualified);
+                lintRules.push({ name: qualified, rules: [...rules] });
+            },
+            registerAuthStrategy: (bare, impl) => {
+                authStrategies.set(qualify("auth-strategy", bare, authStrategies), impl);
+            },
+            log,
+            workspacePath: (...segments) => resolveWorkspacePath(opts.workspaceDir, ...segments),
+        };
+        try {
+            const mod = (await import(pathToFileURL(c.registerPath).href));
+            const fn = mod.register ?? mod.default;
+            if (typeof fn !== "function") {
+                throw new Error(`register module ${c.registerPath} must export a register(api) function (named or default)`);
+            }
+            await fn(api);
+        }
+        catch (e) {
+            // Roll back: nothing this plugin registered survives a failed register().
+            registry.commit(candidateRecord(c, "load-error", `register() failed for plugin "${c.name}": ${e.message}`));
+            continue;
+        }
+        const record = candidateRecord(c, "loaded");
+        record.artifacts = artifacts;
+        const committed = { publishers, renderers, authStrategies, lintRules };
+        registry.commit(record, committed);
+    }
+    return registry;
+}

package/dist/plugins/lock.d.ts

@@ -0,0 +1,40 @@
+export declare const PLUGINS_LOCK_FILE = "plugins-lock.json";
+export declare const PLUGINS_LOCK_SCHEMA = "docsxai/plugins-lock@1";
+/** Where a plugin comes from: an installed package (resolved via Node) or a local directory. */
+export type PluginSourceSpec = {
+    package: string;
+} | {
+    path: string;
+};
+export interface PluginsLockEntry {
+    source: string;
+    version: string;
+    /** Hex sha256 of the register module's file bytes. */
+    sha256: string;
+}
+export interface PluginsLockFile {
+    schema: typeof PLUGINS_LOCK_SCHEMA;
+    plugins: Record<string, PluginsLockEntry>;
+}
+export declare class PluginsLockError extends Error {
+    constructor(message: string);
+}
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Read `<workspace>/plugins-lock.json`. `null` when absent; throws on a malformed file. */
+export declare function readPluginsLock(workspaceDir: string): Promise<PluginsLockFile | null>;
+/** Write `<workspace>/plugins-lock.json` (deterministic key order). Returns the path written. */
+export declare function writePluginsLock(workspaceDir: string, lock: PluginsLockFile): Promise<string>;
+/**
+ * Verify a resolved plugin against the lock. Returns `null` when the entry matches, or a
+ * human-actionable mismatch reason. Callers turn a non-null reason into a `load-error`.
+ */
+export declare function verifyLock(lock: PluginsLockFile, namespace: string, registerBytes: Uint8Array | null): string | null;
+export interface WorkspacePluginsConfig {
+    sources: PluginSourceSpec[];
+    capabilities: string[];
+}
+export declare class PluginsConfigError extends Error {
+    constructor(message: string);
+}
+/** Read the plugin keys from `<workspace>/.docsxai.json`. Absent file → empty config. */
+export declare function readWorkspacePluginsConfig(workspaceDir: string): Promise<WorkspacePluginsConfig>;

package/dist/plugins/lock.js

@@ -0,0 +1,122 @@
+// plugins-lock.json + the plugin keys of `.docsxai.json`.
+//
+// The lock pins the sha256 of each plugin's register-module bytes. When the file exists, every
+// resolve verifies the hash BEFORE importing — a silently-swapped module fails closed with a
+// "run `docsxai plugins sync`" message. `docsxai plugins sync` (re)writes it without ever
+// executing plugin code.
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { resolveWorkspacePath, WORKSPACE_CONFIG_FILE } from "../workspace.js";
+export const PLUGINS_LOCK_FILE = "plugins-lock.json";
+export const PLUGINS_LOCK_SCHEMA = "docsxai/plugins-lock@1";
+export class PluginsLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginsLockError";
+    }
+}
+const lockSchema = z
+    .object({
+    schema: z.literal(PLUGINS_LOCK_SCHEMA),
+    plugins: z.record(z.object({ source: z.string(), version: z.string(), sha256: z.string() }).strict()),
+})
+    .strict();
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function lockPath(workspaceDir) {
+    return resolveWorkspacePath(workspaceDir, PLUGINS_LOCK_FILE);
+}
+/** Read `<workspace>/plugins-lock.json`. `null` when absent; throws on a malformed file. */
+export async function readPluginsLock(workspaceDir) {
+    const p = lockPath(workspaceDir);
+    let text;
+    try {
+        text = await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new PluginsLockError(`${p} is not valid JSON — fix or delete it, then run \`docsxai plugins sync\``);
+    }
+    const result = lockSchema.safeParse(raw);
+    if (!result.success) {
+        throw new PluginsLockError(`${p} does not match schema "${PLUGINS_LOCK_SCHEMA}" — delete it and run \`docsxai plugins sync\``);
+    }
+    return result.data;
+}
+/** Write `<workspace>/plugins-lock.json` (deterministic key order). Returns the path written. */
+export async function writePluginsLock(workspaceDir, lock) {
+    const p = lockPath(workspaceDir);
+    const ordered = {
+        schema: lock.schema,
+        plugins: Object.fromEntries(Object.entries(lock.plugins).sort(([a], [b]) => a.localeCompare(b))),
+    };
+    await fs.writeFile(p, JSON.stringify(ordered, null, 2) + "\n", "utf8");
+    return p;
+}
+/**
+ * Verify a resolved plugin against the lock. Returns `null` when the entry matches, or a
+ * human-actionable mismatch reason. Callers turn a non-null reason into a `load-error`.
+ */
+export function verifyLock(lock, namespace, registerBytes) {
+    const entry = lock.plugins[namespace];
+    if (!entry) {
+        return `plugin "${namespace}" is not in ${PLUGINS_LOCK_FILE} — run \`docsxai plugins sync\``;
+    }
+    if (registerBytes === null) {
+        return `plugin "${namespace}" register module is unreadable — reinstall it, then run \`docsxai plugins sync\``;
+    }
+    const actual = sha256Hex(registerBytes);
+    if (actual !== entry.sha256) {
+        return (`lock mismatch for plugin "${namespace}": register module sha256 ${actual} does not match ` +
+            `${PLUGINS_LOCK_FILE} (${entry.sha256}) — if the change is intentional, run \`docsxai plugins sync\``);
+    }
+    return null;
+}
+export class PluginsConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginsConfigError";
+    }
+}
+const sourceSchema = z.union([
+    z.object({ package: z.string().min(1) }).strict(),
+    z.object({ path: z.string().min(1) }).strict(),
+]);
+const pluginsConfigSchema = z.object({
+    plugins: z.array(sourceSchema).default([]),
+    plugin_capabilities: z.array(z.string()).default([]),
+});
+/** Read the plugin keys from `<workspace>/.docsxai.json`. Absent file → empty config. */
+export async function readWorkspacePluginsConfig(workspaceDir) {
+    const p = resolveWorkspacePath(workspaceDir, WORKSPACE_CONFIG_FILE);
+    let text;
+    try {
+        text = await fs.readFile(p, "utf8");
+    }
+    catch {
+        return { sources: [], capabilities: [] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new PluginsConfigError(`${p} is not valid JSON`);
+    }
+    const result = pluginsConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((i) => `${i.path.length ? i.path.join(".") + ": " : ""}${i.message}`)
+            .join("; ");
+        throw new PluginsConfigError(`${p}: invalid plugin configuration — ${detail}`);
+    }
+    return { sources: result.data.plugins, capabilities: result.data.plugin_capabilities };
+}

package/dist/plugins/manifest.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/** The plugin-runtime contract version this engine build advertises. */
+export declare const RUNTIME_API_VERSION = "1.0.0";
+/**
+ * Namespaces plugins can never claim — the engine's own surfaces live here.
+ * `site-docs` (the pre-rename CLI/product name) stays reserved defensively so a
+ * plugin can never squat the old identity.
+ */
+export declare const RESERVED_NAMESPACES: ReadonlyArray<string>;
+export declare const PLUGIN_KINDS: readonly ["publisher", "renderer", "lint-rules", "auth-strategy"];
+export type PluginKind = (typeof PLUGIN_KINDS)[number];
+export type PluginTrust = "kalebtec" | "community" | "local";
+declare const manifestSchema: z.ZodObject<{
+    apiVersion: z.ZodString;
+    namespace: z.ZodEffects<z.ZodString, string, string>;
+    register: z.ZodString;
+    kinds: z.ZodArray<z.ZodEnum<["publisher", "renderer", "lint-rules", "auth-strategy"]>, "many">;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        plugin: z.ZodString;
+        version: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        version: string;
+        plugin: string;
+    }, {
+        version: string;
+        plugin: string;
+    }>, "many">>;
+    trust: z.ZodDefault<z.ZodEnum<["kalebtec", "community", "local"]>>;
+}, "strict", z.ZodTypeAny, {
+    capabilities: string[];
+    apiVersion: string;
+    namespace: string;
+    register: string;
+    kinds: ("publisher" | "renderer" | "lint-rules" | "auth-strategy")[];
+    dependsOn: {
+        version: string;
+        plugin: string;
+    }[];
+    trust: "local" | "kalebtec" | "community";
+}, {
+    apiVersion: string;
+    namespace: string;
+    register: string;
+    kinds: ("publisher" | "renderer" | "lint-rules" | "auth-strategy")[];
+    capabilities?: string[] | undefined;
+    dependsOn?: {
+        version: string;
+        plugin: string;
+    }[] | undefined;
+    trust?: "local" | "kalebtec" | "community" | undefined;
+}>;
+export type PluginManifest = z.infer<typeof manifestSchema>;
+export declare class PluginManifestError extends Error {
+    constructor(message: string);
+}
+/** Validate the `docsxai` field of a plugin's package.json. Throws {@link PluginManifestError}. */
+export declare function parsePluginManifest(raw: unknown, source: string): PluginManifest;
+/**
+ * A plugin's `apiVersion` is compatible when it shares the runtime's major and its minor is ≤
+ * the runtime's. A plugin built for `1.0.0` runs under runtime `1.5.0`; a plugin built for
+ * `1.6.0` or `2.0.0` does not run under runtime `1.5.0`.
+ */
+export declare function isApiVersionCompatible(pluginApiVersion: string, runtimeApiVersion?: string): boolean;
+/**
+ * Minimal semver-range check for `dependsOn`: supports `^x.y.z`, `~x.y.z`, and exact `x.y.z`
+ * (npm semantics, including the 0.x caret caveats). Anything else returns false.
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export {};

package/dist/plugins/manifest.js

@@ -0,0 +1,115 @@
+// Plugin manifest: the `docsxai` field on a plugin package's package.json. Zod-validated; the
+// rejections here are load-errors, not warnings — a plugin with a lying or malformed manifest
+// never reaches `register()`.
+import { z } from "zod";
+/** The plugin-runtime contract version this engine build advertises. */
+export const RUNTIME_API_VERSION = "1.0.0";
+/**
+ * Namespaces plugins can never claim — the engine's own surfaces live here.
+ * `site-docs` (the pre-rename CLI/product name) stays reserved defensively so a
+ * plugin can never squat the old identity.
+ */
+export const RESERVED_NAMESPACES = [
+    "docsxai",
+    "site-docs",
+    "core",
+    "plugins",
+];
+export const PLUGIN_KINDS = ["publisher", "renderer", "lint-rules", "auth-strategy"];
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const NAMESPACE = /^[a-z][a-z0-9-]*$/;
+// The only capability family today is target-host egress. Unknown prefixes are rejected so a
+// manifest can't smuggle an undisclosed capability past review.
+const CAPABILITY = /^egress:[a-zA-Z0-9*]([a-zA-Z0-9*.-]*[a-zA-Z0-9*])?$/;
+const manifestSchema = z
+    .object({
+    apiVersion: z.string().regex(SEMVER, "apiVersion must be exact semver (x.y.z)"),
+    namespace: z
+        .string()
+        .regex(NAMESPACE, "namespace must match /^[a-z][a-z0-9-]*$/ (kebab-case)")
+        .refine((ns) => !RESERVED_NAMESPACES.includes(ns), {
+        message: `namespace is reserved (${RESERVED_NAMESPACES.join(", ")})`,
+    }),
+    register: z.string().min(1, "register must be a relative path to the register module"),
+    kinds: z.array(z.enum(PLUGIN_KINDS)).min(1, "kinds must declare at least one extension point"),
+    capabilities: z
+        .array(z
+        .string()
+        .regex(CAPABILITY, 'capability must match "egress:<host-glob>" (the only family today)'))
+        .default([]),
+    dependsOn: z
+        .array(z.object({ plugin: z.string().min(1), version: z.string().min(1) }).strict())
+        .default([]),
+    trust: z.enum(["kalebtec", "community", "local"]).default("local"),
+})
+    .strict();
+export class PluginManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginManifestError";
+    }
+}
+/** Validate the `docsxai` field of a plugin's package.json. Throws {@link PluginManifestError}. */
+export function parsePluginManifest(raw, source) {
+    if (raw === undefined || raw === null) {
+        throw new PluginManifestError(`${source}: package.json has no "docsxai" field — not a plugin`);
+    }
+    const result = manifestSchema.safeParse(raw);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((i) => `${i.path.length ? i.path.join(".") + ": " : ""}${i.message}`)
+            .join("; ");
+        throw new PluginManifestError(`${source}: invalid "docsxai" manifest — ${detail}`);
+    }
+    return result.data;
+}
+function parseSemver(v) {
+    const m = SEMVER.exec(v);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/**
+ * A plugin's `apiVersion` is compatible when it shares the runtime's major and its minor is ≤
+ * the runtime's. A plugin built for `1.0.0` runs under runtime `1.5.0`; a plugin built for
+ * `1.6.0` or `2.0.0` does not run under runtime `1.5.0`.
+ */
+export function isApiVersionCompatible(pluginApiVersion, runtimeApiVersion = RUNTIME_API_VERSION) {
+    const plugin = parseSemver(pluginApiVersion);
+    const runtime = parseSemver(runtimeApiVersion);
+    if (!plugin || !runtime)
+        return false;
+    return plugin[0] === runtime[0] && plugin[1] <= runtime[1];
+}
+function compareSemver(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Minimal semver-range check for `dependsOn`: supports `^x.y.z`, `~x.y.z`, and exact `x.y.z`
+ * (npm semantics, including the 0.x caret caveats). Anything else returns false.
+ */
+export function satisfiesRange(version, range) {
+    const v = parseSemver(version);
+    if (!v)
+        return false;
+    const op = range.startsWith("^") || range.startsWith("~") ? range[0] : "";
+    const base = parseSemver(op ? range.slice(1) : range);
+    if (!base)
+        return false;
+    if (compareSemver(v, base) < 0)
+        return false;
+    if (op === "")
+        return compareSemver(v, base) === 0;
+    if (op === "~")
+        return v[0] === base[0] && v[1] === base[1];
+    // Caret: nothing left of the leftmost non-zero digit may change.
+    if (base[0] > 0)
+        return v[0] === base[0];
+    if (base[1] > 0)
+        return v[0] === 0 && v[1] === base[1];
+    return v[0] === 0 && v[1] === 0 && v[2] === base[2];
+}

package/dist/plugins/plan.d.ts

@@ -0,0 +1,51 @@
+import { type PluginManifest } from "./manifest.js";
+import { type PluginsLockFile, type PluginSourceSpec } from "./lock.js";
+import type { PluginRecord } from "./registry.js";
+/** A source whose package.json#docsxai validated. Not yet loaded. */
+export interface ResolvedPluginSource {
+    name: string;
+    version: string;
+    dir: string;
+    registerPath: string;
+    source: string;
+    manifest: PluginManifest;
+}
+export type PluginSourceResolution = {
+    ok: true;
+    candidate: ResolvedPluginSource;
+} | {
+    ok: false;
+    record: PluginRecord;
+};
+export interface ResolvePluginsOptions {
+    /** The workspace all plugin file IO is contained to. */
+    workspaceDir: string;
+    sources: ReadonlyArray<PluginSourceSpec>;
+    /** Operator-enabled capabilities (exact-string subset check). Default: none enabled. */
+    enabledCapabilities?: ReadonlyArray<string>;
+    /** Parsed plugins-lock.json. When present, register-module bytes are verified before import. */
+    lock?: PluginsLockFile | null;
+}
+/** The deterministic output of planning: disabled records, plus survivors in load order. */
+export interface PluginPlan {
+    /** Records for every rejected/disabled source — committed before any plugin loads. */
+    disabled: PluginRecord[];
+    /** Surviving candidates keyed by package name, used by the load half. */
+    live: Map<string, ResolvedPluginSource>;
+    /** Topological order (dependencies before dependents) over `live`. */
+    loadOrder: string[];
+}
+/** Build the PluginRecord for a resolved candidate at a given status. Shared with the load half. */
+export declare function candidateRecord(c: ResolvedPluginSource, status: PluginRecord["status"], reason?: string): PluginRecord;
+/**
+ * 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 declare function resolvePluginSources(workspaceDir: string, sources: ReadonlyArray<PluginSourceSpec>): Promise<PluginSourceResolution[]>;
+/**
+ * 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 declare function planPlugins(opts: ResolvePluginsOptions): Promise<PluginPlan>;