@hubbiparts/uikit 0.1.0 → 0.2.1

package/bin/hubbiparts-uikit.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// hubbiparts-uikit — project context, catalog and maintenance helper for @hubbiparts/uikit.
+// Zero dependencies on purpose: it must run from node_modules in any consumer project.
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = '@hubbiparts/uikit'
+const SKILL_NAME = 'hubbiparts-uikit'
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const componentsDir = path.join(packageRoot, 'dist', 'components', 'ui')
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** Parses the `export { A, B, }` statement emitted by vite-plugin-dts. */
+export const parseExportNames = (declarationSource) => {
+  const names = new Set()
+  for (const match of declarationSource.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const raw of match[1].split(',')) {
+      const name = raw.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop()?.trim()
+      if (name) names.add(name)
+    }
+  }
+  for (const match of declarationSource.matchAll(/export\s+(?:declare\s+)?(?:function|const|type|interface)\s+([A-Za-z0-9_]+)/g)) {
+    names.add(match[1])
+  }
+  return [...names].sort()
+}
+
+const loadCatalog = () => {
+  if (!fs.existsSync(componentsDir)) {
+    throw new Error(`Build output not found at ${componentsDir}. Reinstall ${PACKAGE_NAME} (or run \`npm run build\` inside the kit repository).`)
+  }
+  return fs
+    .readdirSync(componentsDir)
+    .filter((file) => file.endsWith('.d.ts') && file !== 'index.d.ts')
+    .map((file) => {
+      const slug = file.replace(/\.d\.ts$/, '')
+      const source = fs.readFileSync(path.join(componentsDir, file), 'utf8')
+      return { slug, exports: parseExportNames(source) }
+    })
+    .sort((a, b) => a.slug.localeCompare(b.slug))
+}
+
+const latestPublishedVersion = () => {
+  try {
+    return execFileSync('npm', ['view', PACKAGE_NAME, 'version'], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch {
+    return null
+  }
+}
+
+const detectPackageManager = (cwd) => {
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock'))) return 'bun'
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn'
+  return 'npm'
+}
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.scss'])
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'build', '.next', 'coverage', '.git', 'storybook-static', 'dist-playground'])
+
+const walkSources = (dir, visit, depth = 0) => {
+  if (depth > 8 || !fs.existsSync(dir)) return
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRS.has(entry.name) && !entry.name.startsWith('.')) walkSources(path.join(dir, entry.name), visit, depth + 1)
+    } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+      visit(path.join(dir, entry.name))
+    }
+  }
+}
+
+const projectInfo = (cwd, { checkLatest }) => {
+  const manifest = readJson(path.join(cwd, 'package.json'))
+  if (!manifest) throw new Error(`No package.json found in ${cwd}. Run this command from the consumer project root.`)
+  const deps = { ...manifest.dependencies, ...manifest.devDependencies, ...manifest.peerDependencies }
+  const installedManifest = readJson(path.join(cwd, 'node_modules', ...PACKAGE_NAME.split('/'), 'package.json'))
+  const isKitRepository = manifest.name === PACKAGE_NAME
+  const catalog = loadCatalog()
+  const catalogSlugs = new Set(catalog.map((item) => item.slug))
+
+  const srcDir = fs.existsSync(path.join(cwd, 'src')) ? path.join(cwd, 'src') : cwd
+  let styleImportedIn = null
+  const importingFiles = []
+  walkSources(srcDir, (file) => {
+    const content = fs.readFileSync(file, 'utf8')
+    if (!content.includes(PACKAGE_NAME)) return
+    const relative = path.relative(cwd, file)
+    if (content.includes(`${PACKAGE_NAME}/style.css`)) styleImportedIn ??= relative
+    if (/from\s+['"]@hubbiparts\/uikit['"]/.test(content)) importingFiles.push(relative)
+  })
+
+  // Local shadcn copies that duplicate kit components are migration candidates.
+  const localUiDirs = ['src/components/ui', 'components/ui', 'src/shared/components/ui'].map((dir) => path.join(cwd, dir)).filter((dir) => fs.existsSync(dir))
+  const localDuplicates = localUiDirs.flatMap((dir) =>
+    fs
+      .readdirSync(dir)
+      .filter((file) => /\.(tsx|jsx)$/.test(file))
+      .map((file) => file.replace(/\.(tsx|jsx)$/, ''))
+      .filter((slug) => catalogSlugs.has(slug))
+      .map((slug) => path.relative(cwd, path.join(dir, `${slug}.tsx`))),
+  )
+
+  const tailwind = deps.tailwindcss ?? null
+  const tailwindMajor = tailwind ? Number(String(tailwind).replace(/^[^0-9]*/, '').split('.')[0]) : null
+  const installedVersion = isKitRepository ? manifest.version : installedManifest?.version ?? null
+  const latestVersion = checkLatest ? latestPublishedVersion() : null
+
+  return {
+    package: PACKAGE_NAME,
+    isKitRepository,
+    declaredRange: deps[PACKAGE_NAME] ?? null,
+    installedVersion,
+    latestVersion,
+    updateAvailable: Boolean(installedVersion && latestVersion && installedVersion !== latestVersion),
+    packageManager: detectPackageManager(cwd),
+    framework: deps.next ? 'next' : deps['@remix-run/react'] || deps['react-router'] ? 'react-router' : deps.vite ? 'vite' : 'unknown',
+    isRSC: Boolean(deps.next && (fs.existsSync(path.join(cwd, 'app')) || fs.existsSync(path.join(cwd, 'src', 'app')))),
+    react: deps.react ?? null,
+    tailwind: { version: tailwind, major: Number.isFinite(tailwindMajor) ? tailwindMajor : null },
+    iconLibrary: 'lucide-react',
+    primitiveBase: 'radix',
+    styleImportedIn,
+    importingFiles: importingFiles.slice(0, 50),
+    importingFilesCount: importingFiles.length,
+    localDuplicates,
+    components: catalog.map((item) => item.slug),
+  }
+}
+
+const printHelp = () => {
+  console.log(`Usage: npx hubbiparts-uikit <command> [options]
+
+Commands:
+  info [--json] [--offline]     Project context: versions, framework, Tailwind, CSS import, local duplicates
+  list [--json]                 Components shipped by the installed kit version and their exports
+  docs <slug...>                Public exports and TypeScript signatures for components
+  outdated [--json]             Compare the installed version with the latest published version
+  skill install [--dir <path>] [--copy]
+                                Install the agent skill into the project (default: .agents/skills, symlink)
+
+Examples:
+  npx hubbiparts-uikit info --json
+  npx hubbiparts-uikit docs sidebar dialog
+  npx hubbiparts-uikit skill install --dir .claude/skills`)
+}
+
+const installSkill = (cwd, args) => {
+  const dirFlag = args.indexOf('--dir')
+  const targetBase = path.resolve(cwd, dirFlag >= 0 && args[dirFlag + 1] ? args[dirFlag + 1] : '.agents/skills')
+  const source = path.join(packageRoot, 'skills', SKILL_NAME)
+  const target = path.join(targetBase, SKILL_NAME)
+  if (!fs.existsSync(path.join(source, 'SKILL.md'))) throw new Error(`Skill source not found at ${source}.`)
+  fs.mkdirSync(targetBase, { recursive: true })
+  if (fs.existsSync(target) || fs.lstatSync(target, { throwIfNoEntry: false })) {
+    const stat = fs.lstatSync(target)
+    if (!stat.isSymbolicLink()) throw new Error(`${target} already exists and is not a symlink. Remove it or pass a different --dir.`)
+    fs.unlinkSync(target)
+  }
+  if (args.includes('--copy')) {
+    fs.cpSync(source, target, { recursive: true })
+    console.log(`Copied skill to ${path.relative(cwd, target)} (re-run after upgrading the kit to refresh it).`)
+  } else {
+    fs.symlinkSync(path.relative(targetBase, source), target, 'dir')
+    console.log(`Linked ${path.relative(cwd, target)} -> ${path.relative(targetBase, source)} (tracks the installed kit version).`)
+  }
+  console.log(`Reference it from agent configs as: ${path.relative(cwd, path.join(target, 'SKILL.md'))}`)
+}
+
+const main = (argv) => {
+  const [command, ...args] = argv
+  const json = args.includes('--json')
+  const cwd = process.cwd()
+
+  switch (command) {
+    case 'info': {
+      const info = projectInfo(cwd, { checkLatest: !args.includes('--offline') })
+      if (json) console.log(JSON.stringify(info, null, 2))
+      else {
+        for (const [key, value] of Object.entries(info)) {
+          if (key === 'components') console.log(`components: ${value.length} (${value.join(', ')})`)
+          else console.log(`${key}: ${typeof value === 'object' && value !== null ? JSON.stringify(value) : value}`)
+        }
+      }
+      return
+    }
+    case 'list': {
+      const catalog = loadCatalog()
+      if (json) console.log(JSON.stringify(catalog, null, 2))
+      else for (const item of catalog) console.log(`${item.slug.padEnd(18)} ${item.exports.join(', ')}`)
+      return
+    }
+    case 'docs': {
+      const slugs = args.filter((arg) => !arg.startsWith('--'))
+      if (slugs.length === 0) throw new Error('Pass at least one component slug, e.g. `docs button dialog`.')
+      for (const slug of slugs) {
+        const file = path.join(componentsDir, `${slug}.d.ts`)
+        if (!fs.existsSync(file)) {
+          console.log(`## ${slug}\nNot shipped by ${PACKAGE_NAME}. Run \`npx hubbiparts-uikit list\` for the catalog.\n`)
+          continue
+        }
+        console.log(`## ${slug}\nimport { ${parseExportNames(fs.readFileSync(file, 'utf8')).join(', ')} } from '${PACKAGE_NAME}'\nshadcn reference: https://ui.shadcn.com/docs/components/radix/${slug}\n\n\`\`\`ts\n${fs.readFileSync(file, 'utf8').trim()}\n\`\`\`\n`)
+      }
+      return
+    }
+    case 'outdated': {
+      const info = projectInfo(cwd, { checkLatest: true })
+      const result = { installed: info.installedVersion, latest: info.latestVersion, updateAvailable: info.updateAvailable, declaredRange: info.declaredRange }
+      if (json) console.log(JSON.stringify(result, null, 2))
+      else if (!info.latestVersion) console.log('Could not reach the npm registry; latest version unknown.')
+      else console.log(info.updateAvailable ? `Update available: ${info.installedVersion} -> ${info.latestVersion}` : `Up to date (${info.installedVersion}).`)
+      return
+    }
+    case 'skill':
+      if (args[0] !== 'install') throw new Error('Usage: skill install [--dir <path>] [--copy]')
+      installSkill(cwd, args.slice(1))
+      return
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp()
+      return
+    default:
+      throw new Error(`Unknown command "${command}". Run \`npx hubbiparts-uikit help\`.`)
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    main(process.argv.slice(2))
+  } catch (error) {
+    console.error(`hubbiparts-uikit: ${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
+  }
+}