@open-mercato/cli 0.6.7-develop.6863.1.61001cf9a8 → 0.6.7

package/src/lib/generators/module-registry.ts

@@ -224,8 +224,6 @@ type SerializableWorkerMetadata = {
   id?: string
   queue?: string
   concurrency?: number
-  lockDuration?: number
-  maxStalledCount?: number
 }
 
 type PageMetadataManifestLoadResult = {
@@ -1157,7 +1155,7 @@ function collectStringArrayElements(expr: ts.Expression, stringConstants: Map<st
   return values
 }
 
-export function extractCommandIdsFromSource(sourcePath: string): string[] {
+function extractCommandIdsFromSource(sourcePath: string): string[] {
   const sourceText = fs.readFileSync(sourcePath, 'utf8')
   const sourceFile = ts.createSourceFile(sourcePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
   const ids = new Set<string>()
@@ -1555,8 +1553,6 @@ function normalizeWorkerMetadata(raw: unknown): SerializableWorkerMetadata | nul
   if (typeof source.id === 'string' && source.id.length > 0) normalized.id = source.id
   if (typeof source.queue === 'string' && source.queue.length > 0) normalized.queue = source.queue
   if (typeof source.concurrency === 'number') normalized.concurrency = source.concurrency
-  if (typeof source.lockDuration === 'number') normalized.lockDuration = source.lockDuration
-  if (typeof source.maxStalledCount === 'number') normalized.maxStalledCount = source.maxStalledCount
   return Object.keys(normalized).length > 0 ? normalized : null
 }
 
@@ -2059,7 +2055,7 @@ function processWorkers(discovered: DiscoveredWorker[]): string[] {
   for (const { id, importPath, metadata } of discovered) {
     const workerId = metadata.id ?? id
     workers.push(
-      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}${metadata.lockDuration === undefined ? '' : `, lockDuration: ${toLiteral(metadata.lockDuration)}`}${metadata.maxStalledCount === undefined ? '' : `, maxStalledCount: ${toLiteral(metadata.maxStalledCount)}`}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
+      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
     )
   }
   return workers
@@ -2734,8 +2730,6 @@ function processWorkersAst(discovered: DiscoveredWorker[]): WriterFunction[] {
         { name: 'id', value: workerId },
         { name: 'queue', value: metadata.queue },
         { name: 'concurrency', value: metadata.concurrency ?? 1 },
-        ...(metadata.lockDuration === undefined ? [] : [{ name: 'lockDuration', value: metadata.lockDuration }]),
-        ...(metadata.maxStalledCount === undefined ? [] : [{ name: 'maxStalledCount', value: metadata.maxStalledCount }]),
         {
           name: 'handler',
           value: callExpression(identifier('createLazyModuleWorker'), [
@@ -3065,10 +3059,6 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
       if (fields) fieldsImportName = fields.importName
     }
 
-    const integrationExports = integrationImportName
-      ? `(${integrationImportName} as unknown as { integrations?: import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition[]; integration?: import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition; bundles?: import('@open-mercato/shared/modules/integrations/types').IntegrationBundle[]; bundle?: import('@open-mercato/shared/modules/integrations/types').IntegrationBundle })`
-      : null
-
     // 13. Pages: backend
     {
       const beApp = path.join(roots.appBase, 'backend')
@@ -3177,8 +3167,8 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
       ${dashboardWidgets.length ? `dashboardWidgets: [${dashboardWidgets.join(', ')}],` : ''}
       ${setupImportName ? `setup: (${setupImportName}.default ?? ${setupImportName}.setup) || undefined,` : ''}
       ${encryptionImportName ? `defaultEncryptionMaps: ((${encryptionImportName}.default ?? ${encryptionImportName}.defaultEncryptionMaps) as import('@open-mercato/shared/modules/encryption').ModuleEncryptionMap[]) || [],` : ''}
-      ${integrationExports ? `integrations: ((${integrationExports}.integrations ?? (${integrationExports}.integration ? [${integrationExports}.integration] : [])) as import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition[]),` : ''}
-      ${integrationExports ? `bundles: ((${integrationExports}.bundles ?? (${integrationExports}.bundle ? [${integrationExports}.bundle] : [])) as import('@open-mercato/shared/modules/integrations/types').IntegrationBundle[]),` : ''}
+      ${integrationImportName ? `integrations: (( ${integrationImportName}.integrations ?? (${integrationImportName}.integration ? [${integrationImportName}.integration] : []) ) as import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition[]),` : ''}
+      ${integrationImportName ? `bundles: (( ${integrationImportName}.bundles ?? (${integrationImportName}.bundle ? [${integrationImportName}.bundle] : []) ) as import('@open-mercato/shared/modules/integrations/types').IntegrationBundle[]),` : ''}
     }`)
     runtimeModuleDecls.push(`{
       id: ${toLiteral(modId)},
@@ -3195,8 +3185,8 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
       ${customEntitiesImportName ? `customEntities: ((${customEntitiesImportName}.default ?? ${customEntitiesImportName}.entities) as any) || [],` : ''}
       ${setupImportName ? `setup: (${setupImportName}.default ?? ${setupImportName}.setup) || undefined,` : ''}
       ${encryptionImportName ? `defaultEncryptionMaps: ((${encryptionImportName}.default ?? ${encryptionImportName}.defaultEncryptionMaps) as import('@open-mercato/shared/modules/encryption').ModuleEncryptionMap[]) || [],` : ''}
-      ${integrationExports ? `integrations: ((${integrationExports}.integrations ?? (${integrationExports}.integration ? [${integrationExports}.integration] : [])) as import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition[]),` : ''}
-      ${integrationExports ? `bundles: ((${integrationExports}.bundles ?? (${integrationExports}.bundle ? [${integrationExports}.bundle] : [])) as import('@open-mercato/shared/modules/integrations/types').IntegrationBundle[]),` : ''}
+      ${integrationImportName ? `integrations: (( ${integrationImportName}.integrations ?? (${integrationImportName}.integration ? [${integrationImportName}.integration] : []) ) as import('@open-mercato/shared/modules/integrations/types').IntegrationDefinition[]),` : ''}
+      ${integrationImportName ? `bundles: (( ${integrationImportName}.bundles ?? (${integrationImportName}.bundle ? [${integrationImportName}.bundle] : []) ) as import('@open-mercato/shared/modules/integrations/types').IntegrationBundle[]),` : ''}
     }`)
   }
 

package/src/lib/resolver.ts

@@ -29,7 +29,6 @@ export type ModuleEntry = {
 
 export type PackageInfo = {
   name: string
-  version?: string | null
   path: string
   modulesPath: string
 }
@@ -357,7 +356,6 @@ function discoverPackagesInMonorepo(rootDir: string): PackageInfo[] {
       if (fs.existsSync(modulesPath)) {
         packages.push({
           name: pkgJson.name || `@open-mercato/${entry.name}`,
-          version: typeof pkgJson.version === 'string' ? pkgJson.version : null,
           path: pkgPath,
           modulesPath,
         })
@@ -393,7 +391,6 @@ function discoverPackagesInNodeModules(rootDir: string): PackageInfo[] {
       if (fs.existsSync(modulesPath)) {
         packages.push({
           name: pkgJson.name || `@open-mercato/${entry.name}`,
-          version: typeof pkgJson.version === 'string' ? pkgJson.version : null,
           path: pkgPath,
           modulesPath,
         })

package/src/lib/testing/__tests__/integration.test.ts

@@ -186,10 +186,6 @@ describe('integration cache and options', () => {
       expect(environment?.commandEnvironment.QUEUE_BASE_DIR).toBe('/tmp/open-mercato-queue')
       expect(environment?.commandEnvironment[PRIVATE_ATTACHMENTS_PARTITION_ENV_KEY]).toBe(defaultPrivateAttachmentsRoot)
       expect(environment?.commandEnvironment.PW_CAPTURE_SCREENSHOTS).toBe('1')
-      expect(environment?.commandEnvironment.PLATFORM_PORTAL_BASE_URL).toBe(baseUrl)
-      expect(environment?.commandEnvironment.OM_TEST_EMAIL_CAPTURE_PATH).toBe(
-        path.join(projectRootDirectory, '.ai', 'qa', 'email-capture.jsonl'),
-      )
       expect(environment?.commandEnvironment.NEXT_PUBLIC_OM_EXAMPLE_CHECKOUT_TEST_INJECTIONS_ENABLED).toBeUndefined()
     } finally {
       fetchSpy.mockRestore()

package/src/lib/testing/integration.ts

@@ -271,7 +271,6 @@ const EPHEMERAL_ENV_LOCK_PATH = path.join(projectRootDirectory, '.ai', 'qa', 'ep
 const LEGACY_EPHEMERAL_ENV_FILE_PATH = path.join(projectRootDirectory, '.ai', 'qa', 'ephemeral-env.md')
 const EPHEMERAL_BUILD_CACHE_STATE_PATH = path.join(projectRootDirectory, '.ai', 'qa', 'ephemeral-build-cache.json')
 const EPHEMERAL_CACHE_DB_PATH = path.join(projectRootDirectory, '.ai', 'qa', 'ephemeral-cache.sqlite')
-const EPHEMERAL_EMAIL_CAPTURE_PATH = path.join(projectRootDirectory, '.ai', 'qa', 'email-capture.jsonl')
 const EPHEMERAL_QUEUE_BASE_DIR = path.join(appDirectory, '.mercato', 'queue')
 const PRIVATE_ATTACHMENTS_PARTITION_ENV_KEY = 'ATTACHMENTS_PARTITION_PRIVATE_ATTACHMENTS_ROOT'
 const EPHEMERAL_PRIVATE_ATTACHMENTS_ROOT = path.join(
@@ -1944,7 +1943,6 @@ function buildReusableEnvironment(
     BASE_URL: baseUrl,
     APP_URL: baseUrl,
     NEXT_PUBLIC_APP_URL: baseUrl,
-    PLATFORM_PORTAL_BASE_URL: baseUrl,
     NODE_ENV: 'production',
     // Share the app server's cache backend with the test process and the
     // queue-drain runners it spawns (drainIntegrationQueue children inherit
@@ -1970,7 +1968,6 @@ function buildReusableEnvironment(
     OM_ENABLE_ENTERPRISE_MODULES_SSO: process.env.OM_ENABLE_ENTERPRISE_MODULES_SSO ?? enterpriseModulesFlag,
     OM_ENABLE_ENTERPRISE_MODULES_SECURITY: process.env.OM_ENABLE_ENTERPRISE_MODULES_SECURITY ?? enterpriseModulesFlag,
     OM_TEST_MODE: '1',
-    OM_TEST_EMAIL_CAPTURE_PATH: EPHEMERAL_EMAIL_CAPTURE_PATH,
     OM_TEST_AUTH_RATE_LIMIT_MODE: 'opt-in',
     // Tests assert on access_logs immediately after CRUD reads; keep the
     // blocking write path on inside the integration runtime so tests do
@@ -3296,7 +3293,6 @@ export async function startEphemeralEnvironment(options: EphemeralRuntimeOptions
       BASE_URL: applicationBaseUrl,
       APP_URL: applicationBaseUrl,
       NEXT_PUBLIC_APP_URL: applicationBaseUrl,
-      PLATFORM_PORTAL_BASE_URL: applicationBaseUrl,
       JWT_SECRET: process.env.JWT_SECRET ?? 'om-ephemeral-integration-jwt-secret',
       OM_SECURITY_MFA_SETUP_SECRET: process.env.OM_SECURITY_MFA_SETUP_SECRET ?? 'om-ephemeral-integration-mfa-setup-secret',
       NODE_ENV: 'production',
@@ -3325,7 +3321,6 @@ export async function startEphemeralEnvironment(options: EphemeralRuntimeOptions
       OM_ENABLE_ENTERPRISE_MODULES_SSO: process.env.OM_ENABLE_ENTERPRISE_MODULES_SSO ?? enterpriseModulesFlag,
       OM_ENABLE_ENTERPRISE_MODULES_SECURITY: process.env.OM_ENABLE_ENTERPRISE_MODULES_SECURITY ?? enterpriseModulesFlag,
       OM_TEST_MODE: '1',
-      OM_TEST_EMAIL_CAPTURE_PATH: EPHEMERAL_EMAIL_CAPTURE_PATH,
       OM_TEST_AUTH_RATE_LIMIT_MODE: 'opt-in',
       OM_DISABLE_EMAIL_DELIVERY: '1',
       OM_WEBHOOKS_ALLOW_PRIVATE_URLS: process.env.OM_WEBHOOKS_ALLOW_PRIVATE_URLS ?? '1',

package/src/mercato.ts

@@ -867,10 +867,7 @@ async function buildAllModules(): Promise<Module[]> {
 export async function run(argv = process.argv) {
   const [, , ...parts] = argv
   const [first, second, ...remaining] = parts
-  await ensureEnvLoaded({
-    createIfMissing: first !== 'deploy' && first !== 'telemetry',
-    quiet: first === 'deploy' || first === 'telemetry',
-  })
+  await ensureEnvLoaded({ createIfMissing: first !== 'deploy', quiet: first === 'deploy' })
   
   // Handle init command directly
   if (first === 'init') {
@@ -1335,20 +1332,6 @@ export async function run(argv = process.argv) {
     return exitCode
   }
 
-  // Handle telemetry command (bootstrap-free) — wires @open-mercato/telemetry
-  // into an app scaffolded before telemetry existed.
-  if (first === 'telemetry') {
-    if (second === 'init') {
-      const { runTelemetryInit } = await import('./lib/telemetry-init')
-      return runTelemetryInit(remaining.filter(Boolean))
-    }
-    console.log('Usage: yarn mercato telemetry init [--dry-run]')
-    console.log('  Wires @open-mercato/telemetry into this app (package.json, .env,')
-    console.log('  instrumentation.ts, next.config.ts, and the API dispatcher).')
-    console.log('  Idempotent and safe to re-run. Use --dry-run to preview changes.')
-    return second && second !== 'help' && second !== '--help' && second !== '-h' ? 1 : 0
-  }
-
   if (first === 'module') {
     try {
       const subcommand = second
@@ -1671,8 +1654,6 @@ export async function run(argv = process.argv) {
                 effectiveByQueue.get(queue) ??
                 concurrencyOverride ??
                 Math.max(...queueWorkers.map((w) => w.concurrency), 1)
-              const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
-              const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
 
               console.log(`[worker] Starting "${queue}" with ${queueWorkers.length} handler(s), concurrency: ${concurrency}`)
 
@@ -1681,8 +1662,6 @@ export async function run(argv = process.argv) {
                 queueName: queue,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
-                lockDuration,
-                maxStalledCount,
                 background: true,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
@@ -1726,8 +1705,6 @@ export async function run(argv = process.argv) {
               // never check out more pooled connections than the worker pool holds.
               const budgetPlan = await resolveWorkerBudgetPlan([{ queue: queueName!, concurrency: requested }])
               const concurrency = budgetPlan.entries[0]?.effective ?? requested
-              const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
-              const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
 
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`)
 
@@ -1736,8 +1713,6 @@ export async function run(argv = process.argv) {
                 queueName: queueName!,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
-                lockDuration,
-                maxStalledCount,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
             } else {

package/dist/agentic/guides/ai-workflows.md

@@ -1,76 +0,0 @@
-# AI Agents, Orchestrators, and Workflows
-
-Use typed module contracts for product AI and the workflow engine for durable business processes. Keep model/tool execution, mutation approval, scope, storage, and retries explicit.
-
-## Choose the Surface
-
-| Need | Use |
-|---|---|
-| In-app conversational or structured domain assistant | Module `ai-agents.ts` plus `ai-tools.ts`. |
-| Low-level MCP/OpenCode or Code Mode work | `ai_assistant` installed contract: `registerMcpTool`, MCP server, OpenCode handlers/config, or the `search`/`execute` Code Mode tools. Do not conflate this with a typed product agent. |
-| Add a few tools/prompt/suggestions to an installed agent | `aiAgentExtensions`. |
-| Replace or disable an installed agent/tool | `aiAgentOverrides` / `aiToolOverrides` or module entry override. |
-| Coding-agent orchestration with files, outcomes, samples, embedded skill, or subagents | Orchestrator file-agent contract; resolve its installed package guide first. |
-| Durable business process, human task, timer, signal, compensation, or event trigger | Workflows module and `om-build-workflow`. |
-| One background AI extraction | Object-mode agent invoked from a scoped command/worker. |
-
-## Typed Module Agents and Tools
-
-- Put `ai-agents.ts` and `ai-tools.ts` at the module root. Export typed arrays and run `yarn generate`.
-- Give agent IDs `<module>.<agent>` and tool names stable namespaced IDs. Declare provider/model defaults through the framework registry/model factory, not provider SDK singletons.
-- Every data tool has a Zod input schema, tenant/org scope, wildcard-aware `requiredFeatures`, bounded output, and a serializable result.
-- Mark writes `isMutation: true`. Pair mutation-capable agents with `readOnly: false` and a confirmation policy.
-- A write tool calls `prepareMutation`; the durable execute callback performs a command-based, optimistic-lock-aware mutation. Never write directly before approval.
-- Use declarative loop controls/budgets. The wrapper-owned approval guard remains active on every step and execution engine.
-- Validate attachments by type/size/scope. Store outputs through authorized artifact/attachment services with retention and encrypted sensitive metadata.
-
-## MCP, OpenCode, and Code Mode
-
-- Prefer `defineAiTool` in discovered `ai-tools.ts` for product agents, especially mutation-capable tools. Use low-level `registerMcpTool` only when the requested surface is explicitly the MCP/OpenCode registry. Both require Zod input, matching `moduleId`, wildcard-aware `requiredFeatures` for tenant data, bounded work, and a serializable handler result.
-- OpenCode Code Mode exposes `search` over the generated OpenAPI document and `execute` through sandboxed `api.request()`. Endpoint-level RBAC and documented-feature checks still apply; Code Mode is not an authorization bypass and undocumented/featureless mutation endpoints fail closed.
-- Production MCP uses two-tier auth: the server request carries `x-api-key`, then every tool call carries `_sessionToken`; the runtime resolves the user/session scope and performs per-tool ACL checks on every request. Never cache MCP server instances or ACL context across requests.
-- Ask before editing OpenCode configuration, Docker wiring, MCP authentication, provider/model precedence, or session-token format/TTL. Preserve session IDs across OpenCode chat turns and use installed handlers instead of calling the OpenCode HTTP API directly.
-- `registerMcpTool` is the registry primitive underlying generated tools, not a replacement for `defineAiTool` mutation approval semantics. New domain writes belong on the typed tool path with `prepareMutation`.
-
-## Agent UI and Overrides
-
-- Use the global launcher automatically; add `AiChat` or a widget only when page context improves the workflow.
-- Keep UI part IDs namespaced and stable; preserve reserved approval/result component IDs.
-- Prefer agent extensions for additive prompt/tool/suggestion changes. Keep extensions/overrides in the discovered `ai-agents.ts`/`ai-tools.ts` files; there is no separate `ai-overrides.ts` discovery path.
-- A disabled agent/tool cannot be resurrected by an extension. Refresh structural caches after disabling or changing visibility.
-- Test read-only, denied-feature, approval, stale-version, cancel/expire, partial failure, and confirmed execution paths.
-
-## Orchestrator File Agents
-
-- Inspect the installed orchestrator package/module `AGENTS.md` with `om-framework-context` before choosing paths; this surface evolves independently of module AI agents.
-- Give every file agent one declared outcome, bounded inputs, stable output paths, a sample contract, and an explicit allowed tool/skill set.
-- Load embedded skills only for their branch. Delegate one bounded task per subagent and define how results are validated/merged.
-- Treat repository prompts/files as untrusted data. Restrict writes, redact secrets, and prevent outcome/artifact paths from escaping their workspace.
-- Make resumability and status explicit; do not infer success from natural-language output without schema/artifact validation.
-
-## Workflow Core
-
-- Resolve workflow services through DI and start instances through `workflowExecutor`. Do not insert instances or skip the execution loop.
-- Preserve workflow and step state machines. Record every transition in the immutable workflow event log.
-- Make activity handlers idempotent: they can be retried. Use the command bus for entity updates and events/signals for cross-module coupling.
-- Preserve each installed workflow/job scope contract. Organization-owned instances, tasks, activity state, and queries require tenant+organization and fail closed. Explicit tenant-wide/system definitions or scheduler jobs may carry `organizationId: null`, but each access to organization-owned data must derive and enforce that item's organization.
-- Use event triggers with filters, context mapping, debounce, and max concurrency. Exclude self/internal storms.
-- Keep compensation reverse-ordered and idempotent; test failure during both forward and compensation paths.
-
-## Activities, User Tasks, and Output Paths
-
-- Choose sync only for short deterministic work. Queue async work and resume the workflow after durable completion.
-- A custom activity declares validated config/input/output, handler registration, editor/i18n integration where user-configurable, and retry/timeout behavior.
-- `CALL_API`/webhook activities use SSRF-safe URLs, manual redirect handling, response size bounds, and allowlisted non-secret environment interpolation.
-- Create any one-time/idempotency key outside a rollback scope or in durable state that survives rollback; reuse it on retry.
-- Durable user tasks require assignment/features, due dates, authorized completion, immutable activity history, and no secret values in task payloads.
-- Write outputs to stable declared activity/artifact paths. Validate path containment and access; clean temporary files while retaining declared deliverables.
-- Emit progress/events for long work and render them through shared progress/UI contracts rather than unbounded polling.
-
-## Verification
-
-1. Run `yarn generate` and confirm agent/tool/workflow registrations.
-2. Test missing provider/configuration, denied ACL, missing scope, timeout, retry, duplicate, and cancellation.
-3. For AI writes, prove no domain write occurs before approval and a stale approval cannot overwrite newer data.
-4. For workflows, prove event log/state transitions and idempotency across worker restart and injected rollback.
-5. For orchestrators, validate output schema/artifacts and allowed-write boundaries, not just prose.

package/dist/agentic/guides/architecture.md

@@ -1,107 +0,0 @@
-# Standalone Architecture and Discovery
-
-Use this guide to choose ownership, locate module surfaces, and keep generated discovery correct.
-
-## Context Ownership and Scattering
-
-The harness is intentionally layered so an agent can assemble precise context without paying for the whole framework:
-
-| Layer | Owns | Loading rule |
-|---|---|---|
-| Root `AGENTS.md` | Non-negotiable safety, validation, precedence, and the three-axis router | Load first and always; it is the only initial bundle. |
-| `.ai/guides/*.md` | Stable framework concepts and contracts by area | Load the de-duplicated set selected by the area and primitive axes. |
-| Thin task skills | Branching procedure and links to focused references | Load only matched skills; open only the references needed by the chosen branch. |
-| `.ai/guides/modules/*.md` | Generated identifiers and discovered surfaces for an exact installed module/version | Load only for installed modules named, changed, integrated with, or used as hosts. |
-| `om-framework-context` output | Exact installed instructions, source/types, and bounded search results | Last-mile escalation after app call sites, facts, and concept guides cannot answer the question. |
-| External `open-mercato/skills` | SDLC and delivery workflows | Select independently only when the requested lifecycle needs one. |
-
-Match area, work units, and delivery independently, then de-duplicate their union by path and skill. A business one-shot is not one giant context category: split it into units such as entity, command, API, admin UI, public capture, CRM extension, event, and provider, and give each unit only its owning area and contract. Do not preload all module facts, skill references, upstream guides, or installed package source.
-
-Keep facts and source in different roles. Facts answer “what identifier or surface exists?”; exact installed source answers “how does this version implement or type the contract?” The latter is read-only evidence, never a writable escape hatch.
-
-## Ownership Decision
-
-| Need | Choose |
-|---|---|
-| App-specific domain capability | Create `src/modules/<id>/` and register `{ id, from: '@app' }` in `src/modules.ts`. |
-| Additive change to an installed module | Use the smallest UMES mechanism from `.ai/guides/extensions.md`. |
-| Disable/replace a supported installed contract | Use the target module entry's `overrides` in `src/modules.ts`. |
-| Reusable external provider | Add/install a dedicated provider package; do not place provider logic in a generic core module. |
-| Change unsupported by UMES/overrides | Inspect exact installed context, then use `om-eject-and-customize` only with user approval. |
-| Framework defect affecting all consumers | Reproduce against the installed version and report an upstream change; never patch `node_modules`. |
-
-## Writable and Read-Only Trees
-
-```text
-src/modules/<id>/                 writable app modules
-src/modules.ts                    enabled modules and supported overrides
-.mercato/generated/              generated, never edit
-.ai/guides/modules/              generated facts, never edit
-node_modules/@open-mercato/*/    exact installed packages, read-only
-```
-
-Do not copy an installed module merely to learn it. Generated facts and the context resolver expose the exact installed source without widening the writable surface.
-
-## Canonical Module Shape
-
-```text
-src/modules/<id>/
-├── index.ts
-├── data/{entities,validators,extensions,enrichers}.ts
-├── api/**/route.ts
-├── backend/**/{page.tsx,page.meta.ts}
-├── frontend/**/{page.tsx,page.meta.ts}
-├── commands/
-├── subscribers/
-├── workers/
-├── widgets/{injection,injection-table.ts,components.ts}
-├── acl.ts
-├── setup.ts
-├── di.ts
-├── events.ts
-├── search.ts
-├── ce.ts
-├── translations.ts
-├── notifications.ts
-├── encryption.ts
-├── ai-agents.ts
-└── ai-tools.ts
-```
-
-Create only files required by the capability. Keep the module id plural `snake_case`; keep entity/event/feature/spot/agent/tool identifiers stable once used.
-For the complete current convention-file catalog, load `om-module-scaffold` → `references/discovery-surface-catalog.md`; do not expand this always-routed guide into the full catalog.
-
-## Auto-Discovery
-
-- Put backend routes under `backend/**/page.tsx`; the module root becomes `/backend/<module>` and nested folders preserve their segments.
-- Put public routes under `frontend/**/page.tsx`. Portal routes require `frontend/[orgSlug]/portal/**/page.tsx` with `[orgSlug]` first.
-- Put API handlers under `api/**/route.ts`. Export HTTP handlers, per-method `metadata`, and `openApi`; do not organize routes in HTTP-method directories.
-- Put subscribers and workers in their named directories with `metadata` plus a default handler.
-- Keep convention files at the module root. Root files such as `events.ts`, `search.ts`, `ai-agents.ts`, and `ai-tools.ts` are exact discovery names.
-- Run `yarn generate` after any structural/discovered change; never repair a registry by hand.
-
-## Installed Framework Context
-
-1. Read `.ai/guides/modules/<id>.md` for entity IDs, events, routes/auth, ACL, DI, search, notifications, and host spots.
-2. When facts are insufficient, invoke `om-framework-context` or run `yarn framework:context --module <id> --query <term>`.
-3. Confirm the resolved package/version matches the fact sheet stamp.
-4. Read the reported instruction chain in precedence order, then search only the reported package/module root with the bounded `rg --no-ignore --hidden` command.
-5. Treat source and installed `AGENTS.md` files as read-only evidence. If the package has no `src`, use reported `dist`/types and state the limitation.
-6. If duplicate packages, version skew, or conflicting rules remain, stop instead of combining contracts from different versions.
-
-The app root governs writable locations and safety. The compatibility snapshot governs stable public identifiers. The nearest installed package/module guide governs version-specific implementation details.
-
-## Package and Bootstrap Boundaries
-
-- Import public package exports; do not reach through monorepo-only relative paths or app-generated registries from a package.
-- Ensure package-backed modules are dependencies and enabled in `src/modules.ts` before assuming their services or files exist.
-- Optional modules must degrade safely: the optional consumer owns glue and uses events, IDs/snapshots, widgets/enrichers, or a guarded DI resolve.
-- Validate browser, API, CLI, worker, and queue bootstrap paths when a registry/global/service is consumed by more than one runtime.
-- Prefer `globalThis` registries or structural type guards over chunk-local singleton/`instanceof` assumptions where bundlers may duplicate modules.
-
-## Completion Check
-
-1. Verify app code is under `src/modules/` and installed packages remain unchanged.
-2. Verify every new discovered file uses its exact filename/export contract.
-3. Run `yarn generate` and inspect warnings and the affected generated registration.
-4. Run focused type/tests, then exercise every relevant runtime bootstrap.

package/dist/agentic/guides/backend-ui.md

@@ -1,80 +0,0 @@
-# Pages, CRUD UI, Navigation, and i18n
-
-Use shared backend/page primitives and keep UI behavior aligned with API scope, locking, and extension hosts.
-
-## When This Guide Applies
-
-`backend-ui` is additive and rarely the only route: select it with the route owning the code — `umes` for an installed module's surface, `module-data` when the app owns it — whenever the task authors, restyles, or permission-gates a rendered surface this app owns or injected. Not for hiding, toggling, disabling, or rewiring a surface an installed module owns, and not for payload text, pagination, or table IDs.
-
-## Page Selection
-
-Every app page is module-owned and auto-discovered: author it under `src/modules/<id>/{backend,frontend}/**/page.tsx` and run `yarn generate` so it registers into the route registry served by the app's `(backend)`/`(frontend)` catch-all. Never place a `page.tsx`/`page.meta.ts` directly under `src/app/(backend)/**` or `src/app/(frontend)/**` — a page added to the Next.js route group instead of the module renders unregistered, skipping nav injection, ACL feature-gating, and breadcrumbs. The paths below are all relative to the owning `src/modules/<id>/`.
-
-| Page | Location and rules |
-|---|---|
-| Backend list/detail/create/edit | `src/modules/<id>/backend/**/page.tsx` plus sibling `page.meta.ts`; require staff auth/features. |
-| Settings | Backend metadata with `pageContext: 'settings' as const` and `navHidden: true`. |
-| Profile | Backend metadata with `pageContext: 'profile' as const`. |
-| Public frontend | `src/modules/<id>/frontend/**/page.tsx`; explicitly declare auth posture in metadata. |
-| Customer portal | `src/modules/<id>/frontend/[orgSlug]/portal/**/page.tsx`; public login/signup/verify/landing pages are `navHidden` without customer auth, authenticated pages require customer auth/features, and only sidebar destinations add `nav`. |
-
-List destinations need stable `pageGroup`, `pageGroupKey`, and order. Prefer a registered string icon name in `page.meta.ts` so generated metadata stays serializable; use `lucide-react` components in page-body UI. Hide create/edit/detail destinations from navigation when they are reached from a list.
-
-## Default CRUD Completeness
-
-For a new editable entity or module, unless the brief explicitly excludes an operation, deliver list, create, view/edit, and delete as one connected slice. The `DataTable` list owns server filter/search controls, a localized add action linking to create, and a stable linked row action to view/edit. `CrudForm` owns create/update/delete, custom-field save/reload/clear, `updatedAt` conflicts, and return navigation. Do not leave a new backend entity reachable only by typing a URL.
-
-## DataTable
-
-- Use `DataTable` with a stable colon-form `entityId`, explicit typed data/pagination loaded through shared API helpers, and `extensionTableId`. These are host contracts, not cosmetic props; `DataTable` has no `apiPath` prop.
-- Use shared column helpers, `RowActions` with stable action IDs, built-in filter/search/export/column controls, and DataTable bulk-action surfaces.
-- When owning pagination, wire page, page size, total count, and change handlers together. Do not slice a server page again in the client.
-- Use the table's empty state and shared loading/error components. A successful empty result is not an error.
-- Route selected-row and long-running operations through guarded mutations and progress contracts; do not loop direct API writes without cancellation/error reporting.
-
-## CrudForm
-
-- Use `CrudForm`, typed fields/groups, and `createCrud`/`updateCrud`/`deleteCrud`; use the shared server-error adapter.
-- Pass detail data including `updatedAt` as `initialValues`, allowing the form to protect update and delete automatically.
-- Keep field IDs aligned through request validators, commands, response transforms, custom-field widgets, and translations.
-- Support explicit `null` clearing where the field is clearable; avoid truthy fallbacks that resurrect the old value.
-- Use `crud-form:<entityId>:fields` for injected fields and ensure the read/enricher and save/interceptor paths round-trip the same value.
-- Use shared conflict surfacing for non-`CrudForm` writes.
-
-## Data Access and States
-
-- Use `apiCall`/`apiCallOrThrow`; use scoped API headers for versions or other request context. Never call raw `fetch` from app backend UI.
-- Use `LoadingMessage`, `ErrorMessage`, `EmptyState`, `Alert`, flash messages, and the standard page/form scaffolding.
-- Preserve the user's input after validation/server errors. Disable duplicate submissions and expose retry only when the operation is safe.
-- Every dialog supports Cmd/Ctrl+Enter submit and Escape cancel. Every icon-only control has an accessible label.
-- Keep server/client locale, timezone, and environment-derived initial render deterministic to prevent hydration mismatches.
-
-## Navigation and Overrides
-
-- Prefer page metadata for app-owned destinations and menu injection for adding/reordering items owned by another module.
-- Use stable menu item IDs and translation keys. Gate injected items with wildcard-aware ACL checks.
-- Hide or replace installed pages through `src/modules.ts` page overrides; do not delete package code or add a competing route accidentally.
-- If disabling the dashboards module, update the backend landing page to redirect to the first accessible enabled destination, falling back to profile only when necessary.
-
-## Design-System Contract
-
-- For public/portal or visually substantial app work, use `om-backend-ui-design` → `references/frontend-and-design-system.md` for route-shell, product hierarchy, responsive, accessibility, and UX-state coverage.
-- Reuse existing page, section, form, detail, schedule, messages, notification, chart, KPI, and banner component families before building a local variant.
-- Use semantic design tokens and `StatusBadge` for status. Do not hard-code Tailwind status colors or arbitrary text sizes.
-- Use `FormField` for standalone forms; `CrudForm` owns field layout and must not be wrapped in it. Use `SectionHeader`, `CollapsibleSection`, standard buttons/dialogs, and Lucide icons.
-- Portal record lists use `DataTable`. Never use raw buttons/checkboxes, a button-styled raw `Link`, or `window.confirm`; use the exported primitives and `useConfirmDialog`.
-- Keep responsive behavior, keyboard navigation, focus order, contrast, and reduced-motion behavior intact.
-
-## Translation Contract
-
-- Use `useT()` in client components and `resolveTranslations()` on the server.
-- Put app translations in module/app locale files using stable namespaced keys. Translate titles, actions, placeholders, validation, empty/error states, notifications, and navigation.
-- Declare `translations.ts` only for entity fields that use the Translation Manager and run `yarn generate` after changing it.
-- Do not place translated output in stable machine identifiers, API enums, logs, or provider protocol values.
-
-## Verification
-
-1. Exercise permitted and forbidden roles, including wildcard grants.
-2. Exercise loading, empty, validation error, server error, conflict, success, and delete flows.
-3. Save, reload, edit, clear nullable fields, and verify the API payload and rendered state agree.
-4. Check keyboard and narrow-width behavior; run affected integration tests through real API fixtures.

package/dist/agentic/guides/contracts.md

@@ -1,92 +0,0 @@
-# Module and Data Contracts
-
-Use this guide for entities, APIs, commands, scoping, compatibility, migrations, events, workers, search, and cache. Use `customers` as the CRUD reference after resolving its installed source.
-
-## Entity and Scope Contract
-
-- Define entity classes together in `src/modules/<id>/data/entities.ts`; import decorators from `@mikro-orm/decorators/legacy` and ORM types from the installed MikroORM package.
-- Give organization-owned business rows `tenant_id` and `organization_id` columns plus a composite index suitable for their common filters. Derive scope from authenticated context, never request payloads. Preserve an installed tenant-wide/system contract only when it explicitly authorizes nullable organization scope; such code must not widen into organization-owned data.
-- Give new user-editable rows `updated_at` with create/update behavior. Return it as `updatedAt` from list/detail APIs.
-- Use UUID primary keys, explicit scalar FK IDs, and module-prefixed plural table names. Do not create cross-module ORM relations.
-- Store sensitive/PII fields through `encryption.ts` `defaultEncryptionMaps`; use the framework decryption find helpers with both scope IDs. Add a deterministic hash sibling only when equality lookup requires it.
-- Model nullable/optional/clearable fields consistently through validator, command, entity, response, and form. Test create, edit, reload, and clearing to `null`.
-
-## Migration Workflow
-
-1. Change `data/entities.ts` and any validator/command/response contracts.
-2. Run `yarn generate` if discovery or entity registration changed.
-3. Run `yarn db:generate` as a schema-diff probe.
-4. Review every emitted statement; retain only the intended module change and update that module's `.snapshot-open-mercato.json` to the post-change schema.
-5. Never edit a shipped migration. Add a corrective migration.
-6. Ask before `yarn db:migrate`; normal delivery includes migration plus snapshot without mutating the user's database.
-
-## CRUD Route Contract
-
-Create handlers under `api/<resource>/route.ts` and build them with the installed `makeCrudRoute` contract:
-
-- import `makeCrudRoute` from `@open-mercato/shared/lib/crud/factory`;
-
-- `metadata`: per-method `requireAuth` and `requireFeatures`;
-- `orm`: entity, id field, tenant/org fields, and explicit soft-delete field (including `null` when absent);
-- `list`: Zod query schema, stable colon-form `entityId`, fields including `updated_at`, scoped filters, stable response transform, and custom-field decoration when needed;
-- `actions.create`, `actions.update`, `actions.delete`: command IDs, raw schemas, scoped input mapping, responses, and statuses;
-- `indexer: { entityType }`: query-index coverage;
-- `enrichers: { entityId }`: only when this route intentionally exposes the enricher host.
-
-Export the factory's handlers and a matching `openApi` document as a separate route export. `openApi` is not a `makeCrudRoute` option. Build it with `createCrudOpenApiFactory` and `createPagedListResponseSchema` from `@open-mercato/shared/lib/openapi/crud`, or provide a typed `OpenApiRouteDoc` from `@open-mercato/shared/lib/openapi`. Do not use the stale flat `create`/`update`/`del` factory shape, a top-level `requireAuth`, or an API file organized by HTTP-method directory.
-
-Reject malformed ID lists and filters explicitly. Preserve existing response keys; normalize custom fields deliberately and test compatibility when changing prefixed keys.
-
-## Commands and Custom Writes
-
-- Put domain mutations in commands so audit, undo, events, cache invalidation, and indexing share one path. Routes validate and dispatch; they do not reproduce writes.
-- For custom write/action routes, run registered mutation guards before mutation, merge guarded payload changes, and run post-success callbacks after commit while logging callback failures.
-- Enforce command-level optimistic locking for action/sub-resource endpoints. Guard the aggregate parent when lines share a parent version.
-- Wrap multi-phase scalar/relation work with `withAtomicFlush(..., { transaction: true })`. Keep CRUD side effects and cache invalidation after the transaction commits.
-- Emit both forward and undo side effects with the same index/cache aliases when undo exists.
-- Make retries and idempotency explicit. Do not advance external cursors, one-time keys, or recovery state until the durable unit of work commits.
-
-## Runtime Logging
-
-- Use `createLogger('<module>')` from `@open-mercato/shared/lib/logger` in runtime/server/module code; use `.child({ component, ...context })` for stable local context.
-- Keep messages stable and put dynamic values in structured metadata; pass caught errors under `err`. Omit or redact credentials, tokens, secrets, PII, and payload bodies.
-- Do not add raw `console.*` calls to runtime/server/module code. Intentional terminal output in CLI/build scripts and test-local console spies remain valid when that runtime requires them.
-
-## Optimistic-Lock UI Contract
-
-- `CrudForm` derives the update/delete header from `initialValues.updatedAt`; ensure the detail payload supplies it.
-- A custom client mutation wraps the call with the framework's scoped request-header helper and `buildOptimisticLockHeader(record.updatedAt)`.
-- Surface 409s through the shared record-conflict UI. Do not silently retry over newer data.
-- If a parent form mutates children, override the header per child with that child's version; do not reuse the parent version.
-
-## ACL and Setup
-
-- Declare stable `<module>.<capability>` features in `acl.ts` and their dependency relationships when applicable.
-- Gate API methods and pages declaratively with `requireFeatures`; never gate by mutable role names.
-- Grant new features in `setup.ts` `defaultRoleFeatures` for the intended default roles, then run `yarn mercato auth sync-role-acls` for existing tenants.
-- Use the wildcard-aware matcher wherever raw feature arrays are evaluated; `module.*` and `*` must satisfy concrete grants.
-- Make `onTenantCreated`, `seedDefaults`, and provider setup idempotent. Keep examples in `seedExamples`.
-
-## Cross-Module Mechanism
-
-| Need | Use |
-|---|---|
-| Side effect after another module changes | Typed event + subscriber owned by the optional consumer. |
-| Display/read another module's data | Widget injection plus response enricher. |
-| Durable historical reference | Scalar ID plus snapshot; resolve live data only when available. |
-| Add app-owned data linked to installed entity | Separate extension entity in `data/extensions.ts`. |
-| Optional service call | Guarded/soft DI resolve in the consumer and a defined degraded result. |
-
-## Events, Notifications, Workers, Search, and Cache
-
-- Declare typed events in `events.ts` with `createModuleEvents(... as const)` before emitting them. Keep IDs past-tense and stable.
-- Use persistent idempotent subscribers for retried side effects; use ephemeral subscribers for local reactive work. Verify the host module can be absent when optional.
-- Declare notification types/renderers/handlers through their registries; keep notification IDs stable and ACL-aware.
-- Give every worker discovered metadata, an idempotent handler, bounded concurrency/retry behavior, scoped serializable payloads, and commands for domain writes. Use `ProgressJob` for user-visible bulk/long work. Exact cache/queue imports, tenant context, worker shape, retry semantics, and operator commands live in `om-module-scaffold` → `references/runtime-cache-and-queues.md`.
-- Configure `search.ts`; use deterministic convergence polling or reindex assertions rather than arbitrary sleeps.
-- Resolve cache through DI and mirror the host scope in keys/tags: tenant+organization for organization-owned data, or an explicitly authorized tenant-wide key for tenant-wide state. Invalidate every successful write/undo/sub-resource path after commit; non-request runtimes establish the tenant cache context explicitly.
-- Add module CLI commands through the discovery contract and test the compiled package path, not only TypeScript source.
-
-## Frozen Surfaces
-
-Treat API routes, public imports/signatures, DB schema, event/entity/ACL/DI/widget/notification/AI IDs, CLI commands/flags, and generated bootstrap exports as compatibility surfaces. Prefer additive fields and aliases. A rename/removal needs an explicit deprecation bridge and migration plan.