@clearlysh/beehaven 0.8.16

package/dist/commands/init.js

@@ -0,0 +1,408 @@
+/**
+ * beehaven init — Scaffold a new beehaven project.
+ *
+ * Creates:
+ *   src/hive.ts              defineHive + example Workspace
+ *   .dev.vars                Local secrets file
+ *   package.json
+ *   tsconfig.json
+ *   .gitignore
+ *
+ * The CLI auto-generates wrangler.toml + worker.ts when you run
+ * `beehaven dev` or `beehaven deploy` — no need to write those by hand.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, basename } from 'path';
+import { randomUUID } from 'crypto';
+import { color } from '../spinner.js';
+export async function init(cwd, options) {
+    // Validate Node version
+    const nodeVersion = parseInt(process.version.slice(1));
+    if (nodeVersion < 20) {
+        console.error(color.red('✗') + ` Node 20+ required (found ${process.version})`);
+        process.exit(1);
+    }
+    const template = (options?.template ?? 'api');
+    const validTemplates = ['api', 'notes', 'chat', 'game'];
+    if (!validTemplates.includes(template)) {
+        console.error(color.red('✗') + ` Unknown template "${template}". Choose: ${validTemplates.join(', ')}`);
+        process.exit(1);
+    }
+    const projectName = basename(cwd);
+    const projectId = `bh_${randomUUID().slice(0, 8)}`;
+    console.log(`\n  Initializing beehaven in ${projectName}/ (template: ${color.cyan(template)})\n`);
+    // .beehaven/config.json
+    const configDir = join(cwd, '.beehaven');
+    if (!existsSync(configDir))
+        mkdirSync(configDir, { recursive: true });
+    writeFileSync(join(configDir, 'config.json'), JSON.stringify({
+        projectId,
+        projectName,
+        region: 'auto',
+        createdAt: new Date().toISOString(),
+    }, null, 2));
+    console.log('  Created .beehaven/config.json');
+    // src/ directory
+    const srcDir = join(cwd, 'src');
+    if (!existsSync(srcDir))
+        mkdirSync(srcDir, { recursive: true });
+    // src/hive.ts — main entry point with example Workspace
+    if (!existsSync(join(srcDir, 'hive.ts'))) {
+        writeFileSync(join(srcDir, 'hive.ts'), APP_TEMPLATE(projectName, template));
+        console.log('  Created src/hive.ts');
+    }
+    // package.json
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (!pkg.dependencies?.['@clearly-sh/beehaven-core']) {
+            pkg.dependencies = pkg.dependencies || {};
+            pkg.dependencies['@clearly-sh/beehaven-core'] = '^0.3.0';
+            writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+            console.log('  Added @clearly-sh/beehaven-core to package.json');
+        }
+    }
+    else {
+        writeFileSync(pkgPath, JSON.stringify({
+            name: projectName,
+            private: true,
+            type: 'module',
+            scripts: {
+                dev: 'beehaven dev',
+                deploy: 'beehaven deploy',
+            },
+            dependencies: {
+                '@clearly-sh/beehaven-core': '^0.3.0',
+                hono: '^4.0.0',
+            },
+            devDependencies: {
+                '@cloudflare/workers-types': '^4.0.0',
+                typescript: '^5.6.0',
+                wrangler: '^3.0.0',
+            },
+        }, null, 2));
+        console.log('  Created package.json');
+    }
+    // tsconfig.json
+    if (!existsSync(join(cwd, 'tsconfig.json'))) {
+        writeFileSync(join(cwd, 'tsconfig.json'), JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'ESNext',
+                moduleResolution: 'bundler',
+                lib: ['ES2022'],
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                outDir: 'dist',
+                types: ['@cloudflare/workers-types'],
+            },
+            include: ['src/**/*.ts'],
+            exclude: ['node_modules', 'dist', '.beehaven'],
+        }, null, 2));
+        console.log('  Created tsconfig.json');
+    }
+    // .dev.vars — local secrets (never committed)
+    const devVarsPath = join(cwd, '.dev.vars');
+    if (!existsSync(devVarsPath)) {
+        writeFileSync(devVarsPath, `# Local secrets — loaded by wrangler dev automatically
+# These are NOT committed to git.
+#
+# ADMIN_SECRET=change-me
+# FIREBASE_PROJECT_ID=my-project
+`);
+        console.log('  Created .dev.vars');
+    }
+    // .gitignore
+    const gitignorePath = join(cwd, '.gitignore');
+    const gitignoreContent = `node_modules/
+dist/
+.beehaven/
+.dev.vars
+.wrangler/
+`;
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, 'utf8');
+        if (!content.includes('.beehaven/')) {
+            writeFileSync(gitignorePath, content + '\n# Beehaven\n.beehaven/\n.dev.vars\n');
+            console.log('  Updated .gitignore');
+        }
+    }
+    else {
+        writeFileSync(gitignorePath, gitignoreContent);
+        console.log('  Created .gitignore');
+    }
+    // ── Template-specific folder configs ────────────────
+    const foldersDir = join(cwd, 'folders');
+    if (!existsSync(foldersDir))
+        mkdirSync(foldersDir, { recursive: true });
+    const templateFolders = getTemplateFolders(template);
+    for (const [name, config] of Object.entries(templateFolders)) {
+        const folderPath = join(foldersDir, `${name}.json`);
+        if (!existsSync(folderPath)) {
+            writeFileSync(folderPath, JSON.stringify(config, null, 2));
+            console.log(`  Created folders/${name}.json`);
+        }
+    }
+    console.log(`
+  Done! Next steps:
+
+    npm install
+    beehaven dev
+
+  Your project:
+
+    src/hive.ts        Your Workspace classes + defineHive config
+    folders/           Data schemas (one .json per collection)
+    .dev.vars          Local secrets (auto-loaded by wrangler dev)
+    .beehaven/         Auto-generated files (wrangler.toml, worker.ts)
+
+  The CLI generates wrangler.toml and worker.ts for you when you
+  run \`beehaven dev\` or \`beehaven deploy\`. Just write your Workspace
+  classes in src/hive.ts and the SDK handles everything else.
+
+  Docs: https://beehaven.dev/docs
+`);
+}
+// ── Template Folder Configs ─────────────────────────────
+function getTemplateFolders(template) {
+    switch (template) {
+        case 'notes':
+            return {
+                notes: {
+                    type: 'data',
+                    fields: {
+                        title: 'string',
+                        content: 'string',
+                        pinned: 'boolean',
+                        created_at: 'date',
+                        updated_at: 'date',
+                    },
+                    indexes: [['pinned'], ['created_at']],
+                    fts: ['title', 'content'],
+                },
+                tags: {
+                    type: 'data',
+                    fields: { name: 'string', color: 'string', note_id: 'string' },
+                    indexes: [['note_id']],
+                },
+            };
+        case 'chat':
+            return {
+                messages: {
+                    type: 'data',
+                    fields: { text: 'string', sender_id: 'string', room_id: 'string', created_at: 'date' },
+                    indexes: [['room_id', 'created_at']],
+                    sync: 'full',
+                },
+                rooms: {
+                    type: 'data',
+                    fields: {
+                        name: 'string',
+                        description: 'string',
+                        created_by: 'string',
+                        created_at: 'date',
+                    },
+                    indexes: [['created_by']],
+                    presence: { enabled: true, channels: ['typing', 'online'] },
+                },
+            };
+        case 'game':
+            return {
+                players: {
+                    type: 'data',
+                    fields: {
+                        name: 'string',
+                        x: 'number',
+                        y: 'number',
+                        health: 'int',
+                        score: 'int',
+                        team: 'string',
+                    },
+                    indexes: [['team']],
+                    sync: 'full',
+                    resolver: { hz: 30 },
+                },
+            };
+        case 'api':
+        default:
+            return {
+                items: {
+                    type: 'data',
+                    fields: { title: 'string', done: 'boolean', created_at: 'date' },
+                    indexes: [['done'], ['created_at']],
+                },
+            };
+    }
+}
+// ── Templates ──────────────────────────────────────────
+function APP_TEMPLATE(projectName, template = 'api') {
+    const className = toPascalCase(projectName);
+    const body = template === 'chat' ? CHAT_WORKSPACE_BODY(className) : DEFAULT_WORKSPACE_BODY(className);
+    return `import { defineHive, Workspace } from '@clearly-sh/beehaven-core/server';
+
+// ── Your Workspace ─────────────────────────────────────
+// Each Workspace is a Durable Object — a mini computer with
+// folders (data), apps (RPCs), hooks (triggers), and more.
+
+${body}
+
+// ── App config ─────────────────────────────────────────
+// buildings: map of named DOs. Each gets its own SQLite database.
+// auth: verify tokens from your auth provider (Firebase, Clerk, etc.)
+
+export default defineHive({
+  buildings: { main: ${toPascalCase(projectName)}Workspace },
+  auth: {
+    verify: async (token: string, env: any) => {
+      // Replace with your auth verification logic.
+      // Return { userId } on success, null on failure.
+      //
+      // Firebase example:
+      //   import { Passport } from '@clearly-sh/beehaven-core/server';
+      //   const passport = Passport.firebase({ projectId: env.FIREBASE_PROJECT_ID });
+      //   return passport.verify(token);
+      //
+      // Simple dev auth (remove in production!):
+      if (!token) return null;
+      return { userId: token };
+    },
+  },
+});
+
+export { ${toPascalCase(projectName)}Workspace };
+`;
+}
+// ── Per-template Workspace bodies ──────────────────────
+/** Default body — items list. Used by api/notes/game/default templates. */
+function DEFAULT_WORKSPACE_BODY(className) {
+    return `class ${className}Workspace extends Workspace {
+  // ── Data folders ────────────────────────────────────
+  // Like Firestore collections. Each row is auto-synced to clients.
+  items = this.folder('items', {
+    title: 'string',
+    done: 'boolean',
+    created_at: 'date',
+  });
+
+  // ── Hooks (triggers) ───────────────────────────────
+  // Runs after an item is inserted. The SDK auto-broadcasts
+  // deltas to subscribed clients — no manual broadcastDelta needed.
+  onItemInsert = this.hook('items', 'insert', async (row) => {
+    console.log('New item:', row.title);
+  });
+
+  // ── Apps (RPCs) ────────────────────────────────────
+  // Callable from clients via cell.rpc('add-item', { title: '...' })
+  addItem = this.install('add-item', {
+    run: async (input: { title: string }) => {
+      const id = crypto.randomUUID();
+      this.items.insert({ id, title: input.title, done: false, created_at: Date.now() });
+      return { id };
+    },
+  });
+
+  toggleItem = this.install('toggle-item', {
+    run: async (input: { id: string }) => {
+      const item = this.items.get(input.id);
+      if (!item) throw new Error('Item not found');
+      this.items.update(input.id, { done: !item.done });
+      return { ok: true };
+    },
+  });
+
+  deleteItem = this.install('delete-item', {
+    run: async (input: { id: string }) => {
+      this.items.delete(input.id);
+      return { ok: true };
+    },
+  });
+}`;
+}
+/** Chat template body — uses this.messages() for full lifecycle tracking.
+ *  See docs/MESSAGING.md for the surface this exposes. */
+function CHAT_WORKSPACE_BODY(className) {
+    return `class ${className}Workspace extends Workspace {
+  // ── Messages shelf (per RFC #13 / docs/MESSAGING.md) ──
+  // this.messages() gives you the full lifecycle:
+  //   queued → sending → sent → delivered_inbox → delivered_device → read
+  // plus per-recipient per-device receipts, TTL, retry, opt-out.
+  // For an ephemeral ringbuffer-style chat without delivery tracking,
+  // use this.chat() instead.
+  messages = this.messages('messages', {
+    fields: {
+      thread_id: 'string',
+      attachments: 'json',
+    },
+    // 7-day TTL: messages stuck at delivered_inbox past 7 days expire.
+    deliveryTtl: 7 * 86400_000,
+  });
+
+  rooms = this.folder('rooms', {
+    name: 'string',
+    description: 'string',
+    created_by: 'string',
+    created_at: 'date',
+  });
+
+  // ── Apps (RPCs) ────────────────────────────────────
+  // Send a new message. Clients call this via the OptimisticSender
+  // pattern (see useMessages React hook) — local state moves to
+  // 'queued' immediately, the server response transitions to 'sent'.
+  sendMessage = this.install('messages:insert', {
+    run: async (input: { recipients: string[]; body: string; thread_id?: string }, ctx: any) => {
+      const id = crypto.randomUUID();
+      this.messages.insert({
+        id,
+        senderId: ctx.userId,
+        recipients: input.recipients,
+        body: input.body,
+        thread_id: input.thread_id ?? null,
+      });
+      return { id };
+    },
+  });
+
+  // Receipt batching (paired with client MessageAckClient).
+  // The hook batches consecutive acks into one RPC to amortize ops.
+  ackBatch = this.install('messages:ack-batch', {
+    run: async (input: { userId: string; deviceId: string; acks: Array<{ type: 'delivered_device' | 'read'; messageId: string }> }) => {
+      for (const ack of input.acks) {
+        if (ack.type === 'delivered_device') {
+          this.messages.markDeliveredDevice(ack.messageId, input.userId, input.deviceId);
+        } else if (ack.type === 'read') {
+          this.messages.markRead(ack.messageId, input.userId, input.deviceId);
+        }
+      }
+      return { count: input.acks.length };
+    },
+  });
+
+  // ── TTL sweep ─────────────────────────────────────
+  // Messages stuck at delivered_inbox past deliveryTtl transition
+  // to 'expired'. Hourly sweep is fine for most products.
+  sweepExpired = this.cron('0 * * * *', async () => {
+    const expired = this.messages.sweepExpired();
+    if (expired > 0) console.log(\`[chat] expired \${expired} messages\`);
+  });
+
+  // ── Client side (React) ────────────────────────────
+  // import { useMessages } from '@clearly-sh/beehaven-core/react';
+  //
+  // const { messages, send, markRead, status } = useMessages(client, {
+  //   shelf: 'messages',
+  //   userId: currentUser.id,
+  //   deviceId: 'phone-' + deviceFingerprint,
+  // });
+  //
+  // See docs/MESSAGING.md for the full client-side guide.
+}`;
+}
+function toPascalCase(str) {
+    return str
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join('');
+}

package/dist/commands/install.js

@@ -0,0 +1,129 @@
+/**
+ * beehaven install — Install reusable apps, hooks, and folder schemas from packages.
+ *
+ * Packages are git repos or local directories containing beehaven config files.
+ * Installing a package copies its folders/, apps/, and hooks/ into your project.
+ *
+ * Usage:
+ *   beehaven install ./my-auth-hooks          # Local directory
+ *   beehaven install github:user/repo          # GitHub repo (future)
+ *   beehaven install @beehaven/stripe-billing  # Registry (future)
+ *
+ * A package is just a directory with the standard beehaven structure:
+ *   folders/*.json    — Merged into your folders/
+ *   apps/*.ts         — Copied into your apps/
+ *   hooks/*.ts        — Copied into your hooks/
+ *   rules.json       — Merged into your rules.json
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { join } from 'path';
+export async function install(cwd, packagePath) {
+    if (!packagePath) {
+        console.error('  Usage: beehaven install <path>');
+        console.error('  Example: beehaven install ./my-auth-hooks');
+        process.exit(1);
+    }
+    // Resolve package path
+    let srcDir = packagePath;
+    if (packagePath.startsWith('github:')) {
+        console.error('  GitHub packages coming soon. Use a local path for now.');
+        process.exit(1);
+    }
+    if (packagePath.startsWith('@')) {
+        console.error('  Registry packages coming soon. Use a local path for now.');
+        process.exit(1);
+    }
+    if (!existsSync(srcDir)) {
+        console.error(`  Package not found: ${srcDir}`);
+        process.exit(1);
+    }
+    console.log(`\n  Installing from ${srcDir}...\n`);
+    let installed = 0;
+    // Copy folders/*.json
+    const srcFolders = join(srcDir, 'folders');
+    if (existsSync(srcFolders)) {
+        const dstFolders = join(cwd, 'folders');
+        if (!existsSync(dstFolders))
+            mkdirSync(dstFolders, { recursive: true });
+        for (const file of readdirSync(srcFolders)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const dst = join(dstFolders, file);
+            if (existsSync(dst)) {
+                console.log(`  Skip folders/${file} (already exists)`);
+                continue;
+            }
+            copyFileSync(join(srcFolders, file), dst);
+            console.log(`  Added folders/${file}`);
+            installed++;
+        }
+    }
+    // Copy apps/*.ts
+    const srcApps = join(srcDir, 'apps');
+    if (existsSync(srcApps)) {
+        const dstApps = join(cwd, 'apps');
+        if (!existsSync(dstApps))
+            mkdirSync(dstApps, { recursive: true });
+        for (const file of readdirSync(srcApps)) {
+            if (!file.endsWith('.ts') && !file.endsWith('.js'))
+                continue;
+            const dst = join(dstApps, file);
+            if (existsSync(dst)) {
+                console.log(`  Skip apps/${file} (already exists)`);
+                continue;
+            }
+            copyFileSync(join(srcApps, file), dst);
+            console.log(`  Added apps/${file}`);
+            installed++;
+        }
+    }
+    // Copy hooks/*.ts
+    const srcHooks = join(srcDir, 'hooks');
+    if (existsSync(srcHooks)) {
+        const dstHooks = join(cwd, 'hooks');
+        if (!existsSync(dstHooks))
+            mkdirSync(dstHooks, { recursive: true });
+        for (const file of readdirSync(srcHooks)) {
+            if (!file.endsWith('.ts') && !file.endsWith('.js'))
+                continue;
+            const dst = join(dstHooks, file);
+            if (existsSync(dst)) {
+                console.log(`  Skip hooks/${file} (already exists)`);
+                continue;
+            }
+            copyFileSync(join(srcHooks, file), dst);
+            console.log(`  Added hooks/${file}`);
+            installed++;
+        }
+    }
+    // Merge rules.json
+    const srcRules = join(srcDir, 'rules.json');
+    if (existsSync(srcRules)) {
+        const dstRules = join(cwd, 'rules.json');
+        const srcRulesData = JSON.parse(readFileSync(srcRules, 'utf8'));
+        if (existsSync(dstRules)) {
+            const dstRulesData = JSON.parse(readFileSync(dstRules, 'utf8'));
+            const merged = {
+                ...dstRulesData,
+                rules: { ...dstRulesData.rules, ...srcRulesData.rules },
+            };
+            writeFileSync(dstRules, JSON.stringify(merged, null, 2) + '\n');
+            const newRules = Object.keys(srcRulesData.rules || {}).filter((k) => !dstRulesData.rules?.[k]);
+            if (newRules.length > 0) {
+                console.log(`  Merged ${newRules.length} rule(s) into rules.json`);
+                installed += newRules.length;
+            }
+        }
+        else {
+            writeFileSync(dstRules, JSON.stringify(srcRulesData, null, 2) + '\n');
+            console.log(`  Created rules.json`);
+            installed++;
+        }
+    }
+    if (installed === 0) {
+        console.log('  Nothing to install (all files already exist).');
+    }
+    else {
+        console.log(`\n  Installed ${installed} file(s). Run \`beehaven dev\` to apply.\n`);
+    }
+}