@open-mercato/cli 0.6.7-develop.6862.1.c11a64ce0a → 0.6.7

package/.turbo/turbo-build.log

@@ -1,5 +1,6 @@
-[build:cli] found 101 entry points
+[build:cli] found 96 entry points
 Copied create-app/agentic/ → dist/agentic/
+Discovered 7 standalone guides → dist/agentic/guides/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
@@ -19,13 +20,14 @@ Copied create-app/agentic/ → dist/agentic/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customers
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dashboards
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for data_sync
-[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for design_system
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dictionaries
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for directory
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for entities
+Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
+[build:cli] built successfully
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
@@ -55,5 +57,3 @@ Copied create-app/agentic/ → dist/agentic/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for storage_s3
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_akeneo
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for webhooks
-Generated 55 module fact-sheets → dist/agentic/guides/modules/
-[build:cli] built successfully

package/build.mjs

@@ -1,5 +1,4 @@
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { atomicWriteFileSync } from '../../scripts/lib/add-js-extension.mjs'
@@ -27,26 +26,11 @@ await buildPackage(packageDir, {
     // Copy agentic source files from create-app so generators can read them at runtime.
     const agenticSrc = join(packageDir, '..', 'create-app', 'agentic')
     if (existsSync(agenticSrc)) {
-      rmSync(join(outdir, 'agentic'), { recursive: true, force: true })
       cpSync(agenticSrc, join(outdir, 'agentic'), { recursive: true })
       console.log('Copied create-app/agentic/ → dist/agentic/')
     }
 
-    const repositoryRoot = join(packageDir, '..', '..')
-    const upstreamDir = join(outdir, 'agentic', 'guides', 'upstream')
-    mkdirSync(upstreamDir, { recursive: true })
-    const cliVersion = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')).version ?? null
-    const upstreamManifest = { version: 1, generator: `@open-mercato/cli@${cliVersion ?? 'unknown'}`, files: {} }
-    for (const file of ['AGENTS.md', 'BACKWARD_COMPATIBILITY.md']) {
-      const source = join(repositoryRoot, file)
-      const destination = join(upstreamDir, file)
-      cpSync(source, destination)
-      upstreamManifest.files[file] = createHash('sha256').update(readFileSync(source)).digest('hex')
-    }
-    writeFileSync(join(upstreamDir, 'manifest.json'), `${JSON.stringify(upstreamManifest, null, 2)}\n`)
-
-    // Discover module-specific standalone guides across sibling packages. Package-level
-    // guides are intentionally not shipped because they duplicate routed conceptual guides.
+    // Discover standalone guides across sibling packages.
     const packagesDir = join(packageDir, '..')
     const guidesDestDir = join(outdir, 'agentic', 'guides')
     mkdirSync(guidesDestDir, { recursive: true })
@@ -55,7 +39,8 @@ await buildPackage(packageDir, {
     // retains a removed module's full guide or fact-sheet. The legacy `core.<module>.md`
     // redirect stubs are no longer emitted (#3754); this purge also deletes any that linger
     // in an incremental `dist/` from an older build. Mirrors packages/create-app/build.mjs;
-    // conceptual guides remain while stale single-dot package guides are removed below.
+    // the conceptual `module-system.md` and the single-dot package guides are
+    // re-copied/re-discovered below.
     rmSync(join(guidesDestDir, 'modules'), { recursive: true, force: true })
     for (const entry of readdirSync(guidesDestDir)) {
       if (/^core\..+\.md$/.test(entry)) {
@@ -65,11 +50,10 @@ await buildPackage(packageDir, {
 
     let guidesFound = 0
     for (const pkg of readdirSync(packagesDir)) {
-      // Package-level source guides remain for monorepo context, but standalone apps route
-      // through conceptual and module-level guides, so remove their stale emitted copies.
       const guideSource = join(packagesDir, pkg, 'agentic', 'standalone-guide.md')
       if (existsSync(guideSource)) {
-        rmSync(join(guidesDestDir, `${pkg}.md`), { force: true })
+        cpSync(guideSource, join(guidesDestDir, `${pkg}.md`))
+        guidesFound++
       }
 
       const modulesDir = join(packagesDir, pkg, 'src', 'modules')
@@ -92,7 +76,7 @@ await buildPackage(packageDir, {
     // the freshly built ts-morph extractor + resolver-routed discovery, so
     // `mercato agentic:init` bundles the same guides as a create-mercato-app scaffold
     // (packages/create-app/build.mjs). Discovery goes through the resolver, never a
-    // hardcoded packages/* path (.ai/lessons/standalone-scaffolding-and-generators-must-not-assume.md).
+    // hardcoded packages/* path (.ai/lessons.md §161-169).
     const { extractAllModuleFacts, renderModuleFactsJson } = await import(
       pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href
     )
@@ -111,7 +95,7 @@ await buildPackage(packageDir, {
         coreVersion = null
       }
 
-      const { factsByModule, markdownByModule, frameworkMarkdown, warnings } = extractAllModuleFacts({
+      const { factsByModule, markdownByModule, warnings } = extractAllModuleFacts({
         sources,
         registryPath: existsSync(registryPath) ? registryPath : null,
         coreVersion,
@@ -123,7 +107,6 @@ await buildPackage(packageDir, {
         writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
       }
       writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
-      writeFileSync(join(guidesDestDir, 'framework-extension-points.md'), frameworkMarkdown)
 
       for (const warning of warnings) console.warn(warning)
       console.log(`Generated ${Object.keys(markdownByModule).length} module fact-sheets → dist/agentic/guides/modules/`)

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

@@ -1,65 +1,121 @@
-/** Remind Claude Code to generate and review a schema diff after entity edits. */
+/**
+ * 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\/([^/]+)\/data\/entities\.ts$/
-const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
+const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
+const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
 
 interface PostToolUseInput {
-  tool_input?: { file_path?: string }
-}
-
-function projectDir(): string {
-  return process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  tool_input?: {
+    file_path?: string
+    content?: string
+  }
+  tool_name?: string
 }
 
-function normalizedRelative(filePath: string): string {
-  const value = filePath.startsWith('/') ? relative(projectDir(), filePath) : filePath
-  return value.replaceAll('\\', '/')
+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 migrationsDir = join(projectDir(), 'src', 'modules', moduleId, 'migrations')
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
+
   try {
-    const cutoff = Date.now() - 30_000
-    return readdirSync(migrationsDir).some((file) =>
-      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
-    )
+    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 {
-    return false
+    // 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()) return
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  if (!input.trim()) {
+    process.exit(0)
+  }
 
   let data: PostToolUseInput
   try {
     data = JSON.parse(input)
   } catch {
-    return
+    process.exit(0)
   }
 
   const filePath = data.tool_input?.file_path
-  if (!filePath) return
-  const rel = normalizedRelative(filePath)
-  if (MIGRATION_PATTERN.test(rel)) return
+  if (!filePath) {
+    process.exit(0)
+  }
 
-  const match = rel.match(ENTITY_PATTERN)
-  if (!match || hasFreshMigration(match[1])) return
+  const rel = getRelativePath(filePath)
 
-  process.stdout.write(JSON.stringify({
+  // 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 contract changed: ${rel}`,
+      `Entity file modified: ${rel}`,
+      '',
+      `Affected module: ${moduleId}`,
+      '',
+      'A database migration is likely needed. Ask the user whether to run:',
+      '  yarn db:generate',
       '',
-      'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
-      'Run `yarn generate` when discovery changed.',
-      'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
+      'Then regenerate registries:',
+      '  yarn generate',
+      '',
+      'Do NOT run migrations automatically — always confirm with the user first.',
     ].join('\n'),
-  }))
+  }
+
+  process.stdout.write(JSON.stringify(result))
 }
 
-void main()
+main()

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

@@ -1,6 +1,20 @@
 <!-- CODEX_ENFORCEMENT_RULES_START -->
-## Codex enforcement
+## CRITICAL rules — always follow without exception
 
-Read and route through the rest of this file; its `Always`, `Never`, and Task Router sections are the authority for Codex too. They are stated once below rather than duplicated here, so this prelude costs the router no budget.
+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 mercato db generate`
+   - Show the generated migration to the user before applying
+   - Ask for confirmation, then run `yarn mercato 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/cursor/hooks/entity-migration-check.mjs

@@ -1,38 +1,69 @@
-/** Remind Cursor to generate and review a schema diff after entity edits. */
+/**
+ * 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, relative, resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 
-const ENTITY_RE = /^src\/modules\/([^/]+)\/data\/entities\.ts$/
-const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
+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
-    return readdirSync(migrationsDir).some((file) =>
-      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
-    )
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const stat = statSync(join(migrationsDir, file))
+      if (stat.mtimeMs > cutoff) return true
+    }
   } catch {
-    return false
+    // 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('/') ? relative(projectDir, filePath) : filePath).replaceAll('\\', '/')
+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 || hasFreshMigration(projectDir, match[1])) process.exit(0)
-
-process.stderr.write([
-  `Entity contract changed: ${rel}`,
-  '',
-  'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
-  'Run `yarn generate` when discovery changed.',
-  'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
-  '',
-].join('\n'))
+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/rules/entity-guard.mdc

@@ -1,17 +1,29 @@
 ---
-description: Entity schema-diff guard for the canonical standalone entity file
+description: Entity modification guard — triggers migration workflow
 globs:
-  - src/modules/*/data/entities.ts
+  - src/modules/*/entities/**/*.ts
 alwaysApply: false
 ---
 
-# Entity Schema Change
+# Entity Modification — Migration Required
 
-Follow root `AGENTS.md` and `om-data-model-design`:
+You are editing an entity file. After saving, you MUST:
 
-1. Run `yarn db:generate` as a schema-diff probe.
-2. Review and keep only scoped migration SQL plus the touched module snapshot.
-3. Run `yarn generate` when discovery changed.
-4. Ask before applying with `yarn db:migrate`.
+1. **Create a migration** — ask the user before running:
+   ```
+   yarn db:generate
+   ```
 
-Never edit a shipped migration or generated registry.
+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

@@ -1,10 +1,12 @@
 ---
-description: Prevent edits to generated application registries
+description: Prevent editing auto-generated files
 globs:
   - .mercato/generated/**
 alwaysApply: false
 ---
 
-# Generated File
+# NEVER Edit Generated Files
 
-Do not edit this file. Change the app module source and run `yarn generate`; follow root `AGENTS.md` for the routed contract.
+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

@@ -1,8 +1,34 @@
 ---
-description: Route every standalone app task through the root agent rules
+description: Core Open Mercato conventions for standalone app development
 alwaysApply: true
 ---
 
-# {{PROJECT_NAME}} — Cursor Entry Point
+# {{PROJECT_NAME}} — Project Rules
 
-Read `AGENTS.md`, match every applicable Task Router row, and load only the routed guides, skills, and module facts. The root file owns architecture, safety, writable paths, migrations, generation, and validation; do not duplicate or override it here.
+## 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/guides/cache.md

@@ -0,0 +1,45 @@
+# Cache Package — Standalone Developer Guide
+
+`@open-mercato/cache` provides tenant-scoped caching with tag-based invalidation. MUST NOT use raw Redis, SQLite, or in-memory caching directly.
+
+## Strategy Selection
+
+| Strategy | When | Config |
+|----------|------|--------|
+| Memory | Development, single-process | Default (no config) |
+| SQLite | Single-server production | `CACHE_STRATEGY=sqlite` |
+| Redis | Multi-server, shared cache | `CACHE_STRATEGY=redis` |
+
+## Usage
+
+Always resolve via DI:
+
+```typescript
+const cacheService = container.resolve('cacheService')
+
+// Set with tags for targeted invalidation
+await cacheService.set(`${tenantId}:my_module:stats`, value, {
+  tags: [`tenant:${tenantId}`, 'my_module'],
+})
+
+// Get
+const cached = await cacheService.get(`${tenantId}:my_module:stats`)
+
+// Invalidate by tag (clears all entries with that tag)
+await cacheService.invalidateTag('my_module')
+```
+
+## MUST Rules
+
+1. **MUST resolve via DI** — `container.resolve('cacheService')`, never instantiate directly
+2. **MUST scope to tenant** — include `tenantId` in cache keys
+3. **MUST use tag-based invalidation** for CRUD side effects
+4. **MUST NOT cache sensitive data** without encryption
+
+## Adding Cache to a Module
+
+1. Resolve `cacheService` from DI in your service or route handler
+2. Define cache keys: `${tenantId}:${module}:${identifier}`
+3. Tag entries: `{ tags: ['tenant:123', 'my_module'] }`
+4. Add cache invalidation to CRUD side effects (`emitCrudSideEffects` with `cacheAliases`)
+5. Test with `CACHE_STRATEGY=memory` (default in dev)