create-donobu-plugin 1.3.0 → 1.7.0

package/README.md

@@ -1,77 +1,113 @@
 # 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.
+`create-donobu-plugin` is the official scaffolding CLI for Donobu Studio plugins. It generates a TypeScript project wired to Donobu's plugin API and pins dependencies to whatever versions your local Donobu installation already uses.
 
 ## 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.
+Donobu watches a plugins directory inside its working data folder:
 
-Keep those three rules in mind and your plugin will load reliably.
+| Platform | Path                                                   |
+| -------- | ------------------------------------------------------ |
+| 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`. On startup Donobu imports every plugin and calls the exported functions it finds:
+
+- **`loadCustomTools(deps)`** — returns an array of `Tool` instances.
+- **`loadPersistencePlugin(deps)`** — returns `{ key, plugin }` to register a persistence backend, or `null` to skip.
+
+A single plugin may export both functions. Scoped package names (e.g., `@myorg/my-plugin`) are supported.
+
+`npm exec install-donobu-plugin` builds your project and copies `dist/` into the plugins directory. Restarting Donobu is enough to pick up changes.
 
 ## Prerequisites
 
-- Node.js 18+ and npm 8+
+- Node.js 20+ and a package manager (npm 8+, pnpm 10+, or yarn)
 - 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
+## Quick start
+
+### Tool plugin (default)
 
 ```bash
 npx create-donobu-plugin my-support-tools
+cd my-support-tools && npm install
+# Edit src/index.ts to add your custom tools
+npm run build
+npm exec install-donobu-plugin
+# Restart Donobu Studio
 ```
 
-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.
+### Persistence plugin
 
-## Quick start
+```bash
+npx create-donobu-plugin my-storage --type persistence
+cd my-storage && npm install
+# Edit src/index.ts to implement your persistence plugin
+npm run build
+npm exec install-donobu-plugin
+# Set PERSISTENCE_PRIORITY to include your plugin key, then restart Donobu
+```
 
-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
+Plugin names may include lowercase letters, numbers, hyphens, and underscores. The CLI prints usage information if the argument is missing or invalid.
 
 ## Generated project layout
 
-| Item                 | Description                                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------------------------ |
-| `package.json`       | Private ESM package whose `main`/`types` fields point to `dist/`.                                      |
-| `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.             |
-| `README.md`          | Template instructions for the team that owns the generated plugin.                                     |
+| Item                 | Description                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `package.json`       | Private package with `"donobu-plugin": true`. `donobu` is a peer/dev dependency, never bundled. |
+| `tsconfig.json`      | ES2021 + NodeNext compiler settings that emit declarations into `dist/`.                        |
+| `esbuild.config.mjs` | Bundles TypeScript source into `dist/index.mjs`, keeping `donobu` external.                     |
+| `src/index.ts`       | Entry point. Exports `loadCustomTools(deps)` and/or `loadPersistencePlugin(deps)`.              |
+| `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.
+## The deps pattern
 
-## Authoring tools
+Plugins receive all runtime values through the `deps` parameter — **never use value imports from `donobu`**. Only `import type` is allowed because type imports are erased at compile time, while value imports would produce an `import ... from "donobu"` statement in the bundle that Node cannot resolve from the plugins directory.
 
-Every plugin's `index.ts` exports `loadCustomTools(dependencies)` and returns an array of `Tool` instances.
+```ts
+// CORRECT — type imports are erased, runtime values come from deps
+import type { Tool, PluginDependencies } from 'donobu';
+
+export async function loadCustomTools(
+  deps: PluginDependencies,
+): Promise<Tool<any, any>[]> {
+  const logger = deps.donobu.appLogger; // runtime access via deps
+  // ...
+}
+```
+
+```ts
+// WRONG — this creates a runtime import that will fail at load time
+import { appLogger } from 'donobu';
+```
+
+### What is available on `deps`
+
+- **`deps.donobu`** — the full public SDK: `createTool`, `Tool`, `ReplayableInteraction`, `appLogger`, `MiscUtils`, `PlaywrightUtils`, schemas, exception classes, etc.
+
+Feel free to add your own npm dependencies; esbuild bundles everything except the packages listed in `external`.
+
+## Authoring tool plugins
+
+Every tool plugin exports `loadCustomTools(deps)` and returns an array of `Tool` instances. The simplest way to create a tool is `deps.donobu.createTool()`:
 
 ```ts
-// Note that non-type imports from 'donobu' should be extracted from the given
-// 'deps.donobu' parameter in 'loadCustomTools'.
 import type { Tool, PluginDependencies } from 'donobu';
 import { z } from 'zod/v4';
 
 export async function loadCustomTools(
-  deps: PluginDependencies
+  deps: PluginDependencies,
 ): Promise<Tool<any, any>[]> {
-  // Register your custom tools here.
   return [
-    // Here is a small example tool for reference.
     deps.donobu.createTool(deps, {
-      // The tool name, description, and schema are shared with the Donobu agent
-      // to help it decide when, where, and how this tool will be called.
       name: 'judgeWebpageTitle',
       description: 'Judge the quality of a title to a webpage.',
       schema: z.object({ webpageTitle: z.string() }),
-      // This example tool uses a GPT/LLM so we call it out here.
       requiresGpt: true,
       call: async (context, parameters) => {
-        // 'requiredGpt' is true, so we are guaranteed a valid gptClient handle.
         const resp = await context.gptClient!.getMessage([
           {
             type: 'user',
@@ -85,12 +121,8 @@ export async function loadCustomTools(
           },
         ]);
         return {
-          // Returning false or throwing an exception will signal tool call failure.
           isSuccessful: true,
-          // This is what is shared back with the Donobu agent.
           forLlm: resp.text,
-          // Metadata is persisted with the tool call result, but is not shared
-          // with the Donobu agent, so this can be used to store large complex data.
           metadata: null,
         };
       },
@@ -99,11 +131,61 @@ export async function loadCustomTools(
 }
 ```
 
-## Working with injected dependencies
+For tools that need to extend `ReplayableInteraction` or another base class, use a factory function so the base class comes from `deps.donobu` rather than a value import:
+
+```ts
+import type { Tool, PluginDependencies } from 'donobu';
+
+function createMyTool(deps: PluginDependencies): Tool<any, any> {
+  const { ReplayableInteraction } = deps.donobu;
+
+  class MyTool extends ReplayableInteraction</* ... */> {
+    // ...
+  }
+
+  return new MyTool();
+}
+
+export async function loadCustomTools(deps: PluginDependencies) {
+  return [createMyTool(deps)];
+}
+```
+
+## Authoring persistence plugins
+
+Persistence plugins export `loadPersistencePlugin(deps)`. The returned `key` must appear in the `PERSISTENCE_PRIORITY` environment variable for Donobu to use it.
 
-- `deps.donobu` exposes the public SDK: the base `Tool` class, `PlaywrightUtils`, logging helpers, type definitions, etc.
-- `deps.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`.
+```ts
+import type {
+  EnvPersistence,
+  FlowsPersistence,
+  PersistencePlugin,
+  PluginDependencies,
+} from 'donobu';
+
+export async function loadPersistencePlugin(
+  deps: PluginDependencies,
+): Promise<{ key: string; plugin: PersistencePlugin } | null> {
+  const bucket = process.env.MY_STORAGE_BUCKET;
+  if (!bucket) return null; // skip registration if config is missing
+
+  return {
+    key: 'MY_CUSTOM',
+    plugin: {
+      async createFlowsPersistence(): Promise<FlowsPersistence | null> {
+        // Return your FlowsPersistence implementation, or null.
+        return null;
+      },
+      async createEnvPersistence(): Promise<EnvPersistence | null> {
+        // Return your EnvPersistence implementation, or null.
+        return null;
+      },
+    },
+  };
+}
+```
+
+If your persistence classes need SDK utilities like `appLogger` or `FlowNotFoundException`, accept `deps.donobu` as a constructor parameter rather than importing them directly.
 
 ## Build and install
 
@@ -112,7 +194,24 @@ 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 installing so the new bundle is loaded.
+`npm run build` cleans `dist/`, runs TypeScript (for declarations), and bundles the source with esbuild. `npm exec install-donobu-plugin` infers the plugin name from `package.json` and copies `dist/` into the Donobu plugins directory. Restart Donobu after installing so the new bundle is loaded.
+
+## esbuild considerations
+
+The generated `esbuild.config.mjs` bundles your TypeScript source and all third-party dependencies into a single `dist/index.mjs`, while keeping `donobu` external (it is injected at runtime by the plugin loader). The `mainFields: ['module', 'main']` option ensures esbuild prefers ESM entry points from third-party packages for cleaner output.
+
+If you add dependencies that include CJS modules using `require()` for Node builtins (common in Google Cloud, AWS, or gRPC libraries), the bundle may fail at runtime with `"Dynamic require of X is not supported"`. Fix this by adding a `banner` that provides a real `require()`:
+
+```js
+await build({
+  // ... your existing options ...
+  banner: {
+    js: 'import { createRequire } from "module"; const require = createRequire(import.meta.url);',
+  },
+});
+```
+
+This injects a real `require()` via Node's `createRequire`, allowing bundled CJS code to resolve Node builtins normally in the ESM context.
 
 ## Recommended development loop
 
@@ -121,10 +220,9 @@ 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.
+- **"Cannot find package 'donobu'":** Your bundle contains a runtime `import ... from "donobu"`. Ensure all `donobu` imports use `import type` and access runtime values through `deps.donobu`.
+- **"Dynamic require of X is not supported":** A bundled CJS dependency calls `require()` for a Node builtin. Add the `createRequire` banner to your esbuild config (see above).
+- **Schema errors:** Zod throws runtime errors when inputs don't match your schema. Log the error message to quickly see which field failed.

package/index.js

@@ -1,152 +1,131 @@
 #!/usr/bin/env node
 
-import { mkdir, writeFile, readFile } from 'fs/promises';
-import { join, dirname } from 'path';
-import { createRequire } from 'module';
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
 
-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');
-    // Navigate up to find package.json (donobu path might point to dist/main.js)
-    const donobuDir = dirname(donobuPath);
-    let packageJsonPath = join(donobuDir, 'package.json');
-
-    try {
-      await readFile(packageJsonPath, 'utf8');
-    } catch {
-      // If not found, try going up one more directory
-      packageJsonPath = join(dirname(donobuDir), 'package.json');
-    }
+const DONOBU_VERSION = '5.17.2';
+const VALID_PLUGIN_TYPES = ['tool', 'persistence'];
 
-    const packageJsonContent = await readFile(packageJsonPath, 'utf8');
-    const donobuPackageJson = JSON.parse(packageJsonContent);
-
-    return {
-      donobuVersion: donobuPackageJson.version,
-      playwrightVersion:
-        donobuPackageJson.devDependencies?.playwright ||
-        donobuPackageJson.dependencies?.playwright ||
-        donobuPackageJson.peerDependencies?.playwright?.replace(/^>=/, '') ||
-        '1.53.2',
-      playwrightTestVersion:
-        donobuPackageJson.devDependencies?.['@playwright/test'] ||
-        donobuPackageJson.dependencies?.['@playwright/test'] ||
-        donobuPackageJson.peerDependencies?.['@playwright/test']?.replace(
-          /^>=/,
-          ''
-        ) ||
-        '1.53.2',
-    };
-  } catch (error) {
-    console.error('Could not read the Donobu package.json file!');
-    throw error;
-  }
-}
-
-async function createPluginStructure(pluginName) {
+async function createPluginStructure(pluginName, pluginType) {
   const pluginDir = join(process.cwd(), pluginName);
-  console.log(`Creating plugin directory: ${pluginDir}`);
-  // Get current donobu and playwright versions
-  const versions = await getDonobuVersions();
-  console.log(`Using Donobu version: ${versions.donobuVersion}`);
-  console.log(`Using Playwright version: ${versions.playwrightVersion}`);
+  console.log(`Creating ${pluginType} plugin directory: ${pluginDir}`);
+  const donobuVersion = DONOBU_VERSION;
+  console.log(`Using Donobu version: ${donobuVersion}`);
   // Create directory structure
   await mkdir(pluginDir, { recursive: true });
   await mkdir(join(pluginDir, 'src'), { recursive: true });
   console.log('Creating files...');
-  await createTemplateFiles(pluginDir, pluginName, versions);
+
+  if (pluginType === 'persistence') {
+    await createPersistenceTemplateFiles(pluginDir, pluginName, donobuVersion);
+  } else {
+    await createToolTemplateFiles(pluginDir, pluginName, donobuVersion);
+  }
+
   console.log(`\nPlugin "${pluginName}" created successfully!`);
   console.log(`\nNext steps:`);
   console.log(`  cd ${pluginName}`);
   console.log(`  npm install`);
-  console.log(`  # Edit src/index.ts to add your custom tools`);
+  if (pluginType === 'persistence') {
+    console.log(`  # Edit src/index.ts to implement your persistence plugin`);
+  } else {
+    console.log(`  # Edit src/index.ts to add your custom tools`);
+  }
   console.log(`  npx install-donobu-plugin`);
 }
 
-async function createTemplateFiles(pluginDir, pluginName, versions) {
+// ---------------------------------------------------------------------------
+// Shared template helpers
+// ---------------------------------------------------------------------------
+
+function createTsConfig() {
+  return {
+    compilerOptions: {
+      target: 'ES2021',
+      lib: ['ES2021', 'DOM'],
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      rootDir: './src',
+      outDir: './dist',
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+      strict: true,
+      skipLibCheck: true,
+      allowUnusedLabels: false,
+      allowUnreachableCode: false,
+    },
+    include: ['src'],
+    exclude: ['node_modules', 'dist'],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tool plugin templates
+// ---------------------------------------------------------------------------
+
+async function createToolTemplateFiles(pluginDir, pluginName, donobuVersion) {
   // Create package.json
   const packageJson = {
     name: pluginName,
+    'donobu-plugin': true,
     version: '1.0.0',
     private: true,
-    type: 'module',
     description: 'Custom tools for use by Donobu.',
-    main: './dist/index.mjs',
-    types: './dist/index.d.ts',
+    main: 'dist/index.js',
+    types: 'dist/index.d.ts',
     exports: {
-      '.': './dist/index.mjs',
+      types: './dist/index.d.ts',
+      import: './dist/index.mjs',
+      require: './dist/index.js',
     },
     files: ['dist'],
     scripts: {
       clean: 'rm -rf dist',
-      build:
-        'npm run clean && npm install && tsc -p tsconfig.json && node esbuild.config.mjs',
+      build: 'npm run clean && tsc && node esbuild.config.mjs',
     },
     license: 'UNLICENSED',
-    devDependencies: {
-      donobu: `^${versions.donobuVersion}`,
-      playwright: versions.playwrightVersion,
-      '@playwright/test': versions.playwrightTestVersion,
-      typescript: '^5.8.3',
-      esbuild: '^0.25.6',
-    },
     peerDependencies: {
-      donobu: `>=${versions.donobuVersion}`,
-      playwright: `>=${versions.playwrightVersion}`,
-      '@playwright/test': `>=${versions.playwrightTestVersion}`,
+      donobu: `>=${donobuVersion}`,
     },
-    peerDependenciesMeta: {
-      playwright: {
-        optional: false,
-      },
-      '@playwright/test': {
-        optional: false,
-      },
+    devDependencies: {
+      '@types/node': '^22.19.13',
+      donobu: `^${donobuVersion}`,
+      esbuild: '^0.25.12',
+      typescript: '^5.8.3',
     },
-    dependencies: {
-      zod: '^3.25.76',
+    pnpm: {
+      onlyBuiltDependencies: ['better-sqlite3', 'esbuild'],
     },
   };
 
   await writeFile(
     join(pluginDir, 'package.json'),
-    JSON.stringify(packageJson, null, 2)
+    JSON.stringify(packageJson, null, 2),
   );
 
-  // Create tsconfig.json
-  const tsConfig = {
-    compilerOptions: {
-      target: 'ES2020',
-      module: 'NodeNext',
-      moduleResolution: 'NodeNext',
-      rootDir: './src',
-      outDir: './dist',
-      declaration: true,
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-      forceConsistentCasingInFileNames: true,
-    },
-    include: ['src/**/*'],
-  };
-
   await writeFile(
     join(pluginDir, 'tsconfig.json'),
-    JSON.stringify(tsConfig, null, 2)
+    JSON.stringify(createTsConfig(), null, 2),
   );
 
   // Create esbuild.config.mjs
   const esbuildConfig = `import { build } from 'esbuild';
 
 await build({
-  entryPoints: ['dist/index.js'],
+  entryPoints: ['src/index.ts'],
   outfile: 'dist/index.mjs',
   bundle: true,
   format: 'esm',
   platform: 'node',
-  external: ['donobu', 'playwright'],
+
+  // 'donobu' is provided at runtime by the plugin loader via deps.donobu.
+  external: ['donobu'],
+
+  mainFields: ['module', 'main'],
+
   minify: true,
 });
 `;
@@ -182,7 +161,7 @@ export async function loadCustomTools(
               {
                 type: 'text',
                 text: \`Judge the quality of this webpage title on a scale of 1 (worst) to 10 (best) and explain why.
-                       Title: ${parameters.webpageTitle}\`,
+                       Title: \${parameters.webpageTitle}\`,
               },
             ],
           },
@@ -206,7 +185,7 @@ export async function loadCustomTools(
   // Create a basic README
   const readme = `# ${pluginName}
 
-A custom Donobu plugin with tools for browser automation.
+A custom Donobu tool plugin for browser automation.
 
 ## Development
 
@@ -216,33 +195,211 @@ A custom Donobu plugin with tools for browser automation.
    npm run build
    npm exec install-donobu-plugin
    \`\`\`
-3. Restart Donobu to see your tools
+3. Restart Donobu to load your plugin
 `;
 
   await writeFile(join(pluginDir, 'README.md'), readme);
 }
 
+// ---------------------------------------------------------------------------
+// Persistence plugin templates
+// ---------------------------------------------------------------------------
+
+async function createPersistenceTemplateFiles(
+  pluginDir,
+  pluginName,
+  donobuVersion,
+) {
+  // Create package.json — no playwright dependency needed
+  const packageJson = {
+    name: pluginName,
+    'donobu-plugin': true,
+    version: '1.0.0',
+    private: true,
+    description: 'Custom persistence plugin for Donobu.',
+    main: 'dist/index.js',
+    types: 'dist/index.d.ts',
+    exports: {
+      types: './dist/index.d.ts',
+      import: './dist/index.mjs',
+      require: './dist/index.js',
+    },
+    files: ['dist'],
+    scripts: {
+      clean: 'rm -rf dist',
+      build: 'npm run clean && tsc && node esbuild.config.mjs',
+    },
+    license: 'UNLICENSED',
+    peerDependencies: {
+      donobu: `>=${donobuVersion}`,
+    },
+    devDependencies: {
+      '@types/node': '^22.19.13',
+      donobu: `^${donobuVersion}`,
+      esbuild: '^0.25.12',
+      typescript: '^5.8.3',
+    },
+    pnpm: {
+      onlyBuiltDependencies: ['better-sqlite3', 'esbuild'],
+    },
+  };
+
+  await writeFile(
+    join(pluginDir, 'package.json'),
+    JSON.stringify(packageJson, null, 2),
+  );
+
+  await writeFile(
+    join(pluginDir, 'tsconfig.json'),
+    JSON.stringify(createTsConfig(), null, 2),
+  );
+
+  // Create esbuild.config.mjs — only externalize donobu
+  const esbuildConfig = `import { build } from 'esbuild';
+
+await build({
+  entryPoints: ['src/index.ts'],
+  outfile: 'dist/index.mjs',
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+
+  // 'donobu' is provided at runtime by the plugin loader via deps.donobu.
+  external: ['donobu'],
+
+  mainFields: ['module', 'main'],
+
+  minify: true,
+});
+`;
+
+  await writeFile(join(pluginDir, 'esbuild.config.mjs'), esbuildConfig);
+
+  // Create src/index.ts
+  const indexTs = `import type {
+  EnvPersistence,
+  FlowsPersistence,
+  PersistencePlugin,
+  PluginDependencies,
+} from 'donobu';
+
+/**
+ * Called by Donobu on startup when this plugin is installed.
+ *
+ * Return an object with a \`key\` (matching an entry in the
+ * PERSISTENCE_PRIORITY environment variable) and a \`plugin\`
+ * implementing the PersistencePlugin interface.
+ *
+ * Return \`null\` to skip registration (e.g., if required
+ * environment variables are missing).
+ */
+export async function loadPersistencePlugin(
+  deps: PluginDependencies,
+): Promise<{ key: string; plugin: PersistencePlugin } | null> {
+  // Example: skip registration if required config is not set.
+  // const bucket = process.env.MY_STORAGE_BUCKET;
+  // if (!bucket) return null;
+
+  return {
+    // This key must appear in the PERSISTENCE_PRIORITY env variable
+    // for Donobu to use this plugin. For example:
+    //   PERSISTENCE_PRIORITY=MY_CUSTOM,LOCAL,RAM
+    key: 'MY_CUSTOM',
+    plugin: {
+      async createFlowsPersistence(): Promise<FlowsPersistence | null> {
+        // Return your FlowsPersistence implementation here.
+        // Return null if the required configuration is missing.
+        return null;
+      },
+      async createEnvPersistence(): Promise<EnvPersistence | null> {
+        // Return your EnvPersistence implementation here.
+        // Return null if the required configuration is missing.
+        return null;
+      },
+    },
+  };
+}`;
+
+  await writeFile(join(pluginDir, 'src', 'index.ts'), indexTs);
+
+  // Create a basic README
+  const readme = `# ${pluginName}
+
+A custom Donobu persistence plugin.
+
+## Development
+
+1. Edit \`src/index.ts\` to implement your persistence plugin
+2. Build and install the plugin:
+   \`\`\`bash
+   npm run build
+   npm exec install-donobu-plugin
+   \`\`\`
+3. Set the \`PERSISTENCE_PRIORITY\` environment variable to include your plugin key
+4. Restart Donobu to load your plugin
+`;
+
+  await writeFile(join(pluginDir, 'README.md'), readme);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let pluginName = null;
+  let pluginType = 'tool';
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--type' && i + 1 < args.length) {
+      pluginType = args[i + 1];
+      i++; // skip value
+    } else if (!args[i].startsWith('-')) {
+      pluginName = args[i];
+    }
+  }
+
+  return { pluginName, pluginType };
+}
+
 async function main() {
-  const pluginName = process.argv[2];
+  const { pluginName, pluginType } = parseArgs(process.argv);
 
   if (!pluginName) {
-    console.error('Usage: create-donobu-plugin <plugin-name>');
+    console.error(
+      'Usage: create-donobu-plugin <plugin-name> [--type <tool|persistence>]',
+    );
     console.error('');
-    console.error('Example:');
+    console.error('Options:');
+    console.error(
+      '  --type <type>  Plugin type: "tool" (default) or "persistence"',
+    );
+    console.error('');
+    console.error('Examples:');
     console.error('  npm create donobu-plugin my-awesome-plugin');
+    console.error('  npm create donobu-plugin my-storage --type persistence');
     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);
+  }
+
+  // Validate plugin type
+  if (!VALID_PLUGIN_TYPES.includes(pluginType)) {
+    console.error(
+      `Invalid plugin type "${pluginType}". Must be one of: ${VALID_PLUGIN_TYPES.join(', ')}`,
     );
     process.exit(1);
   }
 
   try {
-    await createPluginStructure(pluginName);
+    await createPluginStructure(pluginName, pluginType);
   } catch (error) {
     console.error('Failed to create plugin:', error.message);
     process.exit(1);

package/package.json

@@ -1,24 +1,33 @@
 {
-    "name": "create-donobu-plugin",
-    "version": "1.3.0",
-    "type": "module",
-    "description": "Create a new Donobu plugin",
-    "author": "Donobu",
-    "homepage": "https://donobu.com",
-    "main": "index.js",
-    "bin": {
-        "create-donobu-plugin": "./index.js"
-    },
-    "files": [
-        "index.js"
-    ],
-    "dependencies": {
-        "donobu": "^3.4.0"
-    },
-    "keywords": [
-        "donobu",
-        "plugin",
-        "create"
-    ],
-    "license": "UNLICENSED"
+  "name": "create-donobu-plugin",
+  "version": "1.7.0",
+  "type": "module",
+  "description": "Create a new Donobu plugin",
+  "author": "Donobu",
+  "homepage": "https://donobu.com",
+  "main": "index.js",
+  "bin": {
+    "create-donobu-plugin": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.2",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^16.0.0",
+    "prettier": "^3.8.0"
+  },
+  "keywords": [
+    "donobu",
+    "plugin",
+    "create"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "pnpm install --frozen-lockfile && pnpm run lint --fix && pnpm run format && pnpm run lint",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  }
 }