create-drobek-module 0.3.3

package/README.md

@@ -0,0 +1,38 @@
+# create-drobek-module
+
+Scaffold a [drobek](https://github.com/freema/drobek) platform module:
+
+```sh
+npm create drobek-module@latest erp
+# → drobek-module-erp/ — the module "erp"
+npm create drobek-module@latest @acme/drobek-module-erp
+npm create drobek-module@latest acme-erp -- --module acmeerp
+```
+
+Options: `--module <name>` (the module name, `^[a-z][a-z0-9]{1,30}$`;
+default: the package name without `drobek-module-` and dashes), `--dir
+<parent>`, `--force` (write into a non-empty directory).
+
+The output is a working module against the module contract `^1.1`:
+
+- `src/index.ts` — `defineModule` with `contract`, config + an owner
+  confirmation, a secret, a limit, an own error code and a GET/POST route
+  pair over the module's table;
+- `src/sdk.ts` — the browser half (`drobek.<name>.list()` / `add(title)`);
+- `src/schema.ts` + `migrations/0000_init.sql` — the table `mod_<name>_items`;
+- `SKILL.md` — the five-section skill an agent reads with `skill_info`;
+- `src/index.test.ts` — the routes through the production pipeline
+  (`createModuleTestContext`) over PGlite with the drobek core migrations;
+- `src/skill.test.ts` — `checkSkill`, the SKILL.md gate of the built-in
+  modules (`npm run check`);
+- `README.md` — building, publishing and installing it on a server
+  (`task selfhost:module:add`).
+
+The generated `package.json` installs the contract from npm under the name
+the code imports — `"@drobek/modules": "npm:@freema/drobek-modules@^X.Y.Z"`
+in `devDependencies` — and declares the peer `"@drobek/modules": ">=X.Y.Z"`
+the server's installer checks.
+
+The guide is
+[Writing a module](https://github.com/freema/drobek/blob/main/docs/MODULES.md#writing-a-module).
+Licence: AGPL-3.0-only.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * npm create drobek-module@latest <name> [-- --module <name>] [--dir <parent>] [--force]
+ */
+import { relative } from 'node:path';
+import { parseTarget, scaffold } from './index.js';
+const USAGE = 'usage: npm create drobek-module@latest <name> [-- --module <name>] [--dir <parent>] [--force]';
+function main(argv) {
+    const positional = [];
+    const opts = { force: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-h' || a === '--help') {
+            console.log(USAGE);
+            return 0;
+        }
+        if (a === '--force')
+            opts.force = true;
+        else if (a === '--module' || a === '--dir')
+            opts[a === '--module' ? 'module' : 'dir'] = argv[++i];
+        else if (a.startsWith('-')) {
+            console.error(`unknown option ${a}\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(a);
+    }
+    if (positional.length !== 1) {
+        console.error(USAGE);
+        return 2;
+    }
+    try {
+        const { dir, target, files } = scaffold(parseTarget(positional[0], opts.module), { parent: opts.dir, force: opts.force });
+        const rel = relative(process.cwd(), dir) || '.';
+        console.log(`Created ${rel}/ — the drobek module "${target.moduleName}" (${target.packageName}, ${files.length} files).
+
+  cd ${rel}
+  npm install
+  npm test          # the routes through the production pipeline + the SKILL.md gate
+  npm run build
+
+Install it on a drobek server (docs/MODULES.md → Writing a module):
+  task selfhost:module:add -- <npm spec, tarball or git URL>
+  DROBEK_MODULES=…,${target.modulesEntry}`);
+        return 0;
+    }
+    catch (err) {
+        // db-error-guard: allow — a scaffold refusal (bad name, non-empty dir), not a database error
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/** The template shipped next to dist/ (and next to src/ in the repository). */
+export declare const TEMPLATE_DIR: string;
+export interface ScaffoldTarget {
+    /** The npm package name (`drobek-module-erp`, `@acme/drobek-module-erp`). */
+    packageName: string;
+    /** The module name (`erp`). */
+    moduleName: string;
+    /** The directory created (`drobek-module-erp`). */
+    dirName: string;
+    /** What the operator lists in DROBEK_MODULES: the short name when the package is `drobek-module-<name>`, else the package. */
+    modulesEntry: string;
+}
+/** Resolve `<name>` (a short name, `drobek-module-<x>` or a scoped package) to package, module and directory names. */
+export declare function parseTarget(input: string, moduleOverride?: string): ScaffoldTarget;
+export interface ScaffoldOptions {
+    /** Where the module directory is created (default: the working directory). */
+    parent?: string;
+    /** The @drobek/modules version the module is written against (default: this package's version — they are released together). */
+    drobekVersion?: string;
+    /** Write into an existing non-empty directory. */
+    force?: boolean;
+}
+export interface ScaffoldResult {
+    dir: string;
+    target: ScaffoldTarget;
+    /** The files written, relative to `dir`. */
+    files: string[];
+}
+/** This package's version (= the @drobek/modules release it ships with). */
+export declare function ownVersion(): string;
+/** Replace `{{module}}`, `{{MODULE}}`, `{{package}}`, `{{entry}}`, `{{drobekVersion}}`. */
+export declare function renderTemplate(text: string, target: ScaffoldTarget, drobekVersion: string): string;
+export declare function scaffold(target: ScaffoldTarget, opts?: ScaffoldOptions): ScaffoldResult;

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * create-drobek-module (NSO-349) — scaffold an external drobek platform
+ * module from `template/`:
+ *
+ *   npm create drobek-module@latest erp            → drobek-module-erp/, module "erp"
+ *   npm create drobek-module@latest @acme/drobek-module-erp
+ *   npm create drobek-module@latest acme-erp       → drobek-module-acme-erp/, module "acmeerp"
+ *
+ * The output is a complete module (contract ^1.1): a route pair over its own
+ * table (`mod_<name>_items`, migration 0000_init), the SDK slice, config with
+ * an owner confirmation, a secret, a limit, an own error code, SKILL.md in
+ * the five-section format, and tests — createModuleTestContext over PGlite
+ * with the core migrations, and the checkSkill gate (`npm run check`).
+ * examples/drobek-module-hello in the drobek repository is this output plus
+ * the slot demo.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The template shipped next to dist/ (and next to src/ in the repository). */
+export const TEMPLATE_DIR = fileURLToPath(new URL('../template', import.meta.url));
+/** `defineModule({ name })`: also the URL segment, config key, skill name and table prefix. */
+const MODULE_NAME_RE = /^[a-z][a-z0-9]{1,30}$/;
+const RESERVED = ['sdk', 'v1', 'drobek', 'internal'];
+/** The modules drobek ships: a new module needs its own name (replacing one is an operator decision, docs/MODULES.md). */
+const BUILT_IN = ['auth', 'email', 'forms', 'data', 'proxy', 'files'];
+const PACKAGE_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/** Resolve `<name>` (a short name, `drobek-module-<x>` or a scoped package) to package, module and directory names. */
+export function parseTarget(input, moduleOverride) {
+    const raw = input.trim();
+    const packageName = raw.startsWith('@') || raw.startsWith('drobek-module-') ? raw : `drobek-module-${raw}`;
+    if (!PACKAGE_RE.test(packageName))
+        throw new Error(`"${raw}" is not a valid npm package name (lower case, digits, - . _; optionally @scope/)`);
+    const dirName = packageName.split('/').pop();
+    const moduleName = moduleOverride ?? dirName.replace(/^drobek-module-/, '').replace(/[^a-z0-9]/g, '');
+    if (!MODULE_NAME_RE.test(moduleName)) {
+        throw new Error(`module name "${moduleName}" must match ${MODULE_NAME_RE} (lower case letters and digits, 2–31 characters) — pass --module <name>`);
+    }
+    if (RESERVED.includes(moduleName))
+        throw new Error(`module name "${moduleName}" is reserved (${RESERVED.join(', ')})`);
+    if (BUILT_IN.includes(moduleName))
+        throw new Error(`"${moduleName}" is a built-in drobek module — pick another name (--module <name>)`);
+    return { packageName, moduleName, dirName, modulesEntry: packageName === `drobek-module-${moduleName}` ? moduleName : packageName };
+}
+/** This package's version (= the @drobek/modules release it ships with). */
+export function ownVersion() {
+    return JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version;
+}
+/** Replace `{{module}}`, `{{MODULE}}`, `{{package}}`, `{{entry}}`, `{{drobekVersion}}`. */
+export function renderTemplate(text, target, drobekVersion) {
+    const vars = {
+        module: target.moduleName,
+        MODULE: target.moduleName.toUpperCase(),
+        package: target.packageName,
+        entry: target.modulesEntry,
+        drobekVersion,
+    };
+    return text.replace(/\{\{(\w+)\}\}/g, (all, key) => vars[key] ?? all);
+}
+function templateFiles(dir, base = dir) {
+    return readdirSync(dir)
+        .sort()
+        .flatMap((name) => {
+        const p = join(dir, name);
+        return statSync(p).isDirectory() ? templateFiles(p, base) : [relative(base, p)];
+    });
+}
+/** `_gitignore` → `.gitignore` (npm pack drops a real `.gitignore` from the template). */
+const RENAMED = { _gitignore: '.gitignore' };
+function outputPath(rel) {
+    return rel
+        .split(/[\\/]/)
+        .map((seg) => RENAMED[seg] ?? seg)
+        .join('/');
+}
+export function scaffold(target, opts = {}) {
+    const dir = resolve(opts.parent ?? process.cwd(), target.dirName);
+    if (existsSync(dir) && readdirSync(dir).length > 0 && !opts.force) {
+        throw new Error(`${dir} exists and is not empty (use --force to write into it)`);
+    }
+    const drobekVersion = opts.drobekVersion ?? ownVersion();
+    const files = [];
+    for (const rel of templateFiles(TEMPLATE_DIR)) {
+        const out = outputPath(rel);
+        const text = renderTemplate(readFileSync(join(TEMPLATE_DIR, rel), 'utf8'), target, drobekVersion);
+        mkdirSync(dirname(join(dir, out)), { recursive: true });
+        writeFileSync(join(dir, out), text);
+        files.push(out);
+    }
+    return { dir, target, files };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-drobek-module",
+  "version": "0.3.3",
+  "description": "Scaffold a drobek platform module: npm create drobek-module@latest <name> — routes, SDK, a migration, SKILL.md, vitest + PGlite tests and the checkSkill gate.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "author": "Tomáš Grasl",
+  "homepage": "https://github.com/freema/drobek/blob/main/docs/MODULES.md#writing-a-module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freema/drobek.git",
+    "directory": "packages/create-drobek-module"
+  },
+  "bugs": {
+    "url": "https://github.com/freema/drobek/issues"
+  },
+  "keywords": [
+    "drobek",
+    "drobek-module",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-drobek-module": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/template/README.md

@@ -0,0 +1,57 @@
+# {{package}}
+
+A [drobek](https://github.com/freema/drobek) platform module: server routes
+under `/__drobek/v1/{{module}}/…` on the app hosts, the browser SDK slice
+`drobek.{{module}}`, a per-app config the agent sets with
+`configure_module`, and a skill (`SKILL.md`) the agent reads with
+`skill_info('{{module}}')`. Written against the module contract `^1.1`
+(`@drobek/modules`).
+
+## Develop
+
+```sh
+npm install
+npm test            # routes through the production pipeline (PGlite) + the SKILL.md gate
+npm run check       # the SKILL.md gate alone (checkSkill)
+npm run typecheck
+npm run build       # dist/ — what a drobek server loads
+```
+
+- `src/index.ts` — `defineModule(...)`: config, routes, limits, secrets,
+  errors, the SDK types, the migrations folder.
+- `src/sdk.ts` — the browser half, bundled into `/__drobek/sdk.js`.
+- `src/schema.ts` + `migrations/` — the module's own tables (`mod_{{module}}_*`,
+  journal `__drizzle_migrations_mod_{{module}}`). Add a migration as
+  `migrations/0001_<name>.sql` + a journal entry.
+- `SKILL.md` — five sections, at most 150 lines; every code block is
+  compiled and typechecked by `npm run check`.
+
+The contract is published on npm as `@freema/drobek-modules` and installed
+under the name the code imports, `@drobek/modules`, through an npm alias in
+`devDependencies` (`"@drobek/modules": "npm:@freema/drobek-modules@^X.Y.Z"`).
+A module that imports `@drobek/sdk` directly adds
+`"@drobek/sdk": "npm:@freema/drobek-sdk@^X.Y.Z"` the same way.
+
+## Install on a drobek server
+
+Publish the package (`npm publish`) or pack it (`npm pack` → a tarball the
+server can download). Then, on the server:
+
+```sh
+task selfhost:module:add -- {{package}}@0.1.0     # or the URL of a packed tarball
+```
+
+and add the module to `DROBEK_MODULES` in `.env.production`:
+
+```sh
+DROBEK_MODULES=auth,email,forms,data,proxy,files,{{entry}}
+```
+
+Then restart drobek (see the self-hosting guide). The server refuses a module whose
+`contract` range does not match its module contract version; `zod`,
+`drizzle-orm` and `@drobek/modules` come from the server (they are peer
+dependencies, never bundled).
+
+A module runs inside the drobek process with the whole database: an
+operator installs only modules they trust. The guide:
+[docs/MODULES.md → Writing a module](https://github.com/freema/drobek/blob/main/docs/MODULES.md#writing-a-module).

package/template/SKILL.md

@@ -0,0 +1,88 @@
+# {{module}} — keep a list of items on the server
+
+## 1. When to use
+
+The app keeps a shared list on the server: every visitor of the app sees the
+same items, and adding one is a server call. Nothing is stored in the
+browser.
+
+## 2. Minimal working code
+
+```ts
+// src/main.ts — the bare `drobek` import is the platform SDK (no install).
+import { drobek, DrobekError } from 'drobek';
+
+const list = document.querySelector<HTMLUListElement>('#items')!;
+const form = document.querySelector<HTMLFormElement>('#add')!;
+
+async function render() {
+  const { items } = await drobek.{{module}}.list();
+  list.replaceChildren(...items.map((item) => Object.assign(document.createElement('li'), { textContent: item.title })));
+}
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  const title = String(new FormData(form).get('title') ?? '');
+  try {
+    await drobek.{{module}}.add(title);
+    form.reset();
+    await render();
+  } catch (err) {
+    // err.code: see "Errors → fix"
+    alert(err instanceof DrobekError && err.code === '{{module}}_full' ? 'The list is full.' : String(err));
+  }
+});
+
+void render();
+```
+
+## 3. API and types
+
+```ts api
+// drobek.{{module}}
+export interface Item {
+  id: number;
+  title: string;
+  created_at: string;
+}
+export interface Api {
+  /** The app's items, newest first (at most 100); upstream: the owner set {{MODULE}}_API_KEY */
+  list(): Promise<{ items: Item[]; upstream: boolean }>;
+  /** title: 1–200 characters; rate-limited ({{MODULE}}_ADDS_PER_MINUTE per visitor IP per minute) */
+  add(title: string): Promise<Item>;
+}
+```
+
+HTTP (what the SDK calls): `GET /__drobek/v1/{{module}}/items` and
+`POST /__drobek/v1/{{module}}/items` with `{ "title": "…" }`. Only the app
+itself may call them (same origin; the SDK sends `X-Drobek-SDK: 1`).
+
+Config (configure_module takes a partial config; `null` resets a key):
+
+```json
+{ "app_id": "…", "module": "{{module}}", "config": { "write": "user", "maxItems": 500 } }
+```
+
+- `write`: `"public"` (anyone may add, the default) or `"user"` (only end
+  users signed in through the `auth` module). **Changing it to `"public"`
+  needs the app owner's confirmation**: configure_module answers
+  `applied: false` with a `confirm_url` — give the user that link.
+- `maxItems` (1–100000, default 1000): the most items the app keeps.
+
+## 4. Rules and limits
+
+- `add` is limited to `{{MODULE}}_ADDS_PER_MINUTE` calls per visitor IP per
+  minute (default 30; the operator may set another value per workspace).
+- Optional secret `{{MODULE}}_API_KEY`: the app owner sets it in the
+  dashboard; `list()` answers `upstream: true` then. Never ask the user for
+  its value and never put it in the app's code.
+
+## 5. Errors → fix
+
+| error | cause | fix |
+|---|---|---|
+| `invalid_request` + `details[].path = "title"` | empty title or over 200 characters | send 1–200 characters |
+| `unauthorized` | `write` is `"user"` and nobody is signed in | sign in first (`skill_info('auth')`) |
+| `{{module}}_full` (409) | the app keeps `maxItems` items already | tell the user; the owner can raise `maxItems` |
+| `rate_limited` | too many adds from one visitor | retry after `Retry-After` seconds |
+| `csrf_rejected` | called with fetch from another origin or without the SDK | call through `drobek.{{module}}` from the app itself |

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tgz

package/template/migrations/0000_init.sql

@@ -0,0 +1,13 @@
+-- {{package}}: the items of an app (one row per item).
+-- Module tables are named `mod_{{module}}_*` and reference apps(id) with
+-- ON DELETE CASCADE, so deleting an app deletes its module data.
+CREATE TABLE IF NOT EXISTS "mod_{{module}}_items" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"app_id" text NOT NULL,
+	"title" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "mod_{{module}}_items" ADD CONSTRAINT "mod_{{module}}_items_app_id_apps_id_fk" FOREIGN KEY ("app_id") REFERENCES "public"."apps"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "mod_{{module}}_items_app_idx" ON "mod_{{module}}_items" USING btree ("app_id");

package/template/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1790150400000,
+      "tag": "0000_init",
+      "breakpoints": true
+    }
+  ]
+}

package/template/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "{{package}}",
+  "version": "0.1.0",
+  "description": "A drobek platform module: GET/POST /__drobek/v1/{{module}}/items, drobek.{{module}}.list() / add(title).",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "SKILL.md"
+  ],
+  "keywords": [
+    "drobek-module"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "check": "vitest run src/skill.test.ts",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@drobek/modules": ">={{drobekVersion}}",
+    "drizzle-orm": ">=0.45.0"
+  },
+  "devDependencies": {
+    "@drobek/modules": "npm:@freema/drobek-modules@^{{drobekVersion}}",
+    "@electric-sql/pglite": "^0.2.17",
+    "@types/node": "^22",
+    "drizzle-orm": "^0.45.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/template/src/index.test.ts

@@ -0,0 +1,90 @@
+/**
+ * The module under createModuleTestContext(): its routes run through the
+ * SAME pipeline production uses (rule, CSRF, rate limit, body validation,
+ * uniform errors), over PGlite with the drobek core + module migrations.
+ */
+import { PGlite } from '@electric-sql/pglite';
+import { drizzle } from 'drizzle-orm/pglite';
+import { migrate } from 'drizzle-orm/pglite/migrator';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { DB, HookApp } from '@drobek/modules';
+import { coreMigrationsDir, createModuleTestContext, createTestApp } from '@drobek/modules/testing';
+import mod from './index.js';
+
+let pg: PGlite;
+let db: DB;
+let app: HookApp;
+
+beforeAll(async () => {
+  pg = new PGlite();
+  const d = drizzle(pg);
+  await migrate(d, { migrationsFolder: coreMigrationsDir(), migrationsTable: '__drizzle_migrations_core', migrationsSchema: 'drizzle' });
+  await migrate(d, { migrationsFolder: mod.migrations!.folder, migrationsTable: '__drizzle_migrations_mod_{{module}}', migrationsSchema: 'drizzle' });
+  app = await createTestApp(d);
+  db = d as unknown as DB;
+});
+
+afterAll(async () => {
+  await pg.close();
+});
+
+describe('{{package}}', () => {
+  it('declares the module contract it is written against', () => {
+    expect(mod.name).toBe('{{module}}');
+    expect(mod.contract).toBe('^1.1');
+  });
+
+  it('POST /items adds an item, GET /items lists the newest first', async () => {
+    const t = createModuleTestContext(mod, { db, app });
+    expect((await t.request('GET', '/items')).body).toEqual({ items: [], upstream: false });
+    const first = await t.request('POST', '/items', { body: { title: 'First' } });
+    expect(first.status).toBe(200);
+    expect(first.body).toMatchObject({ id: expect.any(Number), title: 'First' });
+    await t.request('POST', '/items', { body: { title: 'Second' } });
+    const list = (await t.request('GET', '/items')).body as { items: { title: string }[] };
+    expect(list.items.map((i) => i.title)).toEqual(['Second', 'First']);
+    expect(t.audits.map((a) => a.action)).toEqual(['{{module}}.add', '{{module}}.add']);
+  });
+
+  it('validates the body with a field path', async () => {
+    const t = createModuleTestContext(mod, { db, app });
+    const bad = await t.request('POST', '/items', { body: { title: '' } });
+    expect(bad.status).toBe(400);
+    expect(bad.body).toMatchObject({ error: 'invalid_request', details: [{ path: 'title' }] });
+  });
+
+  it('write: "user" lets only signed-in end users add', async () => {
+    const t = createModuleTestContext(mod, { db, app, config: { write: 'user' } });
+    expect((await t.request('POST', '/items', { body: { title: 'x' } })).status).toBe(401);
+    t.setPrincipal({ kind: 'user', id: 'eu_1', email: 'ana@example.com', role: 'user' });
+    expect((await t.request('POST', '/items', { body: { title: 'x' } })).status).toBe(200);
+  });
+
+  it('answers its own error code {{module}}_full past maxItems', async () => {
+    const other = await createTestApp(db);
+    const t = createModuleTestContext(mod, { db, app: other, config: { maxItems: 1 } });
+    expect((await t.request('POST', '/items', { body: { title: 'a' } })).status).toBe(200);
+    const full = await t.request('POST', '/items', { body: { title: 'b' } });
+    expect(full.status).toBe(409);
+    expect(full.body).toMatchObject({ error: '{{module}}_full', details: { max: 1 } });
+  });
+
+  it('enforces {{MODULE}}_ADDS_PER_MINUTE (429)', async () => {
+    const t = createModuleTestContext(mod, { db, app, limits: { {{MODULE}}_ADDS_PER_MINUTE: 1 } });
+    expect((await t.request('POST', '/items', { body: { title: 'a' } })).status).toBe(200);
+    expect((await t.request('POST', '/items', { body: { title: 'b' } })).body).toMatchObject({ error: 'rate_limited' });
+  });
+
+  it('reads its secret without returning it', async () => {
+    const t = createModuleTestContext(mod, { db, app, secrets: { {{MODULE}}_API_KEY: 'k-123456' } });
+    const res = await t.request('GET', '/items');
+    expect(res.body).toMatchObject({ upstream: true });
+    expect(JSON.stringify(res.body)).not.toContain('k-123456');
+  });
+
+  it('opening write to everyone needs the owner\'s confirmation', async () => {
+    const t = createModuleTestContext(mod);
+    expect(await t.confirm({ write: 'user' }, { write: 'public' })).toEqual(['write: anyone may add items']);
+    expect(await t.confirm({}, { maxItems: 5 })).toEqual([]);
+  });
+});