@gzl10/nexus-backend 0.14.0 → 0.15.0

package/claude-commands/nexus-docs.md

@@ -0,0 +1,66 @@
+# Nexus documentation lookup
+
+Search Nexus documentation and explain a concept with examples.
+
+## Arguments
+
+$ARGUMENTS — Concept to look up (e.g. "hooks", "tree entity", "CASL permissions", "field factories", "computed entity", "standalone actions")
+
+## Step 1: Search documentation files
+
+Search these files in order for relevant information:
+
+1. **AGENTS.md** files (quick reference with gotchas):
+   - `packages/sdk/AGENTS.md`
+   - `packages/backend/AGENTS.md`
+   - `packages/client/AGENTS.md`
+   - `packages/ui/AGENTS.md`
+
+2. **llms.txt** (project overview and file map)
+
+3. **CLAUDE.md** (conventions and patterns)
+
+4. **Source code** (for detailed API):
+   - `packages/sdk/src/types/` — type definitions
+   - `packages/sdk/src/fields/` — field factories
+   - `packages/backend/src/runtime/` — entity services
+   - `packages/backend/src/core/` — middleware, CASL, events
+
+Use Grep to search for the concept across these files.
+
+## Step 2: Search demo code
+
+Check demos for usage examples:
+
+- `demos/backend-demo/` — app developer patterns
+- `demos/plugin-demo/` — plugin developer patterns
+
+## Step 3: Explain
+
+Present the answer in this format:
+
+```markdown
+## {Concept}
+
+**What:** One-line description
+
+**When to use:** Scenarios where this applies
+
+**Example:**
+{Minimal working code example}
+
+**Gotchas:**
+- {List of common mistakes}
+
+**Reference files:**
+- {Paths to relevant source files}
+```
+
+## Rules
+
+- Always include a working code example (not pseudocode)
+- Include gotchas specific to the concept
+- Reference the actual source files where the implementation lives
+- If the concept has different behavior per entity type, show each
+- Do NOT make up API signatures — verify against actual source code
+- This command works WITHOUT Neural MCP — it reads local files only

package/claude-commands/nexus-new-action.md

@@ -0,0 +1,99 @@
+# Create a new Nexus standalone action
+
+Add a standalone action to a module. Actions are operations without dedicated persistence (send email, export, batch process).
+
+## Arguments
+
+$ARGUMENTS — Action name (e.g. "export-csv", "send-report", "sync-data"). Kebab-case.
+
+## Step 1: Detect context
+
+Find which module to add the action to:
+
+1. Check current directory — if inside `src/modules/{name}/`, use that module
+2. Otherwise, list available modules and ask
+
+## Step 2: Ask for details
+
+1. **Scope** — where does the action button appear?
+   - `module` — button in the module toolbar (no entity context)
+   - `entity` — button in entity list toolbar (entity context, no specific row)
+   - `row` — dropdown per row (receives `:id` param)
+
+2. **Input fields** — does the action need a form before executing? (optional)
+3. **Output** — what to show after execution?
+   - No output (just success notification)
+   - Structured output (modal with fields)
+   - Page redirect
+4. **Variant** — button style: `default`, `primary`, `danger`
+
+## Step 3: Generate action file
+
+Create `src/modules/{module}/actions/{name}.action.ts`:
+
+```typescript
+import type { ActionDefinition, ModuleContext, Request, Response } from '@gzl10/nexus-sdk'
+import { useTextField, useSelectField } from '@gzl10/nexus-sdk/fields'
+
+export const {camelName}Action: ActionDefinition = {
+  name: '{kebab-name}',
+  label: { en: '{Label}', es: '{Etiqueta}' },
+  icon: '{icon}',
+  scope: '{scope}',       // 'module' | 'entity' | 'row'
+  variant: 'primary',
+
+  // Input form (optional — omit if no form needed)
+  input: {
+    format: useSelectField({
+      label: { en: 'Format', es: 'Formato' },
+      options: [
+        { value: 'csv', label: 'CSV' },
+        { value: 'json', label: 'JSON' }
+      ]
+    })
+  },
+
+  // Handler
+  handler: (ctx: ModuleContext) => async (req: Request, res: Response) => {
+    const { format } = req.body
+
+    // Action logic here
+    // Use ctx.db, ctx.services, ctx.logger, ctx.errors
+
+    res.json({ success: true, message: 'Action completed' })
+  },
+
+  casl: {
+    subject: '{Subject}',
+    permissions: {
+      ADMIN: { actions: ['execute'] }
+    }
+  }
+}
+```
+
+## Step 4: Update module manifest
+
+Read the module's `index.ts`, add the import, and include in `actions[]`:
+
+```typescript
+import { {camelName}Action } from './actions/{name}.action.js'
+
+// Add to manifest
+actions: [...existing, {camelName}Action]
+```
+
+## Step 5: Verify
+
+```bash
+npx tsc --noEmit
+```
+
+## Gotchas
+
+- Actions use `handler: (ctx) => async (req, res) => {}` — factory pattern like hooks
+- `scope: 'row'` actions receive `req.params.id`
+- `input` defines the form shown before execution (Record<string, FieldDefinition>)
+- `output: {}` shows raw JSON result, `output` with fields shows structured modal
+- `batch: true` + `timeout: number` for batch processing with SSE progress
+- `disabled` accepts `FieldCondition` for per-row client-side evaluation

package/claude-commands/nexus-new-entity.md

@@ -0,0 +1,142 @@
+# Create a new Nexus entity
+
+Add an entity to an existing module.
+
+## Arguments
+
+$ARGUMENTS — Entity type and name (e.g. "collection products", "single settings", "tree categories"). If only name given, defaults to collection.
+
+## Step 1: Detect context
+
+Find which module to add the entity to:
+
+1. Check current directory — if inside `src/modules/{name}/`, use that module
+2. Otherwise, list available modules and ask:
+   ```bash
+   ls src/modules/
+   ```
+
+## Step 2: Ask for details
+
+Parse type from arguments (collection/single/tree/dag/view/computed). Then ask:
+
+**For collection:**
+- Table name (default: argument name)
+- Label (en/es)
+- Fields to include (suggest common ones)
+- Timestamps? (default: yes)
+- Soft delete? (default: no)
+- CASL subject name
+
+**For single:**
+- Key name (e.g. "{module}_settings")
+- Label
+- Fields
+- Default values
+
+**For tree:**
+- Table name
+- Label
+- Fields (id and a labelField at minimum)
+
+## Step 3: Generate entity file
+
+Create `src/modules/{module}/entities/{name}.ts`:
+
+### Collection template
+
+```typescript
+import type { CollectionEntityDefinition } from '@gzl10/nexus-sdk'
+import { useIdField, useTextField } from '@gzl10/nexus-sdk/fields'
+
+export const {name}Entity: CollectionEntityDefinition = {
+  table: '{table_name}',
+  type: 'collection',
+  label: { en: '{Label}', es: '{Etiqueta}' },
+  labelField: '{first_text_field}',
+  timestamps: true,
+
+  fields: {
+    id: useIdField(),
+    // ... generated fields
+  },
+
+  casl: {
+    subject: '{Subject}',
+    permissions: {
+      ADMIN: { actions: ['manage'] },
+      EDITOR: { actions: ['read', 'create', 'update'] },
+      USER: { actions: ['read'] }
+    }
+  }
+}
+```
+
+### Single template
+
+```typescript
+import type { SingleEntityDefinition } from '@gzl10/nexus-sdk'
+
+export const {name}Entity: SingleEntityDefinition = {
+  type: 'single',
+  key: '{key_name}',
+  label: { en: '{Label}', es: '{Etiqueta}' },
+  icon: 'Settings',
+
+  fields: {
+    // ... generated fields
+  },
+
+  defaults: {
+    // ... matching fields
+  }
+}
+```
+
+### Tree template
+
+```typescript
+import type { TreeEntityDefinition } from '@gzl10/nexus-sdk'
+import { useIdField, useTextField } from '@gzl10/nexus-sdk/fields'
+
+export const {name}Entity: TreeEntityDefinition = {
+  table: '{table_name}',
+  type: 'tree',
+  label: { en: '{Label}', es: '{Etiqueta}' },
+  labelField: '{first_text_field}',
+
+  fields: {
+    id: useIdField(),
+    // ... generated fields
+  },
+
+  seed: []
+  // parent_id is auto-injected — do NOT define it
+}
+```
+
+## Step 4: Update module manifest
+
+Read the module's `index.ts`, add the import, and include in `definitions[]`:
+
+```typescript
+import { {name}Entity } from './entities/{name}.js'
+
+// Add to definitions array
+definitions: [...existing, {name}Entity]
+```
+
+## Step 5: Run migration
+
+```bash
+npx nexus migrate dev
+```
+
+## Gotchas
+
+- Always use field factories from `@gzl10/nexus-sdk/fields`
+- `required` is top-level, not inside `validation`
+- Select options: direct array `[{value, label}]`
+- Tree requires `seed` (can be `[]`)
+- Single uses `key`, not `table`
+- Entity updates use PUT (not PATCH) — relevant for hooks

package/claude-commands/nexus-new-module.md

@@ -0,0 +1,78 @@
+# Create a new Nexus module
+
+Scaffold a new module in the current project. Modules are auto-discovered from `src/modules/`.
+
+## Arguments
+
+$ARGUMENTS — Module name (e.g. "inventory", "crm", "blog"). Lowercase, no spaces.
+
+## Step 1: Detect project structure
+
+Find the modules directory:
+
+```
+src/modules/          # standard location
+```
+
+If not found, ask the user where modules live.
+
+Check existing modules to avoid name collisions:
+
+```bash
+ls src/modules/
+```
+
+## Step 2: Ask for details
+
+Ask the user (if not provided in arguments):
+
+1. **Category** — one of: content, data, assets, messaging, jobs, ai, analytics, integrations, commerce, security, legal, settings
+2. **Icon** — Ionicons 5 icon name (suggest based on category)
+3. **Initial entity?** — yes/no. If yes, ask type: collection, single, or tree
+
+## Step 3: Generate module
+
+Create `src/modules/{name}/index.ts`:
+
+```typescript
+import type { ModuleManifest } from '@gzl10/nexus-sdk'
+// import entities here
+
+export const {name}Module: ModuleManifest = {
+  name: '{name}',
+  label: { en: '{Name}', es: '{Nombre}' },
+  icon: '{icon}',
+  category: '{category}',
+  definitions: []
+}
+```
+
+**Conventions (CRITICAL):**
+- Named export: `export const {name}Module` — NOT `export default`
+- Category must be one of the 12 valid values — NO 'custom'
+- definitions[] array for entities — they auto-mount, no manual routes
+
+## Step 4: Generate initial entity (if requested)
+
+Use the same patterns as `/nexus-new-entity` but inline here:
+
+- **collection**: `table`, `labelField`, field factories from `@gzl10/nexus-sdk/fields`, `casl`
+- **single**: `key` (not table), `defaults`
+- **tree**: `table`, `seed: []`, parent_id auto-injected
+
+Add the entity import and include it in `definitions[]`.
+
+## Step 5: Verify
+
+```bash
+npx tsc --noEmit
+```
+
+## Gotchas
+
+- Entities use `table` (collection/tree) or `key` (single), NOT `name`
+- Field `required` is top-level in factory config, NOT inside `validation`
+- `useSelectField` options is a direct array `[{value, label}]`, NOT `{static: [...]}`
+- Tree entities require `seed` (can be empty `[]`)
+- Hooks pattern: `hooks: (ctx) => ({ beforeCreate: async (data) => { return data } })`
+- Individual hooks do NOT receive ctx — only the wrapper function does

package/claude-commands/nexus-new-plugin.md

@@ -0,0 +1,153 @@
+# Create a new Nexus plugin
+
+Scaffold a complete plugin project from scratch.
+
+## Arguments
+
+$ARGUMENTS — Plugin name (e.g. "bookmarks", "analytics", "notifications"). Lowercase, no spaces.
+
+## Step 1: Ask for details
+
+1. **Code** — exactly 3 lowercase chars, unique (e.g. "bkm", "anl", "ntf"). Validated: `/^[a-z]{3}$/`
+2. **Category** — one of: content, data, assets, messaging, jobs, ai, analytics, integrations, commerce, security, legal, settings
+3. **Description** — short description (en/es)
+4. **Where to create** — default: current directory as `nexus-plugin-{name}/`
+
+## Step 2: Generate scaffold
+
+Create the following structure:
+
+```
+nexus-plugin-{name}/
+├── src/
+│   ├── index.ts              # PluginManifest + ModuleManifest
+│   └── entities/
+│       └── {name}.ts         # Example collection entity
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+└── README.md
+```
+
+### package.json
+
+```json
+{
+  "name": "@{scope}/nexus-plugin-{name}",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "{description}",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "migrations"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "peerDependencies": {
+    "@gzl10/nexus-sdk": ">=0.14.0"
+  },
+  "devDependencies": {
+    "@gzl10/nexus-sdk": "^0.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}
+```
+
+Ask the user for `@{scope}` (their npm scope).
+
+### tsup.config.ts
+
+```typescript
+import { defineConfig } from 'tsup'
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true
+})
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### src/index.ts
+
+```typescript
+import type { PluginManifest, ModuleManifest } from '@gzl10/nexus-sdk'
+import { {name}Entity } from './entities/{name}.js'
+
+const {name}Module: ModuleManifest = {
+  name: '{name}',
+  label: { en: '{Name}', es: '{Nombre}' },
+  icon: '{icon}',
+  category: '{category}',
+  definitions: [{name}Entity]
+}
+
+export { {name}Module, {name}Entity }
+
+export const {name}Plugin: PluginManifest = {
+  name: '@{scope}/nexus-plugin-{name}',
+  code: '{code}',
+  label: { en: '{Name}', es: '{Nombre}' },
+  icon: '{icon}',
+  version: '1.0.0',
+  description: { en: '{description_en}', es: '{description_es}' },
+  category: '{category}',
+  modules: [{name}Module]
+}
+
+export default {name}Plugin
+```
+
+### Example entity
+
+Generate a collection entity using the same pattern as `/nexus-new-entity` with basic fields (id, name, description).
+
+### README.md
+
+Generate with: what the plugin does, installation (`nexus plugin add`), configuration (if envVars), and entity descriptions.
+
+## Step 3: Initialize
+
+```bash
+cd nexus-plugin-{name}
+pnpm install
+pnpm typecheck
+```
+
+## Gotchas
+
+- `code` must be exactly 3 lowercase chars — validated by `registerPlugin()`
+- `export default` the PluginManifest (plugins use default export, modules use named)
+- `peerDependencies` on `@gzl10/nexus-sdk` — not direct dependency
+- `files: ["dist", "migrations"]` — include migrations dir even if empty initially
+- Plugin name in PluginManifest.name must match package.json name exactly
+- Users install with `nexus plugin add`, not `pnpm add`

package/claude-commands/nexus-update-tutorial-app.md

@@ -0,0 +1,61 @@
+# Update the App Tutorial in Notion
+
+Regenerate the "Tutorial: App basada en Nexus" Notion page from current code and documentation.
+
+## Target
+
+Notion page: `3234fc3785408042be6bf648a2876c54`
+
+## Step 1: Read current sources
+
+Read these files to understand the current state of the API:
+
+1. `packages/sdk/AGENTS.md` — SDK reference and gotchas
+2. `packages/backend/AGENTS.md` — Backend reference, CLI, gotchas
+3. `packages/client/AGENTS.md` — Client reference, NexusApi structure
+4. `packages/ui/AGENTS.md` — UI reference, bootstrap, composables
+5. `demos/backend-demo/src/modules/` — app developer examples
+6. `demos/frontend-demo/src/main.ts` — frontend bootstrap example
+7. `packages/sdk/src/types/entity.ts` — entity definition types (verify signatures)
+8. `packages/sdk/src/types/manifest.ts` — ModuleManifest, Category (verify valid values)
+9. `packages/sdk/src/fields/` — check for new/changed field factories
+
+## Step 2: Read current tutorial
+
+```
+mcp__claude_ai_Notion__notion-fetch(id: "3234fc3785408042be6bf648a2876c54")
+```
+
+## Step 3: Compare and identify changes
+
+For each section of the tutorial, check if the code snippets and descriptions still match the current API:
+
+- Entity definition signatures (table vs name, key, etc.)
+- Field factory parameters and available factories
+- Hooks signature
+- CLI commands
+- Client API (login, createEntityClient, PaginatedResult)
+- bootstrap() options
+- Available plugins list
+- Category valid values
+
+## Step 4: Update Notion
+
+Use `mcp__claude_ai_Notion__notion-update-page` with `command: "update_content"` to update only the sections that changed.
+
+**Rules:**
+- Preserve the section structure (13 sections)
+- Only update code snippets and descriptions that are outdated
+- Keep cross-references to plugin tutorial intact
+- All code examples must be verified against current source code
+- Do NOT guess API signatures — read the actual types
+
+## Step 5: Report
+
+Show summary of what changed:
+
+| Section | Status | What changed |
+|---------|--------|-------------|
+| 1. Prerrequisitos | unchanged | — |
+| 5. Entity types | updated | Added new entity type X |
+| ... | ... | ... |

package/claude-commands/nexus-update-tutorial-plugin.md

@@ -0,0 +1,53 @@
+# Update the Plugin Tutorial in Notion
+
+Regenerate the "Tutorial: Plugin para Nexus" Notion page from current code and documentation.
+
+## Target
+
+Notion page: `3234fc37854080d9a5dece31975385d2`
+
+## Step 1: Read current sources
+
+Read these files to understand the current state of the plugin API:
+
+1. `packages/sdk/AGENTS.md` — SDK reference and gotchas
+2. `packages/backend/AGENTS.md` — Backend reference, CLI, gotchas
+3. `demos/plugin-demo/` — plugin developer reference (all files)
+4. `plugins/tags/src/index.ts` — simplest real plugin
+5. `packages/sdk/src/types/manifest.ts` — PluginManifest interface (verify)
+6. `packages/sdk/src/types/entity.ts` — entity types (verify)
+7. `packages/backend/src/cli.ts` — CLI commands (verify plugin commands)
+
+## Step 2: Read current tutorial
+
+```
+mcp__claude_ai_Notion__notion-fetch(id: "3234fc37854080d9a5dece31975385d2")
+```
+
+## Step 3: Compare and identify changes
+
+For each section, check if snippets match current API:
+
+- PluginManifest interface (properties, code validation)
+- ModuleManifest within plugins
+- Entity definition signatures
+- Field factory parameters
+- CLI plugin commands (add, remove, enable, disable)
+- Migration commands for plugins
+- ctx (ModuleContext) properties
+- Plugin conventions (code, peerDeps, exports, files)
+- List of existing plugins and their codes
+
+## Step 4: Update Notion
+
+Use `mcp__claude_ai_Notion__notion-update-page` with `command: "update_content"` to update only changed sections.
+
+**Rules:**
+- Preserve the 14-section structure
+- Cross-references to App tutorial must remain valid
+- All code examples verified against source
+- Update the plugins reference table (section 14) if new plugins were added
+
+## Step 5: Report
+
+Show summary of changes per section.