waterplane 0.0.1 → 0.1.11

package/packages/host/dist/plugins/pluginregistry.d.ts

@@ -0,0 +1,244 @@
+import type { PluginCaller, PluginCallResult, PluginUsageProbe } from "@waterplane/shared";
+import type { AnswerSuggestion, ComplianceCheck, DecisionLogEntry, DetectedPrompt, HandToAgentResult, HostPluginModule, PluginHookHold, PluginQuestionEvent, PluginStatus, PluginValue, PluginView, RepoTarget, SetupFixOutcome, SetupSubject, UsageInfo } from "@waterplane/shared";
+import type { HostCtx } from "../routes/types.js";
+import type { SessionManager } from "../sessions.js";
+import { type PluginRoute } from "./pluginroutes.js";
+import { type ReleaseBuiltins } from "./builtin.js";
+import { PluginStreams, type StreamSink } from "./pluginstreams.js";
+import { PluginFiles, type ServedFile } from "./pluginfiles.js";
+import { type AssetResult } from "./pluginassets.js";
+import type { Notify } from "../notifytypes.js";
+type Handler = (e: any) => unknown;
+/** One installed plugin, as the registry holds it. */
+export interface PluginEntry {
+    dir: string;
+    source: string;
+    manifest: PluginManifestLike;
+    hostFile: string | null;
+    /** Fixed at load (manifest problems, duplicate id, import failure). */
+    loadError: string | null;
+    /** Loaded from a past brand's manifest file name; the phone says to rename it. */
+    manifestLegacy?: boolean;
+    enabled: boolean;
+    state: "active" | "error" | "off";
+    error?: string;
+    status: PluginStatus | null;
+    mod: HostPluginModule | null;
+    /** Bumped on every activation, so an API handed to a previous one goes quiet. */
+    gen: number;
+    handlers: {
+        prompt: Set<Handler>;
+        question: Set<Handler>;
+        action: Set<Handler>;
+    };
+    onSettings: Set<(v: Record<string, PluginValue>) => void>;
+    stored: Record<string, PluginValue>;
+    /** An in-repo extension (`packages/extensions/<id>/`): always on, never listed unless broken. */
+    builtin?: boolean;
+    /** Contributed setup rows, asked on every check of every repo. */
+    setupChecks: Set<(s: SetupSubject) => ComplianceCheck | null>;
+    /** Contributed fixes by fix id — the ids its rows name in `fix`. */
+    setupFixes: Map<string, (s: SetupSubject) => SetupFixOutcome>;
+    /** `handle(method, fn)` — what `call()` routes to. */
+    methods: Map<string, (args: unknown, caller: PluginCaller) => unknown>;
+    /** Backend ids this activation registered (`api.backend`) — unregistered when it is switched off. */
+    backends: Set<string>;
+    /** Unregisters for the readers this activation contributed (`api.screenReader` / `api.storeReader` / `api.thermalReader`). */
+    readers: Set<() => void>;
+    /** `api.onHook` — what `/api/plugin/<id>/hook` hands its body to. */
+    hook: {
+        fn: (payload: unknown, hold: PluginHookHold) => unknown;
+        maxHoldMs: number;
+    } | null;
+    /** `api.route` — what `* /api/plugin/<id>/*` asks, in registration order (since 1.2). */
+    routes: PluginRoute[];
+    /** Responses held open right now; each answers `{}` when called (switch-off). */
+    holds: Set<() => void>;
+}
+/** What `/api/plugin/<id>/hook` answers: an HTTP status and a JSON body. */
+export interface PluginHookReply {
+    status: number;
+    body: unknown;
+}
+type PluginManifestLike = PluginView["manifest"];
+/** What the registry needs from the host. Functions read `ctx` at CALL time. */
+export interface RegistryDeps {
+    root: string;
+    configDir: string;
+    sessions: SessionManager;
+    decision(row: DecisionLogEntry): void;
+    meter(e: {
+        service: string;
+        model: string;
+        kind: string;
+        inTok: number;
+        outTok: number;
+        ts: number;
+    }): void;
+    notify: Notify;
+    usage(): UsageInfo;
+    /** The plugin list changed — broadcast it. */
+    changed(): void;
+    /** `api.push` — broadcast `plugin.push` to every phone. Absent ⇒ the api refuses in words. */
+    push?(plugin: string, event: string, data: unknown): void;
+    /** The daemon's ctx, read at CALL time: `api.handToAgent` is its backlog add. Absent ⇒ refused in words. */
+    host?: Pick<HostCtx, "backlog" | "intents" | "containRepoDir">;
+    /** Test seam: a repo by id. Absent ⇒ `repos.ts`'s `findTarget(root, id)`, the ids `GET /api/repos` hands out. */
+    findRepo?(repoId: string): Promise<RepoTarget | null>;
+    /** Test seam: a repo by its worktree's REALPATH. Absent ⇒ `discoverTargets(root)` realpath-compared. */
+    findRepoByPath?(realPath: string): Promise<RepoTarget | null>;
+    /** Test seam over `handToAgentVia(host, …)`. */
+    handToAgent?(p: HandToAgentArgs): Promise<HandToAgentResult>;
+    /** The daemon's port, for `api.hookSink()` (loopback). Absent ⇒ the default port. */
+    hookPort?: number;
+    /** How `api.stream` reaches the sockets (`pluginstreams.ts`), read at CALL time. Absent ⇒ every
+     *  `stream.open` is refused in words. */
+    streamSink?(): StreamSink | null;
+    /** `api.usageProbe` — the host's usage-source registry (`usagesources.ts`). Absent ⇒ refused in words. */
+    usageProbe?(plugin: string, def: PluginUsageProbe): () => void;
+}
+export interface HandToAgentArgs {
+    repoDir: string;
+    text: string;
+    label?: string;
+    id?: string;
+    origin: string;
+    fire: boolean;
+}
+/** Fix ids `compliance.ts` answers itself — a plugin may not take one. */
+export declare const CORE_FIX_IDS: readonly string[];
+export declare class PluginRegistry {
+    readonly deps: RegistryDeps;
+    readonly entries: PluginEntry[];
+    /** Plain problems with the configuration itself (a bad plugin-paths.json). */
+    configProblems: string[];
+    /** Session id → fingerprint of the box plugins were last told about (gate condition 3). */
+    readonly told: Map<string, string>;
+    private readonly ledger;
+    /** `api.stream`'s registry and every socket's open subs (`pluginstreams.ts`). */
+    readonly streams: PluginStreams;
+    /** `api.offerFile`'s live offers (`pluginfiles.ts`): memory only, each file deleted when it ends. */
+    readonly files: PluginFiles;
+    private readonly stateDir;
+    private readonly enabledPath;
+    private builtinsStarted;
+    private builtinsDone;
+    /** Resolves once `loadBuiltins()` has run — `main()` awaits it before listening. */
+    readonly builtinsLoaded: Promise<void>;
+    constructor(deps: RegistryDeps);
+    private newEntry;
+    /**
+     * The in-repo extensions (`builtin.ts`). Boot, BEFORE the server listens and
+     * before `loadAll()`: their setup rows are part of the checklist the first
+     * request reads, and an external plugin must not claim a builtin's id. Never
+     * throws — a broken one is an error entry, like any plugin.
+     */
+    loadBuiltins(ids?: readonly string[], rel?: ReleaseBuiltins | null): Promise<void>;
+    private loadBuiltinIds;
+    /** Discover, validate, import and activate. Boot only; never throws. */
+    loadAll(): Promise<void>;
+    /**
+     * Load ONE plugin dir after boot (an install from the updates view takes effect without a restart).
+     * Refused in words, nothing added, when the dir does not read or its id is already loaded; a plugin
+     * that reads but fails to start is LISTED in error like at boot, and its reason is returned.
+     */
+    loadOne(dir: string): Promise<string | null>;
+    /** The loadable plugin with this id (never a duplicate or broken copy). */
+    byId(id: string): PluginEntry | null;
+    views(): PluginView[];
+    private activate;
+    private deactivate;
+    private clearHandlers;
+    /** The port `api.hookSink()` names. */
+    hookPort(): number;
+    /** Which plugin declares backend `id` in its manifest, as "the plugin <Name>"; null when none does. */
+    backendOwner(id: string): string | null;
+    /**
+     * One POST to `/api/plugin/<id>/hook` (loopback already checked by the
+     * route). 404 in words for an unknown, broken or switched-off plugin, or one
+     * that takes no hooks. Otherwise 200 with the handler's answer — HELD while
+     * its promise is pending, and `{}` once `maxHoldMs` passes, the plugin is
+     * switched off, the handler throws, or it answers something that is not JSON.
+     * Never rejects.
+     */
+    hook(pluginId: string, payload: unknown): Promise<PluginHookReply>;
+    /**
+     * The runner for `METHOD /api/plugin/<id>/<parts…>` (`api.route`), or null when the plugin is not
+     * running or serves nothing there — the caller then answers the core's plain 404, as for any
+     * path nobody serves. The runner never rejects: a throw is a 500 in words and the status line.
+     */
+    /** A file a running plugin offered (`api.offerFile`), for `GET /api/plugin-file/<id>/<token>`; null = gone. */
+    offeredFile(pluginId: string, token: string): ServedFile | null;
+    /** `GET|HEAD /api/plugin/<id>/asset/<file>`: unknown plugin / no `assets` / no file ⇒ 404 in words; switched off or not running ⇒ 403. */
+    assetFile(pluginId: string, file: string): AssetResult;
+    route(pluginId: string, method: string, parts: readonly string[]): ((req: {
+        query: Record<string, string>;
+        body: unknown;
+    }) => Promise<PluginHookReply>) | null;
+    /** Shutdown: best effort, never awaited by the flush. */
+    deactivateAll(): void;
+    /**
+     * The process is exiting: every loaded module's synchronous `shutdown()` —
+     * switched on or not, since a switched-off plugin's running sessions keep
+     * what it spawned (opencode's per-session servers). Last in the flush
+     * (`server/shutdown.ts`). Never throws.
+     */
+    shutdownAll(): void;
+    setEnabled(id: string, enabled: boolean): Promise<string | null>;
+    /** Apply settings atomically: one refused value refuses the whole change, in words. */
+    setValues(id: string, values: Record<string, unknown>): string | null;
+    seed(e: PluginEntry, values: Record<string, PluginValue>): void;
+    sessionToggle(id: string, sessionId: string, toggle: string, value: boolean | null): string | null;
+    sessionAnswer(id: string, sessionId: string, value: boolean): string | null;
+    /** Any active answering plugin with its switch on somewhere — the usage reading is then worth keeping warm. */
+    wantsUsage(): boolean;
+    action(id: string, action: string, sessionId?: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Every active plugin's setup rows for one worktree, in load order (builtins first). A throw becomes a warn row naming the plugin. */
+    setupChecks(s: SetupSubject): ComplianceCheck[];
+    /** The fix ids active plugins answer, in load order. */
+    setupFixIds(): string[];
+    /**
+     * Run one contributed fix. Null when no active plugin answers `id`. A throw is
+     * the plugin's status line AND is rethrown, so `fixRepoCompliance` answers it
+     * the way it answers a core fix that threw: `ok: false` with the reason.
+     */
+    runSetupFix(id: string, s: SetupSubject): SetupFixOutcome | null;
+    /** A repo by id — `api.repo()` and `api.handToAgent` both start here. */
+    findRepo(repoId: string): Promise<RepoTarget | null>;
+    /**
+     * A repo by its worktree's realpath, among the repos this host lists — the lookup behind a path
+     * `api.repo()`/`api.handToAgent` is given when its spelling is not the one the id was made from
+     * (`/tmp` vs `/private/tmp`, a symlinked root). Never a folder outside the list.
+     */
+    findRepoByPath(realPath: string): Promise<RepoTarget | null>;
+    /** The backlog add behind `api.handToAgent`, or why there is none. */
+    handToAgent(p: HandToAgentArgs): Promise<HandToAgentResult>;
+    /** Who already answers fix `id`, in words — null when it is free for `e`. */
+    fixTaken(e: PluginEntry, id: string): string | null;
+    /**
+     * Call a method a plugin registered with `api.handle`. The ONE entry point
+     * the generic `plugin.call` wire message routes to; nothing else reaches a
+     * handler. Every failure is a sentence, never a throw.
+     */
+    call(pluginId: string, method: string, args: unknown, caller?: PluginCaller): Promise<PluginCallResult>;
+    /** `call` through the ledger: a repeated ackId runs the handler once. Args must be JSON and small. */
+    callOnce(ackId: string, pluginId: string, method: string, args: unknown, caller?: PluginCaller): Promise<PluginCallResult>;
+    /** A choice box appeared (`sessions.on("prompt")`). */
+    firePrompt(sessionId: string, p: DetectedPrompt): void;
+    /** A turn ended asking something with no box. */
+    fireQuestion(ev: PluginQuestionEvent): void;
+    private fire;
+    /** A throwing handler is the plugin's status line, never the daemon's problem. */
+    handlerFailed(e: PluginEntry, what: string, err: unknown): void;
+    setStatus(e: PluginEntry, s: PluginStatus | null): void;
+    /** Stamp and show a plugin's suggestion. */
+    suggest(e: PluginEntry, sessionId: string, s: Omit<AnswerSuggestion, "by" | "byName"> | null): void;
+    private readEnabled;
+    private readStored;
+    private writeStored;
+    private writeJson;
+}
+export {};