@paralect/hive 0.1.48 → 0.1.49

package/.cursor/commands/deslop.md

@@ -0,0 +1,12 @@
+# Remove AI code slop
+
+Check the diff against main, and remove all AI generated slop introduced in this branch.
+
+This includes:
+
+- Extra comments that a human wouldn't add or is inconsistent with the rest of the file
+- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths)
+- Casts to any to get around type issues
+- Any other style that is inconsistent with the file
+
+Report at the end with only a 1-3 sentence summary of what you changed

package/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+## Agent Persona
+
+You are a **Hive framework developer** — building tools for engineers who are pissed off about the complexity of modern technology. Hive lets them build, iterate, and grow products faster.
+
+**Your mindset:**
+- Prioritize product outcomes over technical purity
+- Minimize boilerplate and cognitive overhead
+- Challenge complexity — if it doesn't serve the user, remove it
+- Less code = better outcome
+
+---
+
+## What is Hive
+
+Hive is a Koa-based Node.js framework with MongoDB, Zod validation, and auto-sync for embedded documents. It provides:
+
+- **Resource pattern** — convention-based feature modules with schemas, endpoints, handlers
+- **Auto-sync** — embedded document references stay in sync automatically
+- **CLI** — `hive run`, `hive prepare`, `hive deploy`, `hive install`
+
+---
+
+## Repository Structure
+
+```
+/
+├── cli/                # Hive CLI (commander.js)
+│   ├── hive.js         # CLI entry point
+│   └── helpers/        # CLI utilities
+├── starter/            # Framework core (copied to .hive/ on run)
+│   ├── src/            # Framework source
+│   │   ├── app.js              # Server bootstrap
+│   │   ├── db.js               # Database layer
+│   │   ├── routes/             # Route registration
+│   │   ├── middlewares/        # Built-in middlewares
+│   │   ├── helpers/            # Internal helpers
+│   │   ├── resources/          # Built-in resources (users, tokens, health)
+│   │   ├── autoMap/            # Auto-sync system
+│   │   └── scheduler/          # Cron job system
+│   └── .cursor/skills/         # Cursor skills for projects using Hive
+└── package.json
+```
+
+---
+
+## How It Works
+
+1. User runs `npx hive run ./src` from their project
+2. CLI copies `starter/` to `.hive/` in user's project
+3. Framework loads user's code from `HIVE_SRC` env var
+4. Schemas, endpoints, handlers merge at runtime
+
+**Key mechanism:** User code in `/src/` extends framework code in `/.hive/`. The framework reads from `process.env.HIVE_SRC` to find user schemas, endpoints, handlers, and config.
+
+---
+
+## Development
+
+```bash
+# Test CLI locally (from repo root)
+node cli/hive.js run ./path/to/test-project/src
+
+# The starter/ folder IS the framework
+# Changes here affect all projects using Hive
+```
+
+---
+
+## Boundaries
+
+| Location | What it is | Editable |
+|----------|-----------|----------|
+| `cli/` | CLI tools | ✅ Yes |
+| `starter/` | Framework core | ✅ Yes |
+| `starter/.cursor/skills/` | Cursor skills for end-users | ✅ Yes |
+| User's `/src/` | User code (not in this repo) | N/A |
+| User's `/.hive/` | Auto-generated, never edit | N/A |
+
+---
+
+## When Editing Skills
+
+Skills in `starter/.cursor/skills/` are documentation for projects **using** Hive. Each skill:
+- Has a `SKILL.md` with frontmatter (name, description, globs)
+- Teaches Cursor how to write code for Hive projects
+- Should be concise and pattern-focused
+
+---
+
+## Philosophy
+
+> Technology should solve people's issues, not create new weird ones.
+
+When in doubt: simpler is better. Challenge unnecessary complexity.

package/README.md

@@ -0,0 +1,271 @@
+# 🐝 Hive
+
+**An AI-native backend framework for engineers who are *pissed off* about the complexity of modern technology.**
+
+Hive preconfigures the entire backend stack: database, cache, queues, event handlers, auth, real-time — so you don't duct-tape different pieces yourself. It dictates a clean architecture that's easy to understand, easy to read, and scales to millions of users.
+
+```bash
+npm install -g @paralect/hive
+
+hive init my-app
+cd my-app
+hive run ./src
+```
+
+Your API is live. MongoDB, validation, auth infrastructure, real-time events — all preconfigured.
+
+---
+
+## 🤖 AI-Native Development
+
+Hive is designed for AI coding assistants. Open your project in Cursor and build with natural language:
+
+```
+add-resource tasks
+add-endpoint tasks post title, status, assignee: { _id }
+add-endpoint tasks get page, perPage
+add-handler tasks
+```
+
+### Commands
+
+| Command | What it does |
+|---------|--------------|
+| `add-resource tasks` | Create resource with schema + folders |
+| `add-endpoint tasks post title, dueOn` | Create POST endpoint with inferred types |
+| `add-endpoint tasks get page, perPage` | Create GET list endpoint |
+| `add-endpoint tasks update /:id title` | Create PUT endpoint |
+| `add-handler tasks` | Create event handlers for DB changes |
+| `add-middleware isAdmin` | Create custom middleware |
+| `add-service slack sendMessage` | Create service with go-to library |
+| `add-scheduler sendReport daily at 9am` | Create cron job |
+
+The AI understands Hive conventions and generates production-ready code.
+
+---
+
+## What's Preconfigured
+
+| Concern | Solution |
+|---------|----------|
+| Database | MongoDB with auto-generated services per schema |
+| Validation | Zod schemas, auto-applied to all endpoints |
+| Auth | Token-based auth infrastructure, ready to extend |
+| Events | Persistent handlers that react to DB changes |
+| Real-time | Socket.io with Redis adapter for scaling |
+| Queues | BullMQ for background jobs |
+| Scheduler | Cron-based jobs, no external service needed |
+| Auto-sync | Embedded documents stay fresh automatically |
+
+You focus on your product. Hive handles the plumbing.
+
+---
+
+## Architecture
+
+Every feature is a **resource** — a folder with predictable structure:
+
+```
+src/resources/{name}/
+├── {name}.schema.js      # Data shape (required)
+├── endpoints/            # API routes
+├── handlers/             # React to DB events
+└── methods/              # Shared logic
+```
+
+This scales. New developers understand it in minutes. Your codebase stays clean at 10 endpoints or 1000.
+
+---
+
+## 📦 Schemas
+
+Define your data once. Hive creates the collection and service.
+
+```javascript
+import { z } from 'zod';
+import dbSchema from 'helpers/schema/db.schema.js';
+
+const schema = dbSchema.extend({
+  title: z.coerce.string().nullable().optional(),
+  status: z.coerce.string().default('pending'),
+  assignee: z.object({
+    _id: z.string(),
+    fullName: z.coerce.string().nullable().optional(),
+  }).nullable().optional(),
+});
+
+export default schema;
+export const secureFields = ['internalNotes'];
+```
+
+Every schema gets `_id`, `createdOn`, `updatedOn` automatically.
+
+---
+
+## 🔌 Endpoints
+
+Four exports. No router config.
+
+```javascript
+import { z } from 'zod';
+import db from 'db';
+
+const tasksService = db.services.tasks;
+
+export const middlewares = [];
+
+export const requestSchema = z.object({
+  page: z.coerce.number().default(1),
+  perPage: z.coerce.number().default(20),
+});
+
+export const handler = async (ctx) => {
+  const { page, perPage } = ctx.validatedData;
+  return tasksService.find({}, { page, perPage, sort: '-createdOn' });
+};
+
+export const endpoint = {
+  url: '/',
+  method: 'get',
+};
+```
+
+Route auto-generated as `GET /tasks`.
+
+---
+
+## 🗄️ Database
+
+Auto-generated services for every schema:
+
+```javascript
+import db from 'db';
+
+const tasksService = db.services.tasks;
+
+// Find
+const { results, count } = await tasksService.find({ status: 'active' }, { page: 1, perPage: 20 });
+const task = await tasksService.findOne({ _id: id });
+
+// Create
+const task = await tasksService.create({ title: 'New', user: ctx.state.user });
+
+// Update
+await tasksService.updateOne({ _id: id }, (doc) => ({ ...doc, status: 'done' }));
+
+// Delete
+await tasksService.remove({ _id: id });
+```
+
+---
+
+## ⚡ Handlers
+
+React to database changes. Perfect for side effects, notifications, syncing data.
+
+```javascript
+import db from 'db';
+import ifUpdated from 'helpers/db/ifUpdated';
+
+const tasksService = db.services.tasks;
+
+tasksService.on('created', async ({ doc }) => {
+  // Send notification, create activity log, etc.
+});
+
+tasksService.on('updated', ifUpdated(['status'], async ({ doc, prevDoc }) => {
+  // Only runs when status changed
+}));
+
+tasksService.on('removed', async ({ doc }) => {
+  // Cleanup related data
+});
+```
+
+---
+
+## 🛡️ Middlewares
+
+Built-in: `allowNoAuth`, `isAuthorized`, `shouldExist`, `attachUser`
+
+Custom:
+
+```javascript
+export default async (ctx, next) => {
+  if (!ctx.state.user?.isAdmin) ctx.throw(403, 'Admin only');
+  return next();
+};
+```
+
+---
+
+## ⏰ Scheduler
+
+Background jobs with cron:
+
+```javascript
+import db from 'db';
+
+export const handler = async () => {
+  await db.services.invoices.updateMany(
+    { isPaid: { $ne: true }, dueOn: { $lt: new Date() } },
+    (doc) => ({ ...doc, isOverdue: true })
+  );
+};
+
+export const cron = '0 9 * * *';
+```
+
+---
+
+## 🔄 Auto-Sync
+
+Embedded documents stay fresh. When a user updates their name, all tasks with that user update automatically.
+
+```json
+{
+  "tasks": {
+    "assignee": { "schema": "users" }
+  }
+}
+```
+
+---
+
+## CLI
+
+```bash
+hive init [name]      # Create new project
+hive run [path]       # Start dev server
+hive prepare [path]   # Build for production
+hive deploy           # Deploy to Hive Cloud
+hive install <plugin> # Install plugin
+hive login            # Login to Hive Cloud
+```
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   ├── resources/        # Your features
+│   ├── middlewares/      # Custom middlewares
+│   ├── services/         # External APIs
+│   └── scheduler/handlers/
+└── .hive/                # Framework (don't edit)
+```
+
+---
+
+## Tech Stack
+
+Proven, boring technology:
+
+- **Koa** — Node.js framework
+- **MongoDB** — Document database
+- **Zod** — Schema validation
+- **Socket.io** — Real-time
+- **BullMQ** — Job queues
+- **Redis** — Cache & pub/sub

package/cli/hive.js

@@ -8,7 +8,73 @@ const mergeDirs = require('./helpers/mergeDirs');
 const execCommand = require('./helpers/execCommand');
 const downloadDirectory = require('./helpers/downloadDirectory');
 const axios = require('axios');
-const tsx = require('tsx/cjs/api')
+const tsx = require('tsx/cjs/api');
+const fs = require('fs');
+
+program
+  .command('init [projectName]')
+  .description('Initialize a new Hive project')
+  .action(async (projectName) => {
+    try {
+      let name = projectName;
+
+      if (!name) {
+        const answer = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'projectName',
+            message: 'Project name:',
+            default: 'my-hive-app'
+          }
+        ]);
+        name = answer.projectName;
+      }
+
+      const projectDir = path.resolve(process.cwd(), name);
+
+      console.log(`\n🐝 Creating Hive project: ${name}\n`);
+
+      await execCommand(`mkdir -p ${projectDir}/src/resources`);
+      await execCommand(`mkdir -p ${projectDir}/src/middlewares`);
+      await execCommand(`mkdir -p ${projectDir}/src/services`);
+      await execCommand(`mkdir -p ${projectDir}/src/scheduler/handlers`);
+
+      fs.writeFileSync(
+        path.join(projectDir, 'package.json'),
+        JSON.stringify({
+          name,
+          version: '1.0.0',
+          scripts: {
+            dev: 'hive run ./src',
+            start: 'hive run ./src'
+          },
+          dependencies: {}
+        }, null, 2)
+      );
+
+      fs.writeFileSync(
+        path.join(projectDir, '.env'),
+        `MONGO_URI=mongodb://localhost:27017/${name}\nPORT=3001\nNODE_ENV=development\n`
+      );
+
+      fs.writeFileSync(
+        path.join(projectDir, '.gitignore'),
+        `node_modules\n.hive\n.env\n`
+      );
+
+      await execCommand(`cp -r ${path.resolve(__dirname, '..')}/starter/.cursor ${projectDir}/`);
+
+      console.log(`✅ Project created!\n`);
+      console.log(`Next steps:\n`);
+      console.log(`  cd ${name}`);
+      console.log(`  hive run ./src\n`);
+      console.log(`Start building with AI commands:`);
+      console.log(`  add-resource tasks`);
+      console.log(`  add-endpoint tasks post title, status\n`);
+    } catch (error) {
+      console.error('An error occurred:', error.message);
+    }
+  });
 
 program
   .command('run [dirPath]')
@@ -16,7 +82,7 @@ program
   .action(async (dirPath = '.') => {
     try {
       process.env.HIVE_SRC = path.resolve(process.cwd(), dirPath);
-      
+
       const hiveProjectDir = path.resolve(process.env.HIVE_SRC, `../.hive`);
       await execCommand(`mkdir -p ${hiveProjectDir}`);
       await execCommand(`cp -r ${path.resolve(__dirname, '..')}/starter/ ${hiveProjectDir}`);
@@ -27,7 +93,7 @@ program
     }
   });
 
-  program
+program
   .command('prepare [dirPath]')
   .description('Prepare Hive server')
   .action(async (dirPath = '.') => {
@@ -42,7 +108,7 @@ program
     }
   });
 
-  program
+program
   .command('deploy')
   .description('Build hive project')
   .action(async () => {
@@ -50,7 +116,7 @@ program
       let outDir = path.resolve(process.cwd(), './dist');
       await mergeDirs({ hiveSrc: path.resolve(process.cwd()), outDir });
 
-      console.log('outDir',  path.resolve(outDir, `./deploy/script`))
+      console.log('outDir', path.resolve(outDir, `./deploy/script`))
       await execCommand(`npm install --prefix ${path.resolve(outDir, `./deploy/script`)}`);
 
       await execCommand('node ./index.js', {
@@ -67,7 +133,7 @@ program
   .action(async (plugin) => {
     try {
       const destDir = process.cwd();
-      
+
       await downloadDirectory(plugin);
     } catch (error) {
       console.error('An error occurred:', error.message);
@@ -80,12 +146,14 @@ program
   .description('Login into Hive Cloud')
   .action(async () => {
     if (process.env.HIVE_TOKEN) {
-      const user = (await axios({ url: `https://hive-api-test.paralect.co/users/me`, method: 'get', headers: {
-        'Authorization': `Bearer ${process.env.HIVE_TOKEN}`
-      } })).data;
+      const user = (await axios({
+        url: `https://hive-api-test.paralect.co/users/me`, method: 'get', headers: {
+          'Authorization': `Bearer ${process.env.HIVE_TOKEN}`
+        }
+      })).data;
 
       console.log(`Already logged in!`, user);
-      
+
       return;
     }
 
@@ -99,7 +167,7 @@ program
 
     try {
       await axios({ url: `https://hive-api-test.paralect.co/auth/login-code`, method: 'post', data: { email } });
-      
+
       const { code } = await inquirer.prompt([
         {
           type: 'input',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paralect/hive",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "",
   "main": "index.js",
   "bin": {