@paralect/hive 0.1.48 → 0.1.50-alpha.0

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/helpers/docker.js

@@ -0,0 +1,59 @@
+const { execSync } = require('child_process');
+
+const isDockerInstalled = () => {
+  try {
+    execSync('docker --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const getContainerStatus = (name) => {
+  try {
+    const result = execSync(`docker inspect --format='{{.State.Status}}' ${name}`, { 
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    return result.trim();
+  } catch {
+    return null; // Container doesn't exist
+  }
+};
+
+const startContainer = async (name, image, port, extraArgs = '') => {
+  const status = getContainerStatus(name);
+
+  if (status === 'running') {
+    console.log(`  ${name} already running`);
+    return true;
+  }
+
+  if (status === 'exited' || status === 'created') {
+    console.log(`  Starting ${name}...`);
+    execSync(`docker start ${name}`, { stdio: 'inherit' });
+    return true;
+  }
+
+  // Container doesn't exist, create it
+  console.log(`  Creating ${name}...`);
+  const cmd = `docker run -d --name ${name} -p ${port}:${port} ${extraArgs} ${image}`;
+  execSync(cmd, { stdio: 'inherit' });
+  return true;
+};
+
+const startMongo = async () => {
+  return startContainer('hive-mongo', 'mongo:7', 27017);
+};
+
+const startRedis = async () => {
+  return startContainer('hive-redis', 'redis:7-alpine', 6379);
+};
+
+module.exports = {
+  isDockerInstalled,
+  getContainerStatus,
+  startContainer,
+  startMongo,
+  startRedis,
+};

package/cli/helpers/envCheck.js

@@ -0,0 +1,123 @@
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+
+const hashCode = (str) => {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash);
+};
+
+const readEnvFile = (envPath) => {
+  if (!fs.existsSync(envPath)) {
+    return {};
+  }
+  
+  const content = fs.readFileSync(envPath, 'utf8');
+  const env = {};
+  
+  content.split('\n').forEach(line => {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const [key, ...valueParts] = trimmed.split('=');
+      if (key) {
+        env[key.trim()] = valueParts.join('=').trim();
+      }
+    }
+  });
+  
+  return env;
+};
+
+const writeEnvFile = (envPath, env) => {
+  const content = Object.entries(env)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('\n') + '\n';
+  
+  fs.writeFileSync(envPath, content);
+};
+
+const updateEnvFile = (envPath, updates) => {
+  const env = readEnvFile(envPath);
+  Object.assign(env, updates);
+  writeEnvFile(envPath, env);
+};
+
+const ensureEnvConfig = async (projectDir) => {
+  const envPath = path.join(projectDir, '.env');
+  const env = readEnvFile(envPath);
+  const projectName = path.basename(projectDir);
+  const updates = {};
+  
+  // Check MONGODB_URI
+  if (!env.MONGODB_URI) {
+    const { mongoChoice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'mongoChoice',
+      message: 'MONGODB_URI not set. How would you like to configure MongoDB?',
+      choices: [
+        { name: 'Use local Docker (localhost:27017)', value: 'local' },
+        { name: 'Enter custom URI', value: 'custom' },
+      ]
+    }]);
+    
+    if (mongoChoice === 'local') {
+      updates.MONGODB_URI = `mongodb://localhost:27017/${projectName}`;
+    } else {
+      const { mongoUri } = await inquirer.prompt([{
+        type: 'input',
+        name: 'mongoUri',
+        message: 'Enter MongoDB URI:',
+        default: `mongodb://localhost:27017/${projectName}`
+      }]);
+      updates.MONGODB_URI = mongoUri;
+    }
+  }
+  
+  // Check REDIS_URI
+  if (!env.REDIS_URI) {
+    const { redisChoice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'redisChoice',
+      message: 'REDIS_URI not set. How would you like to configure Redis?',
+      choices: [
+        { name: 'Use local Docker (localhost:6379)', value: 'local' },
+        { name: 'Enter custom URI', value: 'custom' },
+        { name: 'Skip (Redis optional)', value: 'skip' },
+      ]
+    }]);
+    
+    if (redisChoice === 'local') {
+      const redisDb = hashCode(projectName) % 16;
+      updates.REDIS_URI = `redis://localhost:6379/${redisDb}`;
+    } else if (redisChoice === 'custom') {
+      const { redisUri } = await inquirer.prompt([{
+        type: 'input',
+        name: 'redisUri',
+        message: 'Enter Redis URI:',
+        default: `redis://localhost:6379/0`
+      }]);
+      updates.REDIS_URI = redisUri;
+    }
+  }
+  
+  // Write updates if any
+  if (Object.keys(updates).length > 0) {
+    updateEnvFile(envPath, updates);
+    console.log(`\n  Updated .env with: ${Object.keys(updates).join(', ')}\n`);
+  }
+  
+  return { ...env, ...updates };
+};
+
+module.exports = {
+  readEnvFile,
+  writeEnvFile,
+  updateEnvFile,
+  ensureEnvConfig,
+  hashCode,
+};

package/cli/helpers/findPort.js

@@ -0,0 +1,32 @@
+const net = require('net');
+
+const isPortAvailable = (port) => {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    
+    server.once('error', () => {
+      resolve(false);
+    });
+    
+    server.once('listening', () => {
+      server.close();
+      resolve(true);
+    });
+    
+    server.listen(port, '127.0.0.1');
+  });
+};
+
+const findAvailablePort = async (startPort = 3001, maxAttempts = 100) => {
+  for (let port = startPort; port < startPort + maxAttempts; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available port found between ${startPort} and ${startPort + maxAttempts - 1}`);
+};
+
+module.exports = {
+  isPortAvailable,
+  findAvailablePort,
+};