@open-mercato/cli 0.4.7-main-1768da2e43 → 0.4.7

package/build.mjs

@@ -1,6 +1,6 @@
 import * as esbuild from 'esbuild'
 import { glob } from 'glob'
-import { readFileSync, writeFileSync, chmodSync, existsSync } from 'node:fs'
+import { readFileSync, writeFileSync, chmodSync, existsSync, cpSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -92,4 +92,11 @@ const binContent = readFileSync(binPath, 'utf-8')
 writeFileSync(binPath, '#!/usr/bin/env node\n' + binContent)
 chmodSync(binPath, 0o755)
 
+// Copy agentic source files from create-app so generators can read them at runtime
+const agenticSrc = join(__dirname, '..', 'create-app', 'agentic')
+if (existsSync(agenticSrc)) {
+  cpSync(agenticSrc, join(outdir, 'agentic'), { recursive: true })
+  console.log('Copied create-app/agentic/ → dist/agentic/')
+}
+
 console.log('CLI built successfully')

package/dist/agentic/claude-code/CLAUDE.md.template

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/agentic/claude-code/hooks/entity-migration-check.ts

@@ -0,0 +1,121 @@
+/**
+ * Claude Code PostToolUse hook: entity-migration-check
+ *
+ * Fires after Write/Edit/MultiEdit. Detects entity file modifications
+ * without an accompanying migration and blocks the agent with a reminder.
+ *
+ * Three-state logic:
+ * 1. Migration file was written → exit 0 (agent is already on it)
+ * 2. Not an entity file → exit 0 (not relevant)
+ * 3. Entity written, no fresh migration → block with migration instructions
+ */
+
+import { readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
+const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
+
+interface PostToolUseInput {
+  tool_input?: {
+    file_path?: string
+    content?: string
+  }
+  tool_name?: string
+}
+
+function getRelativePath(filePath: string): string {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  if (filePath.startsWith('/')) {
+    return relative(projectDir, filePath)
+  }
+  return filePath
+}
+
+function hasFreshMigration(moduleId: string): boolean {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
+
+  try {
+    const files = readdirSync(migrationsDir)
+    const now = Date.now()
+    const thirtySecondsAgo = now - 30_000
+
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const stat = statSync(join(migrationsDir, file))
+      if (stat.mtimeMs > thirtySecondsAgo) {
+        return true
+      }
+    }
+  } catch {
+    // migrations directory doesn't exist yet — that's fine
+  }
+
+  return false
+}
+
+async function main(): Promise<void> {
+  let input = ''
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  if (!input.trim()) {
+    process.exit(0)
+  }
+
+  let data: PostToolUseInput
+  try {
+    data = JSON.parse(input)
+  } catch {
+    process.exit(0)
+  }
+
+  const filePath = data.tool_input?.file_path
+  if (!filePath) {
+    process.exit(0)
+  }
+
+  const rel = getRelativePath(filePath)
+
+  // State 1: Migration file was written → agent is already handling it
+  if (MIGRATION_PATTERN.test(rel)) {
+    process.exit(0)
+  }
+
+  // State 2: Not an entity file → not relevant
+  const entityMatch = rel.match(ENTITY_PATTERN)
+  if (!entityMatch) {
+    process.exit(0)
+  }
+
+  const moduleId = entityMatch[1]
+
+  // State 3: Entity written — check for fresh migration
+  if (hasFreshMigration(moduleId)) {
+    process.exit(0)
+  }
+
+  // Block: entity modified without migration
+  const result = {
+    decision: 'block',
+    reason: [
+      `Entity file modified: ${rel}`,
+      '',
+      `Affected module: ${moduleId}`,
+      '',
+      'A database migration is likely needed. Ask the user whether to run:',
+      '  yarn db:generate',
+      '',
+      'Then regenerate registries:',
+      '  yarn generate',
+      '',
+      'Do NOT run migrations automatically — always confirm with the user first.',
+    ].join('\n'),
+  }
+
+  process.stdout.write(JSON.stringify(result))
+}
+
+main()

package/dist/agentic/claude-code/mcp.json.example

@@ -0,0 +1,13 @@
+{
+  "_comment": "Copy to .mcp.json and set MCP_API_KEY (printed by yarn initialize)",
+  "mcpServers": {
+    "open-mercato": {
+      "command": "yarn",
+      "args": ["mercato", "mcp:dev"],
+      "env": {
+        "APP_URL": "http://localhost:3000",
+        "MCP_API_KEY": "${MCP_API_KEY}"
+      }
+    }
+  }
+}

package/dist/agentic/claude-code/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx tsx \"$CLAUDE_PROJECT_DIR/.claude/hooks/entity-migration-check.ts\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/agentic/codex/enforcement-rules.md

@@ -0,0 +1,20 @@
+<!-- CODEX_ENFORCEMENT_RULES_START -->
+## CRITICAL rules — always follow without exception
+
+1. **After editing any entity file** (`src/modules/<id>/entities/*.ts`):
+   - STOP immediately before any further action
+   - Tell the user: "I modified an entity in module <id>. Should I create a migration?"
+   - If yes: run `yarn db:generate`
+   - Show the generated migration to the user before applying
+   - Ask for confirmation, then run `yarn db:migrate`
+   - Run `yarn generate` after migration is applied
+
+2. **After editing `src/modules.ts`**: immediately run `yarn generate`
+
+3. **Never edit `.mercato/generated/*`**: edit the source and run `yarn generate` instead
+
+4. **Before significant features**: check `.ai/specs/` for an existing spec.
+   If none exists, ask the user whether to create one first.
+
+---
+<!-- CODEX_ENFORCEMENT_RULES_END -->

package/dist/agentic/codex/mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "open-mercato": {
+      "command": "yarn",
+      "args": ["mercato", "mcp:dev"],
+      "env": {
+        "APP_URL": "http://localhost:3000",
+        "MCP_API_KEY": "${MCP_API_KEY}"
+      }
+    }
+  }
+}

package/dist/agentic/cursor/hooks/entity-migration-check.mjs

@@ -0,0 +1,69 @@
+/**
+ * Cursor afterFileEdit hook: entity-migration-check
+ *
+ * Detects entity file modifications without an accompanying migration
+ * and exits non-zero to block the agent with a reminder.
+ *
+ * Three-state logic:
+ * 1. Migration file was written → exit 0 (agent is already on it)
+ * 2. Not an entity file → exit 0 (not relevant)
+ * 3. Entity written, no fresh migration → exit 1 with warning
+ */
+
+import { readdirSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const ENTITY_RE = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
+const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
+
+function hasFreshMigration(projectDir, moduleId) {
+  const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
+  try {
+    const files = readdirSync(migrationsDir)
+    const cutoff = Date.now() - 30_000
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const stat = statSync(join(migrationsDir, file))
+      if (stat.mtimeMs > cutoff) return true
+    }
+  } catch {
+    // migrations directory doesn't exist yet
+  }
+  return false
+}
+
+const filePath = process.argv[2]
+if (!filePath) process.exit(0)
+
+const projectDir = resolve('.')
+const rel = filePath.startsWith('/') ? filePath.slice(projectDir.length + 1) : filePath
+
+// State 1: Migration file written
+if (MIGRATION_RE.test(rel)) process.exit(0)
+
+// State 2: Not an entity file
+const match = rel.match(ENTITY_RE)
+if (!match) process.exit(0)
+
+const moduleId = match[1]
+
+// State 3: Entity file without fresh migration
+if (hasFreshMigration(projectDir, moduleId)) process.exit(0)
+
+process.stderr.write(
+  [
+    `Entity file modified: ${rel}`,
+    '',
+    `Affected module: ${moduleId}`,
+    '',
+    'A database migration is likely needed. Ask the user whether to run:',
+    '  yarn db:generate',
+    '',
+    'Then regenerate registries:',
+    '  yarn generate',
+    '',
+    'Do NOT run migrations automatically — always confirm with the user first.',
+    '',
+  ].join('\n'),
+)
+process.exit(1)

package/dist/agentic/cursor/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterFileEdit": {
+      "command": "node",
+      "args": [".cursor/hooks/entity-migration-check.mjs"],
+      "description": "Check if entity edit requires a database migration"
+    }
+  }
+}

package/dist/agentic/cursor/mcp.json.example

@@ -0,0 +1,13 @@
+{
+  "_comment": "Copy to .cursor/mcp.json and set MCP_API_KEY (printed by yarn initialize)",
+  "mcpServers": {
+    "open-mercato": {
+      "command": "yarn",
+      "args": ["mercato", "mcp:dev"],
+      "env": {
+        "APP_URL": "http://localhost:3000",
+        "MCP_API_KEY": "${MCP_API_KEY}"
+      }
+    }
+  }
+}

package/dist/agentic/cursor/rules/entity-guard.mdc

@@ -0,0 +1,29 @@
+---
+description: Entity modification guard — triggers migration workflow
+globs:
+  - src/modules/*/entities/**/*.ts
+alwaysApply: false
+---
+
+# Entity Modification — Migration Required
+
+You are editing an entity file. After saving, you MUST:
+
+1. **Create a migration** — ask the user before running:
+   ```
+   yarn db:generate
+   ```
+
+2. **Show the migration** to the user and wait for confirmation before applying
+
+3. **Apply the migration** (only after user confirms):
+   ```
+   yarn db:migrate
+   ```
+
+4. **Regenerate registries**:
+   ```
+   yarn generate
+   ```
+
+Do NOT skip any step. Do NOT run migrations without user confirmation.

package/dist/agentic/cursor/rules/generated-guard.mdc

@@ -0,0 +1,12 @@
+---
+description: Prevent editing auto-generated files
+globs:
+  - .mercato/generated/**
+alwaysApply: false
+---
+
+# NEVER Edit Generated Files
+
+This file is auto-generated by `yarn generate`. Any manual edits will be overwritten.
+
+To change generated output, edit the source modules in `src/modules/` and run `yarn generate`.

package/dist/agentic/cursor/rules/open-mercato.mdc

@@ -0,0 +1,34 @@
+---
+description: Core Open Mercato conventions for standalone app development
+alwaysApply: true
+---
+
+# {{PROJECT_NAME}} — Project Rules
+
+## What this project is
+
+A standalone Open Mercato application. Build domain features ON TOP of the framework.
+To customise a core module beyond the extension system: `yarn mercato eject <module>`.
+Never edit node_modules/@open-mercato/* directly.
+
+## Task routing
+
+Read AGENTS.md before starting any task — it maps task types to the minimum files to load.
+
+## Module system
+
+Modules in `src/modules/<id>/`. Register with `from: '@app'` in `src/modules.ts`.
+Run `yarn generate` after any module or entity change. Never edit `.mercato/generated/*`.
+
+## Entity and migration rule
+
+After editing any entity in `src/modules/<id>/entities/`:
+1. Create migration: `yarn db:generate`
+2. Show migration to user, confirm before applying
+3. Apply: `yarn db:migrate`
+4. Regenerate: `yarn generate`
+
+## Spec-driven development
+
+Check `.ai/specs/` before any significant feature. If no spec exists, ask the user
+whether to create one first.

package/dist/agentic/shared/AGENTS.md.template

@@ -0,0 +1,180 @@
+# Agent Context Routing — {{PROJECT_NAME}}
+
+Read this file before any task. Load ONLY the files listed for your task type.
+Do NOT load the entire src/ tree — Open Mercato apps can have many modules.
+
+## What This Project Is
+
+A standalone Open Mercato application built ON TOP of the framework.
+The framework lives in `node_modules/@open-mercato/*`. Never edit `node_modules` directly.
+To customise a built-in module beyond extensions, eject with `yarn mercato eject <module>`.
+
+## Task → Context Map
+
+Match your task, then load the listed file(s) BEFORE writing code. A task may match multiple rows.
+
+### Module Development
+
+| Task | Load |
+|---|---|
+| Scaffold a new module from scratch | `.ai/skills/module-scaffold/SKILL.md` |
+| Design entities and relationships | `.ai/skills/data-model-design/SKILL.md` |
+| Build backend UI (forms, tables, pages) | `.ai/skills/backend-ui-design/SKILL.md` |
+| Build an integration provider | `.ai/skills/integration-builder/SKILL.md` |
+
+### Extending Core Modules (UMES)
+
+| Task | Load |
+|---|---|
+| Extend a core module (add fields, columns, menus, interceptors, enrichers) | `.ai/skills/system-extension/SKILL.md` |
+| Eject and customize a core module | `.ai/skills/eject-and-customize/SKILL.md` |
+| Add a response enricher to another module's API | `.ai/guides/core.md` → Response Enrichers |
+| Add an API interceptor (before/after hooks) | `.ai/guides/core.md` → API Interceptors |
+| Inject widgets into forms/tables/menus | `.ai/guides/core.md` → Widget Injection |
+| Replace or wrap a UI component | `.ai/guides/core.md` → Component Replacement |
+
+### Framework Feature Usage
+
+| Task | Load |
+|---|---|
+| Add/modify an entity, create migration | `.ai/guides/core.md` → Module Files, then `yarn db:generate` |
+| Add a REST API endpoint | `.ai/guides/core.md` → API Routes |
+| Add a backend page | `.ai/guides/ui.md` → CrudForm / DataTable |
+| Add event subscribers or emit events | `.ai/guides/events.md` |
+| Add real-time browser updates (SSE) | `.ai/guides/events.md` → DOM Event Bridge |
+| Add search to a module | `.ai/guides/search.md` |
+| Add caching | `.ai/guides/cache.md` |
+| Add background workers | `.ai/guides/queue.md` |
+| Use i18n (translations) | `.ai/guides/shared.md` → i18n |
+| Use encrypted queries | `.ai/guides/shared.md` → Encryption |
+| Use apiCall / UI components | `.ai/guides/ui.md` |
+| Add permissions (RBAC) | `.ai/guides/core.md` → Access Control |
+| Add notifications | `.ai/guides/core.md` → Notifications |
+| Add custom fields | `.ai/guides/core.md` → Custom Fields |
+
+### Quality & Process
+
+| Task | Load |
+|---|---|
+| Debug / fix errors | `.ai/skills/troubleshooter/SKILL.md` |
+| Review code changes | `.ai/skills/code-review/SKILL.md` |
+| Write a spec | `.ai/skills/spec-writing/SKILL.md`, `.ai/specs/SPEC-000-template.md` |
+
+## Module Anatomy
+
+Each module in `src/modules/<id>/` is self-contained and auto-discovered:
+
+```
+src/modules/<id>/
+├── index.ts              # Module metadata
+├── data/
+│   ├── entities.ts       # MikroORM entity classes
+│   ├── validators.ts     # Zod validation schemas
+│   ├── extensions.ts     # Cross-module entity links
+│   └── enrichers.ts      # Response enrichers
+├── api/
+│   ├── <resource>/route.ts  # REST handlers (auto-discovered by method)
+│   └── interceptors.ts      # API route interception hooks
+├── backend/              # Admin UI pages (auto-discovered)
+│   └── page.tsx          # → /backend/<module>
+├── frontend/             # Public pages (auto-discovered)
+├── subscribers/          # Event handlers (export metadata + default handler)
+├── workers/              # Background jobs (export metadata + default handler)
+├── widgets/
+│   ├── injection/        # UI widgets injected into other modules
+│   ├── injection-table.ts # Widget-to-slot mappings
+│   └── components.ts     # Component replacement/wrapper definitions
+├── di.ts                 # Awilix DI registrations
+├── acl.ts                # Permission features
+├── setup.ts              # Tenant init, role features, seed data
+├── events.ts             # Typed event declarations
+├── search.ts             # Search indexing configuration
+├── ce.ts                 # Custom entities / custom field sets
+├── translations.ts       # Translatable fields per entity
+├── notifications.ts      # Notification type definitions
+└── notifications.client.ts  # Client-side notification renderers
+```
+
+Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
+
+## Critical Conventions
+
+- After any module/entity change: `yarn generate`
+- After any entity edit: `yarn db:generate` (never hand-write migrations)
+- NEVER edit `.mercato/generated/*` — auto-generated
+- NEVER edit `node_modules/@open-mercato/*` — eject instead
+- Custom modules use `from: '@app'` in `src/modules.ts`
+- Confirm migrations with user before `yarn db:migrate`
+
+## Naming Conventions
+
+- Module IDs: plural, snake_case (`order_items`)
+- Event IDs: `module.entity.action` (singular entity, past tense: `sales.order.created`)
+- DB tables: plural, snake_case with module prefix (`catalog_products`)
+- DB columns: snake_case (`created_at`, `organization_id`)
+- JS/TS identifiers: camelCase
+- Feature IDs: `<module>.<action>` (`my_module.view`, `my_module.create`)
+- UUID primary keys, explicit foreign keys, junction tables for M2M
+
+## Key Imports Quick Reference
+
+```typescript
+// Translations
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+// API calls (MUST use — never raw fetch)
+import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+
+// CRUD forms
+import { CrudForm, createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/crud'
+import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+
+// UI components (MUST use — never raw <button>)
+import { Button } from '@open-mercato/ui/primitives/button'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { FormHeader, FormFooter } from '@open-mercato/ui/backend/forms'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+// Encrypted queries (MUST use instead of em.find)
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Events
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+// Widget injection
+import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'
+
+// Types
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'
+import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'
+```
+
+## Key Commands
+
+| Command | Purpose |
+|---|---|
+| `yarn dev` | Start dev server |
+| `yarn generate` | Regenerate `.mercato/generated/` |
+| `yarn db:generate` | Create migration for entity changes |
+| `yarn db:migrate` | Apply pending migrations |
+| `yarn initialize` | Bootstrap DB + first admin account |
+| `yarn build` | Build for production |
+| `yarn mercato eject <module>` | Copy a core module into `src/modules/` |
+
+## Architecture Rules
+
+- NO direct ORM relationships between modules — use foreign key IDs
+- Always filter by `organization_id` for tenant-scoped entities
+- Validate all inputs with Zod; derive types via `z.infer`
+- Use DI (Awilix) for services; avoid `new`-ing directly
+- No `any` types — use Zod schemas with `z.infer`, narrow with runtime checks
+- Every dialog: `Cmd/Ctrl+Enter` submit, `Escape` cancel
+- Keep `pageSize` at or below 100
+- Every API route MUST export `openApi`
+
+## Stack
+
+Next.js App Router, TypeScript, MikroORM, Awilix DI, Zod

package/dist/agentic/shared/ai/lessons.md

@@ -0,0 +1,4 @@
+# Lessons Learned
+
+Record patterns, mistakes, and insights discovered during development.
+AI agents will update this file as they work on the codebase.