@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/engines/docs/lib/render-template.mjs

@@ -10,6 +10,9 @@ import {
   renderBehaviorTable,
   renderActionsTable,
   renderValidationDictionaryTable,
+  renderListColumnsTable,
+  renderListFiltersTable,
+  renderListPaginationBlock,
   renderStateMatrixTable,
   renderActionFlowsDetailed,
   renderCustomWidgetSpecs
@@ -66,6 +69,9 @@ export function renderWithTemplate(spec, context) {
     renderBehaviorTable,
     renderActionsTable,
     renderValidationDictionaryTable,
+    renderListColumnsTable,
+    renderListFiltersTable,
+    renderListPaginationBlock,
     renderStateMatrixTable,
     renderActionFlowsDetailed,
     renderCustomWidgetSpecs

package/engines/docs/render-docs.mjs

@@ -8,7 +8,9 @@ import { renderSpecMarkdown } from './lib/render-spec-markdown.mjs'
 import {
   irGeneratedMarkdownPath,
   irSpecPathForBundle,
-  writeIrSpecMarkdownFile
+  writeIrSpecMarkdownFile,
+  writeDataModelMarkdownFile,
+  writeApiMarkdownFile,
 } from './lib/render-bundle-markdown.mjs'
 
 const projectRoot = process.cwd()
@@ -34,7 +36,7 @@ const legacyRoot = cliFlag('legacy-root') ? path.resolve(cliFlag('legacy-root'))
 
 const devAppBaseUrl = resolveDevAppBaseUrl(projectRoot)
 
-import { renderFeatureBackendSpec, listBackendSpecFiles } from '../../scripts/backend-api/render-backend-spec.mjs'
+import { renderFeatureBackendSpec, listBackendSpecFiles } from '../openapi/render-backend-spec.mjs'
 import { writeQaList } from './lib/render-qa-list.mjs'
 
 async function main() {
@@ -63,6 +65,8 @@ async function main() {
     try {
       const mdOut = irGeneratedMarkdownPath(bundleFile)
       await writeIrSpecMarkdownFile(specIr, mdOut, { projectRoot, devAppBaseUrl })
+      await writeDataModelMarkdownFile(bundleFile)
+      await writeApiMarkdownFile(bundleFile)
     } catch (error) {
       failed++
       console.error(`docs:render: FAIL ${path.relative(projectRoot, specIr)}: ${error.message ?? error}`)

package/engines/docs/vitepress/config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitepress'
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { buildSurfacesSidebarItems, SKIP_NAV_DIRS, markdownNavText } from './surfaces-nav.mjs'
+import { buildSurfacesSidebarItems, SKIP_NAV_DIRS, markdownNavText, leafGeneratedNavNodes } from './surfaces-nav.mjs'
 
 import { fileURLToPath } from 'node:url'
 
@@ -89,12 +89,12 @@ function mdTitleFromFile(filePath: string, fallback: string) {
 }
 
 function attachGeneratedDocs(dirPath: string, urlPrefix: string, items: any[]) {
-  const spec = path.join(dirPath, 'ir', 'generated', 'spec.md')
-  if (fs.existsSync(spec)) {
-    items.push({
-      text: mdTitleFromFile(spec, 'spec'),
-      link: `${urlPrefix}ir/generated/spec`,
-    })
+  const toLink = (abs: string) => {
+    const rel = path.relative(dirPath, abs).split(path.sep).join('/').replace(/\.md$/, '')
+    return `${urlPrefix}${rel}`
+  }
+  for (const node of leafGeneratedNavNodes(dirPath, toLink)) {
+    items.push({ text: node.text, link: node.link })
   }
 }
 

package/engines/docs/vitepress/surfaces-nav.mjs

@@ -83,6 +83,38 @@ export function isFunctionLeaf(dir) {
   return existsSync(path.join(dir, 'ir', 'spec.yaml'))
 }
 
+/**
+ * VitePress nav entries for ir/generated under a function leaf.
+ * @param {string} leafDir
+ * @param {(absPath: string) => string} toHref
+ */
+export function leafGeneratedNavNodes(leafDir, toHref) {
+  const pageId = pageIdFromLeaf(leafDir)
+  const specMd = path.join(leafDir, 'ir', 'generated', 'spec.md')
+  const dmMd = path.join(leafDir, 'ir', 'generated', 'data-model.md')
+  const apiMd = path.join(leafDir, 'ir', 'generated', 'api.md')
+  const nodes = []
+  if (existsSync(specMd)) {
+    nodes.push({
+      text: `Spec · ${pageId}`,
+      link: toHref(specMd),
+    })
+  }
+  if (existsSync(dmMd)) {
+    nodes.push({
+      text: 'Data model',
+      link: toHref(dmMd),
+    })
+  }
+  if (existsSync(apiMd)) {
+    nodes.push({
+      text: 'API summary',
+      link: toHref(apiMd),
+    })
+  }
+  return nodes
+}
+
 export function pageIdFromLeaf(dir) {
   const specFile = path.join(dir, 'ir', 'spec.yaml')
   if (existsSync(specFile)) {
@@ -119,18 +151,16 @@ export function walkSurfacesNav(dir, toHref) {
     if (SKIP_NAV_DIRS.has(ent.name)) continue
     const full = path.join(dir, ent.name)
     if (isNumericSeq(ent.name) && isFunctionLeaf(full)) {
-      const pageId = pageIdFromLeaf(full)
-      const specMd = path.join(full, 'ir', 'generated', 'spec.md')
-      
-      // Bỏ qua nếu chưa chạy split (chưa có spec.md)
-      if (!existsSync(specMd)) continue
-      
-      const href = toHref(specMd)
-      children.push({
-        text: `${ent.name} + ${pageId}`,
-        href,
-        link: href,
-      })
+      const leafNodes = leafGeneratedNavNodes(full, toHref)
+      if (!leafNodes.length) continue
+      if (leafNodes.length === 1) {
+        children.push(leafNodes[0])
+      } else {
+        children.push({
+          text: `${ent.name} · ${pageIdFromLeaf(full)}`,
+          items: leafNodes,
+        })
+      }
       continue
     }
     const nested = walkSurfacesNav(full, toHref)
@@ -163,8 +193,9 @@ export function buildSurfacesSidebarItems(surfacesDir, urlPrefix) {
 function toVitepressItem(node) {
   const item = { text: node.text }
   if (node.link) item.link = node.link
-  if (node.items?.length) {
-    item.items = node.items.map(toVitepressItem)
+  const nested = node.items || node.children
+  if (nested?.length) {
+    item.items = nested.map(toVitepressItem)
     item.collapsed = true
   }
   return item

package/engines/openapi/check-backend-spec.mjs

@@ -44,7 +44,7 @@ export async function checkBackendSpecFiles(options, cwd = process.cwd()) {
   return files
 }
 
-function parseArgs(argv) {
+export function parseApiCheckArgs(argv) {
   const options = { spec: null }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -55,7 +55,7 @@ function parseArgs(argv) {
 }
 
 async function main() {
-  await checkBackendSpecFiles(parseArgs(process.argv.slice(2)), process.cwd())
+  await checkBackendSpecFiles(parseApiCheckArgs(process.argv.slice(2)), process.cwd())
 }
 
 if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {

package/engines/openapi/lib/markdown-table.mjs

@@ -0,0 +1,8 @@
+export {
+  MD_NONE,
+  escapeMarkdownHeading,
+  escapeCell,
+  renderTable,
+  objectRows,
+  formatCellValue,
+} from '../../docs/lib/markdown-table.mjs'

package/engines/openapi/lib/render-backend-spec-markdown.mjs

@@ -0,0 +1,78 @@
+import { stringify } from 'yaml'
+import { renderTable, escapeMarkdownHeading, MD_NONE } from './markdown-table.mjs'
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {{ specFile?: string, slug?: string }} context
+ */
+export function renderBackendSpecMarkdown(spec, context = {}) {
+  const feature = spec.feature ?? {}
+  const title = feature.title ?? context.slug ?? 'Backend API'
+  const lines = [
+    `# ${escapeMarkdownHeading(title)}`,
+    '',
+    `- **Source:** \`${context.specFile ?? '01-backend-spec.yaml'}\``,
+    `- **Status:** ${feature.status ?? 'draft'}`,
+    '',
+  ]
+
+  if (feature.source) {
+    lines.push('## Traceability', '', '```yaml', stringify(feature.source).trim(), '```', '')
+  }
+
+  const endpoints = spec.api?.endpoints ?? []
+  if (endpoints.length) {
+    lines.push('## Endpoints', '')
+    lines.push(
+      renderTable(
+        ['id', 'method', 'path', 'action', 'purpose'],
+        endpoints.map((ep) => [
+          ep.id ?? '',
+          ep.method ?? '',
+          ep.path ?? '',
+          ep.action ?? '',
+          ep.purpose ?? '',
+        ]),
+      ),
+    )
+    lines.push('')
+  } else {
+    lines.push('## Endpoints', '', MD_NONE, '')
+  }
+
+  if (spec.decisions?.length) {
+    lines.push('## Decisions', '')
+    for (const d of spec.decisions) {
+      lines.push(`- **${d.id ?? 'DEC'}:** ${d.summary ?? ''}`)
+    }
+    lines.push('')
+  }
+
+  if (spec.changeLog?.length) {
+    lines.push('## Change log', '')
+    for (const c of spec.changeLog) {
+      lines.push(`- **${c.id ?? 'CHG'}:** ${c.summary ?? ''}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n').endsWith('\n') ? lines.join('\n') : `${lines.join('\n')}\n`
+}
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {{ specFile?: string, slug?: string }} context
+ */
+export function renderCommonSpecMarkdown(spec, context = {}) {
+  const title = spec.title ?? context.slug ?? 'Common API'
+  return [
+    `# ${escapeMarkdownHeading(title)}`,
+    '',
+    `- **Source:** \`${context.specFile ?? 'common.yaml'}\``,
+    '',
+    '```yaml',
+    stringify(spec).trim(),
+    '```',
+    '',
+  ].join('\n')
+}

package/engines/registry-sync/be-capabilities-sync.mjs

@@ -0,0 +1,118 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const REGISTRY_REL = 'registries/be-capabilities.registry.json';
+
+const BE_SCAN_RULES = {
+  laravel: [
+    { kind: 'exceptionHandler', globs: ['app/Exceptions/Handler.php'], tags: ['#err:validation', '#err:not-found', '#err:permission-denied'] },
+    { kind: 'middleware', dir: 'app/Http/Middleware', tags: ['#api: middleware'] },
+    { kind: 'helpers', dir: 'app/Support', tags: ['#helper: support'] },
+    { kind: 'helpers', dir: 'app/Helpers', tags: ['#helper: app'] },
+    { kind: 'auth', globs: ['app/Http/Controllers/Controller.php', 'routes/api.php'], tags: ['#api: auth'] },
+  ],
+  nestjs: [
+    { kind: 'exceptionHandler', globs: ['src/common/filters/http-exception.filter.ts', 'src/filters/http-exception.filter.ts'], tags: ['#err:validation'] },
+    { kind: 'middleware', dir: 'src/common/middleware', tags: ['#api: middleware'] },
+    { kind: 'auth', globs: ['src/auth/auth.guard.ts', 'src/common/guards/jwt-auth.guard.ts'], tags: ['#api: auth', '#err:permission-denied'] },
+    { kind: 'helpers', dir: 'src/common', tags: ['#helper: common'] },
+  ],
+  fastapi: [
+    { kind: 'exceptionHandler', globs: ['app/core/exceptions.py', 'app/exceptions.py'], tags: ['#err:validation'] },
+    { kind: 'middleware', dir: 'app/middleware', tags: ['#api: middleware'] },
+    { kind: 'auth', globs: ['app/core/security.py', 'app/auth/deps.py'], tags: ['#api: auth'] },
+  ],
+};
+
+function loadJson(abs, fallback) {
+  if (!fs.existsSync(abs)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function listFilesInDir(root, relDir, max = 80) {
+  const dir = path.join(root, relDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (d, depth) => {
+    if (depth > 4 || out.length >= max) return;
+    for (const ent of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, ent.name);
+      if (ent.isDirectory()) walk(full, depth + 1);
+      else if (/\.(php|ts|py)$/.test(ent.name)) {
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(dir, 0);
+  return out;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} beAdapter
+ * @param {string} packageRoot
+ * @param {{ dryRun?: boolean }} opts
+ */
+export function syncBeCapabilitiesRegistry(projectRoot, beAdapter, packageRoot, opts = {}) {
+  const rules = BE_SCAN_RULES[beAdapter] ?? BE_SCAN_RULES.laravel;
+  const registryPath = path.join(projectRoot, REGISTRY_REL);
+  const baseTemplate = path.join(packageRoot, 'templates/shared/be-capabilities.registry.base.json');
+  const registry = loadJson(registryPath, loadJson(baseTemplate, { version: 1, capabilities: {} }));
+
+  const capabilities = { ...(registry.capabilities ?? {}) };
+  const middleware = [];
+  const exceptionHandlers = [];
+  const helpers = [];
+
+  for (const rule of rules) {
+    if (rule.globs) {
+      for (const g of rule.globs) {
+        const abs = path.join(projectRoot, g);
+        if (!fs.existsSync(abs)) continue;
+        const entry = { path: g, tags: rule.tags, kind: rule.kind };
+        capabilities[g] = entry;
+        if (rule.kind === 'exceptionHandler') exceptionHandlers.push(entry);
+        else if (rule.kind === 'auth') helpers.push(entry);
+      }
+    }
+    if (rule.dir) {
+      const files = listFilesInDir(projectRoot, rule.dir);
+      for (const f of files) {
+        const entry = { path: f, tags: rule.tags, kind: rule.kind };
+        capabilities[f] = entry;
+        if (rule.kind === 'middleware') middleware.push(entry);
+        else helpers.push(entry);
+      }
+    }
+  }
+
+  const merged = {
+    ...registry,
+    adapter: beAdapter,
+    capabilities,
+    middleware,
+    exceptionHandlers,
+    helpers,
+    scannedAt: new Date().toISOString(),
+  };
+
+  const report = {
+    registryPath: REGISTRY_REL,
+    capabilityKeys: Object.keys(capabilities).length,
+    middleware: middleware.length,
+    exceptionHandlers: exceptionHandlers.length,
+  };
+
+  if (opts.dryRun) {
+    return { ok: true, dryRun: true, report, registry: merged };
+  }
+
+  const dir = path.dirname(registryPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(registryPath, JSON.stringify(merged, null, 2) + '\n');
+  return { ok: true, report, registryPath };
+}

package/engines/registry-sync/fe-design-sync.mjs

@@ -0,0 +1,258 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const REGISTRY_REL = 'registries/design.registry.json';
+
+const UI_CANDIDATES = {
+  nuxt4: ['components/ui'],
+  nextjs: ['src/components/ui'],
+};
+
+const MOLECULE_CANDIDATES = {
+  nuxt4: ['components/molecules', 'components/organisms'],
+  nextjs: ['src/components/molecules', 'src/components/organisms', 'src/components/common'],
+};
+
+/** Vue/Nuxt composables + React hooks / shared logic */
+const COMPOSABLE_CANDIDATES = {
+  nuxt4: ['composables', 'app/composables', 'utils'],
+  nextjs: ['src/hooks', 'src/composables', 'composables', 'src/lib'],
+};
+
+const SHELL_CANDIDATES = {
+  nuxt4: {
+    DataListPage: ['components/organisms/DataListPage.vue', 'components/pages/DataListPage.vue'],
+    DataFormPage: ['components/organisms/DataFormPage.vue'],
+    DataDetailPage: ['components/organisms/DataDetailPage.vue'],
+  },
+  nextjs: {
+    DataListPage: ['src/components/organisms/data-list-page.tsx', 'src/components/templates/data-list-page.tsx'],
+    DataFormPage: ['src/components/organisms/data-form-page.tsx'],
+    DataDetailPage: ['src/components/organisms/data-detail-page.tsx'],
+  },
+};
+
+function folderToPascalCase(kebab) {
+  return String(kebab)
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function existsFile(root, rel) {
+  return fs.existsSync(path.join(root, rel));
+}
+
+function loadJson(abs, fallback) {
+  if (!fs.existsSync(abs)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function deepMergeRegistry(base, patch) {
+  const out = { ...base, ...patch };
+  out.shells = { ...(base.shells ?? {}), ...(patch.shells ?? {}) };
+  out.fieldWidgets = { ...(base.fieldWidgets ?? {}), ...(patch.fieldWidgets ?? {}) };
+  out.components = { ...(base.components ?? {}), ...(patch.components ?? {}) };
+  out.aliasIndex = { ...(base.aliasIndex ?? {}), ...(patch.aliasIndex ?? {}) };
+  out.componentAliases = { ...(base.componentAliases ?? {}), ...(patch.componentAliases ?? {}) };
+  out.composables = { ...(base.composables ?? {}), ...(patch.composables ?? {}) };
+  out.helpers = { ...(base.helpers ?? {}), ...(patch.helpers ?? {}) };
+  return out;
+}
+
+/** @param {string} base filename without ext */
+function composableExportName(base) {
+  if (/^use[A-Z]/.test(base)) return base;
+  if (base.startsWith('use-')) {
+    const rest = base.slice(4).split('-').map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+    return `use${rest}`;
+  }
+  return null;
+}
+
+function walkDirFiles(dir, exts, max = 500) {
+  const found = [];
+  if (!fs.existsSync(dir)) return found;
+  const stack = [dir];
+  while (stack.length && found.length < max) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const full = path.join(current, ent.name);
+      if (ent.isDirectory()) {
+        if (!['node_modules', '.git', 'dist', '.flowgrid'].includes(ent.name)) stack.push(full);
+      } else if (ent.isFile() && exts.some((e) => ent.name.endsWith(e))) {
+        found.push(full);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} feAdapter nuxt4 | nextjs
+ * @param {string} packageRoot flowgrid package (for base template)
+ * @param {{ dryRun?: boolean }} opts
+ */
+export function syncFeDesignRegistry(projectRoot, feAdapter, packageRoot, opts = {}) {
+  const adapter = feAdapter === 'nuxt4' ? 'nuxt4' : 'nextjs';
+  const registryDir = path.join(projectRoot, 'registries');
+  const registryPath = path.join(projectRoot, REGISTRY_REL);
+  const baseTemplate = path.join(packageRoot, 'templates/shared/design.registry.base.json');
+  let registry = loadJson(registryPath, loadJson(baseTemplate, { version: 1, shells: {}, fieldWidgets: {}, components: {} }));
+
+  const components = { ...(registry.components ?? {}) };
+  const fieldWidgets = { ...(registry.fieldWidgets ?? {}) };
+  const shells = { ...(registry.shells ?? {}) };
+  const composables = { ...(registry.composables ?? {}) };
+  const helpers = { ...(registry.helpers ?? {}) };
+
+  for (const rel of UI_CANDIDATES[adapter] ?? UI_CANDIDATES.nextjs) {
+    const uiDir = path.join(projectRoot, rel);
+    if (!fs.existsSync(uiDir)) continue;
+    const entries = fs.readdirSync(uiDir, { withFileTypes: true });
+    for (const entry of entries) {
+      let canonical;
+      let relPath;
+      if (adapter === 'nuxt4' && entry.isDirectory()) {
+        canonical = folderToPascalCase(entry.name);
+        relPath = `${rel}/${entry.name}`;
+      } else if (adapter === 'nextjs' && entry.isFile() && /\.(tsx|ts|vue)$/.test(entry.name)) {
+        const base = entry.name.replace(/\.(tsx|ts|vue)$/, '');
+        canonical = folderToPascalCase(base);
+        relPath = `${rel}/${entry.name}`;
+      } else {
+        continue;
+      }
+      components[canonical] = {
+        canonical,
+        category: 'ui',
+        tags: [`#ui: ${canonical}`],
+        portal: { layer: 'ui', path: relPath, status: 'implemented' },
+        source: 'registry:sync',
+      };
+      fieldWidgets[canonical] = fieldWidgets[canonical] ?? {
+        tag: `#widget: ${canonical}`,
+        component: canonical,
+        portal: { ui: canonical, status: 'implemented' },
+        source: 'registry:sync',
+      };
+    }
+  }
+
+  const molRoots = MOLECULE_CANDIDATES[adapter] ?? [];
+  const molFiles = molRoots.flatMap((r) => walkDirFiles(path.join(projectRoot, r), ['.vue', '.tsx', '.ts']));
+  for (const abs of molFiles) {
+    const base = path.basename(abs).replace(/\.(vue|tsx|ts)$/, '');
+    const moName = base.startsWith('Mo') ? base : base.match(/^mo-/) ? `Mo${folderToPascalCase(base.slice(3))}` : null;
+    const key = moName ?? (base.startsWith('Data') ? base : null);
+    if (!key) continue;
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    fieldWidgets[key] = {
+      tag: `#widget: ${key}`,
+      component: key,
+      portal: { molecule: key, path: rel, status: 'implemented' },
+      source: 'registry:sync',
+    };
+    if (key.startsWith('Mo')) {
+      components[key] = {
+        canonical: key,
+        category: 'molecule',
+        tags: [`#needs-component: ${key}`],
+        portal: { layer: 'molecule', path: rel, status: 'implemented' },
+        source: 'registry:sync',
+      };
+    }
+  }
+
+  const compRoots = COMPOSABLE_CANDIDATES[adapter] ?? [];
+  const compFiles = compRoots.flatMap((r) =>
+    walkDirFiles(path.join(projectRoot, r), ['.ts', '.js', '.mts']),
+  );
+  for (const abs of compFiles) {
+    const base = path.basename(abs).replace(/\.(ts|js|mts)$/, '');
+    if (base === 'index' || base.endsWith('.test') || base.endsWith('.spec')) continue;
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    const useName = composableExportName(base);
+    if (useName) {
+      composables[useName] = {
+        export: useName,
+        tags: [`#composable: ${useName}`],
+        path: rel,
+        status: 'implemented',
+        source: 'registry:sync',
+      };
+      continue;
+    }
+    const helperKey = folderToPascalCase(base);
+    if (rel.includes('/utils/') || rel.startsWith('utils/') || rel.includes('/lib/')) {
+      helpers[helperKey] = {
+        symbol: helperKey,
+        tags: [`#helper: ${helperKey}`],
+        path: rel,
+        status: 'implemented',
+        source: 'registry:sync',
+      };
+    }
+  }
+
+  for (const [shellName, candidates] of Object.entries(SHELL_CANDIDATES[adapter] ?? {})) {
+    const hit = candidates.find((c) => existsFile(projectRoot, c));
+    const prev = shells[shellName] ?? registry.shells?.[shellName] ?? { tag: `#shell: ${shellName}` };
+    shells[shellName] = {
+      ...prev,
+      tag: prev.tag ?? `#shell: ${shellName}`,
+      portal: {
+        ...(prev.portal ?? {}),
+        status: hit ? 'implemented' : prev.portal?.status ?? 'planned',
+        path: hit ?? prev.portal?.path,
+      },
+    };
+  }
+
+  const componentsJson = path.join(projectRoot, 'components.json');
+  if (fs.existsSync(componentsJson)) {
+    const cj = loadJson(componentsJson, {});
+    const uiAlias = cj?.aliases?.ui ?? cj?.aliases?.components;
+    if (typeof uiAlias === 'string') {
+      registry._shadcnUiAlias = uiAlias;
+    }
+  }
+
+  const merged = deepMergeRegistry(registry, {
+    components,
+    fieldWidgets,
+    shells,
+    composables,
+    helpers,
+    scannedAt: new Date().toISOString(),
+    scannedAdapter: adapter,
+  });
+
+  const report = {
+    registryPath: REGISTRY_REL,
+    uiComponents: Object.keys(components).length,
+    composables: Object.keys(merged.composables ?? {}).length,
+    helpers: Object.keys(merged.helpers ?? {}).length,
+    fieldWidgets: Object.keys(merged.fieldWidgets ?? {}).length,
+    shellsImplemented: Object.values(merged.shells ?? {}).filter((s) => s.portal?.status === 'implemented').length,
+  };
+
+  if (opts.dryRun) {
+    return { ok: true, dryRun: true, report, registry: merged };
+  }
+
+  if (!fs.existsSync(registryDir)) fs.mkdirSync(registryDir, { recursive: true });
+  fs.writeFileSync(registryPath, JSON.stringify(merged, null, 2) + '\n');
+  return { ok: true, report, registryPath };
+}