sinapse-ai 1.24.0 → 1.25.0

package/packages/installer/src/updater/index.js

@@ -20,10 +20,11 @@ const fs = require('fs-extra');
 const path = require('path');
 const os = require('os');
 const https = require('https');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const { hashFile, hashesMatch } = require('../installer/file-hasher');
 const { PostInstallValidator, formatReport: formatValidationReport } = require('../installer/post-install-validator');
 const { _testing: { installGlobalAgents } } = require('../wizard/index');
+const { installSinapseCore } = require('../installer/sinapse-ai-installer');
 
 /**
  * Update status types
@@ -601,20 +602,35 @@ class SINAPSEUpdater {
 
     try {
       // Use npm to update the package
-      const cmd = `npm install sinapse-ai@${targetVersion} --save-exact`;
-      this.log(`Running: ${cmd}`);
+      const packageSpec = `sinapse-ai@${targetVersion}`;
+      this.log(`Running: npm install ${packageSpec} --save-exact`);
 
-      execSync(cmd, {
+      execFileSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', packageSpec, '--save-exact'], {
         cwd: this.projectRoot,
         stdio: this.options.verbose ? 'inherit' : 'pipe',
         timeout: 120000, // 2 minutes
       });
 
-      result.success = true;
-      result.filesUpdated = 1; // At least package updated
+      const recordedProviders = Array.isArray(this.versionInfo?.providers)
+        ? this.versionInfo.providers
+        : [];
+      const includeClaude = recordedProviders.length > 0
+        ? recordedProviders.includes('claude-code')
+        : fs.existsSync(path.join(this.projectRoot, '.claude', 'skill-manifest.json'));
+      const includeCodex = recordedProviders.length > 0
+        ? recordedProviders.includes('codex')
+        : fs.existsSync(path.join(this.projectRoot, '.codex', 'catalog.json'))
+          && fs.existsSync(path.join(this.projectRoot, '.agents', 'skills', 'sinapse-agent', 'SKILL.md'));
+      const delivery = await installSinapseCore({
+        targetDir: this.projectRoot,
+        includeClaude,
+        includeCodex,
+        overwriteManagedAdapters: true,
+      });
+      if (!delivery.success) throw new Error(`Framework payload reconciliation failed: ${delivery.errors.join('; ')}`);
 
-      // TODO: Copy new files from node_modules to .sinapse-ai
-      // preserving customizedFiles
+      result.success = true;
+      result.filesUpdated = 1 + delivery.installedFiles.length;
 
       return result;
     } catch (error) {
@@ -637,6 +653,7 @@ class SINAPSEUpdater {
       installedAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
       mode: this.versionInfo?.mode || 'project-development',
+      providers: Array.isArray(this.versionInfo?.providers) ? this.versionInfo.providers : [],
       fileHashes: {}, // Will be populated by file copy
     };
 
@@ -764,14 +781,14 @@ class SINAPSEUpdater {
       const installResult = await installGlobalAgents();
       result.installed = installResult.count;
       if (installResult.errors.length > 0) {
-        console.log(`  Agent install warnings: ${installResult.errors.join(', ')}`);
+        console.log(`  Agent install warnings: ${sanitizeLogText(installResult.errors.join(', '))}`);
       }
 
       result.migrated = true;
       console.log(`  v6 migration complete: ${result.removed} removed, ${result.installed} installed`);
     } catch (error) {
       // Migration errors should not block the update
-      console.log(`  v6 migration warning: ${error.message}`);
+      console.log(`  v6 migration warning: ${sanitizeLogText(error.message)}`);
     }
 
     return result;
@@ -788,13 +805,17 @@ class SINAPSEUpdater {
    */
   log(message) {
     if (this.options.verbose) {
-      // eslint-disable-next-line no-control-regex
-      const sanitized = String(message).replace(/[\x00-\x08\x0B-\x1F\x7F]/g, '');
+      const sanitized = sanitizeLogText(message);
       console.log(`[SINAPSEUpdater] ${sanitized}`);
     }
   }
 }
 
+function sanitizeLogText(value) {
+  // eslint-disable-next-line no-control-regex
+  return String(value).replace(/[\x00-\x1F\x7F\u2028\u2029]/g, ' ');
+}
+
 /**
  * Format update check result for console
  *
@@ -920,5 +941,5 @@ module.exports = {
   FileAction,
   formatCheckResult,
   formatUpdateResult,
+  sanitizeLogText,
 };
-

package/packages/installer/src/wizard/feedback.js

@@ -22,7 +22,7 @@ const { t } = require('./i18n');
  * Do NOT inline these numbers elsewhere in this file — reference `ECOSYSTEM`
  * so there is exactly one place to update when `sync:counts` changes.
  */
-const ECOSYSTEM = Object.freeze({ squads: 17, agents: 172, tasks: '1,200' });
+const ECOSYSTEM = Object.freeze({ squads: 17, agents: 172, tasks: '1,411' });
 
 /**
  * Create and start a spinner with SINAPSE styling

package/packages/installer/src/wizard/ide-config-generator.js

@@ -544,6 +544,9 @@ async function copyClaudeHooksFolder(projectRoot) {
     'enforce-story-gate.cjs',
     'doc-first-gate.cjs',
     'enforce-framework-boundary.cjs',
+    'enforce-permission-mode.cjs',
+    'enforce-nsn-guard.cjs',
+    'verify-packages.cjs',
     'secret-scanning.cjs',
     'write-path-validation.cjs',
     // Frente 4.3 — DORA + OTel telemetry hooks (STREAM A)
@@ -619,6 +622,21 @@ const HOOK_EVENT_MAP = {
     matcher: 'Write|Edit',
     timeout: 5,
   },
+  'enforce-permission-mode.cjs': {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit|Bash',
+    timeout: 5,
+  },
+  'enforce-nsn-guard.cjs': {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    timeout: 5,
+  },
+  'verify-packages.cjs': {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    timeout: 10,
+  },
   'write-path-validation.cjs': {
     event: 'PreToolUse',
     matcher: 'Write|Edit',

package/packages/installer/src/wizard/index.js

@@ -88,6 +88,11 @@ async function writeClaudeSettings(language, projectDir = process.cwd()) {
   }
 }
 
+async function writeProviderLanguageSettings({ selectedLLM, language, projectDir = process.cwd() }) {
+  if (!language || !shouldConfigureClaude(selectedLLM)) return false;
+  return writeClaudeSettings(language, projectDir);
+}
+
 /** Detect system locale and return wizard language code. */
 function detectSystemLocale() {
   try {
@@ -285,6 +290,14 @@ function llmLabel(selectedLLM) {
   }
 }
 
+function shouldConfigureClaude(selectedLLM) {
+  return selectedLLM === 'claude-code' || selectedLLM === 'both';
+}
+
+function shouldConfigureCodex(selectedLLM) {
+  return selectedLLM === 'codex' || selectedLLM === 'both';
+}
+
 /**
  * 18 orqx agent definitions to install globally (17 squad orqx + 1 master).
  * Each entry maps agent-id to its squad directory name.
@@ -512,6 +525,7 @@ async function runWizard(options = {}) {
       sinapseCoreResult = await installSinapseCore({
         targetDir: process.cwd(),
         includeCodex: (answers.selectedLLM || 'claude-code') !== 'claude-code',
+        includeClaude: (answers.selectedLLM || 'claude-code') !== 'codex',
         onProgress: (_status) => {
           // Silent progress - spinner handles feedback
         },
@@ -557,7 +571,8 @@ async function runWizard(options = {}) {
 
     // Install global orqx agent definitions to ~/.claude/agents/ (only for Claude Code)
     const selectedLLM = answers.selectedLLM || 'claude-code';
-    if (selectedLLM === 'claude-code' || selectedLLM === 'both') {
+    const targetProjectRoot = process.cwd();
+    if (shouldConfigureClaude(selectedLLM)) {
       console.log('\n🤖 ' + t('installingGlobalAgents'));
       try {
         const globalAgentsResult = await installGlobalAgents();
@@ -708,100 +723,106 @@ async function runWizard(options = {}) {
       // Legacy per-squad IDE copy path removed; sync pipeline handles IDE propagation.
     }
 
+    if (shouldConfigureClaude(selectedLLM)) {
     // Story INS-4.3: Wire settings.json boundary generator after .sinapse-ai/ copy
-    console.log('\n🔒 ' + t('generatingBoundaryRules'));
-    try {
-      const settingsGenerator = require('../../../../.sinapse-ai/infrastructure/scripts/generate-settings-json');
-      settingsGenerator.generate(process.cwd());
-      const settingsContent = await fse.readFile(path.join(process.cwd(), '.claude', 'settings.json'), 'utf8').catch(() => '{}');
-      const settingsParsed = JSON.parse(settingsContent);
-      const denyCount = (settingsParsed.permissions && settingsParsed.permissions.deny) ? settingsParsed.permissions.deny.length : 0;
-      console.log(`✅ settings.json: generated (${denyCount} deny rules)`);
-      answers.settingsGenerated = true;
-      answers.settingsDenyCount = denyCount;
-    } catch (error) {
-      console.warn(`⚠️  settings.json generation failed: ${error.message} — run 'sinapse doctor --fix' post-install`);
-      answers.settingsGenerated = false;
-    }
+      console.log('\n🔒 ' + t('generatingBoundaryRules'));
+      try {
+        const settingsGenerator = require('../../../../.sinapse-ai/infrastructure/scripts/generate-settings-json');
+        settingsGenerator.generate(process.cwd());
+        const settingsContent = await fse.readFile(path.join(process.cwd(), '.claude', 'settings.json'), 'utf8').catch(() => '{}');
+        const settingsParsed = JSON.parse(settingsContent);
+        const denyCount = (settingsParsed.permissions && settingsParsed.permissions.deny) ? settingsParsed.permissions.deny.length : 0;
+        console.log(`✅ settings.json: generated (${denyCount} deny rules)`);
+        answers.settingsGenerated = true;
+        answers.settingsDenyCount = denyCount;
+      } catch (error) {
+        console.warn(`⚠️  settings.json generation failed: ${error.message} — run 'sinapse doctor --fix' post-install`);
+        answers.settingsGenerated = false;
+      }
 
-    // Story INS-4.3: Copy skills (Gap #11)
-    console.log('\n📚 ' + t('copyingSkills'));
-    try {
-      const skillsResult = await copySkillFiles(process.cwd());
-      if (skillsResult.skipped) {
-        console.log('   ℹ️  Skills: source not found (skipped)');
-      } else {
-        console.log(`✅ Skills: ${skillsResult.count} copied`);
+      // Story INS-4.3: Copy skills (Gap #11)
+      console.log('\n📚 ' + t('copyingSkills'));
+      try {
+        const skillsResult = await copySkillFiles(process.cwd());
+        if (skillsResult.skipped) {
+          console.log('   ℹ️  Skills: source not found (skipped)');
+        } else {
+          console.log(`✅ Skills: ${skillsResult.count} copied`);
+        }
+        answers.skillsCopied = skillsResult.count;
+        answers.skillsSkipped = skillsResult.skipped;
+      } catch (error) {
+        console.warn(`⚠️  Skills copy failed: ${error.message}`);
+        answers.skillsCopied = 0;
       }
-      answers.skillsCopied = skillsResult.count;
-      answers.skillsSkipped = skillsResult.skipped;
-    } catch (error) {
-      console.warn(`⚠️  Skills copy failed: ${error.message}`);
-      answers.skillsCopied = 0;
-    }
 
-    // Story INS-4.3: Copy extra commands (Gap #12)
-    console.log('\n📋 ' + t('copyingExtraCommands'));
-    try {
-      const commandsResult = await copyExtraCommandFiles(process.cwd());
-      if (commandsResult.skipped) {
-        console.log('   ℹ️  Extra commands: source not found (skipped)');
-      } else {
-        console.log(`✅ Commands: ${commandsResult.count} extras copied`);
+      // Story INS-4.3: Copy extra commands (Gap #12)
+      console.log('\n📋 ' + t('copyingExtraCommands'));
+      try {
+        const commandsResult = await copyExtraCommandFiles(process.cwd());
+        if (commandsResult.skipped) {
+          console.log('   ℹ️  Extra commands: source not found (skipped)');
+        } else {
+          console.log(`✅ Commands: ${commandsResult.count} extras copied`);
+        }
+        answers.extraCommandsCopied = commandsResult.count;
+        answers.extraCommandsSkipped = commandsResult.skipped;
+      } catch (error) {
+        console.warn(`⚠️  Extra commands copy failed: ${error.message}`);
+        answers.extraCommandsCopied = 0;
       }
-      answers.extraCommandsCopied = commandsResult.count;
-      answers.extraCommandsSkipped = commandsResult.skipped;
-    } catch (error) {
-      console.warn(`⚠️  Extra commands copy failed: ${error.message}`);
-      answers.extraCommandsCopied = 0;
-    }
 
-    // Story INS-4.5: IDE Sync — transform agents/skills/commands for each configured IDE
-    console.log('\n🔄 ' + t('runningIdeSync'));
-    const targetProjectRoot = process.cwd();
-    const savedCwd = process.cwd();
-    try {
-      process.chdir(targetProjectRoot);
-      await commandSync({ quiet: true });
-      answers.ideSyncStatus = 'synced';
-      console.log('✅ IDE sync: synced');
-
-      // Validate sync output (commandValidate does not support quiet — suppress its console output)
-      const _origLog = console.log;
-      console.log = () => {};
+      // Story INS-4.5: IDE Sync — transform agents/skills/commands for each configured IDE
+      console.log('\n🔄 ' + t('runningIdeSync'));
+      const savedCwd = process.cwd();
       try {
-        await commandValidate({ quiet: true });
-        answers.ideSyncValidation = 'pass';
-      } catch {
-        answers.ideSyncValidation = 'drift';
+        process.chdir(targetProjectRoot);
+        await commandSync({ quiet: true });
+        answers.ideSyncStatus = 'synced';
+        console.log('✅ IDE sync: synced');
+
+        // Validate sync output (commandValidate does not support quiet — suppress its console output)
+        const _origLog = console.log;
+        console.log = () => {};
+        try {
+          await commandValidate({ quiet: true });
+          answers.ideSyncValidation = 'pass';
+        } catch {
+          answers.ideSyncValidation = 'drift';
+        } finally {
+          console.log = _origLog;
+        }
+        if (answers.ideSyncValidation === 'drift') {
+          console.warn('⚠️  ' + t('ideSyncDriftWarning'));
+        }
+      } catch (syncError) {
+        console.warn(`⚠️  IDE sync failed: ${syncError.message} — run 'sinapse doctor --fix' post-install`);
+        answers.ideSyncStatus = 'failed';
+        answers.ideSyncValidation = 'skipped';
       } finally {
-        console.log = _origLog;
-      }
-      if (answers.ideSyncValidation === 'drift') {
-        console.warn('⚠️  ' + t('ideSyncDriftWarning'));
+        process.chdir(savedCwd);
       }
-    } catch (syncError) {
-      console.warn(`⚠️  IDE sync failed: ${syncError.message} — run 'sinapse doctor --fix' post-install`);
-      answers.ideSyncStatus = 'failed';
-      answers.ideSyncValidation = 'skipped';
-    } finally {
-      process.chdir(savedCwd);
+
     }
 
     // Codex local-first sync: the ide-sync above drives claude-code only now,
     // so .codex/agents + .codex/skills are regenerated here from the canonical
     // source (the static .codex payload — scripts/tasks/JSONs — was already
     // copied by installSinapseCore when Codex was selected). Codex installs only.
-    if (selectedLLM === 'codex' || selectedLLM === 'both') {
+    if (shouldConfigureCodex(selectedLLM)) {
       console.log('\n🔄 ' + t('runningCodexSync'));
       const savedCwdCodex = process.cwd();
       try {
         const { syncCodexLocalFirst } = require('../../../../.sinapse-ai/infrastructure/scripts/sync-codex-local-first');
+        const { syncCodexNativeAgents } = require('../../../../.codex/scripts/sync-codex-native');
         process.chdir(targetProjectRoot);
         const codexResult = syncCodexLocalFirst({ projectRoot: targetProjectRoot, quiet: true });
+        const nativeResult = codexResult.ok
+          ? syncCodexNativeAgents(targetProjectRoot)
+          : { total: 0 };
         answers.codexSyncStatus = codexResult.ok ? 'synced' : 'failed';
         const m = codexResult.metrics || {};
-        console.log(`✅ Codex sync: ${codexResult.ok ? 'synced' : 'issues'} (${m.codexAgents || 0} agents, ${m.codexSkills || 0} skills)`);
+        console.log(`✅ Codex sync: ${codexResult.ok ? 'synced' : 'issues'} (${m.codexAgents || 0} adapters, ${nativeResult.total || 0} native agents, ${m.codexSkills || 0} compatibility skills)`);
       } catch (codexErr) {
         console.warn(`⚠️  Codex sync failed: ${codexErr.message} — run 'npm run sync:ide:codex' post-install`);
         answers.codexSyncStatus = 'failed';
@@ -877,8 +898,11 @@ async function runWizard(options = {}) {
       });
 
       // Story ACT-12: Write language to Claude Code settings.json
-      if (answers.language) {
-        const langWritten = await writeClaudeSettings(answers.language);
+      if (answers.language && shouldConfigureClaude(selectedLLM)) {
+        const langWritten = await writeProviderLanguageSettings({
+          selectedLLM,
+          language: answers.language,
+        });
         if (langWritten) {
           console.log('  - Language written to .claude/settings.json');
         } else {
@@ -1266,6 +1290,7 @@ module.exports = {
   // Exported for testing
   _testing: {
     writeClaudeSettings,
+    writeProviderLanguageSettings,
     getExistingLanguage,
     LANGUAGE_MAP,
     detectProjectType,
@@ -1274,6 +1299,8 @@ module.exports = {
     detectSystemLocale,
     llmToIDEs,
     llmLabel,
+    shouldConfigureClaude,
+    shouldConfigureCodex,
     installGlobalAgents,
     buildAgentTemplate,
     generateAgentsMd,

package/scripts/gen-agent-badges.js

@@ -96,8 +96,24 @@ for (const b of badges) if (!b.icon) { b.icon = squadIcon[b.squad] || '◆'; b.h
 // The badge uses only the FIRST name (never the full name).
 for (const b of badges) b.name = b.name.split(/\s+/)[0];
 
+// Some source .md files carry the emoji as a LITERAL escape sequence
+// ("\U0001F9E0" as text). Decode at generation time so every consumer
+// (statusline, selo block) receives the real glyph — never garbage.
+function decodeEmoji(e) {
+  if (typeof e !== 'string' || !e) return e;
+  if (!e.includes('\\u') && !e.includes('\\U')) return e;
+  try {
+    const decoded = e
+      .replace(/\\U([0-9A-Fa-f]{8})/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+      .replace(/\\u([0-9A-Fa-f]{4})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+    return decoded || e;
+  } catch {
+    return e;
+  }
+}
+
 const out = {};
-for (const b of badges) out[b.id] = { emoji: b.icon, area: b.area, name: b.name };
+for (const b of badges) out[b.id] = { emoji: decodeEmoji(b.icon), area: b.area, name: b.name };
 fs.writeFileSync(OUT, JSON.stringify(out, null, 2));
 
 const generic = badges.filter((b) => b.icon === '◆').length;

package/scripts/release-readiness.js

@@ -48,6 +48,9 @@ const GATES = [
   { id: 'parity', name: 'Cross-IDE parity (10.18)', cmd: ['npm', 'run', 'validate:parity', '--silent'] },
   { id: 'manifest', name: 'Install manifest', cmd: ['npm', 'run', 'validate:manifest', '--silent'] },
   { id: 'install-docs', name: 'Install docs', cmd: ['npm', 'run', 'validate:docs', '--silent'] },
+  { id: 'providers', name: 'Native providers', cmd: ['npm', 'run', 'validate:providers', '--silent'] },
+  { id: 'engineering', name: 'Engineering applicability', cmd: ['npm', 'run', 'validate:engineering-applicability', '--silent'] },
+  { id: 'publish', name: 'Publish safety', cmd: ['npm', 'run', 'validate:publish', '--silent'] },
 ];
 
 function parseArgs(argv = process.argv.slice(2)) {
@@ -60,10 +63,13 @@ function parseArgs(argv = process.argv.slice(2)) {
 
 function runGate(gate) {
   const start = Date.now();
-  const result = spawnSync(gate.cmd[0], gate.cmd.slice(1), {
+  const npmCli = gate.cmd[0] === 'npm' ? process.env.npm_execpath : null;
+  const executable = npmCli ? process.execPath : gate.cmd[0];
+  const args = npmCli ? [npmCli, ...gate.cmd.slice(1)] : gate.cmd.slice(1);
+  const result = spawnSync(executable, args, {
     cwd: PROJECT_ROOT,
     encoding: 'utf8',
-    shell: process.platform === 'win32',
+    shell: false,
   });
   const elapsed = Date.now() - start;
   return {
@@ -72,7 +78,7 @@ function runGate(gate) {
     status: result.status === 0 ? 'PASS' : 'FAIL',
     exitCode: result.status,
     elapsedMs: elapsed,
-    stderr: result.stderr ? result.stderr.split('\n').slice(-5).join('\n') : '',
+    stderr: result.stderr ? result.stderr.split('\n').slice(-5).join('\n') : (result.error?.message || ''),
   };
 }
 

package/scripts/research/generate-react-bits-catalog.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const valueOf = flag => {
+  const index = args.indexOf(flag);
+  return index === -1 ? undefined : args[index + 1];
+};
+
+const repo = resolve(valueOf('--repo') || '../.tmp-react-bits-research');
+const output = resolve(valueOf('--output') || 'docs/framework/react-bits');
+const infoPath = join(repo, 'src', 'constants', 'Information.js');
+
+if (!existsSync(join(repo, '.git')) || !existsSync(infoPath)) {
+  throw new Error(`React Bits checkout not found or incomplete: ${repo}`);
+}
+
+const sha = execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+const commitDate = execFileSync('git', ['-C', repo, 'show', '-s', '--format=%cI', 'HEAD'], {
+  encoding: 'utf8'
+}).trim();
+const { componentMetadata, VARIANTS } = await import(`${pathToFileURL(infoPath).href}?sha=${sha}`);
+
+if (!componentMetadata || !Array.isArray(VARIANTS) || VARIANTS.length !== 4) {
+  throw new Error('Required React Bits metadata exports are missing or changed');
+}
+
+const categories = ['Animations', 'TextAnimations', 'Components', 'Backgrounds'];
+const categorySlugs = {
+  Animations: 'animations',
+  TextAnimations: 'text-animations',
+  Components: 'components',
+  Backgrounds: 'backgrounds'
+};
+
+const walk = directory =>
+  readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? walk(path) : [path];
+  });
+
+const codeMetadataFiles = walk(join(repo, 'src', 'constants', 'code')).filter(path => path.endsWith('.js'));
+const codeMetadata = new Map();
+
+for (const path of codeMetadataFiles) {
+  const source = readFileSync(path, 'utf8');
+  const sourceMatch = source.match(/@(?:content|ts-default)\/([^/]+)\/([^/]+)\//);
+  if (!sourceMatch) continue;
+  const dependencyMatch = source.match(/dependencies\s*:\s*([`'"])([\s\S]*?)\1/);
+  const dependencies = dependencyMatch
+    ? dependencyMatch[2].replace(/^\s*(?:npm|pnpm|yarn|bun)\s+(?:i|install|add)\s+/, '').trim()
+    : '';
+  codeMetadata.set(`${sourceMatch[1]}/${sourceMatch[2]}`.toLowerCase(), { dependencies, path });
+}
+
+const findComponentDirectory = (category, name) => {
+  const root = join(repo, 'src', 'ts-default', category);
+  const match = readdirSync(root, { withFileTypes: true }).find(
+    entry => entry.isDirectory() && entry.name.toLowerCase() === name.toLowerCase()
+  );
+  if (!match) throw new Error(`Missing TS source directory for ${category}/${name}`);
+  return join(root, match.name);
+};
+
+const extractProps = source => {
+  const blocks = [];
+  const declarations = /(?:type|interface)\s+\w*Props\w*(?:\s+extends[^\{]+)?\s*(?:=\s*)?\{/g;
+  for (const match of source.matchAll(declarations)) {
+    let depth = 1;
+    let cursor = match.index + match[0].length;
+    const start = cursor;
+    while (cursor < source.length && depth > 0) {
+      if (source[cursor] === '{') depth += 1;
+      if (source[cursor] === '}') depth -= 1;
+      cursor += 1;
+    }
+    blocks.push(source.slice(start, cursor - 1));
+  }
+
+  const props = new Set();
+  for (const block of blocks) {
+    for (const line of block.split('\n')) {
+      const match = line.match(/^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:/);
+      if (match) props.add(match[1]);
+    }
+  }
+  return [...props];
+};
+
+const escapeCell = value => String(value || '').replaceAll('|', '\\|').replaceAll('\n', ' ');
+const entries = Object.entries(componentMetadata).map(([key, metadata]) => {
+  const directory = findComponentDirectory(metadata.category, metadata.name);
+  const sourceFile = readdirSync(directory).find(file => file.endsWith('.tsx'));
+  if (!sourceFile) throw new Error(`Missing TSX source for ${key}`);
+  const source = readFileSync(join(directory, sourceFile), 'utf8');
+  const demoPath = join(repo, 'src', 'demo', metadata.category, `${metadata.name}Demo.jsx`);
+  const demo = existsSync(demoPath) ? readFileSync(demoPath, 'utf8') : '';
+  const demoProps = [...demo.matchAll(/\bname\s*:\s*['"]([^'"]+)['"]/g)].map(match => match[1]);
+  const props = [...new Set(demoProps.length ? demoProps : extractProps(source))];
+  const code = codeMetadata.get(key.toLowerCase()) || codeMetadata.get(
+    `${metadata.category}/${basename(directory)}`.toLowerCase()
+  );
+  if (!code) throw new Error(`Missing code metadata for ${key}`);
+
+  const variantConfig = {
+    'JS-CSS': { root: 'content', extension: 'jsx' },
+    'JS-TW': { root: 'tailwind', extension: 'jsx' },
+    'TS-CSS': { root: 'ts-default', extension: 'tsx' },
+    'TS-TW': { root: 'ts-tailwind', extension: 'tsx' }
+  };
+  const declaredVariants = metadata.variants || VARIANTS;
+  const variants = Object.fromEntries(declaredVariants.map(variant => {
+    const config = variantConfig[variant];
+    const sourcePath = join(repo, 'src', config.root, metadata.category, basename(directory), `${basename(directory)}.${config.extension}`);
+    const registryPath = join(repo, 'public', 'r', `${metadata.name}-${variant}.json`);
+    if (!existsSync(sourcePath) || !existsSync(registryPath)) throw new Error(`Missing published variant ${key}/${variant}`);
+    const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+    const sourceBytes = statSync(sourcePath).size;
+    return [variant, {
+      source: sourcePath.slice(repo.length + 1).replaceAll('\\', '/'),
+      sourceBytes,
+      functional: sourceBytes > 0,
+      dependencies: registry.dependencies || [],
+      registryDependencies: registry.registryDependencies || []
+    }];
+  }));
+
+  return {
+    key,
+    ...metadata,
+    documentedDependencies: code.dependencies ? code.dependencies.split(/\s+/).filter(Boolean) : [],
+    dependencies: [...new Set(Object.values(variants).flatMap(variant => variant.dependencies))],
+    props,
+    variants,
+    sourceDirectory: basename(directory),
+    sourceFile
+  };
+});
+
+mkdirSync(output, { recursive: true });
+for (const category of categories) {
+  const list = entries.filter(entry => entry.category === category).sort((a, b) => a.name.localeCompare(b.name));
+  const lines = [
+    `# React Bits - ${category}`,
+    '',
+    `> Snapshot oficial: \`${sha}\` (${commitDate}). Total nesta categoria: **${list.length}**.`,
+    '',
+    'Cada item abaixo aponta para a documentacao e para o codigo TypeScript/CSS oficial fixado no commit pesquisado.',
+    '',
+    '| Componente | O que faz | Dependencias | Props publicas | Variantes |',
+    '|---|---|---|---|---|'
+  ];
+
+  for (const entry of list) {
+    const sourceUrl = `https://github.com/DavidHDev/react-bits/tree/${sha}/src/ts-default/${entry.category}/${entry.sourceDirectory}`;
+    const label = `[${entry.name}](${entry.docsUrl}) ([fonte](${sourceUrl}))`;
+    const props = entry.props.length ? entry.props.map(prop => `\`${prop}\``).join(', ') : 'children / DOM props';
+    const variantStatus = Object.entries(entry.variants)
+      .map(([variant, details]) => details.functional ? variant : `${variant} (VAZIA no upstream)`)
+      .join(', ');
+    const dependencies = entry.dependencies.length ? entry.dependencies.join(' ') : 'none';
+    lines.push(
+      `| ${label} | ${escapeCell(entry.description)} | \`${escapeCell(dependencies)}\` | ${escapeCell(props)} | ${variantStatus} |`
+    );
+  }
+
+  lines.push('', '## Comandos por componente', '');
+  lines.push('Substituir `<Component>` pelo nome exato da primeira coluna:');
+  lines.push('', '```bash');
+  lines.push('npx shadcn@latest add @react-bits/<Component>-TS-TW');
+  lines.push('npx shadcn@latest add https://reactbits.dev/r/<Component>-TS-TW');
+  lines.push('npx jsrepo@latest add https://reactbits.dev/r/<Component>-TS-TW');
+  lines.push('```', '');
+  writeFileSync(join(output, `${categorySlugs[category]}.md`), `${lines.join('\n')}\n`);
+}
+
+const dependencyCounts = new Map();
+for (const entry of entries) {
+  const packages = entry.dependencies;
+  for (const packageName of packages) dependencyCounts.set(packageName, (dependencyCounts.get(packageName) || 0) + 1);
+}
+
+const incompleteVariants = entries.flatMap(entry => Object.entries(entry.variants)
+  .filter(([, details]) => !details.functional)
+  .map(([variant, details]) => ({ component: entry.name, category: entry.category, variant, source: details.source })));
+
+const summary = {
+  source: 'https://github.com/DavidHDev/react-bits',
+  sha,
+  commitDate,
+  total: entries.length,
+  categories: Object.fromEntries(categories.map(category => [category, entries.filter(item => item.category === category).length])),
+  variants: VARIANTS,
+  registryItems: entries.reduce((total, entry) => total + Object.keys(entry.variants).length, 0),
+  documentedProps: entries.reduce((total, entry) => total + entry.props.length, 0),
+  incompleteVariants,
+  dependencies: Object.fromEntries([...dependencyCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])))
+};
+writeFileSync(join(output, 'catalog-summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+writeFileSync(join(output, 'inventory.json'), `${JSON.stringify({ ...summary, components: entries }, null, 2)}\n`);
+
+process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);