@paralect/hive 0.1.48 → 0.1.49

package/starter/.cursor/skills/hive-middleware/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: hive-middleware
+description: How to create and use middlewares in Hive framework
+globs:
+  - src/middlewares/*.js
+alwaysApply: false
+---
+
+# Middlewares
+
+Location: `/src/middlewares/{name}.js`
+
+## Built-in Middlewares
+
+| Name | Purpose |
+|------|---------|
+| `allowNoAuth` | Skip authentication |
+| `isAuthorized` | Require authenticated user |
+| `shouldExist` | Load resource, 404 if not found |
+| `attachUser` | Load user from token |
+
+## Creating Middleware
+
+**Simple:**
+```javascript
+export default async (ctx, next) => {
+  // Before handler
+  if (!ctx.state.user?.isAdmin) {
+    ctx.throw(403, 'Admin only');
+  }
+  return next();  // Don't forget!
+};
+```
+
+**With parameters:**
+```javascript
+export default (resourceName) => async (ctx, next) => {
+  const doc = await db.services[resourceName].findOne({
+    _id: ctx.params[`${resourceName}Id`],
+  });
+  
+  if (!doc) ctx.throw(404, `${resourceName} not found`);
+  
+  ctx.state[resourceName] = doc;
+  return next();
+};
+```
+
+**With runOrder (lower runs first):**
+```javascript
+const middleware = async (ctx, next) => {
+  ctx.state.isSkipAuth = true;
+  return next();
+};
+middleware.runOrder = -1;
+export default middleware;
+```
+
+## Using in Endpoints
+
+```javascript
+// By name
+export const middlewares = ['allowNoAuth'];
+
+// With arguments
+export const middlewares = [{ name: 'shouldExist', args: ['projects'] }];
+
+// Direct import
+import isAdmin from 'middlewares/isAdmin';
+export const middlewares = [isAdmin];
+
+// Factory function
+import canEditProject from 'middlewares/canEditProject';
+export const middlewares = [canEditProject((ctx) => ctx.params.projectId)];
+
+// Inline
+export const middlewares = [
+  async (ctx, next) => {
+    // Custom logic
+    return next();
+  },
+];
+```
+
+## Global Middleware
+
+Create `/src/middlewares/global.js` to run on all endpoints:
+
+```javascript
+import isAuthorized from 'middlewares/isAuthorized';
+import attachRootProject from 'middlewares/attachRootProject';
+
+export default async (ctx, next) => {
+  await isAuthorized(ctx, async () => {
+    await attachRootProject(ctx, next);
+  });
+};
+```
+
+## Rules
+
+- Always call `next()` or throw
+- Use `runOrder` to control execution order
+- Factory functions for parameterized middlewares

package/starter/.cursor/skills/hive-overview/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: hive-overview
+description: Hive framework structure and conventions. Apply when working with this codebase.
+globs:
+  - src/**/*.js
+alwaysApply: false
+---
+
+# Hive Framework Overview
+
+Hive is a Koa-based Node.js framework with MongoDB, Zod validation, and auto-sync for embedded documents.
+
+## Directory Structure
+
+| Directory | Purpose | Edit? |
+|-----------|---------|-------|
+| `/.hive/` | Framework core | No - read only |
+| `/src/` | Application code | Yes |
+
+## Resources
+
+A resource is a feature module in `/src/resources/{name}/`:
+
+```
+src/resources/{name}/
+├── {name}.schema.js      # Required: DB schema
+├── endpoints/            # API routes
+├── handlers/             # Event listeners
+└── methods/              # Reusable functions
+```
+
+## Built-in (in .hive/)
+
+- `tokens` - Auth token storage
+- `users` - Base user schema  
+- `db` - Database layer with services
+
+## Key Imports
+
+```javascript
+import db from 'db';                    // Database
+import config from 'app-config';        // Config
+import { z } from 'zod';                // Validation
+```
+
+## Services Access
+
+```javascript
+const taskService = db.services.tasks;  // Auto-created from schema
+```

package/starter/.cursor/skills/hive-scheduler/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: hive-scheduler
+description: How to create scheduled jobs in Hive framework
+globs:
+  - src/scheduler/handlers/*.js
+alwaysApply: false
+---
+
+# Scheduler Jobs
+
+Background jobs on cron schedules.
+
+Location: `/src/scheduler/handlers/{jobName}.js`
+
+## Template
+
+```javascript
+import db from 'db';
+
+export const handler = async () => {
+  // Job logic
+};
+
+export const cron = '0 * * * *';  // Every hour
+```
+
+## Cron Patterns
+
+```
+┌─ minute (0-59)
+│ ┌─ hour (0-23)
+│ │ ┌─ day of month (1-31)
+│ │ │ ┌─ month (1-12)
+│ │ │ │ ┌─ day of week (0-6)
+* * * * *
+```
+
+| Pattern | Schedule |
+|---------|----------|
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour |
+| `0 */12 * * *` | Every 12 hours |
+| `0 0 * * *` | Daily at midnight |
+| `0 9 * * 1` | Mondays at 9am |
+
+## Examples
+
+**Sync external data:**
+```javascript
+import db from 'db';
+import moment from 'moment';
+import externalApi from 'services/externalApi';
+
+export const handler = async () => {
+  const items = await externalApi.list({
+    updatedSince: moment().subtract(5, 'minutes').toDate(),
+  });
+  
+  for (const item of items) {
+    await db.services.items.updateOne(
+      { externalId: item.id },
+      (doc) => ({ ...doc, ...item })
+    );
+  }
+};
+
+export const cron = '*/5 * * * *';
+```
+
+**Mark overdue:**
+```javascript
+import db from 'db';
+import moment from 'moment';
+
+export const handler = async () => {
+  await db.services.invoices.updateMany(
+    {
+      isPaid: { $ne: true },
+      isDue: { $ne: true },
+      dueOn: { $lt: new Date() },
+    },
+    (doc) => ({ ...doc, isDue: true })
+  );
+};
+
+export const cron = '0 */12 * * *';
+```
+
+## Rules
+
+- Export both `handler` and `cron`
+- Keep jobs idempotent (safe to re-run)
+- Log progress for debugging

package/starter/.cursor/skills/hive-schema/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: hive-schema
+description: How to create database schemas in Hive framework
+globs:
+  - src/resources/**/*.schema.js
+alwaysApply: false
+---
+
+# Creating Database Schemas
+
+Location: `/src/resources/{name}/{name}.schema.js`
+
+## Template
+
+```javascript
+import { z } from 'zod';
+import dbSchema from 'helpers/schema/db.schema.js';
+
+const schema = dbSchema.extend({
+  // Fields here
+});
+
+export default schema;
+
+export const secureFields = []; // Hidden from API responses
+```
+
+## Field Patterns
+
+**Simple fields:**
+```javascript
+title: z.coerce.string().nullable().optional(),
+count: z.coerce.number().nullable().optional(),
+isActive: z.coerce.boolean().nullable().optional(),
+dueOn: z.coerce.date().nullable().optional(),
+```
+
+**Reference to another document:**
+```javascript
+user: z
+  .object({
+    _id: z.string(),
+    fullName: z.coerce.string().nullable().optional(),
+    avatarUrl: z.coerce.string().nullable().optional(),
+  })
+  .nullable()
+  .optional(),
+```
+
+**Array of references:**
+```javascript
+managers: z
+  .array(
+    z.object({
+      _id: z.string(),
+      fullName: z.coerce.string().nullable().optional(),
+    }).nullable().optional(),
+  )
+  .nullable()
+  .optional(),
+```
+
+**Flexible object:**
+```javascript
+data: z.object({}).passthrough().nullable().optional(),
+```
+
+## Rules
+
+- Always use `z.coerce` for type safety
+- Always add `.nullable().optional()` unless required
+- Include fields you need in references (for auto-sync)
+- Add sensitive fields to `secureFields` array

package/starter/.cursor/skills/hive-service/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: hive-service
+description: How to create external services in Hive framework
+globs:
+  - src/services/*.js
+alwaysApply: false
+---
+
+# Services
+
+Services wrap external APIs and utilities.
+
+Location: `/src/services/{name}.js`
+
+## API Client Template
+
+```javascript
+import config from 'app-config';
+import axios from 'axios';
+
+const client = axios.create({
+  baseURL: 'https://api.example.com',
+  headers: {
+    Authorization: `Bearer ${config.example.apiKey}`,
+  },
+});
+
+export default {
+  getItems: async (params) => {
+    const response = await client.get('/items', { params });
+    return response.data;
+  },
+  
+  createItem: async (data) => {
+    const response = await client.post('/items', data);
+    return response.data;
+  },
+};
+```
+
+## SDK Wrapper Template
+
+```javascript
+import config from 'app-config';
+import { WebClient } from '@slack/web-api';
+
+const client = new WebClient(config.slack.botToken);
+
+export default {
+  client,
+  
+  postMessage: async ({ channel, text }) => {
+    return client.chat.postMessage({ channel, text });
+  },
+};
+```
+
+## Utility Service Template
+
+```javascript
+import _ from 'lodash';
+
+export const when = (condition, result, elseResult = {}) => {
+  if (_.isUndefined(condition)) return {};
+  if (!condition) return elseResult;
+  return _.isFunction(result) ? result() : result;
+};
+
+export const base64 = {
+  encode: (obj) => Buffer.from(JSON.stringify(obj)).toString('base64'),
+  decode: (str) => JSON.parse(Buffer.from(str, 'base64').toString()),
+};
+```
+
+## Using Services
+
+```javascript
+import harvest from 'services/harvest';
+import slackService from 'services/slack';
+import { when } from 'services/utils';
+
+// API calls
+const invoices = await harvest.getInvoices({ projectId });
+
+// SDK usage
+await slackService.postMessage({ channel: '#general', text: 'Hello' });
+
+// Utilities
+const query = { ...when(status, { status }) };
+```

package/starter/src/app.js

@@ -14,6 +14,7 @@ import cors from "@koa/cors";
 import helmet from "koa-helmet";
 import qs from "koa-qs";
 import bodyParser from "koa-bodyparser";
+
 import requestLogger from "koa-logger";
 import db from "db";
 import socketIo from "socketIo";
@@ -42,9 +43,9 @@ const main = async () => {
   app.use(bodyParser({
     enableTypes: ["json", "form", "text"],
 
-    formLimit: '10mb',
-    textLimit: '10mb',
-    jsonLimit: '10mb',
+    formLimit: config._hive.bodyParser?.formLimit || "10mb",
+    textLimit: config._hive.bodyParser?.textLimit || "10mb",
+    jsonLimit: config._hive.bodyParser?.jsonLimit || "10mb",
   }));
 
   app.use(mount("/health", get.handler));