@repogo/plugins 0.1.34 → 0.1.37

package/dist/context.d.ts

@@ -2,16 +2,74 @@ import type { Bucket } from "./buckets";
 import type { Collection } from "./collections";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
-import type { MethodKind } from "./define";
+import type { HTTPAccess, MethodKind } from "./define";
+import type { Duration } from "./duration";
 /** An alert for the user's phones: what it says, and the page a tap opens. */
 export type Notice = {
     title: string;
     body: string;
     /** A page target, `.repogo/tabs/vercel.md?project=a`; a tap opens it. */
     page?: string;
+    /** An `https` or `itms-services` link a tap opens instead of the page, such as a build's install. */
+    url?: string;
     /** Alerts sharing a collapse id replace one another; defaults to the plugin and title. */
     collapse?: string;
 };
+/** A Live Activity's color: the cards' named colors, less `secondary`. */
+export type ActivityTint = "primary" | "accent" | "success" | "warning" | "danger" | "blue" | "green" | "orange" | "red" | "purple" | "pink" | "teal" | "yellow" | "gray";
+/** A segment per step, or one bar. */
+export type ActivityProgress = {
+    kind: "steps";
+    /** 1 to 8 names of at most 24 characters. */
+    steps: string[];
+    /** The active step, 0 to `steps.length`; the ones before it are complete. */
+    current: number;
+} | {
+    kind: "bar";
+    /** 0 to 1. */
+    value: number;
+};
+/** The card's clock, which the phone ticks with no pushes. */
+export type ActivityTimer = {
+    kind: "elapsed";
+    /** Unix ms; the activity's first start unless said. */
+    startedAt?: number;
+} | {
+    kind: "countdown";
+    /** Unix ms; reaching it ends nothing. */
+    endsAt: number;
+} | {
+    kind: "none";
+};
+/**
+ * A Live Activity on the user's phones, sent whole each time: the same `id`
+ * updates it, a field left out takes its default, and status `done` or
+ * `failed` ends it with this state.
+ */
+export type Activity = {
+    /** The activity's id within the plugin, at most 64 bytes. */
+    id: string;
+    /** At most 60 characters, as a notice's title. */
+    title: string;
+    /** At most 120 characters, as a notice's body. */
+    body?: string;
+    /** A page target of the calling project, `.repogo/tabs/deploys.ui?project=web`; a tap opens it. */
+    page?: string;
+    /** An SF Symbol name, `shippingbox`; `circle.dotted`, or a check or a cross once ended, unless said. */
+    symbol?: string;
+    /** Colors the symbol, the progress and the label; white, or green or red once ended, unless said. */
+    tint?: ActivityTint;
+    /** The card's value, at most 24 characters; "2 of 4", "40%" or the status unless said, and "" hides it. */
+    label?: string;
+    /** The Dynamic Island's value, at most 10 characters; the label, or "2/4", unless said. */
+    compactLabel?: string;
+    /** No progress unless said. */
+    progress?: ActivityProgress;
+    /** Elapsed since the first start unless said. */
+    timer?: ActivityTimer;
+    /** `running` unless said; `done` and `failed` end it. */
+    status?: "running" | "done" | "failed";
+};
 /** One method as `ctx.plugins()` and the agent's `plugins` tool list it. */
 export type ManifestMethod = {
     /** `<plugin>.<method>`, the name `ctx.call` takes. */
@@ -20,6 +78,8 @@ export type ManifestMethod = {
     description: string | null;
     /** What a card asks before running it; null runs on tap. */
     confirm: string | null;
+    /** Who may call it at the environment's own address; null, no one. */
+    http: HTTPAccess | null;
     /** JSON Schema of the input, and of the output when the method declares one. */
     input: unknown;
     output: unknown;
@@ -32,6 +92,8 @@ export type ManifestCron = {
     nextRunAt: number | null;
     lastRunAt: number | null;
     lastError: string | null;
+    /** How long its last run took: a run far past its interval blocked or waited on something. */
+    lastDurationMs: number | null;
     running: boolean;
     runs: number;
 };
@@ -49,6 +111,21 @@ export type ManifestStorage = {
         path: string;
     }[];
 };
+/**
+ * One schedule the host gives a Worker, from a line of `~/.repogo/crons.json`: call
+ * `<plugin>.<method>` with `{}` when `schedule` comes due in `timezone` (the environment's).
+ */
+export type CronEntry = {
+    plugin: string;
+    method: string;
+    schedule: string;
+    timezone?: string;
+};
+/** A schedule and how it's going; `error` says why it couldn't be set, and then nothing runs. */
+export type CronStatus = ManifestCron & {
+    plugin: string;
+    error: string | null;
+};
 export type Manifest = {
     plugins: {
         name: string;
@@ -58,8 +135,27 @@ export type Manifest = {
         storage: ManifestStorage;
     }[];
 };
+/** Who started a call: a tap or a card's query, an agent's `plugin_call`, a cron, or plugin code with none of those behind it. */
+export type Caller = "card" | "agent" | "cron" | "code" | "http";
+/** How `ctx.agent` runs a chat: which agent, in which project, and how long to wait for its answer. */
+export type AgentOptions = {
+    /** `claude` or `codex`, as `agents.list` names them. */
+    agent: string;
+    /** The project the chat runs in; the calling project unless said. */
+    project?: string;
+    title?: string;
+    /** How long to wait for the answer; 10 minutes unless said. */
+    timeout?: Duration;
+};
+/** What the agent answered, and the chat it answered in, to open or message later. */
+export type AgentReply = {
+    chatId: string;
+    text: string;
+};
 export type Context = {
     plugin: string;
+    /** Who started the outermost call; `ctx.call` passes it on. */
+    caller: Caller;
     /** The project's checkout, for a plugin that reads the project's files. */
     root: string;
     collections: Record<string, Collection<any>>;
@@ -73,6 +169,13 @@ export type Context = {
      * `ctx.host("git.status", { path: ctx.root })`. Its answer doesn't re-run a query.
      */
     host: (method: string, params?: unknown) => Promise<unknown>;
+    /**
+     * Runs a tool of an MCP server the user switched on for the calling project:
+     * `ctx.mcp("stripe", "stripe_api_read", { … })`, answering the tool's result.
+     * A query may run only read-only tools; a destructive tool runs only from a
+     * method with a `confirm`. Its answer doesn't re-run a query.
+     */
+    mcp: (server: string, tool: string, input?: unknown) => Promise<unknown>;
     /**
      * The plugins beside this one, in the same folder (the project's, or the
      * environment's), with their methods: what `call` can reach.
@@ -82,5 +185,18 @@ export type Context = {
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;
+    /**
+     * Shows or updates a Live Activity on every paired phone:
+     * `await ctx.activity({ id: "deploy", title: "Deploying", progress: { kind: "steps", steps: ["Build", "Ship"], current: 0 } })`.
+     * A plugin shows at most two at once.
+     */
+    activity: (activity: Activity) => Promise<void>;
+    /**
+     * Starts a chat with `prompt` and waits for the agent's whole answer:
+     * `await ctx.agent("Why is the build failing?", { agent: "claude" })`.
+     * Throws once `timeout` passes, naming the chat, which keeps running.
+     */
+    agent: (prompt: string, options: AgentOptions) => Promise<AgentReply>;
+    /** The same as `console.log`: every console line is kept with the plugin and the call that wrote it. */
     log: (...args: unknown[]) => void;
 };

package/dist/cron.d.ts

@@ -0,0 +1,21 @@
+export type Schedule = {
+    seconds: Set<number> | null;
+    minutes: Set<number>;
+    hours: Set<number>;
+    days: Set<number>;
+    months: Set<number>;
+    weekdays: Set<number>;
+    /** Day fields given as other than `*`, for cron's either-day rule. */
+    daysRestricted: boolean;
+    weekdaysRestricted: boolean;
+};
+/** Reads a schedule, or throws saying what's wrong with it. */
+export declare function parseSchedule(source: string): Schedule;
+/** Throws unless `zone` is a time zone this machine knows, such as "America/New_York". */
+export declare function checkTimezone(zone: string): void;
+/**
+ * The first due time strictly after `after` (ms), in `zone`, or null when there
+ * is none within four years (`0 0 31 2 *`). A wall time that a fall-back night
+ * shows twice is due only the first time.
+ */
+export declare function nextDue(s: Schedule, after: number, zone: string): number | null;

package/dist/define.d.ts

@@ -1,5 +1,8 @@
 import type { z } from "zod";
+import type { CacheOptions } from "./cache";
 import type { Context } from "./context";
+import { type Duration } from "./duration";
+import type { Workflow } from "./workflow/definition";
 import type { Retain } from "./streams";
 export type Collections = Record<string, z.ZodObject>;
 /** A stream's lines' schema, or that and how long it keeps them (7 days or 50 MB a key unless it says). */
@@ -25,26 +28,25 @@ export type Method<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodT
      * runs, such as "Delete every item?". Methods without one run on tap.
      */
     confirm?: string;
+    /** Who may call it at the environment's own address; unset, no one. */
+    http?: HTTPAccess;
+    /** Set by `cached`: the query answers from what it saved, and checks again when that's old. */
+    cache?: CacheOptions;
     run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>;
 };
-export type Handler = (payload: any, ctx: Context) => unknown | Promise<unknown>;
 /**
- * Runs one of the plugin's methods on a schedule, called with `{}` as a tap
- * would: `{ method: "watch", schedule: "*\/5 * * * *" }`. `schedule` is a cron,
- * five fields or six with seconds first; `timezone` defaults to the environment's.
+ * `key`: the host checks a key the caller sends. `none`: anyone reaches the
+ * method, which checks the caller itself, such as a provider's signature.
  */
-export type Cron = {
-    method: string;
-    schedule: string;
-    timezone?: string;
-};
+export type HTTPAccess = "key" | "none";
+export type Handler = (payload: any, ctx: Context) => unknown | Promise<unknown>;
 export type PluginDefinition = {
     /** One line, shown to the agent in the index of plugins. */
     description?: string;
     /**
      * Where the plugin's data lives: `<namespace>/` in the data dir, holding `data.db`
      * and its buckets' and streams' files. Plugins naming the same namespace share its
-     * data. The plugin's folder name when left out; by convention a project's own is
+     * data. Required once the plugin keeps data; by convention a project's own is
      * `<project>.<name>` (`repogo.plans`) and data for every project a bare name (`todos`).
      */
     namespace?: string;
@@ -56,8 +58,13 @@ export type PluginDefinition = {
     /** Append-only JSONL per key, in `<namespace>/streams/<name>/`, kept as `retain` says. */
     streams?: Record<string, StreamDefinition>;
     methods?: Record<string, Method<any, any>>;
+    workflows?: Record<string, Workflow<any, any>>;
     on?: Record<string, Handler>;
-    crons?: Cron[];
+    /**
+     * Data named here gets no generated methods (list, create, delete…), so cards
+     * and agents reach it only through the plugin's own: an audit log, say.
+     */
+    private?: string[];
 };
 export declare function definePlugin<T extends PluginDefinition>(plugin: T): T;
 export declare function method<I extends z.ZodType, O extends z.ZodType = z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>, options?: {
@@ -65,6 +72,24 @@ export declare function method<I extends z.ZodType, O extends z.ZodType = z.ZodT
     output?: O;
     description?: string;
     confirm?: string;
+    http?: true | {
+        auth: HTTPAccess;
+    };
+}): Method<I, O>;
+/**
+ * A query that answers at once from what it saved last time, for answers that
+ * are slow to get: a CLI's list, another service's API. When the saved answer
+ * is older than `fresh`, `run` goes again in the background, and cards showing
+ * it redraw only if the answer changed. With nothing saved, the first call
+ * waits for `run`. Each project keeps its own answers unless `shared`.
+ * `run` is read-only, like a query's; it has `timeout` (a minute unless it says).
+ */
+export declare function cached<I extends z.ZodType, O extends z.ZodType = z.ZodType>(input: I, run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>, options: {
+    fresh: Duration;
+    shared?: boolean;
+    timeout?: Duration;
+    output?: O;
+    description?: string;
 }): Method<I, O>;
 /**
  * A method that sends items as they happen: a log tail, a build's output. Each

package/dist/generated.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { Bucket } from "./buckets";
+import type { MethodKind } from "./define";
+import type { Kv } from "./kv";
+import type { Stream } from "./streams";
+export type Generated = {
+    kind: MethodKind;
+    description: string;
+    input: z.ZodType;
+    output?: z.ZodType;
+    confirm?: string;
+    run: (input: any, signal: AbortSignal) => unknown;
+};
+export declare function kvMethods(name: string, kv: Kv<any>, schema: z.ZodType): Record<string, Generated>;
+export declare function streamMethods(name: string, stream: Stream<any>, schema: z.ZodType): Record<string, Generated>;
+export declare function bucketMethods(name: string, bucket: Bucket<any>, schema: z.ZodObject): Record<string, Generated>;

package/dist/index.d.ts

@@ -1,9 +1,16 @@
-export { definePlugin, method, stream } from "./define";
-export type { PluginDefinition, Method, MethodKind, Cron, StreamDefinition } from "./define";
-export type { Context, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
+export { cached, definePlugin, method, stream } from "./define";
+export { upload, type UploadedFile } from "./uploads";
+export type { PluginDefinition, Method, MethodKind, HTTPAccess, StreamDefinition } from "./define";
+export type { Activity, ActivityProgress, ActivityTimer, ActivityTint, AgentOptions, AgentReply, Caller, Context, CronEntry, CronStatus, Manifest, ManifestCron, ManifestMethod, ManifestStorage } from "./context";
+export type { LogLevel, LogRecord } from "./logs";
 export type { BucketFile, FileStatus, PutFile } from "./buckets";
 export type { KvEntry, SetOptions } from "./kv";
 export type { Retain, StreamEntry, StreamKey } from "./streams";
 export type { Duration } from "./duration";
 export { MethodError, toCallError, type CallError } from "./errors";
 export { z } from "zod";
+export { workflow, type Workflow, type WorkflowContext, type WorkflowOptions } from "./workflow/definition";
+export { NonRetryable } from "./workflow/errors";
+export type { StepContext } from "./workflow/definition";
+export type { StepOptions } from "./workflow/policy";
+export type { RunSummary } from "./workflow/contracts";

package/dist/index.js

@@ -1,4 +1,47 @@
 // @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  z: () => z3,
+  workflow: () => workflow,
+  upload: () => upload,
+  toCallError: () => toCallError,
+  stream: () => stream,
+  method: () => method,
+  definePlugin: () => definePlugin,
+  cached: () => cached,
+  NonRetryable: () => NonRetryable,
+  MethodError: () => MethodError
+});
+
+// src/duration.ts
+var unitMs = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function parseDuration(duration) {
+  if (typeof duration === "number") {
+    if (!Number.isFinite(duration) || duration <= 0)
+      throw new Error(`a duration is a positive number of ms: ${duration}`);
+    return duration;
+  }
+  const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(duration);
+  if (!match)
+    throw new Error(`a duration is like "30s", "5m", "1h" or "7d": ${duration}`);
+  const ms = Number(match[1]) * unitMs[match[2]];
+  if (ms <= 0)
+    throw new Error(`a duration is longer than zero: ${duration}`);
+  return ms;
+}
+
 // src/define.ts
 function definePlugin(plugin) {
   return plugin;
@@ -10,14 +53,34 @@ function method(input, run, options = {}) {
     kind: options.kind ?? "mutation",
     output: options.output,
     description: options.description,
-    confirm: options.confirm
+    confirm: options.confirm,
+    http: options.http === true ? "key" : options.http?.auth
+  };
+}
+function cached(input, run, options) {
+  return {
+    input,
+    run,
+    kind: "query",
+    output: options.output,
+    description: options.description,
+    cache: { fresh: parseDuration(options.fresh), shared: options.shared ?? false, timeout: parseDuration(options.timeout ?? "1m") }
   };
 }
 function stream(input, run, options = {}) {
   return { input, run, kind: "stream", description: options.description };
 }
-// src/errors.ts
+// src/uploads.ts
+import { AsyncLocalStorage } from "async_hooks";
 import { z } from "zod";
+var callFiles = new AsyncLocalStorage;
+function upload() {
+  return z.object({ id: z.string(), name: z.string(), type: z.string(), size: z.number(), path: z.string() }).refine((file) => (callFiles.getStore() ?? []).some((held) => held.id === file.id && held.path === file.path), {
+    message: "Not a file uploaded for this call."
+  });
+}
+// src/errors.ts
+import { z as z2 } from "zod";
 
 class MethodError extends Error {
   code;
@@ -32,7 +95,7 @@ function toCallError(error) {
   if (error instanceof MethodError) {
     return { code: error.code, message: error.message, ...error.fieldErrors ? { fieldErrors: error.fieldErrors } : {} };
   }
-  if (error instanceof z.ZodError) {
+  if (error instanceof z2.ZodError) {
     const fieldErrors = {};
     for (const issue of error.issues)
       fieldErrors["/" + issue.path.join("/")] ??= issue.message;
@@ -44,12 +107,44 @@ function toCallError(error) {
 }
 
 // src/index.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
+
+// src/workflow/scope.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var attemptScope = new AsyncLocalStorage2;
+var workflowScope = new AsyncLocalStorage2;
+
+// src/workflow/definition.ts
+function workflowContext(base, run) {
+  return {
+    ...base,
+    ...run,
+    get signal() {
+      return attemptScope.getStore()?.signal ?? run.signal;
+    },
+    step: { run: (name, callback, options) => run.step.run(name, (context) => callback({ ...context, runId: run.runId, idempotencyKey: `${run.runId}:${name}` }), options) }
+  };
+}
+function workflow(input, run, options = {}) {
+  return { input, run, ...options };
+}
+// src/workflow/errors.ts
+class NonRetryable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NonRetryable";
+  }
+}
 export {
-  z2 as z,
+  z3 as z,
+  workflow,
+  upload,
   toCallError,
   stream,
   method,
   definePlugin,
+  cached,
+  NonRetryable,
   MethodError
 };
+export { parseDuration, callFiles, MethodError, toCallError, attemptScope, workflowScope, workflowContext, exports_src };

package/dist/logs.d.ts

@@ -0,0 +1,55 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Caller } from "./context";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogRecord = {
+    /** ms since the epoch. */
+    at: number;
+    plugin: string;
+    level: LogLevel;
+    /** `<plugin>.<method>` of the run the line was written in; empty outside a run. */
+    method: string;
+    caller: Caller | "";
+    /** One id per outermost call, so a call's lines read together. */
+    callId: string;
+    /** The chat whose agent made the call, for `caller: "agent"`. */
+    chatId: string;
+    /** The arguments formatted as the console prints them, at most `textLimit` characters. */
+    text: string;
+    /** The arguments as given, as JSON can carry them. */
+    data: unknown[];
+};
+/** What a line is attributed to: the plugin, and the run when there is one. */
+export type LogContext = {
+    plugin: string;
+    method?: string;
+    caller?: Caller;
+    callId?: string;
+    chatId?: string;
+};
+/** The run the code writing a line is in; the runtime sets it around every method, handler and cron. */
+export declare const logContext: AsyncLocalStorage<LogContext>;
+/**
+ * Runs `work` as an outermost run under `context`. An error nothing catches
+ * reaches its handler with no async context, so the newest run going is the
+ * best guess at whose it is.
+ */
+export declare function runWith<T>(context: LogContext, work: () => Promise<T>): Promise<T>;
+/** A line longer than this is cut: a dumped payload is read in the plugin's own data, not its log. */
+export declare const textLimit: number;
+type Sink = (record: LogRecord) => void;
+/**
+ * Replaces `console.log`, `info`, `debug`, `warn` and `error` with ones that
+ * record each call. `passThrough` keeps printing them too, for tests.
+ */
+export declare function captureConsole(to: Sink, options?: {
+    passThrough?: boolean;
+}): void;
+/** Puts the console back and stops recording. */
+export declare function releaseConsole(): void;
+/**
+ * Records one line under `context`, else the current run, else the newest run
+ * going, as an error nothing caught lands in. With no capture installed the
+ * line prints as the console would.
+ */
+export declare function record(level: LogLevel, args: unknown[], context?: LogContext): void;
+export {};