@repogo/plugins 0.1.41 → 0.1.43

package/README.md

@@ -7,7 +7,7 @@ phone draw its data live and run its methods when you tap.
 
 - [Quick start](#quick-start)
 - [Where plugins live](#where-plugins-live)
-- [Methods](#methods): queries, mutations, streams, cached queries
+- [Methods](#methods): reads, writes, destructive methods, streams, cached reads
 - [Data](#data): namespaces, collections, kv, streams, buckets, uploads
 - [Workflows](#workflows)
 - [Crons](#crons)
@@ -21,22 +21,22 @@ phone draw its data live and run its methods when you tap.
 ## Quick start
 
 ```ts
-// .repogo/plugins/notes/app.ts
+// ~/.repogo/plugins/notes/app.ts
 import { definePlugin, method, z } from "@repogo/plugins";
 
 export default definePlugin({
-  description: "Notes for this project",
-  namespace: "myproject.notes",
+  description: "Notes for any project",
+  namespace: "notes",
   collections: { notes: z.object({ text: z.string(), done: z.boolean().default(false) }) },
   methods: {
     open: method(z.object({}), async (_, ctx) => ctx.collections.notes.list({ where: { done: false } }), {
-      kind: "query",
+      effect: "read",
       description: "Notes not done yet, newest first",
     }),
     clear: method(z.object({}), async (_, ctx) => {
       for (const note of await ctx.collections.notes.list({ limit: 500 })) await ctx.collections.notes.delete(note.id);
       return null;
-    }, { confirm: "Delete every note?" }),
+    }, { effect: "destructive", confirm: "Delete every note?" }),
   },
 });
 ```
@@ -46,9 +46,9 @@ a minute; at once when something calls it), and it gets:
 
 - `notes.open` and `notes.clear`, the methods it wrote;
 - `notes.notes.list`, `.get`, `.create`, `.update` and `.delete`, generated for its collection;
-- a `data.db` in `~/.repogo/plugin-data/myproject.notes/`.
+- a `data.db` in `~/.repogo/plugin-data/notes/`.
 
-Add the package to `.repogo/plugins/package.json` (`bun add @repogo/plugins`) for
+Add the package to `~/.repogo/plugins/package.json` (`bun add @repogo/plugins`) for
 types and editor help. The host runs plugins with its own copy of this package,
 the version it shipped with, so a plugin always matches its host. Plugins run on
 [Bun](https://bun.sh); install it on the environment.
@@ -57,30 +57,39 @@ the version it shipped with, so a plugin always matches its host. Plugins run on
 
 | Folder | For | `ctx.root` |
 | --- | --- | --- |
-| `<project>/.repogo/plugins/<name>/app.ts` | One project | The project's checkout |
-| `~/.repogo/plugins/<name>/app.ts` | Every project (Vercel, Gmail, builds) | The project that called it |
+| `~/.repogo/plugins/<name>/app.ts` | Every project | The project that called it |
 
-A plugin's name is its folder's: lowercase letters, digits and hyphens. A
-project plugin hides an environment one of the same name. Each folder's plugins
-run together in one Worker, so a plugin's blocking code stalls the others in its
-folder: use async APIs.
+Plugins live only on the environment, in folders the user put there. A project
+can't ship plugin code: the host never imports a repo's `.repogo/plugins`, so
+cloning or opening a project never runs anything in it. A plugin about one
+project (its keys, its database, its plans) is still an environment plugin: it
+reads that project from `ctx.root`, and says so instead of acting when it's
+called from a project it doesn't fit.
+
+A project ships no pages either: the app loads `.ui` and `.html` pages only
+from `~/.repogo/plugins`, so a cloned repo can't put its own page, and the
+script an `.html` page runs, in front of the user. A page about one project
+lives beside its plugin and takes the project as state (`?project=…`).
+
+A plugin's name is its folder's: lowercase letters, digits and hyphens. The
+environment's plugins run together in one Worker, so a plugin's blocking code
+stalls the others: use async APIs.
 
 Pages beside an environment plugin (`pages/*.ui`, or `pages/*.md`) open from
 any project as `~/.repogo/plugins/<name>/pages/<page>.ui`. A
 `.ui` page is card markup with no fence; a `.md` page is writing with cards.
 
-In the full iOS app, `~/.repogo/plugins/plugin.ui` supplies a shared Plugins
-tab. A project’s `.repogo/plugin.ui` overrides the entire page for that
-project; entries are not merged. If neither exists, the tab is absent.
-Both are plain card markup without a code fence. Read and preserve existing
+In the full iOS app, `~/.repogo/plugins/plugin.ui` is the Plugins tab in
+every project; a project's `.repogo/plugin.ui` is never read. If it doesn't
+exist, the tab is absent. It is plain card markup without a code fence. Read and preserve existing
 entries, and link to plugin pages with `page:` actions.
 
-A user-facing plugin needs both its saved page and a link from the applicable `plugin.ui`. Saving a file in `.repogo/tabs` or naming it `index.ui` does not register a project tab. Plugin discovery can list a page without a navigation entry; verify the effective `plugin.ui` links to the existing page.
+A user-facing plugin needs both its saved page and a link from `~/.repogo/plugins/plugin.ui`. Saving a file in a pages folder or naming it `index.ui` does not add it to the tab. Plugin discovery can list a page without a navigation entry; verify `plugin.ui` links to the existing page.
 
 ## Methods
 
 ```ts
-method(input, run, { kind?, description?, output?, confirm? })
+method(input, run, { effect?, description?, output?, confirm? })
 stream(input, async function* run, { description? })
 ```
 
@@ -88,14 +97,18 @@ stream(input, async function* run, { description? })
 filled in before `run` sees it. `run(input, ctx)` returns the result: anything
 JSON can carry.
 
-| Kind | Does | Who runs it |
+| Effect | Does | Who runs it |
 | --- | --- | --- |
-| `query` | Only reads; writing throws | Cards on their own, and again whenever data it read changes |
-| `mutation` (the default) | Reads and writes | Only when someone acts: a tap, an agent, a cron, other code |
-| `stream` | Only reads; yields items as they happen | A card while it shows it |
-
-Mark every method that only reads as `kind: "query"`: that's what lets a card
-show it and keep it current. Give each a `description`; agents read it to choose
+| `read` | Only reads; writing throws | Cards on their own, and again whenever data it read changes |
+| `write` (the default) | Reads and writes | Only when someone acts: a tap, an agent, a cron, other code |
+| `destructive` | Writes what can't be undone; needs a `confirm` | Only after the user answers its question, on a tap |
+| `stream()` | A read that yields items as they happen | A card while it shows it |
+
+Mark every method that only reads `effect: "read"`: that's what lets a card
+show it and keep it current. Mark what can't be undone (a delete, a send, a
+deploy) `effect: "destructive"` with a `confirm` question; a destructive method
+without one doesn't load. A method with a `confirm` never runs from an agent's
+`plugin_call` or a cron: the agent draws a button, and the user's tap asks. Give each a `description`; agents read it to choose
 a method. `output`, a zod schema of the result, tells agents and cards its
 field names.
 
@@ -108,7 +121,7 @@ or the voice agent reads the whole of one.
 ```ts
 open: method(z.object({ limit: z.number().int().min(1).max(100).default(20) }), async ({ limit }, ctx) =>
   (await ctx.collections.notes.list({ where: { done: false }, limit })).map(({ id, text }) => ({ id, text: text.slice(0, 200) })),
-  { kind: "query", description: "Notes not done yet, newest first" }),
+  { effect: "read", description: "Notes not done yet, newest first" }),
 ```
 
 A **stream** sends each `yield` to the card as it happens, for as long as the
@@ -142,7 +155,7 @@ projects: cached(z.object({ limit: z.number().int().min(1).max(200).default(100)
 
 - Answers are kept per method, input and project (`ctx.root`). `shared: true`
   keeps one for every project, for answers that don't depend on it.
-- `run` is read-only, like a query's, and has `timeout` (a minute unless it says).
+- `run` is read-only, like any read's, and has `timeout` (a minute unless it says).
 - A background check that fails keeps the saved answer, goes to the plugin's
   logs, and is tried again after another `fresh`.
 - Answers live in the namespace's `data.db`, so a plugin with a cached method
@@ -193,7 +206,7 @@ await ctx.collections.tasks.delete(task.id);
 await ctx.collections.tasks.deleteMany({ where: { status: "done" }, offset: 100, limit: 500 }); // done ones past the newest 100, 500 at a time
 ```
 
-`list` is newest first by default, at most 100 unless `limit` says (up to 500).
+`list` is newest first by default, at most 100 unless `limit` says (the generated `list` takes up to 500).
 `where` matches top-level fields exactly; `null` matches a missing one.
 `orderBy` is `id`, `createdAt`, `updatedAt` or one of the record's own fields, and
 `offset` passes over that many first. `deleteMany` takes the same options and
@@ -480,7 +493,7 @@ For integration tests, import `testWorkflowRuntime` from
 `@repogo/plugins/testing` and pass the fixture's plugins directory. It uses real
 temporary storage and a subprocess per run, as the host does. Call the same lifecycle methods,
 use `await app.wait("reports.report", id)` to await a terminal/blocked run, and
-`await app.close()` afterward. The in-memory `testRuntime({ plugin })` helper
+`await app.close()` afterward. The plain `testRuntime({ plugin })` helper
 does not execute durable workflows.
 
 
@@ -501,7 +514,7 @@ itself. Each line names a plugin, one of its methods and a schedule:
 | Field | What |
 | --- | --- |
 | `plugin`, `method` | The plugin's folder name and one of its methods, called with `{}` as a tap would |
-| `project` | The project whose `.repogo/plugins` holds it, an absolute path or one starting `~/`; left out, `~/.repogo/plugins` |
+| `project` | The project the run gets as `ctx.root`, an absolute path or one starting `~/`; left out, the home folder. The plugin is always the environment's |
 | `schedule` | A cron: five fields (minute hour day-of-month month day-of-week), or six with seconds first (`*/5 * * * * *`); each `*`, a number, a range, a list or a step |
 | `timezone` | Defaults to the environment's |
 | `enabled` | `false` keeps the line without running it |
@@ -520,9 +533,9 @@ isn't valid JSON pauses every line until it's fixed. Each line also shows
 has the same for a plugin's own, and a query reading them re-runs around each run.
 
 Schedule something only when the user asks for it. A cron's `ctx.root` is its
-project, or the home folder for a plugin in `~/.repogo/plugins`. Plugins in one
-folder share a thread: code that blocks it holds up every other cron there, and
-the host's log names the crons that were running when it happened.
+line's project, or the home folder without one. Plugins share a thread: code
+that blocks it holds up every other cron, and the host's log names the crons
+that were running when it happened.
 
 ## Logging
 
@@ -530,7 +543,7 @@ Write `console.log` (or `warn`, `error`, `debug`); nothing else is needed. The
 host keeps every line with the plugin, the method and the call that wrote it,
 who called (`card`, `agent`, `cron`), and the chat for an agent's call, plus
 the arguments as JSON. An error a method throws, or one nothing caught, is
-kept too, with its stack. Read them with the agent's `plugin_logs` tool, or on
+kept too, with its stack. Read them with the agent's `plugins_logs` tool, or on
 a card with `<Data method="repogo:plugins.logs">`, which reloads as lines land:
 `plugin`, `level` (that level and worse), `method`, `since`, `until`, `query`
 (a substring) and `limit` narrow it. The `plugins` tool shows each plugin's
@@ -593,7 +606,7 @@ ends it with that state, left up for 15 minutes:
 ```ts
 deploy: method(z.object({ project: z.string() }), async ({ project }, ctx) => {
   const steps = ["Build", "Test", "Deploy", "Verify"];
-  const page = `.repogo/tabs/deploys.ui?project=${project}`;
+  const page = `~/.repogo/plugins/deploys/pages/index.ui?project=${project}`;
   const show = (current: number, body: string) =>
     ctx.activity({ id: `deploy:${project}`, title: `Deploying ${project}`, body, page,
       symbol: "shippingbox", progress: { kind: "steps", steps, current } });
@@ -633,10 +646,10 @@ or CLI of its own. It answers the tool's structured content, else its text
 customers: method(z.object({}), async (_, ctx) => {
   const list = await ctx.mcp("stripe", "stripe_api_read", { stripe_api_operation_id: "GetCustomers", /* … */ });
   return list.data.map((c) => ({ id: c.id, email: c.email }));
-}, { kind: "query" }),
+}, { effect: "read" }),
 ```
 
-A query may run only the server's read-only tools, as a card's `Data` may. A
+A read may run only the server's read-only tools, as a card's `Data` may. A
 tool marked destructive runs only from a method with a `confirm`, or one
 called from it with `ctx.call`: the user's answer to that question is its
 yes. A refusal throws `FORBIDDEN`; a tool's own error throws `INTERNAL` with
@@ -667,17 +680,17 @@ Events run in memory: none is retried, and a handler that throws is logged.
 ## How cards and agents reach a plugin
 
 **Agents** use two tools. `plugins` lists every plugin with a line per method
-(its kind, whether it asks first, and its input's fields, optional ones ending
+(its effect, whether it asks first, and its input's fields, optional ones ending
 in `?`), and every line of `~/.repogo/crons.json` with how it's going.
 `plugins` with `plugin` set answers that plugin in full: each method's input
 and output JSON Schema and confirm, its `storage` (each bucket's and stream's
 folder), the pages that show its methods, and the cron lines naming it.
 `plugin_call` runs one. Inspect a method's schema before naming it in a card.
-Verify query fields with a read-only call. Do not execute mutations just to
+Verify a read's fields with a read-only call. Do not execute writes just to
 check a card; run them only when the user's task calls for that action.
 
 **Cards** name methods as `plugin:<plugin>.<method>`. A `Data` element runs a
-query, or follows a stream, and redraws when its data changes. `Button`,
+read, or follows a stream, and redraws when its data changes. `Button`,
 `Item` and `Swipe` actions call methods; on iOS, `Toggle` can call one on a
 user flip. `Upload` calls a plugin method with staged files. Params must match
 the discovered input schema. These fragments assume `q` and `note` are supplied
@@ -701,10 +714,10 @@ by the enclosing card:
 ### Saving from a switch
 
 Prefer SDK storage for plugin-owned data. A storage declaration generates
-methods; ordinary saves do not need a custom mutation. For example:
+methods; ordinary saves do not need a custom write method. For example:
 
 ```ts
-// .repogo/plugins/preferences/app.ts
+// ~/.repogo/plugins/preferences/app.ts
 import { definePlugin, z } from "@repogo/plugins";
 
 export default definePlugin({
@@ -746,9 +759,10 @@ schema answers `VALIDATION` with a message per field. Anything else thrown is
 `INTERNAL` with its message.
 
 A method's `confirm` is asked before a card's tap runs it. An agent's
-`plugin_call` gets it back as a `CONFIRM` error until it calls again with
-`confirmed: true`, once the user agrees. Ordinary `ctx.call` from plugin code skips
-it; an unattended workflow refuses confirmation-gated methods. Give one to anything that can't be undone. `{{field}}` in the question is
+`plugin_call` never runs it: it gets the question back as a `CONFIRM` error and
+draws a button, and the user's tap asks. Ordinary `ctx.call` from plugin code skips
+it; an unattended workflow refuses confirmation-gated methods. A `destructive`
+method must have one. `{{field}}` in the question is
 filled from the call's input, so it can say what it acts on:
 `confirm: "Restart {{machine}}?"`.
 

package/dist/context.d.ts

@@ -2,7 +2,7 @@ import type { Bucket } from "./buckets";
 import type { Collection } from "./collections";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
-import type { HTTPAccess, MethodKind } from "./define";
+import type { Effect, HTTPAccess } 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 = {
@@ -74,7 +74,9 @@ export type Activity = {
 export type ManifestMethod = {
     /** `<plugin>.<method>`, the name `ctx.call` takes. */
     name: string;
-    kind: MethodKind;
+    effect: Effect;
+    /** A read that sends items as they happen. */
+    stream: boolean;
     description: string | null;
     /** What a card asks before running it; null runs on tap. */
     confirm: string | null;
@@ -113,13 +115,15 @@ export type ManifestStorage = {
 };
 /**
  * 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).
+ * `<plugin>.<method>` with `{}` when `schedule` comes due in `timezone` (the environment's),
+ * with `root` (the line's project) as `ctx.root`, else the Worker's own.
  */
 export type CronEntry = {
     plugin: string;
     method: string;
     schedule: string;
     timezone?: string;
+    root?: string;
 };
 /** A schedule and how it's going; `error` says why it couldn't be set, and then nothing runs. */
 export type CronStatus = ManifestCron & {
@@ -181,7 +185,7 @@ export type Context = {
      * environment's), with their methods: what `call` can reach.
      */
     plugins: () => Manifest["plugins"];
-    /** Aborts when a stream's last watcher leaves; a query or mutation's never does. */
+    /** Aborts when a stream's last watcher leaves; a read or write's never does. */
     signal: AbortSignal;
     /** Sends an alert to every phone paired with this environment. */
     notify: (notice: Notice) => void;

package/dist/define.d.ts

@@ -11,26 +11,28 @@ export type StreamDefinition = z.ZodType | {
     retain: Retain;
 };
 /**
- * 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. 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.
+ * What a method does. `read` only reads, so cards may run it on their own and
+ * again when its data changes. `write` changes data, and runs only when the
+ * user acts. `destructive` can't be undone, and must ask first (`confirm`).
+ * Unmarked methods write: repeating one is never assumed safe.
  */
-export type MethodKind = "query" | "mutation" | "stream";
+export type Effect = "read" | "write" | "destructive";
 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. */
     output?: O;
-    kind: MethodKind;
+    effect: Effect;
+    /** Set by `stream`: a read that sends items as they happen. */
+    stream?: true;
     description?: string;
     /**
-     * For what can't be undone: the question a card's button asks before it
-     * runs, such as "Delete every item?". Methods without one run on tap.
+     * The question asked before it runs, such as "Delete {{name}}?", filled from
+     * its input; required for a destructive method. 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. */
+    /** Set by `cached`: the read answers from what it saved, and checks again when that's old. */
     cache?: CacheOptions;
     run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>;
 };
@@ -67,22 +69,27 @@ export type PluginDefinition = {
     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?: {
-    kind?: MethodKind;
+type MethodOptions<O extends z.ZodType> = {
     output?: O;
     description?: string;
-    confirm?: string;
     http?: true | {
         auth: HTTPAccess;
     };
-}): Method<I, O>;
+} & ({
+    effect: "destructive";
+    confirm: string;
+} | {
+    effect?: "read" | "write";
+    confirm?: string;
+});
+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?: MethodOptions<O>): Method<I, O>;
 /**
- * A query that answers at once from what it saved last time, for answers that
+ * A read 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).
+ * `run` is read-only, like any read'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;
@@ -95,8 +102,9 @@ export declare function cached<I extends z.ZodType, O extends z.ZodType = z.ZodT
  * 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.
+ * on (`Bun.spawn(cmd, { signal: ctx.signal })`). Like any read, 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>;
+export {};

package/dist/generated.d.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import type { Bucket } from "./buckets";
-import type { MethodKind } from "./define";
+import type { Effect } from "./define";
 import type { Kv } from "./kv";
 import type { Stream } from "./streams";
 export type Generated = {
-    kind: MethodKind;
+    effect: Effect;
+    stream?: true;
     description: string;
     input: z.ZodType;
     output?: z.ZodType;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { cached, definePlugin, method, stream } from "./define";
 export { upload, type UploadedFile } from "./uploads";
-export type { PluginDefinition, Method, MethodKind, HTTPAccess, StreamDefinition } from "./define";
+export type { PluginDefinition, Method, Effect, 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";

package/dist/index.js

@@ -47,10 +47,12 @@ function definePlugin(plugin) {
   return plugin;
 }
 function method(input, run, options = {}) {
+  if ("kind" in options)
+    throw new Error('method: kind is now effect: "read", "write" or "destructive"');
   return {
     input,
     run,
-    kind: options.kind ?? "mutation",
+    effect: options.effect ?? "write",
     output: options.output,
     description: options.description,
     confirm: options.confirm,
@@ -61,14 +63,14 @@ function cached(input, run, options) {
   return {
     input,
     run,
-    kind: "query",
+    effect: "read",
     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 };
+  return { input, run, effect: "read", stream: true, description: options.description };
 }
 // src/uploads.ts
 import { AsyncLocalStorage } from "async_hooks";

package/dist/runtime.d.ts

@@ -2,14 +2,15 @@ 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 { HTTPAccess, PluginDefinition, MethodKind } from "./define";
+import type { Effect, HTTPAccess, PluginDefinition } from "./define";
 import { EventBus } from "./events";
 import type { WorkflowBridge } from "./workflow/contracts";
 import { type UploadedFile } from "./uploads";
 export type RegisteredMethod = {
     name: string;
     plugin: string;
-    kind: MethodKind;
+    effect: Effect;
+    stream?: true;
     description?: string;
     confirm?: string;
     http?: HTTPAccess;
@@ -35,9 +36,11 @@ type NoticeListener = (notice: SentNotice) => void;
 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. */
+    /** The plugin, method, schedule, zone and root: an entry the host sends again keeps its job, and its state. */
     signature: string;
     plugin: string;
+    /** The project the run gets as `ctx.root`; none keeps the Worker's own. */
+    root?: string;
     /** `<plugin>.<method>`. */
     method: string;
     schedule: string;
@@ -98,9 +101,9 @@ export declare class Runtime {
         caller: Caller;
     }): Promise<unknown>;
     /**
-     * Calls a method and reports what it read and wrote. `expect: "query"` is how
+     * Calls a method and reports what it read and wrote. `expect: "read"` is how
      * a card runs a method on its own: it refuses anything that might write, and
-     * so does everything the query calls.
+     * so does everything the read calls.
      */
     /**
      * `confirmed` is false for a tap the user hasn't answered; `ctx.call` leaves it out.
@@ -108,7 +111,7 @@ export declare class Runtime {
      * pass on to the code the method calls.
      */
     call(name: string, input?: unknown, options?: {
-        expect?: MethodKind;
+        expect?: "read";
         confirmed?: boolean;
         root?: string;
         caller?: Caller;

package/dist/testing.js

@@ -91,6 +91,7 @@ function carryable(value) {
 
 // src/runtime.ts
 import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
+import { existsSync } from "fs";
 import { mkdir as mkdir3, readdir as readdir3 } from "fs/promises";
 import { join as join3 } from "path";
 import { z as z5 } from "zod";
@@ -155,7 +156,7 @@ function recordRead(tag) {
 }
 function assertWritable(tag) {
   if (current.getStore()?.readOnly) {
-    throw new MethodError("FORBIDDEN", `A query can't change data (it tried to write ${tag}).`);
+    throw new MethodError("FORBIDDEN", `A read can't change data (it tried to write ${tag}).`);
   }
 }
 function recordWrite(tag) {
@@ -953,28 +954,28 @@ function kvMethods(name, kv, schema) {
   const entry = z.object({ key: z.string(), value: schema, expiresAt: z.string().nullable(), createdAt: z.string(), updatedAt: z.string() });
   return {
     get: {
-      kind: "query",
+      effect: "read",
       description: `Get one ${name} entry by key, or null`,
       input: z.object({ key }),
       output: entry.nullable(),
       run: ({ key: key2 }) => kv.entry(key2)
     },
     list: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} entries in key order, optionally by prefix`,
       input: z.object({ prefix: z.string().optional(), limit }),
       output: z.array(entry),
       run: (input) => kv.list(input)
     },
     set: {
-      kind: "mutation",
+      effect: "write",
       description: `Set a ${name} key; ttl ("5m", "1h", "7d" or ms) makes it expire`,
       input: z.object({ key, value: schema, ttl }),
       output: entry,
       run: ({ key: key2, value, ttl: ttl2 }) => kv.set(key2, value, { ttl: ttl2 })
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} key`,
       input: z.object({ key }),
       output: z.null(),
@@ -988,41 +989,42 @@ function streamMethods(name, stream, schema) {
   const line = z.object({ id: z.string(), key: z.string(), offset: z.number(), at: z.string(), data: schema });
   return {
     tail: {
-      kind: "stream",
+      effect: "read",
+      stream: true,
       description: `Follow a ${name} key live: its last lines (100 unless last says), then each new one, until it ends`,
       input: z.object({ key, from: z.number().int().min(0).optional(), last: z.number().int().positive().max(500).optional() }),
       run: ({ key: key2, from, last }, signal) => stream.follow(key2, { from, last, signal })
     },
     read: {
-      kind: "query",
+      effect: "read",
       description: `Read a ${name} key's lines from an offset`,
       input: z.object({ key, from: z.number().int().min(0).optional(), limit }),
       output: z.array(line),
       run: ({ key: key2, ...options }) => stream.read(key2, options)
     },
     keys: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} keys, most recently written first`,
       input: z.object({ limit }),
       output: z.array(z.object({ key: z.string(), lines: z.number(), bytes: z.number(), endedAt: z.string().nullable(), updatedAt: z.string() })),
       run: (input) => stream.keys(input)
     },
     append: {
-      kind: "mutation",
+      effect: "write",
       description: `Append a line to a ${name} key`,
       input: z.object({ key, data: schema }),
       output: line,
       run: ({ key: key2, data }) => stream.append(key2, data)
     },
     end: {
-      kind: "mutation",
+      effect: "write",
       description: `End a ${name} key: followers stop and appends fail`,
       input: z.object({ key }),
       output: z.null(),
       run: async ({ key: key2 }) => (await stream.end(key2), null)
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} key and its lines`,
       input: z.object({ key }),
       output: z.null(),
@@ -1051,28 +1053,28 @@ function bucketMethods(name, bucket, schema) {
   const revision = z.number().int().optional();
   return {
     list: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} files, newest first, optionally in one folder or with one status`,
       input: z.object({ folder: z.string().optional(), status: status.optional(), limit }),
       output: z.array(file),
       run: (input) => bucket.list(input)
     },
     search: {
-      kind: "query",
+      effect: "read",
       description: `Search ${name} files by name, folder and meta`,
       input: z.object({ query: z.string(), limit }),
       output: z.array(file),
       run: ({ query, limit: limit2 }) => bucket.search(query, { limit: limit2 })
     },
     get: {
-      kind: "query",
+      effect: "read",
       description: `Get one ${name} file by id, or null`,
       input: z.object({ id }),
       output: file.nullable(),
       run: ({ id: id2 }) => bucket.get(id2)
     },
     put: {
-      kind: "mutation",
+      effect: "write",
       description: `Add a file to ${name}: its name, and text or an absolute path to copy`,
       input: z.object({
         name: z.string(),
@@ -1089,21 +1091,21 @@ function bucketMethods(name, bucket, schema) {
       }
     },
     update: {
-      kind: "mutation",
+      effect: "write",
       description: `Change fields of a ${name} file's meta; null removes one`,
       input: z.object({ id, meta: z.record(z.string(), z.unknown()), revision }),
       output: file,
       run: ({ id: id2, meta, revision: revision2 }) => bucket.update(id2, meta, { revision: revision2 })
     },
     move: {
-      kind: "mutation",
+      effect: "write",
       description: `Rename a ${name} file or move it to another folder`,
       input: z.object({ id, name: z.string().optional(), folder: z.string().optional(), revision }),
       output: file,
       run: ({ id: id2, name: name2, folder, revision: revision2 }) => bucket.move(id2, { name: name2, folder }, { revision: revision2 })
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} file and its meta`,
       input: z.object({ id }),
       output: z.null(),
@@ -1524,29 +1526,29 @@ function workflowMethods(plugin, namespace, name, definition, ctx, bridge, direc
     return bridge({ operation, dir, plugin, namespace, workflow: name, root: ctx.root, caller: ctx.caller, input, settings: workflowSettings(definition) });
   };
   const id = z4.object({ id: z4.string().uuid() }).strict();
-  const spec = (method, kind, input, description, confirm, output) => ({
+  const spec = (method, effect, input, description, confirm, output) => ({
     name: `${plugin}.${name}.${method}`,
     plugin,
-    kind,
+    effect,
     input,
     description,
     confirm,
     output,
     run: async (input2, raw) => {
-      if (kind === "query")
+      if (effect === "read")
         recordRead(workflowTag(namespace));
       const request = method === "start" ? { ...input2, input: raw.input } : input2;
       return invoke(method, request);
     }
   });
   return [
-    spec("list", "query", z4.object({ limit: z4.number().int().min(1).max(100).default(20), status: z4.string().optional(), cursor: z4.string().optional() }).strict(), "List workflow runs", undefined, z4.object({ items: z4.array(RunSummarySchema), cursor: z4.string().nullable() })),
-    spec("get", "query", id, "Get one workflow run"),
-    spec("start", "mutation", z4.object({ input: definition.input, key: z4.string().min(1).max(200).optional() }).strict(), definition.description ?? "Start a durable workflow", definition.confirm, RunSummarySchema),
-    spec("retry", "mutation", id, "Retry a safely failed query step", undefined, RunSummarySchema),
-    spec("restart", "mutation", id, "Start a run that needs attention over from the beginning, on the current code", undefined, RunSummarySchema),
-    spec("cancel", "mutation", id, "Request cancellation of a workflow", undefined, RunSummarySchema),
-    spec("cancelAll", "mutation", z4.object({ status: z4.string().optional() }).strict(), "Cancel every unfinished run, or only those in one status", undefined, z4.object({ cancelled: z4.number().int() }))
+    spec("list", "read", z4.object({ limit: z4.number().int().min(1).max(100).default(20), status: z4.string().optional(), cursor: z4.string().optional() }).strict(), "List workflow runs", undefined, z4.object({ items: z4.array(RunSummarySchema), cursor: z4.string().nullable() })),
+    spec("get", "read", id, "Get one workflow run"),
+    spec("start", "write", z4.object({ input: definition.input, key: z4.string().min(1).max(200).optional() }).strict(), definition.description ?? "Start a durable workflow", definition.confirm, RunSummarySchema),
+    spec("retry", "write", id, "Retry a safely failed query step", undefined, RunSummarySchema),
+    spec("restart", "write", id, "Start a run that needs attention over from the beginning, on the current code", undefined, RunSummarySchema),
+    spec("cancel", "write", id, "Request cancellation of a workflow", undefined, RunSummarySchema),
+    spec("cancelAll", "write", z4.object({ status: z4.string().optional() }).strict(), "Cancel every unfinished run, or only those in one status", undefined, z4.object({ cancelled: z4.number().int() }))
   ];
 }
 function workflowSettings(definition) {
@@ -1606,6 +1608,8 @@ class Runtime {
         continue;
       if (only && !only.includes(entry.name))
         continue;
+      if (!existsSync(join3(pluginsDir, entry.name, "app.ts")))
+        continue;
       const module = await logContext.run({ plugin: entry.name }, () => import(join3(pluginsDir, entry.name, "app.ts")));
       await this.add(entry.name, module.default);
     }
@@ -1731,7 +1735,8 @@ class Runtime {
       this.register({
         name: fullName,
         plugin: name,
-        kind: method.kind,
+        effect: method.effect,
+        stream: method.stream,
         description: method.description,
         confirm: method.confirm,
         http: method.http,
@@ -1787,17 +1792,17 @@ class Runtime {
       return runWith(where, () => this.call(name, input, options));
     if (where !== logContext.getStore())
       return logContext.run(where, () => this.call(name, input, options));
-    if ((options.expect === "query" || currentAccess()?.readOnly) && method.kind === "mutation") {
+    if ((options.expect === "read" || currentAccess()?.readOnly) && method.effect !== "read") {
       throw new MethodError("FORBIDDEN", `${name} changes data, so it only runs when the user acts.`);
     }
     const raw = input ?? {};
     const parsed = method.input.parse(raw);
     if (method.confirm && (options.confirmed === false || workflowScope.getStore()))
       throw new MethodError("CONFIRM", fillConfirm(method.confirm, parsed));
-    if (method.kind === "stream")
+    if (method.stream)
       return { result: await this.sample(name, input), reads: [], invalidates: [] };
     const confirmed = this.callConfirmed.getStore() ?? false;
-    const run = await tracked(method.kind === "query", (tags) => this.notifyInvalidated(tags), () => this.callConfirmed.run(confirmed || method.confirm !== undefined, async () => {
+    const run = await tracked(method.effect === "read", (tags) => this.notifyInvalidated(tags), () => this.callConfirmed.run(confirmed || method.confirm !== undefined, async () => {
       const result = await method.run(parsed, raw);
       await this.events.emit(name, { input: parsed, result });
       return result;
@@ -1816,8 +1821,8 @@ class Runtime {
     const method = this.methods.get(name);
     if (!method)
       throw new MethodError("NOT_FOUND", `There is no method ${name}.`);
-    if (method.kind !== "stream")
-      throw new MethodError("VALIDATION", `${name} is a ${method.kind}, not a stream.`);
+    if (!method.stream)
+      throw new MethodError("VALIDATION", `${name} is not a stream.`);
     const raw = input ?? {};
     const parsed = method.input.parse(raw);
     const root = options.root ?? this.callRoot.getStore() ?? this.root;
@@ -1872,7 +1877,7 @@ class Runtime {
     const statuses = [];
     for (const entry of entries) {
       const timezone = entry.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
-      const signature = `${entry.plugin}.${entry.method} ${entry.schedule} ${timezone}`;
+      const signature = `${entry.plugin}.${entry.method} ${entry.schedule} ${timezone} ${entry.root ?? ""}`;
       try {
         const job = kept.get(signature) ?? this.cronJob(entry, timezone, signature);
         jobs.push(job);
@@ -1904,8 +1909,8 @@ class Runtime {
     const method = this.methods.get(name);
     if (!method || method.plugin !== entry.plugin)
       throw new Error(`${entry.method} isn't one of ${entry.plugin}'s methods`);
-    if (method.kind === "stream")
-      throw new Error(`${name} is a stream; a cron runs a query or a mutation`);
+    if (method.stream)
+      throw new Error(`${name} is a stream; a cron runs a read or a write`);
     if (method.confirm)
       throw new Error(`${name} asks before it runs, so nothing may run it on a schedule`);
     if (!method.input.safeParse({}).success)
@@ -1922,6 +1927,7 @@ class Runtime {
     return {
       signature,
       plugin: entry.plugin,
+      root: entry.root,
       method: name,
       schedule: entry.schedule,
       timezone,
@@ -1946,7 +1952,7 @@ class Runtime {
       job.running = true;
       job.lastRunAt = now;
       const startedAt = Date.now();
-      started.push(this.call(job.method, {}, { caller: "cron" }).then(() => {
+      started.push(this.call(job.method, {}, { caller: "cron", root: job.root }).then(() => {
         job.lastError = null;
       }, (error) => {
         job.lastError = toCallError(error).message;
@@ -2007,7 +2013,8 @@ class Runtime {
       description: plugin.description ?? null,
       methods: [...this.methods.values()].filter((method) => method.plugin === name).map((method) => ({
         name: method.name,
-        kind: method.kind,
+        effect: method.effect,
+        stream: method.stream ?? false,
         description: method.description ?? null,
         confirm: method.confirm ?? null,
         http: method.http ?? null,
@@ -2083,6 +2090,9 @@ class Runtime {
   register(method) {
     if (this.methods.has(method.name))
       throw new Error(`${method.name} is defined twice; rename the method or the data`);
+    if (method.effect === "destructive" && !method.confirm) {
+      throw new Error(`${method.name} is destructive, so it needs a confirm question, such as { confirm: "Delete {{id}}?" }`);
+    }
     this.methods.set(method.name, method);
   }
   registerGenerated(plugin, name, methods) {
@@ -2099,26 +2109,26 @@ class Runtime {
     const prefix = `${plugin}.${name}`;
     const id = z5.object({ id: z5.string() });
     const record2 = schema.extend({ id: z5.string(), createdAt: z5.string(), updatedAt: z5.string() });
-    const crud = (method, kind, input, output, description, run, confirm) => this.register({
+    const crud = (method, effect, input, output, description, run, confirm) => this.register({
       name: `${prefix}.${method}`,
       plugin,
-      kind,
+      effect,
       description,
       confirm,
       input,
       output,
       run: async (value, raw) => run(value, raw)
     });
-    crud("list", "query", z5.object({
+    crud("list", "read", z5.object({
       limit: z5.number().int().positive().max(500).optional(),
       offset: z5.number().int().min(0).optional(),
       orderBy: z5.string().optional(),
       order: z5.enum(["asc", "desc"]).optional()
     }), z5.array(record2), `List ${name} records, newest first unless orderBy says`, (input) => collection.list(input));
-    crud("get", "query", id, record2.nullable(), `Get one ${name} record by id, or null`, (input) => collection.get(input.id));
-    crud("create", "mutation", schema, record2, `Create a ${name} record`, (input) => collection.create(input));
-    crud("update", "mutation", id.extend(schema.partial().shape), record2, `Update fields on a ${name} record`, ({ id: id2, ...fields }, raw) => collection.update(id2, Object.fromEntries(Object.entries(fields).filter(([key]) => Object.hasOwn(raw ?? {}, key)))));
-    crud("delete", "mutation", id, z5.null(), `Delete a ${name} record by id`, async (input) => {
+    crud("get", "read", id, record2.nullable(), `Get one ${name} record by id, or null`, (input) => collection.get(input.id));
+    crud("create", "write", schema, record2, `Create a ${name} record`, (input) => collection.create(input));
+    crud("update", "write", id.extend(schema.partial().shape), record2, `Update fields on a ${name} record`, ({ id: id2, ...fields }, raw) => collection.update(id2, Object.fromEntries(Object.entries(fields).filter(([key]) => Object.hasOwn(raw ?? {}, key)))));
+    crud("delete", "destructive", id, z5.null(), `Delete a ${name} record by id`, async (input) => {
       await collection.delete(input.id);
       return null;
     }, "Delete this record?");
@@ -2147,7 +2157,7 @@ function cronState(job) {
 function mcpFailure(server, tool, error) {
   switch (error.code) {
     case "NOT_READ_ONLY":
-      return new MethodError("FORBIDDEN", `${server}.${tool} changes data, so it runs from a mutation, not a query.`);
+      return new MethodError("FORBIDDEN", `${server}.${tool} changes data, so it runs from a write, not a read.`);
     case "CONFIRM":
       return new MethodError("FORBIDDEN", `${server}.${tool} may destroy data, so it runs only from a method with a confirm.`);
   }

package/dist/workflow-executor.js

@@ -47,10 +47,12 @@ function definePlugin(plugin) {
   return plugin;
 }
 function method(input, run, options = {}) {
+  if ("kind" in options)
+    throw new Error('method: kind is now effect: "read", "write" or "destructive"');
   return {
     input,
     run,
-    kind: options.kind ?? "mutation",
+    effect: options.effect ?? "write",
     output: options.output,
     description: options.description,
     confirm: options.confirm,
@@ -61,14 +63,14 @@ function cached(input, run, options) {
   return {
     input,
     run,
-    kind: "query",
+    effect: "read",
     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 };
+  return { input, run, effect: "read", stream: true, description: options.description };
 }
 // src/uploads.ts
 import { AsyncLocalStorage } from "async_hooks";
@@ -19669,6 +19671,7 @@ function carryable(value) {
 
 // src/runtime.ts
 import { AsyncLocalStorage as AsyncLocalStorage5 } from "async_hooks";
+import { existsSync } from "fs";
 import { mkdir as mkdir3, readdir as readdir3 } from "fs/promises";
 import { join as join3 } from "path";
 
@@ -19732,7 +19735,7 @@ function recordRead(tag) {
 }
 function assertWritable(tag) {
   if (current.getStore()?.readOnly) {
-    throw new MethodError("FORBIDDEN", `A query can't change data (it tried to write ${tag}).`);
+    throw new MethodError("FORBIDDEN", `A read can't change data (it tried to write ${tag}).`);
   }
 }
 function recordWrite(tag) {
@@ -20529,28 +20532,28 @@ function kvMethods(name, kv, schema) {
   const entry = exports_external.object({ key: exports_external.string(), value: schema, expiresAt: exports_external.string().nullable(), createdAt: exports_external.string(), updatedAt: exports_external.string() });
   return {
     get: {
-      kind: "query",
+      effect: "read",
       description: `Get one ${name} entry by key, or null`,
       input: exports_external.object({ key }),
       output: entry.nullable(),
       run: ({ key: key2 }) => kv.entry(key2)
     },
     list: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} entries in key order, optionally by prefix`,
       input: exports_external.object({ prefix: exports_external.string().optional(), limit }),
       output: exports_external.array(entry),
       run: (input2) => kv.list(input2)
     },
     set: {
-      kind: "mutation",
+      effect: "write",
       description: `Set a ${name} key; ttl ("5m", "1h", "7d" or ms) makes it expire`,
       input: exports_external.object({ key, value: schema, ttl }),
       output: entry,
       run: ({ key: key2, value, ttl: ttl2 }) => kv.set(key2, value, { ttl: ttl2 })
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} key`,
       input: exports_external.object({ key }),
       output: exports_external.null(),
@@ -20564,41 +20567,42 @@ function streamMethods(name, stream2, schema) {
   const line = exports_external.object({ id: exports_external.string(), key: exports_external.string(), offset: exports_external.number(), at: exports_external.string(), data: schema });
   return {
     tail: {
-      kind: "stream",
+      effect: "read",
+      stream: true,
       description: `Follow a ${name} key live: its last lines (100 unless last says), then each new one, until it ends`,
       input: exports_external.object({ key, from: exports_external.number().int().min(0).optional(), last: exports_external.number().int().positive().max(500).optional() }),
       run: ({ key: key2, from, last }, signal) => stream2.follow(key2, { from, last, signal })
     },
     read: {
-      kind: "query",
+      effect: "read",
       description: `Read a ${name} key's lines from an offset`,
       input: exports_external.object({ key, from: exports_external.number().int().min(0).optional(), limit }),
       output: exports_external.array(line),
       run: ({ key: key2, ...options }) => stream2.read(key2, options)
     },
     keys: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} keys, most recently written first`,
       input: exports_external.object({ limit }),
       output: exports_external.array(exports_external.object({ key: exports_external.string(), lines: exports_external.number(), bytes: exports_external.number(), endedAt: exports_external.string().nullable(), updatedAt: exports_external.string() })),
       run: (input2) => stream2.keys(input2)
     },
     append: {
-      kind: "mutation",
+      effect: "write",
       description: `Append a line to a ${name} key`,
       input: exports_external.object({ key, data: schema }),
       output: line,
       run: ({ key: key2, data }) => stream2.append(key2, data)
     },
     end: {
-      kind: "mutation",
+      effect: "write",
       description: `End a ${name} key: followers stop and appends fail`,
       input: exports_external.object({ key }),
       output: exports_external.null(),
       run: async ({ key: key2 }) => (await stream2.end(key2), null)
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} key and its lines`,
       input: exports_external.object({ key }),
       output: exports_external.null(),
@@ -20627,28 +20631,28 @@ function bucketMethods(name, bucket, schema) {
   const revision = exports_external.number().int().optional();
   return {
     list: {
-      kind: "query",
+      effect: "read",
       description: `List ${name} files, newest first, optionally in one folder or with one status`,
       input: exports_external.object({ folder: exports_external.string().optional(), status: status.optional(), limit }),
       output: exports_external.array(file2),
       run: (input2) => bucket.list(input2)
     },
     search: {
-      kind: "query",
+      effect: "read",
       description: `Search ${name} files by name, folder and meta`,
       input: exports_external.object({ query: exports_external.string(), limit }),
       output: exports_external.array(file2),
       run: ({ query, limit: limit2 }) => bucket.search(query, { limit: limit2 })
     },
     get: {
-      kind: "query",
+      effect: "read",
       description: `Get one ${name} file by id, or null`,
       input: exports_external.object({ id }),
       output: file2.nullable(),
       run: ({ id: id2 }) => bucket.get(id2)
     },
     put: {
-      kind: "mutation",
+      effect: "write",
       description: `Add a file to ${name}: its name, and text or an absolute path to copy`,
       input: exports_external.object({
         name: exports_external.string(),
@@ -20665,21 +20669,21 @@ function bucketMethods(name, bucket, schema) {
       }
     },
     update: {
-      kind: "mutation",
+      effect: "write",
       description: `Change fields of a ${name} file's meta; null removes one`,
       input: exports_external.object({ id, meta: exports_external.record(exports_external.string(), exports_external.unknown()), revision }),
       output: file2,
       run: ({ id: id2, meta: meta3, revision: revision2 }) => bucket.update(id2, meta3, { revision: revision2 })
     },
     move: {
-      kind: "mutation",
+      effect: "write",
       description: `Rename a ${name} file or move it to another folder`,
       input: exports_external.object({ id, name: exports_external.string().optional(), folder: exports_external.string().optional(), revision }),
       output: file2,
       run: ({ id: id2, name: name2, folder, revision: revision2 }) => bucket.move(id2, { name: name2, folder }, { revision: revision2 })
     },
     delete: {
-      kind: "mutation",
+      effect: "destructive",
       description: `Delete a ${name} file and its meta`,
       input: exports_external.object({ id }),
       output: exports_external.null(),
@@ -21115,29 +21119,29 @@ function workflowMethods(plugin, namespace, name, definition, ctx, bridge, direc
     return bridge({ operation, dir, plugin, namespace, workflow: name, root: ctx.root, caller: ctx.caller, input: input2, settings: workflowSettings(definition) });
   };
   const id = exports_external.object({ id: exports_external.string().uuid() }).strict();
-  const spec = (method2, kind, input2, description, confirm, output2) => ({
+  const spec = (method2, effect, input2, description, confirm, output2) => ({
     name: `${plugin}.${name}.${method2}`,
     plugin,
-    kind,
+    effect,
     input: input2,
     description,
     confirm,
     output: output2,
     run: async (input3, raw) => {
-      if (kind === "query")
+      if (effect === "read")
         recordRead(workflowTag(namespace));
       const request = method2 === "start" ? { ...input3, input: raw.input } : input3;
       return invoke(method2, request);
     }
   });
   return [
-    spec("list", "query", exports_external.object({ limit: exports_external.number().int().min(1).max(100).default(20), status: exports_external.string().optional(), cursor: exports_external.string().optional() }).strict(), "List workflow runs", undefined, exports_external.object({ items: exports_external.array(RunSummarySchema), cursor: exports_external.string().nullable() })),
-    spec("get", "query", id, "Get one workflow run"),
-    spec("start", "mutation", exports_external.object({ input: definition.input, key: exports_external.string().min(1).max(200).optional() }).strict(), definition.description ?? "Start a durable workflow", definition.confirm, RunSummarySchema),
-    spec("retry", "mutation", id, "Retry a safely failed query step", undefined, RunSummarySchema),
-    spec("restart", "mutation", id, "Start a run that needs attention over from the beginning, on the current code", undefined, RunSummarySchema),
-    spec("cancel", "mutation", id, "Request cancellation of a workflow", undefined, RunSummarySchema),
-    spec("cancelAll", "mutation", exports_external.object({ status: exports_external.string().optional() }).strict(), "Cancel every unfinished run, or only those in one status", undefined, exports_external.object({ cancelled: exports_external.number().int() }))
+    spec("list", "read", exports_external.object({ limit: exports_external.number().int().min(1).max(100).default(20), status: exports_external.string().optional(), cursor: exports_external.string().optional() }).strict(), "List workflow runs", undefined, exports_external.object({ items: exports_external.array(RunSummarySchema), cursor: exports_external.string().nullable() })),
+    spec("get", "read", id, "Get one workflow run"),
+    spec("start", "write", exports_external.object({ input: definition.input, key: exports_external.string().min(1).max(200).optional() }).strict(), definition.description ?? "Start a durable workflow", definition.confirm, RunSummarySchema),
+    spec("retry", "write", id, "Retry a safely failed query step", undefined, RunSummarySchema),
+    spec("restart", "write", id, "Start a run that needs attention over from the beginning, on the current code", undefined, RunSummarySchema),
+    spec("cancel", "write", id, "Request cancellation of a workflow", undefined, RunSummarySchema),
+    spec("cancelAll", "write", exports_external.object({ status: exports_external.string().optional() }).strict(), "Cancel every unfinished run, or only those in one status", undefined, exports_external.object({ cancelled: exports_external.number().int() }))
   ];
 }
 function workflowSettings(definition) {
@@ -21197,6 +21201,8 @@ class Runtime {
         continue;
       if (only && !only.includes(entry.name))
         continue;
+      if (!existsSync(join3(pluginsDir, entry.name, "app.ts")))
+        continue;
       const module = await logContext.run({ plugin: entry.name }, () => import(join3(pluginsDir, entry.name, "app.ts")));
       await this.add(entry.name, module.default);
     }
@@ -21322,7 +21328,8 @@ class Runtime {
       this.register({
         name: fullName,
         plugin: name,
-        kind: method2.kind,
+        effect: method2.effect,
+        stream: method2.stream,
         description: method2.description,
         confirm: method2.confirm,
         http: method2.http,
@@ -21378,17 +21385,17 @@ class Runtime {
       return runWith(where, () => this.call(name, input2, options));
     if (where !== logContext.getStore())
       return logContext.run(where, () => this.call(name, input2, options));
-    if ((options.expect === "query" || currentAccess()?.readOnly) && method2.kind === "mutation") {
+    if ((options.expect === "read" || currentAccess()?.readOnly) && method2.effect !== "read") {
       throw new MethodError("FORBIDDEN", `${name} changes data, so it only runs when the user acts.`);
     }
     const raw = input2 ?? {};
     const parsed = method2.input.parse(raw);
     if (method2.confirm && (options.confirmed === false || workflowScope.getStore()))
       throw new MethodError("CONFIRM", fillConfirm(method2.confirm, parsed));
-    if (method2.kind === "stream")
+    if (method2.stream)
       return { result: await this.sample(name, input2), reads: [], invalidates: [] };
     const confirmed = this.callConfirmed.getStore() ?? false;
-    const run = await tracked(method2.kind === "query", (tags) => this.notifyInvalidated(tags), () => this.callConfirmed.run(confirmed || method2.confirm !== undefined, async () => {
+    const run = await tracked(method2.effect === "read", (tags) => this.notifyInvalidated(tags), () => this.callConfirmed.run(confirmed || method2.confirm !== undefined, async () => {
       const result = await method2.run(parsed, raw);
       await this.events.emit(name, { input: parsed, result });
       return result;
@@ -21407,8 +21414,8 @@ class Runtime {
     const method2 = this.methods.get(name);
     if (!method2)
       throw new MethodError("NOT_FOUND", `There is no method ${name}.`);
-    if (method2.kind !== "stream")
-      throw new MethodError("VALIDATION", `${name} is a ${method2.kind}, not a stream.`);
+    if (!method2.stream)
+      throw new MethodError("VALIDATION", `${name} is not a stream.`);
     const raw = input2 ?? {};
     const parsed = method2.input.parse(raw);
     const root = options.root ?? this.callRoot.getStore() ?? this.root;
@@ -21463,7 +21470,7 @@ class Runtime {
     const statuses = [];
     for (const entry of entries) {
       const timezone = entry.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
-      const signature = `${entry.plugin}.${entry.method} ${entry.schedule} ${timezone}`;
+      const signature = `${entry.plugin}.${entry.method} ${entry.schedule} ${timezone} ${entry.root ?? ""}`;
       try {
         const job = kept.get(signature) ?? this.cronJob(entry, timezone, signature);
         jobs.push(job);
@@ -21495,8 +21502,8 @@ class Runtime {
     const method2 = this.methods.get(name);
     if (!method2 || method2.plugin !== entry.plugin)
       throw new Error(`${entry.method} isn't one of ${entry.plugin}'s methods`);
-    if (method2.kind === "stream")
-      throw new Error(`${name} is a stream; a cron runs a query or a mutation`);
+    if (method2.stream)
+      throw new Error(`${name} is a stream; a cron runs a read or a write`);
     if (method2.confirm)
       throw new Error(`${name} asks before it runs, so nothing may run it on a schedule`);
     if (!method2.input.safeParse({}).success)
@@ -21513,6 +21520,7 @@ class Runtime {
     return {
       signature,
       plugin: entry.plugin,
+      root: entry.root,
       method: name,
       schedule: entry.schedule,
       timezone,
@@ -21537,7 +21545,7 @@ class Runtime {
       job.running = true;
       job.lastRunAt = now;
       const startedAt = Date.now();
-      started.push(this.call(job.method, {}, { caller: "cron" }).then(() => {
+      started.push(this.call(job.method, {}, { caller: "cron", root: job.root }).then(() => {
         job.lastError = null;
       }, (error62) => {
         job.lastError = toCallError(error62).message;
@@ -21598,7 +21606,8 @@ class Runtime {
       description: plugin.description ?? null,
       methods: [...this.methods.values()].filter((method2) => method2.plugin === name).map((method2) => ({
         name: method2.name,
-        kind: method2.kind,
+        effect: method2.effect,
+        stream: method2.stream ?? false,
         description: method2.description ?? null,
         confirm: method2.confirm ?? null,
         http: method2.http ?? null,
@@ -21674,6 +21683,9 @@ class Runtime {
   register(method2) {
     if (this.methods.has(method2.name))
       throw new Error(`${method2.name} is defined twice; rename the method or the data`);
+    if (method2.effect === "destructive" && !method2.confirm) {
+      throw new Error(`${method2.name} is destructive, so it needs a confirm question, such as { confirm: "Delete {{id}}?" }`);
+    }
     this.methods.set(method2.name, method2);
   }
   registerGenerated(plugin, name, methods) {
@@ -21690,26 +21702,26 @@ class Runtime {
     const prefix = `${plugin}.${name}`;
     const id = exports_external.object({ id: exports_external.string() });
     const record3 = schema.extend({ id: exports_external.string(), createdAt: exports_external.string(), updatedAt: exports_external.string() });
-    const crud = (method2, kind, input2, output2, description, run, confirm) => this.register({
+    const crud = (method2, effect, input2, output2, description, run, confirm) => this.register({
       name: `${prefix}.${method2}`,
       plugin,
-      kind,
+      effect,
       description,
       confirm,
       input: input2,
       output: output2,
       run: async (value, raw) => run(value, raw)
     });
-    crud("list", "query", exports_external.object({
+    crud("list", "read", exports_external.object({
       limit: exports_external.number().int().positive().max(500).optional(),
       offset: exports_external.number().int().min(0).optional(),
       orderBy: exports_external.string().optional(),
       order: exports_external.enum(["asc", "desc"]).optional()
     }), exports_external.array(record3), `List ${name} records, newest first unless orderBy says`, (input2) => collection.list(input2));
-    crud("get", "query", id, record3.nullable(), `Get one ${name} record by id, or null`, (input2) => collection.get(input2.id));
-    crud("create", "mutation", schema, record3, `Create a ${name} record`, (input2) => collection.create(input2));
-    crud("update", "mutation", id.extend(schema.partial().shape), record3, `Update fields on a ${name} record`, ({ id: id2, ...fields }, raw) => collection.update(id2, Object.fromEntries(Object.entries(fields).filter(([key]) => Object.hasOwn(raw ?? {}, key)))));
-    crud("delete", "mutation", id, exports_external.null(), `Delete a ${name} record by id`, async (input2) => {
+    crud("get", "read", id, record3.nullable(), `Get one ${name} record by id, or null`, (input2) => collection.get(input2.id));
+    crud("create", "write", schema, record3, `Create a ${name} record`, (input2) => collection.create(input2));
+    crud("update", "write", id.extend(schema.partial().shape), record3, `Update fields on a ${name} record`, ({ id: id2, ...fields }, raw) => collection.update(id2, Object.fromEntries(Object.entries(fields).filter(([key]) => Object.hasOwn(raw ?? {}, key)))));
+    crud("delete", "destructive", id, exports_external.null(), `Delete a ${name} record by id`, async (input2) => {
       await collection.delete(input2.id);
       return null;
     }, "Delete this record?");
@@ -21738,7 +21750,7 @@ function cronState(job) {
 function mcpFailure(server, tool, error62) {
   switch (error62.code) {
     case "NOT_READ_ONLY":
-      return new MethodError("FORBIDDEN", `${server}.${tool} changes data, so it runs from a mutation, not a query.`);
+      return new MethodError("FORBIDDEN", `${server}.${tool} changes data, so it runs from a write, not a read.`);
     case "CONFIRM":
       return new MethodError("FORBIDDEN", `${server}.${tool} may destroy data, so it runs only from a method with a confirm.`);
   }

package/package.json

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