create-donobu-plugin 1.1.0 → 1.2.1

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/index.js

@@ -1,26 +1,26 @@
 #!/usr/bin/env node
 
-import { mkdir, writeFile, readFile } from "fs/promises";
-import { join, dirname } from "path";
-import { createRequire } from "module";
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { createRequire } from 'module';
 
 async function getDonobuVersions() {
   try {
     // Find the donobu package.json by resolving the module path
     const require = createRequire(import.meta.url);
-    const donobuPath = require.resolve("donobu");
+    const donobuPath = require.resolve('donobu');
     // Navigate up to find package.json (donobu path might point to dist/main.js)
     const donobuDir = dirname(donobuPath);
-    let packageJsonPath = join(donobuDir, "package.json");
+    let packageJsonPath = join(donobuDir, 'package.json');
 
     try {
-      await readFile(packageJsonPath, "utf8");
+      await readFile(packageJsonPath, 'utf8');
     } catch {
       // If not found, try going up one more directory
-      packageJsonPath = join(dirname(donobuDir), "package.json");
+      packageJsonPath = join(dirname(donobuDir), 'package.json');
     }
 
-    const packageJsonContent = await readFile(packageJsonPath, "utf8");
+    const packageJsonContent = await readFile(packageJsonPath, 'utf8');
     const donobuPackageJson = JSON.parse(packageJsonContent);
 
     return {
@@ -28,19 +28,19 @@ async function getDonobuVersions() {
       playwrightVersion:
         donobuPackageJson.devDependencies?.playwright ||
         donobuPackageJson.dependencies?.playwright ||
-        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, "") ||
-        "1.53.2",
+        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, '') ||
+        '1.53.2',
       playwrightTestVersion:
-        donobuPackageJson.devDependencies?.["@playwright/test"] ||
-        donobuPackageJson.dependencies?.["@playwright/test"] ||
-        donobuPackageJson.peerDependencies?.["@playwright/test"]?.replace(
+        donobuPackageJson.devDependencies?.['@playwright/test'] ||
+        donobuPackageJson.dependencies?.['@playwright/test'] ||
+        donobuPackageJson.peerDependencies?.['@playwright/test']?.replace(
           /^>=/,
-          ""
+          ''
         ) ||
-        "1.53.2",
+        '1.53.2',
     };
   } catch (error) {
-    console.error("Could not read the Donobu package.json file!");
+    console.error('Could not read the Donobu package.json file!');
     throw error;
   }
 }
@@ -54,8 +54,8 @@ async function createPluginStructure(pluginName) {
   console.log(`Using Playwright version: ${versions.playwrightVersion}`);
   // Create directory structure
   await mkdir(pluginDir, { recursive: true });
-  await mkdir(join(pluginDir, "src"), { recursive: true });
-  console.log("Creating files...");
+  await mkdir(join(pluginDir, 'src'), { recursive: true });
+  console.log('Creating files...');
   await createTemplateFiles(pluginDir, pluginName, versions);
   console.log(`\nPlugin "${pluginName}" created successfully!`);
   console.log(`\nNext steps:`);
@@ -69,71 +69,71 @@ async function createTemplateFiles(pluginDir, pluginName, versions) {
   // Create package.json
   const packageJson = {
     name: pluginName,
-    version: "1.0.0",
+    version: '1.0.0',
     private: true,
-    type: "module",
-    description: "Custom tools for use by Donobu.",
-    main: "./dist/index.mjs",
-    types: "./dist/index.d.ts",
+    type: 'module',
+    description: 'Custom tools for use by Donobu.',
+    main: './dist/index.mjs',
+    types: './dist/index.d.ts',
     exports: {
-      ".": "./dist/index.mjs",
+      '.': './dist/index.mjs',
     },
-    files: ["dist"],
+    files: ['dist'],
     scripts: {
-      clean: "rm -rf dist",
+      clean: 'rm -rf dist',
       build:
-        "npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs",
+        'npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs',
     },
-    license: "UNLICENSED",
+    license: 'UNLICENSED',
     devDependencies: {
       donobu: `^${versions.donobuVersion}`,
       playwright: versions.playwrightVersion,
-      "@playwright/test": versions.playwrightTestVersion,
-      typescript: "^5.8.3",
-      esbuild: "^0.25.6",
+      '@playwright/test': versions.playwrightTestVersion,
+      typescript: '^5.8.3',
+      esbuild: '^0.25.6',
     },
     peerDependencies: {
       donobu: `>=${versions.donobuVersion}`,
       playwright: `>=${versions.playwrightVersion}`,
-      "@playwright/test": `>=${versions.playwrightTestVersion}`,
+      '@playwright/test': `>=${versions.playwrightTestVersion}`,
     },
     peerDependenciesMeta: {
       playwright: {
         optional: false,
       },
-      "@playwright/test": {
+      '@playwright/test': {
         optional: false,
       },
     },
     dependencies: {
-      zod: "^3.24.1",
+      zod: '^3.25.76',
     },
   };
 
   await writeFile(
-    join(pluginDir, "package.json"),
+    join(pluginDir, 'package.json'),
     JSON.stringify(packageJson, null, 2)
   );
 
   // Create tsconfig.json
   const tsConfig = {
     compilerOptions: {
-      target: "ES2020",
-      module: "NodeNext",
-      moduleResolution: "NodeNext",
-      rootDir: "./src",
-      outDir: "./dist",
+      target: 'ES2020',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      rootDir: './src',
+      outDir: './dist',
       declaration: true,
       strict: true,
       esModuleInterop: true,
       skipLibCheck: true,
       forceConsistentCasingInFileNames: true,
     },
-    include: ["src/**/*"],
+    include: ['src/**/*'],
   };
 
   await writeFile(
-    join(pluginDir, "tsconfig.json"),
+    join(pluginDir, 'tsconfig.json'),
     JSON.stringify(tsConfig, null, 2)
   );
 
@@ -151,7 +151,7 @@ await build({
 });
 `;
 
-  await writeFile(join(pluginDir, "esbuild.config.mjs"), esbuildConfig);
+  await writeFile(join(pluginDir, 'esbuild.config.mjs'), esbuildConfig);
 
   // Create src/index.ts
   const indexTs = `import type { Tool } from "donobu";
@@ -165,10 +165,10 @@ export async function loadCustomTools(
 }
 `;
 
-  await writeFile(join(pluginDir, "src", "index.ts"), indexTs);
+  await writeFile(join(pluginDir, 'src', 'index.ts'), indexTs);
 
   // Create src/createTool.ts
-  const createToolTs = `import { z } from "zod";
+  const createToolTs = `import { z } from "zod/v4";
 import type { ToolCallContext, ToolCallResult, Tool } from "donobu";
 import { PluginDependencies } from "./PluginDependencies.js";
 
@@ -244,7 +244,7 @@ export interface CreateToolOptions<
 }
 `;
 
-  await writeFile(join(pluginDir, "src", "createTool.ts"), createToolTs);
+  await writeFile(join(pluginDir, 'src', 'createTool.ts'), createToolTs);
 
   // Create src/PluginDependencies.ts
   const pluginDepsTs = `export interface PluginDependencies {
@@ -254,7 +254,7 @@ export interface CreateToolOptions<
 `;
 
   await writeFile(
-    join(pluginDir, "src", "PluginDependencies.ts"),
+    join(pluginDir, 'src', 'PluginDependencies.ts'),
     pluginDepsTs
   );
 
@@ -274,24 +274,24 @@ A custom Donobu plugin with tools for browser automation.
 3. Restart Donobu to see your tools
 `;
 
-  await writeFile(join(pluginDir, "README.md"), readme);
+  await writeFile(join(pluginDir, 'README.md'), readme);
 }
 
 async function main() {
   const pluginName = process.argv[2];
 
   if (!pluginName) {
-    console.error("Usage: create-donobu-plugin <plugin-name>");
-    console.error("");
-    console.error("Example:");
-    console.error("  npm create donobu-plugin my-awesome-plugin");
+    console.error('Usage: create-donobu-plugin <plugin-name>');
+    console.error('');
+    console.error('Example:');
+    console.error('  npm create donobu-plugin my-awesome-plugin');
     process.exit(1);
   }
 
   // Validate plugin name
   if (!/^[a-z0-9-_]+$/.test(pluginName)) {
     console.error(
-      "Plugin name must contain only lowercase letters, numbers, hyphens, and underscores"
+      'Plugin name must contain only lowercase letters, numbers, hyphens, and underscores'
     );
     process.exit(1);
   }
@@ -299,7 +299,7 @@ async function main() {
   try {
     await createPluginStructure(pluginName);
   } catch (error) {
-    console.error("Failed to create plugin:", error.message);
+    console.error('Failed to create plugin:', error.message);
     process.exit(1);
   }
 }

package/package.json

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