create-donobu-plugin 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,120 @@
+# create-donobu-plugin
+
+`create-donobu-plugin` is the official scaffolding CLI for Donobu Studio plugins. It generates a TypeScript workspace wired to Donobu’s plugin API, pins dependencies to whatever versions your local Studio installation already uses, and ships with helper utilities so you can focus on describing new tools instead of wiring.
+
+## How Donobu loads plugins
+
+- Donobu watches a plugins directory inside its working data folder (macOS: `~/Library/Application Support/Donobu Studio/plugins`, Windows: `%APPDATA%/Donobu Studio/plugins`, Linux: `~/.config/Donobu Studio/plugins`).
+- Each plugin ships a bundled `dist/index.mjs` that exports one async function named `loadCustomTools(dependencies)`. When Donobu starts it imports every plugin bundle and calls that function to collect tools.
+- `npm exec install-donobu-plugin` builds your project and copies the resulting `dist/` folder into `<workingDir>/plugins/<plugin-name>`, so restarting Donobu is enough to pick up changes.
+
+Keep those three rules in mind and your plugin will load reliably.
+
+## Prerequisites
+
+- Node.js 18+ and npm 8+
+- A local Donobu Studio installation (desktop or backend) so the installer has somewhere to copy the plugin bundle
+- Playwright browsers installed (Donobu will prompt you if they are missing)
+- Write access to the Donobu Studio working directory
+
+## Installation
+
+```bash
+npx create-donobu-plugin my-support-tools
+```
+
+Provide the plugin name as the first argument. Names may include lowercase letters, numbers, hyphens, and underscores. The CLI prints usage information if the argument is missing or invalid.
+
+## Quick start
+
+1. Scaffold a plugin: `npx create-donobu-plugin my-support-tools`
+2. `cd my-support-tools && npm install`
+3. Implement your tools in `src/index.ts`
+4. `npm run build`
+5. `npm exec install-donobu-plugin`
+6. Restart Donobu Studio and verify the tools appear in the UI/logs
+
+## Generated project layout
+
+| Item                        | Description                                                                                                                                                    |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `package.json`              | Private ESM package whose `main`/`types` fields point to `dist/`. Dev dependencies are aligned with the local Donobu install so you don’t chase version drift. |
+| `tsconfig.json`             | NodeNext compiler settings that emit JS + declarations into `dist/`.                                                                                           |
+| `esbuild.config.mjs`        | Bundles the compiled JS into `dist/index.mjs`, keeping Donobu and Playwright as external dependencies.                                                         |
+| `src/index.ts`              | Entry point that must export `loadCustomTools(dependencies)` and return an array of tools.                                                                     |
+| `src/createTool.ts`         | Helper around `dependencies.donobu.Tool` that reduces boilerplate when defining tools.                                                                         |
+| `src/PluginDependencies.ts` | Strongly typed view of the objects Donobu injects into your plugin (`donobu` and `playwright`).                                                                |
+| `README.md`                 | Template instructions for the team that owns the generated plugin.                                                                                             |
+
+Because the scaffold reuses the Donobu versions already on disk, regenerating the project after a Donobu upgrade is the fastest way to stay in lockstep.
+
+## Authoring tools
+
+Every plugin exports `loadCustomTools(dependencies)` and returns an array of `Tool` instances. You can instantiate `dependencies.donobu.Tool` directly or use the provided helper:
+
+```ts
+// src/index.ts
+import { z } from 'zod/v4';
+import { createTool } from './createTool.js';
+import type { PluginDependencies } from './PluginDependencies.js';
+
+export async function loadCustomTools(deps: PluginDependencies) {
+  const pingSchema = z.object({
+    url: z.string().url(),
+  });
+
+  const pingTool = createTool(deps, {
+    name: 'pingEndpoint',
+    description: 'Fetches a URL within the Donobu-controlled browser context.',
+    requiresGpt: false,
+    schema: pingSchema,
+    async call(ctx, { url }) {
+      const page = await ctx.browserContext.newPage();
+      const response = await page.goto(url);
+      return {
+        isSuccessful: !!response,
+        forLlm: `Fetched ${url} with status ${response?.status()}`,
+        metadata: { status: response?.status() },
+      };
+    },
+  });
+
+  return [pingTool];
+}
+```
+
+Guidelines:
+
+- Define Zod schemas for every tool so inputs from humans or the LLM are validated before your code runs.
+- Use `callFromGpt` if the GPT path needs different behavior; otherwise the helper routes GPT calls through `call`.
+- Request `requiresGpt: true` only when the tool cannot run without LLM assistance.
+
+## Working with injected dependencies
+
+- `dependencies.donobu` exposes the public SDK: the base `Tool` class, `PlaywrightUtils`, logging helpers, type definitions, etc.
+- `dependencies.playwright` points to the same Playwright build Donobu uses, so your plugin and the core runtime stay aligned.
+- Feel free to add your own dependencies; `esbuild` bundles everything except the packages listed in `external`.
+
+## Build and install
+
+```bash
+npm run build
+npm exec install-donobu-plugin
+```
+
+`npm run build` cleans `dist/`, reinstalls dependencies (to ensure version parity), runs TypeScript, and bundles the result. `npm exec install-donobu-plugin` validates the current folder, infers the plugin name (prefers `package.json`, falls back to the git repo name or `$USER`), and copies `dist/` into the Donobu plugins directory. Restart Donobu after every install so the new bundle is loaded.
+
+## Recommended development loop
+
+1. Make changes in `src/`
+2. `npm run build && npm exec install-donobu-plugin`
+3. Restart Donobu Studio or the backend process
+4. Trigger your tool from the UI or API to verify behavior
+
+Because the default build script runs `npm install`, consider splitting the script into `build` and `bundle` variants if you need faster inner-loop iterations.
+
+## Troubleshooting
+
+- **Plugin not appearing:** Ensure `npm exec install-donobu-plugin` ran successfully and that `dist/index.mjs` exists. Restart Donobu and watch the logs for plugin loading messages.
+- **Schema errors:** Zod throws runtime errors when inputs don’t match your schema. Log the error message to quickly see which field failed.
+- **Version mismatch:** If Donobu upgrades Playwright or its SDK, re-run the scaffold (or update the plugin’s dev dependencies) so you stay compatible.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-donobu-plugin",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "description": "Create a new Donobu plugin",
     "author": "Donobu",
@@ -13,7 +13,7 @@
         "index.js"
     ],
     "dependencies": {
-        "donobu": "^2.30.1"
+        "donobu": "^3.3.0"
     },
     "keywords": [
         "donobu",