@repogo/plugins 0.1.30 → 0.1.32

package/README.md

@@ -22,6 +22,22 @@ export default definePlugin({
 });
 ```
 
+A `stream` sends items as they happen, for as long as a card shows it. Each
+`yield` is one item; `ctx.signal` aborts when the card goes, so hand it to what
+you start:
+
+```ts
+tail: stream(z.object({ file: z.string() }), async function* ({ file }, ctx) {
+  const tail = Bun.spawn(["tail", "-f", file], { signal: ctx.signal });
+  let partial = "";
+  for await (const chunk of tail.stdout.pipeThrough(new TextDecoderStream())) {
+    const lines = (partial + chunk).split("\n");
+    partial = lines.pop()!;
+    for (const line of lines) yield { id: crypto.randomUUID(), text: line };
+  }
+}),
+```
+
 `db` names the SQLite file the collections live in, `~/.repogo/plugin-data/<db>.db`
 on the environment; left out, it is the plugin's folder name. Name a project's own
 data `<project>.<name>`. A bare name (`todos`) is shared by every plugin that

package/dist/context.d.ts

@@ -15,6 +15,8 @@ export type Context = {
     db: Record<string, Collection<any>>;
     call: (method: string, input?: unknown) => Promise<unknown>;
     emit: (name: string, payload: unknown) => Promise<void>;
+    /** Aborts when a stream's last watcher leaves; a query or mutation's never does. */
+    signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;
     log: (...args: unknown[]) => void;

package/dist/define.d.ts

@@ -3,10 +3,11 @@ import type { Context } from "./context";
 export type Collections = Record<string, z.ZodObject>;
 /**
  * A query only reads, so cards may run it on their own and again when its data
- * changes. A mutation writes, and runs only when the user acts. Unmarked
- * methods are mutations: repeating one is never assumed safe.
+ * changes. A mutation writes, and runs only when the user acts. A stream only
+ * reads too, and sends items as they happen for as long as someone watches.
+ * Unmarked methods are mutations: repeating one is never assumed safe.
  */
-export type MethodKind = "query" | "mutation";
+export type MethodKind = "query" | "mutation" | "stream";
 export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> = {
     input: I;
     /** What it returns; the agent and cards read field names from it. */
@@ -41,3 +42,12 @@ export declare function method<I extends z.ZodType, O extends z.ZodType = z.ZodT
     description?: string;
     confirm?: string;
 }): Method<I, O>;
+/**
+ * A method that sends items as they happen: a log tail, a build's output. Each
+ * `yield` is one item; a card shows them as a list that grows. It runs while
+ * someone watches and `ctx.signal` aborts when the last one leaves, so pass it
+ * on (`Bun.spawn(cmd, { signal: ctx.signal })`). Like a query, it may not write.
+ */
+export declare function stream<I extends z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => AsyncIterable<unknown>, options?: {
+    description?: string;
+}): Method<I>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { definePlugin, method } from "./define";
+export { definePlugin, method, stream } from "./define";
 export type { PluginDefinition, Method, MethodKind } from "./define";
 export type { Context } from "./context";
 export { MethodError, toCallError, type CallError } from "./errors";

package/dist/index.js

@@ -13,6 +13,9 @@ function method(input, run, options = {}) {
     confirm: options.confirm
   };
 }
+function stream(input, run, options = {}) {
+  return { input, run, kind: "stream", description: options.description };
+}
 // src/errors.ts
 import { z } from "zod";
 
@@ -45,6 +48,7 @@ import { z as z2 } from "zod";
 export {
   z2 as z,
   toCallError,
+  stream,
   method,
   definePlugin,
   MethodError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repogo/plugins",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Write RepoGo plugins: collections and methods over SQLite that agents and cards call",
   "type": "module",
   "exports": {