@repogo/plugins 0.0.0-stage → 0.1.25

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 RepoGo
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @repogo/plugins
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write plugins for a [RepoGo](https://repogo.app) project: small apps on your
+environment with their own SQLite data, that agents call as tools and cards
+draw live on your phone.
+
+```ts
+// .repogo/plugins/notes/app.ts
+import { definePlugin, method, z } from "@repogo/plugins";
+
+export default definePlugin({
+  description: "Notes for this project",
+  collections: { notes: z.object({ text: z.string() }) },
+  methods: {
+    search: method(z.object({ text: z.string() }), async ({ text }, ctx) =>
+      (await ctx.db.notes.list()).filter((note) => note.text.includes(text)), { kind: "query" }),
+    clear: method(z.object({}), async (_, ctx) => {
+      for (const note of await ctx.db.notes.list()) await ctx.db.notes.delete(note.id);
+    }, { confirm: "Delete every note?" }),
+  },
+});
+```
+
+Add it to `.repogo/plugins/package.json` (`bun add @repogo/plugins`) for types
+and editor help. The RepoGo host runs plugins with its own copy of this
+package, the version it shipped with, so a plugin always matches the host.
+Plugins run on [Bun](https://bun.sh); install it on the environment.

package/dist/collections.d.ts

@@ -0,0 +1,35 @@
+import type { SQL } from "bun";
+import type { z } from "zod";
+import type { EventBus } from "./events";
+export type Record_<T> = T & {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ListOptions = {
+    where?: Record<string, string | number | boolean | null>;
+    orderBy?: "createdAt" | "updatedAt";
+    order?: "asc" | "desc";
+    limit?: number;
+};
+export declare class Collection<S extends z.ZodObject> {
+    private sql;
+    private events;
+    private plugin;
+    private name;
+    private schema;
+    private table;
+    readonly tag: string;
+    /** Writes run one at a time, so an update's read and write can't interleave with another's. */
+    private writes;
+    constructor(sql: SQL, events: EventBus, plugin: string, name: string, schema: S);
+    setup(): Promise<void>;
+    private serial;
+    create(input: z.input<S>): Promise<Record_<z.infer<S>>>;
+    get(id: string): Promise<Record_<z.infer<S>> | null>;
+    update(id: string, patch: Partial<z.input<S>>): Promise<Record_<z.infer<S>>>;
+    delete(id: string): Promise<void>;
+    list(options?: ListOptions): Promise<Record_<z.infer<S>>[]>;
+    private eventName;
+    private toRecord;
+}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { Collection } from "./collections";
+export type Context = {
+    plugin: string;
+    /** The project's checkout, for a plugin that reads the project's files. */
+    root: string;
+    db: Record<string, Collection<any>>;
+    call: (method: string, input?: unknown) => Promise<unknown>;
+    emit: (name: string, payload: unknown) => Promise<void>;
+    log: (...args: unknown[]) => void;
+};

package/dist/define.d.ts

@@ -0,0 +1,37 @@
+import type { z } from "zod";
+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.
+ */
+export type MethodKind = "query" | "mutation";
+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;
+    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.
+     */
+    confirm?: string;
+    run: (input: z.infer<I>, ctx: Context) => unknown | Promise<unknown>;
+};
+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;
+    collections?: Collections;
+    methods?: Record<string, Method<any, any>>;
+    on?: Record<string, Handler>;
+};
+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;
+    output?: O;
+    description?: string;
+    confirm?: string;
+}): Method<I, O>;

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/** CONFIRM: the method asks first; its message is the question to put to the user. */
+export type ErrorCode = "VALIDATION" | "NOT_FOUND" | "FORBIDDEN" | "CONFIRM" | "INTERNAL";
+/** What a failed call returns: a code, a sentence, and per-field messages keyed by JSON pointer ("/minutes"). */
+export type CallError = {
+    code: ErrorCode;
+    message: string;
+    fieldErrors?: Record<string, string>;
+};
+export declare class MethodError extends Error {
+    readonly code: ErrorCode;
+    readonly fieldErrors?: Record<string, string> | undefined;
+    constructor(code: ErrorCode, message: string, fieldErrors?: Record<string, string> | undefined);
+}
+export declare function toCallError(error: unknown): CallError;

package/dist/events.d.ts

@@ -0,0 +1,13 @@
+export type Event = {
+    name: string;
+    payload: unknown;
+    at: string;
+};
+export type Listener = (event: Event) => unknown | Promise<unknown>;
+export declare class EventBus {
+    private listeners;
+    private all;
+    on(name: string, listener: Listener): void;
+    onAny(listener: Listener): void;
+    emit(name: string, payload: unknown): Promise<void>;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,49 @@
+// @bun
+// src/define.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+function method(input, run, options = {}) {
+  return {
+    input,
+    run,
+    kind: options.kind ?? "mutation",
+    output: options.output,
+    description: options.description,
+    confirm: options.confirm
+  };
+}
+// src/errors.ts
+import { z } from "zod";
+
+class MethodError extends Error {
+  code;
+  fieldErrors;
+  constructor(code, message, fieldErrors) {
+    super(message);
+    this.code = code;
+    this.fieldErrors = fieldErrors;
+  }
+}
+function toCallError(error) {
+  if (error instanceof MethodError) {
+    return { code: error.code, message: error.message, ...error.fieldErrors ? { fieldErrors: error.fieldErrors } : {} };
+  }
+  if (error instanceof z.ZodError) {
+    const fieldErrors = {};
+    for (const issue of error.issues)
+      fieldErrors["/" + issue.path.join("/")] ??= issue.message;
+    return { code: "VALIDATION", message: "Check the highlighted fields.", fieldErrors };
+  }
+  return { code: "INTERNAL", message: error instanceof Error ? error.message : String(error) };
+}
+
+// src/index.ts
+import { z as z2 } from "zod";
+export {
+  z2 as z,
+  toCallError,
+  method,
+  definePlugin,
+  MethodError
+};

package/dist/tracking.d.ts

@@ -0,0 +1,35 @@
+export type Access = {
+    reads: Set<string>;
+    writes: Set<string>;
+    /** Inside a query: nothing may write. */
+    readOnly: boolean;
+    /** The call returned; later writes (detached work) are announced on their own. */
+    done: {
+        value: boolean;
+    };
+    /** The runtime this call belongs to, which announces its late writes. */
+    announce: (tags: string[]) => void;
+};
+export declare function currentAccess(): Access | undefined;
+export type Tracked<T> = {
+    ok: true;
+    value: T;
+    access: Access;
+    outermost: boolean;
+} | {
+    ok: false;
+    error: unknown;
+    access: Access;
+    outermost: boolean;
+};
+/**
+ * Runs `work` tracking its reads and writes. A call inside another adds to the
+ * outer one's sets; a query inside a writable call gets a read-only scope over
+ * those same sets. The access comes back even when `work` throws, so writes
+ * that committed before the error are still announced.
+ */
+export declare function tracked<T>(readOnly: boolean, announce: (tags: string[]) => void, work: () => Promise<T>): Promise<Tracked<T>>;
+export declare function recordRead(tag: string): void;
+/** Called before a write runs: a query, and anything it calls, may not write. */
+export declare function assertWritable(tag: string): void;
+export declare function recordWrite(tag: string): void;

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@repogo/plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.25",
+  "description": "Write RepoGo plugins: collections and methods over SQLite that agents and cards call",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --target=bun --outdir dist --external zod && tsc -p tsconfig.build.json",
+    "build:runtime": "bun build src/run.ts src/worker.ts --target=bun --outdir ../internal/plugins/runtime",
+    "prepack": "cp ../LICENSE.md LICENSE.md && bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.0"
+  },
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://repogo.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/repogoapp/host.git",
+    "directory": "plugins-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}