@open-mercato/cli 0.6.8-develop.6930.1.1e5976efc3 → 0.6.8-develop.6940.1.177ea30c6e

package/.turbo/turbo-build.log

@@ -2,8 +2,12 @@
 Copied create-app/agentic/ → dist/agentic/
 [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
+Generated 56 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:11
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:31
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:58
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for content
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_docs
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_keys
@@ -56,5 +60,65 @@ 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 56 module fact-sheets → dist/agentic/guides/modules/
+[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
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:11
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:31
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:58
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for content
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_docs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_keys
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for attachments
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for audit_logs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for auth
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for business_rules
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for catalog
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for communication_channels
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for configs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for currencies
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customer_accounts
+[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
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for eudr
+[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
+[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
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for perspectives
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for planner
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for portal
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for progress
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for query_index
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for resources
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sales
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for shipping_carriers
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for staff
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_excel
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for translations
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for wms
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for workflows
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for record_locks
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for security
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sso
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for system_status_overlays
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for events
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for gateway_stripe
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for onboarding
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for scheduler
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for search
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for generators
+[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
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for example
+Generated 1 local reference projection(s) → dist/agentic/guides/reference-modules/
 [build:cli] built successfully

package/build.mjs

@@ -57,6 +57,9 @@ await buildPackage(packageDir, {
     // 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.
     rmSync(join(guidesDestDir, 'modules'), { recursive: true, force: true })
+    rmSync(join(guidesDestDir, 'reference-modules'), { recursive: true, force: true })
+    rmSync(join(guidesDestDir, 'reference-module-facts.json'), { force: true })
+    rmSync(join(guidesDestDir, 'module-facts.v2.json'), { force: true })
     for (const entry of readdirSync(guidesDestDir)) {
       if (/^core\..+\.md$/.test(entry)) {
         rmSync(join(guidesDestDir, entry))
@@ -88,19 +91,29 @@ await buildPackage(packageDir, {
       console.log(`Discovered ${guidesFound} standalone guides → dist/agentic/guides/`)
     }
 
-    // Generate per-module fact-sheets (Layer 2) for every package-provided module via
-    // the freshly built ts-morph extractor + resolver-routed discovery, so
+    // Generate per-module fact-sheets plus legacy-v1 and corrected-v2 JSON sidecars
+    // for every package-provided module via the freshly built ts-morph extractor and
+    // 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).
-    const { extractAllModuleFacts, renderModuleFactsJson } = await import(
-      pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href
-    )
-    const { discoverPackageModuleSources } = await import(
+    const {
+      assertPackageModuleFactsOnly,
+      extractAllModuleFacts,
+      extractLocalReferenceModuleFacts,
+      renderModuleFactsJson,
+      renderReferenceModuleFactsJson,
+    } = await import(pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href)
+    const { discoverLocalReferenceModuleSource, discoverPackageModuleSources } = await import(
       pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts-discovery.js')).href
     )
     const { createResolver } = await import(pathToFileURL(join(outdir, 'lib', 'resolver.js')).href)
 
+    // Mirrors packages/create-app/build.mjs: the disabled app-local example never enters
+    // the normal package outputs and is projected into its own reference bundle so
+    // `mercato agentic:init` bundles exactly what a create-mercato-app scaffold does.
+    const REFERENCE_MODULE_IDS = ['example']
+
     const sources = discoverPackageModuleSources(createResolver(join(packagesDir, '..')))
     if (sources.length > 0) {
       const registryPath = join(packagesDir, '..', 'apps', 'mercato', '.mercato', 'generated', 'modules.runtime.generated.ts')
@@ -116,17 +129,54 @@ await buildPackage(packageDir, {
         registryPath: existsSync(registryPath) ? registryPath : null,
         coreVersion,
       })
+      const { factsByModule: legacyFactsByModule } = extractAllModuleFacts({
+        sources,
+        registryPath: existsSync(registryPath) ? registryPath : null,
+        coreVersion,
+        factsContractVersion: 1,
+      })
+
+      assertPackageModuleFactsOnly(factsByModule)
+      assertPackageModuleFactsOnly(legacyFactsByModule)
 
       const modulesGuidesDir = join(guidesDestDir, 'modules')
       mkdirSync(modulesGuidesDir, { recursive: true })
       for (const [moduleId, markdown] of Object.entries(markdownByModule)) {
         writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
       }
-      writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
+      writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(legacyFactsByModule))
+      writeFileSync(join(guidesDestDir, 'module-facts.v2.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/`)
+
+      const referenceBundle = {}
+      const referenceGuidesDir = join(guidesDestDir, 'reference-modules')
+      const templateRoot = join(packagesDir, 'create-app', 'template')
+      for (const moduleId of REFERENCE_MODULE_IDS) {
+        const reference = discoverLocalReferenceModuleSource({ appRoot: templateRoot, moduleId })
+        if (!reference) {
+          throw new Error(`[module-facts] reference module "${moduleId}" is missing from the create-app template`)
+        }
+        const { entry, markdown, warnings: referenceWarnings, unresolvedTargets } = extractLocalReferenceModuleFacts({
+          packageSources: sources,
+          reference,
+          registryPath: existsSync(registryPath) ? registryPath : null,
+          coreVersion,
+        })
+        referenceBundle[moduleId] = entry
+        mkdirSync(referenceGuidesDir, { recursive: true })
+        writeFileSync(join(referenceGuidesDir, `${moduleId}.md`), markdown)
+        for (const warning of referenceWarnings) console.warn(warning)
+        for (const target of unresolvedTargets) {
+          console.warn(`[module-facts][reference] unresolved first-party target: ${target}`)
+        }
+      }
+      writeFileSync(join(guidesDestDir, 'reference-module-facts.json'), renderReferenceModuleFactsJson(referenceBundle))
+      console.log(
+        `Generated ${REFERENCE_MODULE_IDS.length} local reference projection(s) → dist/agentic/guides/reference-modules/`,
+      )
     } else {
       console.warn('[module-facts] no package modules discovered; skipping fact-sheet generation')
     }

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

@@ -18,7 +18,7 @@ Every app page is module-owned and auto-discovered: author it under `src/modules
 | 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.
+List destinations need stable `pageGroup`, `pageGroupKey`, and order. A `page.meta.ts` `icon` MUST be a name the installed icon registry already lists — an unlisted Lucide name renders no icon at all, silently — so verify it before use; 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
 
@@ -78,3 +78,9 @@ For a new editable entity or module, unless the brief explicitly excludes an ope
 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.
+
+## Canonical example source
+
+This guide stays the rule owner. For one compiling implementation of a table, form, page shell, or rendered injected widget, open the exact row in [`src/modules/example/references/surface-map.md`](../../src/modules/example/references/surface-map.md) — its `Backend UI` section links each file — or go straight to [`components/TodosTable.tsx`](../../src/modules/example/components/TodosTable.tsx) and [`components/TodoForm.tsx`](../../src/modules/example/components/TodoForm.tsx). That module is source-present and runtime-disabled: read one row, never the tree, and rename every `example` identifier.
+
+When you need what the component *accepts*, not how the example uses it, open the installed implementation: [`@open-mercato/ui/src/backend/DataTable.tsx`](../../node_modules/@open-mercato/ui/src/backend/DataTable.tsx). That exact file is what your app installs. Read-only: never edit inside `node_modules`, and take no sibling or import target this guide does not link.