create-drobek-module 0.3.3

package/template/src/index.ts

@@ -0,0 +1,111 @@
+/**
+ * {{package}} — a drobek platform module (module contract ^1.1).
+ *
+ *   DROBEK_MODULES=…,{{entry}}
+ *
+ *   GET  /__drobek/v1/{{module}}/items → { items, upstream }   (newest first, at most 100)
+ *   POST /__drobek/v1/{{module}}/items → the new item           ({ title }, rate-limited per visitor IP)
+ *   drobek.{{module}}.list() / add(title)
+ *   config { write, maxItems } — opening `write` to everyone needs the owner's OK.
+ *
+ * docs/MODULES.md in the drobek repository is the contract; SKILL.md is what
+ * the agent reads (`skill_info('{{module}}')`).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { count, desc, eq } from 'drizzle-orm';
+import { ModuleError, defineModule, z, type ModuleContext } from '@drobek/modules';
+import { items } from './schema.js';
+
+const here = (rel: string) => fileURLToPath(new URL(rel, import.meta.url));
+
+/** The SDK entry next to this file: dist/sdk.js when built, src/sdk.ts in a source checkout. */
+const sdkEntry = existsSync(here('./sdk.js')) ? here('./sdk.js') : here('./sdk.ts');
+
+export const config = z.object({
+  /** Who may add items: anyone, or end users signed in through the auth module. */
+  write: z.enum(['public', 'user']),
+  /** The most items one app keeps. */
+  maxItems: z.number().int().min(1).max(100_000),
+});
+export type Config = z.infer<typeof config>;
+
+/** What `drobek.{{module}}` looks like to the app (sdk.d.ts); src/sdk.ts implements it. */
+const SDK_TYPES = `
+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>;
+}
+`;
+
+const itemView = (row: typeof items.$inferSelect) => ({ id: row.id, title: row.title, created_at: row.createdAt.toISOString() });
+
+async function itemCount(db: ModuleContext['db'], appId: string): Promise<number> {
+  const [row] = await db.select({ n: count() }).from(items).where(eq(items.appId, appId));
+  return Number(row?.n ?? 0);
+}
+
+export default defineModule<Config>({
+  name: '{{module}}',
+  version: '0.1.0',
+  contract: '^1.1',
+  skill: {
+    useWhen: 'the app keeps a list of items on the server (the {{module}} module)',
+    markdown: readFileSync(here('../SKILL.md'), 'utf8'),
+  },
+  configSchema: config,
+  configDefaults: { write: 'public', maxItems: 1000 },
+  // A change that widens who can write waits for the app owner's confirmation.
+  confirmRequired(before, after) {
+    return before.write !== after.write && after.write === 'public' ? ['write: anyone may add items'] : [];
+  },
+  // Names only: the owner sets the value in the dashboard; ctx.secrets.get reads it.
+  secrets: [{ name: '{{MODULE}}_API_KEY', description: 'The key of the upstream API this module calls (optional)' }],
+  // The operator (or the limits provider, per workspace) may change the default.
+  limits: [{ env: '{{MODULE}}_ADDS_PER_MINUTE', default: 30, meaning: 'items one visitor IP may add per minute' }],
+  // Every code a route throws besides the core ones (a ModuleError with another code is a 500).
+  errors: [
+    {
+      code: '{{module}}_full',
+      meaning: 'HTTP 409. The app already keeps `maxItems` items (`details.max`).',
+      fix: 'Tell the user the list is full; the app owner can raise maxItems with configure_module.',
+    },
+  ],
+  routes(r) {
+    r.get('/items', { rule: 'public' }, async (_req, ctx) => {
+      const rows = await ctx.db.select().from(items).where(eq(items.appId, ctx.app.id)).orderBy(desc(items.id)).limit(100);
+      // Call your upstream with the key here; the value never leaves the server.
+      const key = await ctx.secrets.get('{{MODULE}}_API_KEY');
+      return { items: rows.map(itemView), upstream: key !== null };
+    });
+    r.post(
+      '/items',
+      {
+        rule: (c) => c.write,
+        body: z.object({ title: z.string().trim().min(1).max(200) }),
+        rateLimit: { bucket: 'add', max: '{{MODULE}}_ADDS_PER_MINUTE', windowMs: 60_000, per: 'ip' },
+        maxBodyBytes: 4096,
+      },
+      async (req, ctx) => {
+        if ((await itemCount(ctx.db, ctx.app.id)) >= ctx.config.maxItems) {
+          throw new ModuleError('{{module}}_full', `This app keeps at most ${ctx.config.maxItems} items.`, {
+            status: 409,
+            details: { max: ctx.config.maxItems },
+          });
+        }
+        const [row] = await ctx.db.insert(items).values({ appId: ctx.app.id, title: req.body.title }).returning();
+        await ctx.audit('add', { id: row.id });
+        return itemView(row);
+      }
+    );
+  },
+  sdk: { entry: sdkEntry, types: SDK_TYPES },
+  migrations: { folder: here('../migrations') },
+});

package/template/src/schema.ts

@@ -0,0 +1,18 @@
+/**
+ * The module's own table, created by ../migrations (journal
+ * `__drizzle_migrations_mod_{{module}}`). Module tables are named
+ * `mod_{{module}}_*` and reference apps(id) with ON DELETE CASCADE, so
+ * deleting an app deletes its module data.
+ */
+import { bigserial, index, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+
+export const items = pgTable(
+  'mod_{{module}}_items',
+  {
+    id: bigserial('id', { mode: 'number' }).primaryKey(),
+    appId: text('app_id').notNull(),
+    title: text('title').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('mod_{{module}}_items_app_idx').on(t.appId)]
+);

package/template/src/sdk.ts

@@ -0,0 +1,20 @@
+/**
+ * The browser half of the module: the drobek server bundles it into
+ * `/__drobek/sdk.js` as `drobek.{{module}}`. It runs in the app's page — keep
+ * it dependency-free (type imports only). The declared types are SDK_TYPES
+ * in src/index.ts.
+ */
+import type { SdkCore } from '@drobek/modules';
+
+export interface Item {
+  id: number;
+  title: string;
+  created_at: string;
+}
+
+export default function sdk(core: SdkCore) {
+  return {
+    list: () => core.request<{ items: Item[]; upstream: boolean }>('GET', '/items'),
+    add: (title: string) => core.request<Item>('POST', '/items', { body: { title } }),
+  };
+}

package/template/src/skill.test.ts

@@ -0,0 +1,15 @@
+/**
+ * SKILL.md is what an agent reads (`skill_info`). checkSkill runs the gate
+ * drobek runs on its built-in modules: the five sections, ≤ 150 lines, only
+ * real error codes, and every code block compiled + typechecked against this
+ * module's SDK types. `npm run check` runs this file alone.
+ */
+import { describe, expect, it } from 'vitest';
+import { checkSkill, formatSkillIssue } from '@drobek/modules/testing';
+import mod from './index.js';
+
+describe('SKILL.md', () => {
+  it('passes checkSkill', async () => {
+    expect((await checkSkill(mod)).map(formatSkillIssue)).toEqual([]);
+  });
+});

package/template/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "types": ["node"]
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["./src/**/*.test.ts"]
+}

package/template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+
+// checkSkill compiles and typechecks SKILL.md in one TypeScript program (a few seconds).
+export default defineConfig({
+  test: { testTimeout: 60_000, hookTimeout: 60_000 },
+});