@repogo/plugins 0.1.34 → 0.1.35

package/dist/runtime.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { type Schedule } from "./cron";
+import type { Caller, CronEntry, CronStatus, Manifest, Notice } from "./context";
+export type { Manifest, ManifestCron, ManifestMethod } from "./context";
+import type { PluginDefinition, MethodKind } from "./define";
+import { EventBus } from "./events";
+export type RegisteredMethod = {
+    name: string;
+    plugin: string;
+    kind: MethodKind;
+    description?: string;
+    confirm?: string;
+    input: z.ZodType;
+    output?: z.ZodType;
+    /** `raw` is the input as sent, before defaults filled it in. */
+    run: (input: unknown, raw: unknown) => Promise<unknown>;
+};
+/** A call's result with the data it read (what a query depends on) and wrote (what it invalidates). */
+export type CallResult = {
+    result: unknown;
+    reads: string[];
+    invalidates: string[];
+};
+type InvalidationListener = (tags: string[]) => void;
+/** A notice as the host hears it: which plugin, from which project. */
+export type SentNotice = Notice & {
+    plugin: string;
+    root: string;
+};
+type NoticeListener = (notice: SentNotice) => void;
+/** Runs a host method for a plugin's `ctx.host`; the plugins server passes it to the host. */
+export type HostCaller = (plugin: string, method: string, params: unknown) => Promise<unknown>;
+/** A schedule as the runtime keeps it: read once, with its last run. */
+type CronJob = {
+    /** The plugin, method, schedule and zone: an entry the host sends again keeps its job, and its state. */
+    signature: string;
+    plugin: string;
+    /** `<plugin>.<method>`. */
+    method: string;
+    schedule: string;
+    timezone: string;
+    parsed: Schedule;
+    nextRunAt: number | null;
+    lastRunAt: number | null;
+    lastDurationMs: number | null;
+    lastError: string | null;
+    running: boolean;
+    runs: number;
+};
+export declare class Runtime {
+    private dataDir;
+    private root;
+    private host?;
+    readonly events: EventBus;
+    readonly methods: Map<string, RegisteredMethod>;
+    readonly plugins: Map<string, PluginDefinition>;
+    readonly crons: CronJob[];
+    private databases;
+    /** Every kv, stream and bucket by tag, shared by the plugins that name it, with its schema's JSON. */
+    private stores;
+    private invalidationListeners;
+    private noticeListeners;
+    pluginsDir: string | null;
+    private constructor();
+    /** The caller's project while a call runs, for plugins that serve every project. */
+    private callRoot;
+    /** A running stream's signal, `ctx.signal` to the code it runs. */
+    private callSignal;
+    /** Who started the outermost call, `ctx.caller` to the code it runs. */
+    private callCaller;
+    /** Whether the user answered a `confirm` for this call or one it runs within, which a destructive MCP tool needs. */
+    private callConfirmed;
+    /** Read through `ctx.plugins()` and written as each cron run starts and ends; this runtime's own, so other Workers aren't stirred. */
+    private cronsTag;
+    /**
+     * `root` is the project's checkout, `ctx.root` to its plugins; the working
+     * directory when left out. Without `host`, `ctx.host` fails.
+     */
+    static open(options: {
+        dataDir: string;
+        root?: string;
+        host?: HostCaller;
+    }): Promise<Runtime>;
+    /** `only` names the plugins to import, for a Worker that runs schedules: their neighbours' code never runs. */
+    loadDir(pluginsDir: string, only?: string[] | null): Promise<void>;
+    add(name: string, plugin: PluginDefinition): Promise<void>;
+    /**
+     * Calls a method and reports what it read and wrote. `expect: "query"` is how
+     * a card runs a method on its own: it refuses anything that might write, and
+     * so does everything the query calls.
+     */
+    /**
+     * `confirmed` is false for a tap the user hasn't answered; `ctx.call` leaves it out.
+     * `root` (the caller's project, for the environment's own plugins) and `caller`
+     * pass on to the code the method calls.
+     */
+    call(name: string, input?: unknown, options?: {
+        expect?: MethodKind;
+        confirmed?: boolean;
+        root?: string;
+        caller?: Caller;
+        chat?: string;
+    }): Promise<CallResult>;
+    /**
+     * Runs a stream method, passing each item it yields to `onItem` until it
+     * returns, throws or `signal` aborts. Bad input throws here, before it starts.
+     */
+    stream(name: string, input: unknown, options: {
+        root?: string;
+        caller?: Caller;
+        signal: AbortSignal;
+    }, onItem: (item: unknown) => void): Promise<void>;
+    /** A stream called once, by an agent or by code: what arrives within `sampleMs`, at most `sampleLimit` items. */
+    private sample;
+    /** Notices plugins send, for the host to push to the phones. */
+    onNotify(listener: NoticeListener): () => boolean;
+    /** Tags written by any call, as they commit; cards refetch the queries that read them. */
+    onInvalidate(listener: InvalidationListener): () => boolean;
+    /**
+     * Replaces the schedules with `entries`, the host's whole set for this folder,
+     * and says how each went. One the host sent before keeps its timing and runs;
+     * one left out is never started again, though a run already going finishes.
+     */
+    setCrons(entries: CronEntry[]): CronStatus[];
+    /** Checks an entry against what's loaded, so one that could never run says why. */
+    private cronJob;
+    /**
+     * Starts every cron due by `now` and returns the runs it started, for a test
+     * to wait on. A due time that comes while the job still runs is skipped, as is
+     * one missed by more than two minutes: nothing is caught up.
+     */
+    tickCrons(now?: number): Promise<void>[];
+    /**
+     * The run a line is attributed to: the outermost call's id, caller and chat
+     * stay through the calls it makes; the plugin and method are the code running.
+     */
+    private logContextFor;
+    /** Starts a chat for the plugin and waits for the agent's answer. */
+    private agent;
+    manifest(): Manifest;
+    /** The crons running now, to name in a warning when something has blocked the Worker. */
+    get runningCrons(): string[];
+    /** Whether any plugin keeps kv, streams or buckets, which `tickStorage` looks after. */
+    get hasStorage(): boolean;
+    /**
+     * Expires kv keys, trims streams and rescans buckets, each as often as it
+     * needs; the Worker calls it every few seconds. One store failing doesn't stop the rest.
+     */
+    tickStorage(now?: number): Promise<void>;
+    close(): void;
+    private database;
+    private store;
+    private storesOf;
+    private notifyInvalidated;
+    private register;
+    private registerGenerated;
+    private registerCrud;
+}

package/dist/testing.d.ts

@@ -0,0 +1,49 @@
+import type { Caller, CronEntry, CronStatus, Manifest, Notice } from "./context";
+import type { PluginDefinition } from "./define";
+import { type LogRecord } from "./logs";
+export type TestCall = {
+    /** False is a tap the user hasn't answered yet: a method with a `confirm` answers CONFIRM. */
+    confirmed?: boolean;
+    caller?: Caller;
+    root?: string;
+    /** The chat an agent calls from, kept on the call's log lines. */
+    chat?: string;
+};
+export type TestRuntime = {
+    /** Runs `<plugin>.<method>` and returns its answer, or throws its MethodError. */
+    call: (method: string, input?: unknown, options?: TestCall) => Promise<unknown>;
+    /** Sets the schedules, the whole set, as the host does from `~/.repogo/crons.json`. */
+    setCrons: (crons: CronEntry[]) => CronStatus[];
+    /** Runs every cron due at `now` and waits for them. */
+    tickCrons: (now?: number) => Promise<void>;
+    manifest: () => Manifest;
+    /** Every `ctx.notify` so far, in order. */
+    notices: Notice[];
+    /** Every console line a plugin wrote so far, with the call it was written in; errors a method threw too. */
+    logs: LogRecord[];
+    /** Closes the data and deletes its folder. */
+    close: () => Promise<void>;
+};
+/** What `ctx.mcp` asks the host: the tool, its input, and whether a query or a confirmed method asks. */
+export type TestMCPCall = {
+    project: string;
+    server: string;
+    tool: string;
+    input: unknown;
+    read: boolean;
+    confirmed: boolean;
+};
+/** Stands in for the user's MCP servers: answers a tool's result, or throws to refuse as a tool error. */
+export type TestMCP = (call: TestMCPCall) => unknown;
+/** Stands in for the host's methods (`chats.start`, `git.status`, …) behind `ctx.host` and `ctx.agent`; throw a MethodError to refuse. */
+export type TestHost = (method: string, params: unknown) => unknown;
+/**
+ * `const app = await testRuntime({ notes })`, then `await app.call("notes.add", { text: "hi" })`.
+ * `ctx.root` is an empty temporary folder unless `root` names a fixture project;
+ * `mcp` answers `ctx.mcp`, `host` the other host methods. Console lines still print.
+ */
+export declare function testRuntime(plugins: Record<string, PluginDefinition>, options?: {
+    root?: string;
+    mcp?: TestMCP;
+    host?: TestHost;
+}): Promise<TestRuntime>;