create-mercato-app 0.6.5-develop.5382.1.f542de69af → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +40 -17
  2. package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +40 -17
  3. package/package.json +4 -5
  4. package/template/.env.example +19 -0
  5. package/template/.railwayignore +2 -2
  6. package/template/src/modules/example/backend/payments/page.tsx +0 -4
package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md CHANGED
@@ -39,7 +39,7 @@ When the developer reports a problem, follow this order:
39
39
 
40
40
  ### Step 2: Check Generated Files
41
41
 
42
- Run these commands first — they fix 60%+ of issues:
42
+ These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per [Step 4](#step-4-propose-before-fixing)):
43
43
 
44
44
  ```bash
45
45
  yarn generate # Regenerate module discovery files
@@ -61,6 +61,28 @@ ls .mercato/generated/
61
61
  yarn typecheck
62
62
  ```
63
63
 
64
+ ### Step 4: Propose Before Fixing
65
+
66
+ Once you have diagnosed the root cause, **do not apply the fix immediately**. First present:
67
+
68
+ 1. The **root cause** — what is actually broken and why.
69
+ 2. The **proposed fix** — the exact commands and/or code changes you intend to apply.
70
+
71
+ Then **wait for explicit user confirmation** before applying any **mutating** change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.
72
+
73
+ **Read-only diagnostics may run without asking** — they only gather information and change nothing:
74
+
75
+ | Allowed without confirmation (read-only) | Requires confirmation (mutating) |
76
+ |------------------------------------------|----------------------------------|
77
+ | `yarn typecheck` | `yarn generate` |
78
+ | `grep` / file reads / `ls` | `yarn db:generate` |
79
+ | log / browser-console inspection | `yarn db:migrate` |
80
+ | `docker compose ps` | editing files |
81
+ | `curl` against a running endpoint (GET) | restarting the dev server (`yarn dev`) |
82
+ | | `docker compose up` |
83
+
84
+ When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.
85
+
64
86
  ---
65
87
 
66
88
  ## 2. Module Issues
@@ -76,24 +98,24 @@ yarn typecheck
76
98
  // Must have this entry:
77
99
  { id: '<module_id>', from: '@app' }
78
100
  ```
79
- Fix: Add the entry and run `yarn generate`.
101
+ Proposed fix: Add the entry and run `yarn generate`.
80
102
 
81
103
  2. **Did you run `yarn generate`?**
82
104
  Check if `.mercato/generated/` contains your module's entries.
83
- Fix: Run `yarn generate`.
105
+ Proposed fix: Run `yarn generate`.
84
106
 
85
107
  3. **Is the module folder named correctly?**
86
108
  Must be plural, snake_case: `src/modules/<module_id>/`
87
- Fix: Rename folder to match module ID.
109
+ Proposed fix: Rename folder to match module ID.
88
110
 
89
111
  4. **Does `index.ts` export `metadata`?**
90
112
  ```typescript
91
113
  export const metadata: ModuleInfo = { name: '<module_id>', ... }
92
114
  ```
93
- Fix: Add the metadata export.
115
+ Proposed fix: Add the metadata export.
94
116
 
95
117
  5. **Is the dev server running with latest changes?**
96
- Fix: Restart with `yarn dev`.
118
+ Proposed fix: Restart with `yarn dev`.
97
119
 
98
120
  ### Module loads but pages 404
99
121
 
@@ -104,17 +126,17 @@ yarn typecheck
104
126
  1. **Are backend page files in the right location?**
105
127
  - List page: `backend/page.tsx` (not `backend/index.tsx`)
106
128
  - Detail page: `backend/<entities>/[id].tsx` (bracket notation)
107
- Fix: Rename to match auto-discovery convention.
129
+ Proposed fix: Rename to match auto-discovery convention.
108
130
 
109
131
  2. **Do pages export `metadata` with `requireAuth`?**
110
132
  ```typescript
111
133
  export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
112
134
  ```
113
- Fix: Add metadata export.
135
+ Proposed fix: Add metadata export.
114
136
 
115
137
  3. **Does the user have the required ACL features?**
116
138
  Check `setup.ts` has `defaultRoleFeatures` for the user's role.
117
- Fix: Add features to role defaults, re-run setup.
139
+ Proposed fix: Add features to role defaults, re-run setup.
118
140
 
119
141
  ---
120
142
 
@@ -130,22 +152,22 @@ yarn typecheck
130
152
  ```bash
131
153
  yarn db:generate # Probes/creates migration file
132
154
  ```
133
- Fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
155
+ Proposed fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
134
156
 
135
157
  2. **Is the entity declared in the right file with the right imports?**
136
158
  Entity classes belong in `src/modules/<module_id>/data/entities.ts` and decorators must come from `@mikro-orm/decorators/legacy`.
137
- Fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
159
+ Proposed fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
138
160
 
139
161
  3. **Did you apply the migration?**
140
162
  ```bash
141
163
  yarn db:migrate # Applies pending migrations
142
164
  ```
143
- Fix: Run `yarn db:migrate`.
165
+ Proposed fix: Run `yarn db:migrate`.
144
166
 
145
167
  4. **Is the migration file correct?**
146
168
  Check `src/modules/<module_id>/migrations/` for the latest migration.
147
169
  Verify it has the expected columns and types.
148
- Fix: If wrong, delete the migration file, fix the entity, and regenerate.
170
+ Proposed fix: If wrong, delete the migration file, fix the entity, and regenerate.
149
171
 
150
172
  ### Migration generation creates unexpected changes
151
173
 
@@ -160,11 +182,11 @@ yarn typecheck
160
182
 
161
183
  2. **Did you modify a core module entity without ejecting?**
162
184
  Never edit `node_modules/@open-mercato/*`.
163
- Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
185
+ Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
164
186
 
165
187
  3. **Is a module snapshot stale?**
166
188
  Check whether the generated SQL recreates a table or column that already has a committed migration.
167
- Fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
189
+ Proposed fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
168
190
 
169
191
  ### Entity changes not reflected
170
192
 
@@ -443,9 +465,10 @@ yarn dev # 5. Restart dev server
443
465
 
444
466
  ## Rules
445
467
 
446
- - **ALWAYS** run `yarn generate` as first diagnostic step
468
+ - **ALWAYS** present the diagnosed root cause and the proposed fix (commands/code), then **wait for explicit user confirmation before applying any mutating change** (see [Step 4](#step-4-propose-before-fixing)). Only read-only diagnostics may run without asking.
447
469
  - **ALWAYS** check server logs / browser console for actual error messages
448
470
  - **NEVER** edit files in `.mercato/generated/` or `node_modules/`
449
471
  - **NEVER** assume the issue — verify with actual error output
472
+ - Treat `yarn generate` as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
450
473
  - Fix the root cause, not the symptom — temporary workarounds become permanent bugs
451
- - When suggesting a fix, include the exact command or code change needed
474
+ - When proposing a fix, include the exact command or code change needed
package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md CHANGED
@@ -39,7 +39,7 @@ When the developer reports a problem, follow this order:
39
39
 
40
40
  ### Step 2: Check Generated Files
41
41
 
42
- Run these commands first — they fix 60%+ of issues:
42
+ These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per [Step 4](#step-4-propose-before-fixing)):
43
43
 
44
44
  ```bash
45
45
  yarn generate # Regenerate module discovery files
@@ -61,6 +61,28 @@ ls .mercato/generated/
61
61
  yarn typecheck
62
62
  ```
63
63
 
64
+ ### Step 4: Propose Before Fixing
65
+
66
+ Once you have diagnosed the root cause, **do not apply the fix immediately**. First present:
67
+
68
+ 1. The **root cause** — what is actually broken and why.
69
+ 2. The **proposed fix** — the exact commands and/or code changes you intend to apply.
70
+
71
+ Then **wait for explicit user confirmation** before applying any **mutating** change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.
72
+
73
+ **Read-only diagnostics may run without asking** — they only gather information and change nothing:
74
+
75
+ | Allowed without confirmation (read-only) | Requires confirmation (mutating) |
76
+ |------------------------------------------|----------------------------------|
77
+ | `yarn typecheck` | `yarn generate` |
78
+ | `grep` / file reads / `ls` | `yarn db:generate` |
79
+ | log / browser-console inspection | `yarn db:migrate` |
80
+ | `docker compose ps` | editing files |
81
+ | `curl` against a running endpoint (GET) | restarting the dev server (`yarn dev`) |
82
+ | | `docker compose up` |
83
+
84
+ When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.
85
+
64
86
  ---
65
87
 
66
88
  ## 2. Module Issues
@@ -76,24 +98,24 @@ yarn typecheck
76
98
  // Must have this entry:
77
99
  { id: '<module_id>', from: '@app' }
78
100
  ```
79
- Fix: Add the entry and run `yarn generate`.
101
+ Proposed fix: Add the entry and run `yarn generate`.
80
102
 
81
103
  2. **Did you run `yarn generate`?**
82
104
  Check if `.mercato/generated/` contains your module's entries.
83
- Fix: Run `yarn generate`.
105
+ Proposed fix: Run `yarn generate`.
84
106
 
85
107
  3. **Is the module folder named correctly?**
86
108
  Must be plural, snake_case: `src/modules/<module_id>/`
87
- Fix: Rename folder to match module ID.
109
+ Proposed fix: Rename folder to match module ID.
88
110
 
89
111
  4. **Does `index.ts` export `metadata`?**
90
112
  ```typescript
91
113
  export const metadata: ModuleInfo = { name: '<module_id>', ... }
92
114
  ```
93
- Fix: Add the metadata export.
115
+ Proposed fix: Add the metadata export.
94
116
 
95
117
  5. **Is the dev server running with latest changes?**
96
- Fix: Restart with `yarn dev`.
118
+ Proposed fix: Restart with `yarn dev`.
97
119
 
98
120
  ### Module loads but pages 404
99
121
 
@@ -104,17 +126,17 @@ yarn typecheck
104
126
  1. **Are backend page files in the right location?**
105
127
  - List page: `backend/page.tsx` (not `backend/index.tsx`)
106
128
  - Detail page: `backend/<entities>/[id].tsx` (bracket notation)
107
- Fix: Rename to match auto-discovery convention.
129
+ Proposed fix: Rename to match auto-discovery convention.
108
130
 
109
131
  2. **Do pages export `metadata` with `requireAuth`?**
110
132
  ```typescript
111
133
  export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
112
134
  ```
113
- Fix: Add metadata export.
135
+ Proposed fix: Add metadata export.
114
136
 
115
137
  3. **Does the user have the required ACL features?**
116
138
  Check `setup.ts` has `defaultRoleFeatures` for the user's role.
117
- Fix: Add features to role defaults, re-run setup.
139
+ Proposed fix: Add features to role defaults, re-run setup.
118
140
 
119
141
  ---
120
142
 
@@ -130,22 +152,22 @@ yarn typecheck
130
152
  ```bash
131
153
  yarn db:generate # Probes/creates migration file
132
154
  ```
133
- Fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
155
+ Proposed fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
134
156
 
135
157
  2. **Is the entity declared in the right file with the right imports?**
136
158
  Entity classes belong in `src/modules/<module_id>/data/entities.ts` and decorators must come from `@mikro-orm/decorators/legacy`.
137
- Fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
159
+ Proposed fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
138
160
 
139
161
  3. **Did you apply the migration?**
140
162
  ```bash
141
163
  yarn db:migrate # Applies pending migrations
142
164
  ```
143
- Fix: Run `yarn db:migrate`.
165
+ Proposed fix: Run `yarn db:migrate`.
144
166
 
145
167
  4. **Is the migration file correct?**
146
168
  Check `src/modules/<module_id>/migrations/` for the latest migration.
147
169
  Verify it has the expected columns and types.
148
- Fix: If wrong, delete the migration file, fix the entity, and regenerate.
170
+ Proposed fix: If wrong, delete the migration file, fix the entity, and regenerate.
149
171
 
150
172
  ### Migration generation creates unexpected changes
151
173
 
@@ -160,11 +182,11 @@ yarn typecheck
160
182
 
161
183
  2. **Did you modify a core module entity without ejecting?**
162
184
  Never edit `node_modules/@open-mercato/*`.
163
- Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
185
+ Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
164
186
 
165
187
  3. **Is a module snapshot stale?**
166
188
  Check whether the generated SQL recreates a table or column that already has a committed migration.
167
- Fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
189
+ Proposed fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
168
190
 
169
191
  ### Entity changes not reflected
170
192
 
@@ -443,9 +465,10 @@ yarn dev # 5. Restart dev server
443
465
 
444
466
  ## Rules
445
467
 
446
- - **ALWAYS** run `yarn generate` as first diagnostic step
468
+ - **ALWAYS** present the diagnosed root cause and the proposed fix (commands/code), then **wait for explicit user confirmation before applying any mutating change** (see [Step 4](#step-4-propose-before-fixing)). Only read-only diagnostics may run without asking.
447
469
  - **ALWAYS** check server logs / browser console for actual error messages
448
470
  - **NEVER** edit files in `.mercato/generated/` or `node_modules/`
449
471
  - **NEVER** assume the issue — verify with actual error output
472
+ - Treat `yarn generate` as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
450
473
  - Fix the root cause, not the symptom — temporary workarounds become permanent bugs
451
- - When suggesting a fix, include the exact command or code change needed
474
+ - When proposing a fix, include the exact command or code change needed
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-mercato-app",
3
- "version": "0.6.5-develop.5382.1.f542de69af",
3
+ "version": "0.6.5",
4
4
  "type": "module",
5
5
  "description": "Create a new Open Mercato application",
6
6
  "main": "./dist/index.js",
@@ -21,8 +21,8 @@
21
21
  "tar": "^7.5.16"
22
22
  },
23
23
  "devDependencies": {
24
- "@types/node": "^25.9.2",
25
- "esbuild": "^0.28.0",
24
+ "@types/node": "^25.9.3",
25
+ "esbuild": "^0.28.1",
26
26
  "tsx": "^4.22.4",
27
27
  "typescript": "^6.0.3"
28
28
  },
@@ -41,6 +41,5 @@
41
41
  "scaffolding",
42
42
  "cli"
43
43
  ],
44
- "license": "MIT",
45
- "stableVersion": "0.6.4"
44
+ "license": "MIT"
46
45
  }
package/template/.env.example CHANGED
@@ -194,6 +194,16 @@ CACHE_STRATEGY=sqlite
194
194
  # Default TTL in milliseconds (optional)
195
195
  CACHE_TTL=300000
196
196
 
197
+ # Max entries retained by the in-memory cache strategy before LRU eviction
198
+ # (default: 50000). Bounds memory for the process-wide cache singleton. A
199
+ # non-positive value disables the cap (unbounded — not recommended).
200
+ #CACHE_MEMORY_MAX_ENTRIES=50000
201
+
202
+ # The cache service is shared process-wide (a singleton) so cross-request
203
+ # caches actually hit. Set to off/false to fall back to a per-request cache
204
+ # instance (legacy behavior). Default: on.
205
+ #OM_CACHE_SINGLETON=on
206
+
197
207
  # Redis Configuration
198
208
  #REDIS_PORT=6379
199
209
 
@@ -212,12 +222,21 @@ DB_POOL_MIN=5
212
222
  DB_POOL_MAX=20
213
223
  DB_POOL_IDLE_TIMEOUT=30000
214
224
  DB_POOL_ACQUIRE_TIMEOUT=60000
225
+ # Connection-pinning guards (milliseconds). idle_in_transaction defaults to 120000 in every
226
+ # environment so a leaked open transaction cannot pin a pool connection forever; set to 0 to disable.
227
+ #DB_IDLE_IN_TRANSACTION_TIMEOUT_MS=120000
228
+ # Opt-in server-side timeouts. Unset = no timeout (legacy behavior). Set to cap runaway
229
+ # queries / lock waits so they cannot exhaust the pool. Recommended in production.
230
+ #DB_STATEMENT_TIMEOUT_MS=30000
231
+ #DB_LOCK_TIMEOUT_MS=10000
215
232
 
216
233
  # Audit log retention windows
217
234
  # Core resources (users, roles) keep access history longer to support investigations.
218
235
  AUDIT_LOGS_CORE_RETENTION_DAYS=7
219
236
  # Non-core reads rotate aggressively to limit storage.
220
237
  AUDIT_LOGS_NON_CORE_RETENTION_HOURS=8
238
+ # Minimum gap between retention sweeps per process. 0 rotates on every write.
239
+ AUDIT_LOGS_ROTATE_INTERVAL_MS=60000
221
240
 
222
241
  # Tenant data encryption (enabled by default)
223
242
  TENANT_DATA_ENCRYPTION=yes
package/template/.railwayignore CHANGED
@@ -9,8 +9,8 @@ node_modules/
9
9
  coverage/
10
10
  test-results/
11
11
  playwright-report/
12
- storage/
13
- data/
12
+ /storage/
13
+ /data/
14
14
  *.db
15
15
  *.db-shm
16
16
  *.db-wal
package/template/src/modules/example/backend/payments/page.tsx CHANGED
@@ -20,8 +20,6 @@ import {
20
20
  Ban,
21
21
  ArrowDownToLine,
22
22
  Undo2,
23
- CheckCircle2,
24
- AlertCircle,
25
23
  Info,
26
24
  Zap,
27
25
  } from 'lucide-react'
@@ -433,7 +431,6 @@ export default function PaymentGatewayDemoPage() {
433
431
  {/* Error Display */}
434
432
  {error && (
435
433
  <Alert variant="destructive">
436
- <AlertCircle className="size-4" />
437
434
  <AlertTitle>{t('example.payments.error.title', 'Error')}</AlertTitle>
438
435
  <AlertDescription>{error}</AlertDescription>
439
436
  </Alert>
@@ -442,7 +439,6 @@ export default function PaymentGatewayDemoPage() {
442
439
  {/* Action Result */}
443
440
  {actionResult && (
444
441
  <Alert variant="success">
445
- <CheckCircle2 className="size-4" />
446
442
  <AlertTitle>{t('example.payments.success.title', 'Success')}</AlertTitle>
447
443
  <AlertDescription>{actionResult}</AlertDescription>
448
444
  </Alert>