@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/ctx/bus.js

@@ -0,0 +1,101 @@
+import { assertNamespace } from "./namespace.js";
+/** 未注入 logger 时的兜底：输出到 stderr。 */
+const consoleLog = {
+    error: (msg, fields) => console.error(`[bus] ${msg}`, fields ?? ""),
+};
+/** 调用 handler：同步抛错与返回 Promise 的 reject 都被吞掉并记录，保证 handler 间互相隔离。 */
+function invokeIsolated(log, label, fn) {
+    Promise.resolve()
+        .then(fn)
+        .catch((err) => log.error("bus handler threw", { channel: label, err }));
+}
+/** 创建共享订阅者：首次订阅时才惰性打开唯一一条连接，并把频道多路复用到各 handler 集合。 */
+export function createBusSubscriber(subFactory, log = consoleLog) {
+    let conn = null;
+    let closed = false;
+    const channels = new Map();
+    const ensure = () => {
+        if (conn)
+            return conn;
+        const c = subFactory();
+        c.on("message", (channel, message) => {
+            for (const h of [...(channels.get(channel)?.handlers ?? [])]) {
+                invokeIsolated(log, channel, () => h(message));
+            }
+        });
+        c.on("error", (err) => log.error("bus subscriber connection error", { err }));
+        conn = c;
+        return c;
+    };
+    return {
+        async subscribe(channel, handler) {
+            if (closed)
+                throw new Error("bus subscriber is closed");
+            const c = ensure();
+            let st = channels.get(channel);
+            if (!st) {
+                const handlers = new Set();
+                st = { handlers, ready: Promise.resolve() };
+                channels.set(channel, st);
+                const created = st;
+                created.ready = c.subscribe(channel).then(() => undefined);
+                created.ready.catch(() => {
+                    if (channels.get(channel) === created)
+                        channels.delete(channel);
+                });
+            }
+            st.handlers.add(handler);
+            try {
+                await st.ready;
+            }
+            catch (err) {
+                st.handlers.delete(handler);
+                throw err;
+            }
+            let removed = false;
+            const state = st;
+            return async () => {
+                if (removed)
+                    return;
+                removed = true;
+                state.handlers.delete(handler);
+                if (state.handlers.size === 0 && channels.get(channel) === state) {
+                    channels.delete(channel);
+                    if (!closed)
+                        await c.unsubscribe(channel);
+                }
+            };
+        },
+        async close() {
+            closed = true;
+            channels.clear();
+            const c = conn;
+            conn = null;
+            if (c)
+                await c.quit().catch(() => c.disconnect());
+        },
+    };
+}
+/** 创建 ctx.bus：频道为 `cap:<namespace>:<topic>`，payload 为 JSON。 */
+export function createBus(pub, subscriber, namespace, log = consoleLog) {
+    assertNamespace(namespace);
+    const ch = (topic) => `cap:${namespace}:${topic}`;
+    return {
+        async publish(topic, payload) {
+            await pub.publish(ch(topic), JSON.stringify(payload));
+        },
+        subscribe(topic, handler) {
+            return subscriber.subscribe(ch(topic), (message) => {
+                let payload;
+                try {
+                    payload = JSON.parse(message);
+                }
+                catch {
+                    log.error("bus ignoring malformed message", { channel: ch(topic) });
+                    return;
+                }
+                invokeIsolated(log, ch(topic), () => handler(payload));
+            });
+        },
+    };
+}

package/dist/ctx/create-ctx.d.ts

@@ -0,0 +1,109 @@
+import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { Kysely } from "kysely";
+import { type RegisteredHook } from "../extensions/hooks.js";
+import { RegistrationLedger } from "../extensions/ledger.js";
+import { type UiActionHandler, type UiRender } from "../ui/registry.js";
+import { type BusSubscriber } from "./bus.js";
+import { type Keyring } from "./secrets.js";
+/** 内核提供给插件宿主的共享依赖。 */
+export interface KernelDeps {
+    db: Kysely<any>;
+    dbUrl: string;
+    /** PG 建立连接的超时（迁移器的独立连接使用）。 */
+    connectTimeoutMs?: number;
+    redis: Redis;
+    busSubscriber: BusSubscriber;
+    redisUrl: string;
+    keyring: Keyring;
+    runWorkers: boolean;
+    /** 内核 logger（`debug` 可选：插件 Logger 没有它，测试可不给）。 */
+    log: Logger & {
+        debug?(msg: string, fields?: Record<string, unknown>): void;
+    };
+}
+/** 插件 HTTP 路由；`path` 已含 `/plugins/<name>` 前缀。 */
+export type Route = {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    handler: (req: Request) => Promise<Response>;
+};
+/** 插件经 `ctx.tools.register` 注册的工具。 */
+export type RegisteredTool = {
+    spec: ToolSpec;
+    handler: ToolHandler;
+};
+/** 插件经 `ctx.extensionPoints` 取用其他插件能力时，内核注入的访问接口。 */
+export interface ExtensionPointAccess {
+    /** 已加载（setup 完成）的提供方，按加载顺序；按完整引用（含主版本）精确匹配。 */
+    providers(ref: ExtensionPointRef): {
+        plugin: string;
+        impl: unknown;
+    }[];
+    /** Names of the extensions enabled in the organization (`extension_org_configs.enabled` plus required bootstrap plugins, `enabled.ts`); queried every time, not cached. */
+    enabledPlugins(orgId: string): Promise<Set<string>>;
+}
+/**
+ * Queries the names of the extensions enabled in the organization (org config rows plus the
+ * required bootstrap plugins, see `extensions/enabled.ts`), not cached.
+ */
+export declare function queryEnabledPlugins(db: Kysely<any>, orgId: string): Promise<Set<string>>;
+/** 插件的 PG schema 名：`plugin_<name>`，name 中的 `-` 换成 `_`。 */
+export declare function pluginSchemaName(name: string): string;
+/** 内核视角的插件 ctx：插件契约之外还带宿主要用的登记信息与关闭方法。 */
+export type KernelExtensionContext = ExtensionContext & {
+    /** 本实例的登记账（C17）：每次登记记一笔，撤销时逐项撤销。 */
+    ledger: RegistrationLedger;
+    /**
+     * 撤销第一步：停止取新的队列任务；`deadline`（epoch 毫秒）之后撤销队列 worker 时不再等进行中的任务。
+     */
+    beginDispose(deadline: number): Promise<void>;
+    /** 等本实例队列 worker 进行中的任务结束，最多等到 `deadline`（epoch 毫秒）。 */
+    drainQueues(deadline: number): Promise<"drained" | "timeout">;
+    /** 中止 `ctx.signal`（幂等）。 */
+    abort(): void;
+    routes: Route[];
+    provided: Map<ExtensionPointRef, unknown>;
+    /** 已注册的工具（按注册顺序）。 */
+    registeredTools: RegisteredTool[];
+    /** Hooks registered through `ctx.hooks.on` (registration order). */
+    registeredHooks: RegisteredHook[];
+    /** 经 `ctx.ui.view` 注册的视图（按贡献 id）。 */
+    uiViews: ReadonlyMap<string, UiRender>;
+    /** 经 `ctx.ui.action` 注册的动作处理函数（按贡献 id）。 */
+    uiActions: ReadonlyMap<string, UiActionHandler>;
+    /** setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on` 抛错。 */
+    sealTools(): void;
+    /** 中止 signal、封账并逐项撤销仍在账上的登记、关闭队列连接（幂等）。 */
+    close(): Promise<void>;
+};
+/**
+ * 插件实例的部署配置（已校验）：`ctx.config` 是读它的 getter。hot 字段改动时宿主替换 `value`（C10），
+ * 插件下次读 `ctx.config` 就是新值；非 hot 改动重新加载实例（新 ctx）。
+ */
+export declare class LiveConfig {
+    value: unknown;
+    constructor(value: unknown);
+}
+/**
+ * Builds the namespaced ctx for one extension from its permission manifest, and returns its
+ * registered routes, provided extension points and a close function.
+ * `deploymentConfig` may be a {@link LiveConfig} (shared by the instance, replaceable in place);
+ * otherwise a fixed value is wrapped.
+ * - Granted automatically: `kv`, `lock`, `bus`, `queue`, `log`, `db`, `config`, `provide`;
+ * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`; `http.route`
+ *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
+ *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
+ *   this extension, the extension still enabled in that org and the caller still an active member of
+ *   the org (org not deleted); returns the current role;
+ * - `extensionPoints` only gives extension points declared in `requires` / `optional` that are not
+ *   brokered (through `extensionPointAccess`).
+ * - `hooks.on` only during setup, only mount points declared in `permissions.hooks` and available
+ *   (`HOOKS_AVAILABLE`), `policy` only on `POLICY_HOOKS` declared in `permissions.policyHooks`; kept on the ctx (`registeredHooks`, read by
+ *   the host's `HookRegistry` from active instances only) and recorded in the ledger.
+ * An undeclared access throws `ExtensionPermissionError` and audits `extension.permission_denied`
+ * (once per extension and item).
+ */
+export declare function createExtensionContext(deps: KernelDeps, manifest: ExtensionManifest, deploymentConfig: unknown, extensionPointAccess?: ExtensionPointAccess): KernelExtensionContext;