@ecomiq/storefront 1.1.9 → 2.0.1

package/src/codegen.mjs

@@ -0,0 +1,704 @@
+/**
+ * Codegen de Ecomiq.
+ *
+ * Lee `pages/` y `ecomiq.config.js` del proyecto del usuario y genera una app
+ * interna en `.ecomiq/` que sigue las convenciones de TanStack Start
+ * (routes con createFileRoute, router.tsx, vite.config.ts). El usuario nunca
+ * ve ni edita estos archivos: son un artefacto de build, como `.next/`.
+ *
+ * Convención de páginas:
+ *   pages/index.tsx                 → /
+ *   pages/products.$productId.tsx   → /products/:productId
+ *   pages/products.index.tsx        → /products
+ *   pages/api/$.ts                  → /api/$  (server route / proxy)
+ *
+ * Páginas cerradas del framework (siempre generadas, no overrideables):
+ *   /checkout/             ← redirect a /cart (checkout.index, sin layout padre)
+ *   /checkout/$checkoutId  ← flujo de checkout
+ *   /thank-you             ← post-compra
+ */
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  watch as watchFileSystem,
+  writeFileSync,
+  existsSync,
+  symlinkSync,
+  lstatSync,
+  readlinkSync,
+  unlinkSync,
+  statSync,
+  realpathSync,
+} from 'node:fs'
+import { createRequire } from 'node:module'
+import { resolve, join, relative, dirname, isAbsolute, sep } from 'node:path'
+
+const HEADER = '/* Generado por Ecomiq — no editar. */\n'
+const ROUTE_MANIFEST_FILE = 'generated-routes.json'
+
+/** Rutas reservadas que viven solo en el package (templates no pueden overridear). */
+const FRAMEWORK_LOCKED_PAGES = [
+  {
+    // index (no `checkout.tsx`): evita que TanStack anide $checkoutId bajo un layout
+    // que redirige a /cart.
+    rel: 'checkout.index.tsx',
+    routeId: '/checkout/',
+    importFrom: '@ecomiq/storefront/internal/checkout',
+  },
+  {
+    rel: 'checkout.$checkoutId.tsx',
+    routeId: '/checkout/$checkoutId',
+    importFrom: '@ecomiq/storefront/internal/checkout-session',
+  },
+  {
+    rel: 'thank-you.tsx',
+    routeId: '/thank-you',
+    importFrom: '@ecomiq/storefront/internal/thank-you',
+  },
+]
+
+export async function generateApp({ cwd, appDir, frameworkRoot, config }) {
+  const pagesDir = resolve(cwd, 'pages')
+  if (!existsSync(pagesDir)) {
+    throw new Error('No existe la carpeta pages/. Crea al menos pages/index.tsx')
+  }
+
+  const srcDir = join(appDir, 'src')
+  const routesDir = join(srcDir, 'routes')
+  mkdirSync(routesDir, { recursive: true })
+
+  // ── 1. dependencias internas resolubles desde .ecomiq (soporta npm, pnpm y monorepos) ──
+  linkFrameworkDependencies(appDir, frameworkRoot, cwd)
+
+  // ── 2. package.json interno (type: module para que Vite resuelva bien) ──
+  writeGeneratedFile(
+    join(appDir, 'package.json'),
+    JSON.stringify({ name: 'ecomiq-app', private: true, type: 'module' }, null, 2),
+  )
+
+  // ── 3. tsconfig interno ──
+  writeGeneratedFile(
+    join(appDir, 'tsconfig.json'),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          jsx: 'react-jsx',
+          module: 'ESNext',
+          moduleResolution: 'Bundler',
+          target: 'ES2022',
+          strict: true,
+          skipLibCheck: true,
+          verbatimModuleSyntax: true,
+          types: ['vite/client'],
+        },
+        include: ['src', '../pages', '../lib'],
+      },
+      null,
+      2,
+    ),
+  )
+
+  const publicConfig = {
+    name: config.name,
+    slug: config.slug,
+  }
+  if (config.description !== undefined) publicConfig.description = config.description
+  if (config.theme !== undefined) publicConfig.theme = config.theme
+  if (config.seo !== undefined) publicConfig.seo = config.seo
+  if (config.analytics !== undefined) publicConfig.analytics = config.analytics
+  if (config.layout !== undefined) publicConfig.layout = config.layout
+
+  for (const serverOnlyKey of ['api', 'dev', 'deploy', 'env']) {
+    if (Object.hasOwn(publicConfig, serverOnlyKey)) {
+      throw new Error(`La clave server-only \`${serverOnlyKey}\` no puede serializarse en app-config.ts`)
+    }
+  }
+
+  writeGeneratedFile(
+    join(srcDir, 'app-config.ts'),
+    HEADER +
+      `import type { PublicEcomiqConfig } from '@ecomiq/storefront'\n\n` +
+      `const config = ${JSON.stringify(publicConfig, null, 2)} satisfies PublicEcomiqConfig\n` +
+      `export default config\n`,
+  )
+
+  writeGeneratedFile(
+    join(srcDir, 'server.ts'),
+    HEADER +
+      `import startServer, { createServerEntry } from '@tanstack/react-start/server-entry'\n` +
+      `import config from '../../ecomiq.config.js'\n` +
+      `import { registerServerConfig } from '@ecomiq/storefront/internal/server-config'\n\n` +
+      `export default createServerEntry({\n` +
+      `  async fetch(...args) {\n` +
+      `    let api = config.api\n` +
+      `    if (import.meta.env.DEV && config.dev?.apiBaseUrl) {\n` +
+      `      api = { ...api, baseUrl: config.dev.apiBaseUrl }\n` +
+      `    }\n` +
+      `    registerServerConfig({ slug: config.slug, api })\n` +
+      `    return startServer.fetch(...args)\n` +
+      `  },\n` +
+      `})\n`,
+  )
+
+  // ── 5. styles.css: tokens del framework + fuentes de contenido del usuario ──
+  const themeOverrides = buildThemeOverrides(config)
+  writeGeneratedFile(
+    join(srcDir, 'styles.css'),
+    HEADER.replace('/*', '/*!') +
+      `@import '@ecomiq/storefront/styles.css';\n` +
+      `@source '../../pages';\n` +
+      `@source '../../components';\n` +
+      `@source '../../lib';\n` +
+      `@source '../../layout.tsx';\n` +
+      (themeOverrides ? `\n${themeOverrides}\n` : ''),
+  )
+
+  // ── 6. router.tsx ──
+  writeTemplate(frameworkRoot, srcDir, 'router.tsx')
+
+  // ── 7. __root.tsx (shell HTML + providers) ──
+  writeTemplate(frameworkRoot, routesDir, '__root.tsx')
+
+  // ── 7b. user-layout.tsx: layout.tsx del usuario si existe, si no el default ──
+  const hasCustomLayout = existsSync(resolve(cwd, 'layout.tsx')) || existsSync(resolve(cwd, 'layout.jsx'))
+  writeGeneratedFile(
+    join(srcDir, 'user-layout.tsx'),
+    HEADER +
+      (hasCustomLayout
+        ? `export { default } from '../../layout'\n`
+        : `export { default } from '@ecomiq/storefront/internal/default-layout'\n`),
+  )
+
+  // ── 8. rutas generadas desde pages/ (páginas UI + API server routes) ──
+  const entries = listPageEntries(pagesDir)
+  const pageEntries = entries.filter((e) => e.kind === 'page')
+  const apiEntries = entries.filter((e) => e.kind === 'api')
+  if (pageEntries.length === 0) {
+    throw new Error('pages/ está vacío. Crea al menos pages/index.tsx')
+  }
+
+  assertNoFrameworkPageOverrides(pageEntries)
+
+  const desiredRoutes = [
+    ...pageEntries.map((entry) => entry.rel.replace(/\.jsx$/, '.tsx')),
+    ...apiEntries.map((entry) => entry.rel),
+    ...FRAMEWORK_LOCKED_PAGES.map((page) => page.rel),
+  ].sort()
+
+  for (const entry of pageEntries) {
+    const routeId = fileToRouteId(entry.rel)
+    const outFile = join(routesDir, entry.rel.replace(/\.jsx$/, '.tsx'))
+    mkdirSync(dirname(outFile), { recursive: true })
+    const importPath = relative(dirname(outFile), join(pagesDir, entry.rel))
+      .replace(/\\/g, '/')
+      .replace(/\.(tsx|jsx)$/, '')
+    writeGeneratedFile(outFile, routeFileSource(routeId, importPath, entry.rel))
+  }
+
+  for (const entry of apiEntries) {
+    const routeId = fileToRouteId(entry.rel)
+    const outFile = join(routesDir, entry.rel)
+    mkdirSync(dirname(outFile), { recursive: true })
+    // Extensión explícita: archivos como `$.ts` no resuelven bien sin ella.
+    const importPath = relative(dirname(outFile), join(pagesDir, entry.rel)).replace(/\\/g, '/')
+    writeGeneratedFile(outFile, apiRouteFileSource(routeId, importPath))
+  }
+
+  for (const locked of FRAMEWORK_LOCKED_PAGES) {
+    const outFile = join(routesDir, locked.rel)
+    mkdirSync(dirname(outFile), { recursive: true })
+    writeGeneratedFile(
+      outFile,
+      frameworkLockedPageRouteSource(locked.routeId, locked.importFrom, locked.rel),
+    )
+  }
+
+  reconcileGeneratedRoutes(appDir, routesDir, desiredRoutes)
+
+  // ── 9. wrangler.jsonc para deploy en Cloudflare Workers ──
+  const workerName = config.deploy?.name ?? slugify(config.name ?? 'ecomiq-store')
+  writeGeneratedFile(
+    join(appDir, 'wrangler.jsonc'),
+    JSON.stringify(
+      {
+        $schema: 'node_modules/wrangler/config-schema.json',
+        name: workerName,
+        main: 'src/server.ts',
+        compatibility_date: '2026-01-01',
+        compatibility_flags: ['nodejs_compat'],
+        observability: {
+          enabled: false,
+          head_sampling_rate: 1,
+          logs: {
+            enabled: true,
+            head_sampling_rate: 1,
+            persist: true,
+            invocation_logs: true,
+          },
+          traces: {
+            enabled: false,
+            persist: true,
+            head_sampling_rate: 1,
+          },
+        },
+        ...(config.deploy?.routes ? { routes: config.deploy.routes } : {}),
+        vars: config.env ?? {},
+      },
+      null,
+      2,
+    ),
+  )
+
+  // ── 10. .gitignore para que .ecomiq no se versione dentro de sí mismo ──
+  writeGeneratedFile(join(appDir, '.gitignore'), '*\n')
+}
+
+export function watchPages({
+  cwd,
+  appDir,
+  frameworkRoot,
+  config,
+  debounceMs = 75,
+  /** Intervalo de polling (ms) como respaldo cuando `fs.watch` no emite eventos (p. ej. sandbox). */
+  pollMs = 0,
+  onGenerate = () => {},
+  onError = () => {},
+}) {
+  const pagesDir = resolve(cwd, 'pages')
+  if (!existsSync(pagesDir)) {
+    throw new Error('No existe la carpeta pages/. Crea al menos pages/index.tsx')
+  }
+
+  let closed = false
+  let dirty = false
+  let running = false
+  let timer
+  let lastPagesSignature = pagesDirSignature(pagesDir)
+
+  async function flush() {
+    if (running || closed) return
+    running = true
+
+    while (dirty && !closed) {
+      dirty = false
+      try {
+        await generateApp({ cwd, appDir, frameworkRoot, config })
+        lastPagesSignature = pagesDirSignature(pagesDir)
+        onGenerate()
+      } catch (error) {
+        onError(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+
+    running = false
+  }
+
+  function schedule() {
+    if (closed) return
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = undefined
+      dirty = true
+      void flush()
+    }, debounceMs)
+  }
+
+  const watcher = watchFileSystem(pagesDir, { recursive: true }, schedule)
+  watcher.on('error', (error) => onError(error))
+
+  let pollTimer
+  if (pollMs > 0) {
+    pollTimer = setInterval(() => {
+      if (closed) return
+      const next = pagesDirSignature(pagesDir)
+      if (next !== lastPagesSignature) {
+        lastPagesSignature = next
+        schedule()
+      }
+    }, pollMs)
+  }
+
+  return {
+    close() {
+      closed = true
+      dirty = false
+      if (timer) clearTimeout(timer)
+      if (pollTimer) clearInterval(pollTimer)
+      watcher.close()
+    },
+  }
+}
+
+/** Firma ligera de `pages/` para detectar altas/bajas/renombres sin depender de `fs.watch`. */
+function pagesDirSignature(pagesDir) {
+  const parts = []
+  for (const entry of listPageEntries(pagesDir)) {
+    const full = join(pagesDir, entry.rel)
+    parts.push(`${entry.rel}:${statSync(full).mtimeMs}`)
+  }
+  return parts.sort().join('|')
+}
+
+/** Lista pages UI (.tsx/.jsx) y API server routes (.ts) de forma recursiva. */
+function listPageEntries(pagesDir, prefix = '') {
+  const entries = []
+  const dir = prefix ? join(pagesDir, prefix) : pagesDir
+  for (const name of readdirSync(dir).sort()) {
+    if (
+      name.startsWith('.') ||
+      name === '__tests__' ||
+      /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(name)
+    ) continue
+    const rel = prefix ? `${prefix}/${name}` : name
+    const full = join(pagesDir, rel)
+    if (statSync(full).isDirectory()) {
+      entries.push(...listPageEntries(pagesDir, rel))
+      continue
+    }
+    if (/\.(tsx|jsx)$/.test(name)) entries.push({ kind: 'page', rel })
+    else if (/\.ts$/.test(name) && !name.endsWith('.d.ts')) entries.push({ kind: 'api', rel })
+  }
+  return entries
+}
+
+function reconcileGeneratedRoutes(appDir, routesDir, desiredRoutes) {
+  const manifestPath = join(appDir, ROUTE_MANIFEST_FILE)
+  const previousRoutes = readRouteManifest(manifestPath)
+  const desired = new Set(desiredRoutes)
+
+  for (const relativePath of previousRoutes) {
+    if (desired.has(relativePath)) continue
+    const outputPath = ownedRoutePath(routesDir, relativePath)
+    if (outputPath) rmSync(outputPath, { force: true })
+  }
+
+  writeGeneratedFile(
+    manifestPath,
+    JSON.stringify({ version: 1, routes: desiredRoutes }, null, 2) + '\n',
+  )
+}
+
+function readRouteManifest(manifestPath) {
+  if (!existsSync(manifestPath)) return []
+
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    if (manifest?.version !== 1 || !Array.isArray(manifest.routes)) return []
+    return manifest.routes.filter((route) => typeof route === 'string')
+  } catch {
+    return []
+  }
+}
+
+function ownedRoutePath(routesDir, relativePath) {
+  if (
+    relativePath.length === 0 ||
+    isAbsolute(relativePath) ||
+    relativePath.split('/').includes('..')
+  ) {
+    return null
+  }
+  const outputPath = resolve(routesDir, relativePath)
+  if (!outputPath.startsWith(resolve(routesDir) + sep)) return null
+  return outputPath
+}
+
+/**
+ * 'products.$productId.tsx' → '/products/$productId'
+ * 'api/$.ts' → '/api/$'
+ * 'index.tsx' → '/'
+ */
+function fileToRouteId(relPath) {
+  const withoutExt = relPath.replace(/\.(tsx|jsx|ts)$/, '')
+  if (withoutExt === 'index') return '/'
+
+  const segments = []
+  for (const part of withoutExt.split('/')) {
+    const bits = part.split('.').map((s) => (s === 'index' ? '' : s))
+    segments.push(...bits.filter(Boolean))
+  }
+  return '/' + segments.join('/') + (withoutExt.endsWith('.index') ? '/' : '')
+}
+
+/** Relativo desde routes/<rel> hasta src/app-config. */
+function appConfigImportFrom(relPath) {
+  const nestDepth = relPath.split('/').length - 1
+  return '../'.repeat(nestDepth + 1) + 'app-config'
+}
+
+/** Código de una ruta interna que envuelve la página del usuario. */
+function routeFileSource(routeId, importPath, relPath) {
+  const appConfigImport = appConfigImportFrom(relPath)
+
+  return (
+    HEADER +
+    `import { createFileRoute } from '@tanstack/react-router'\n` +
+    `import appConfig from '${appConfigImport}'\n` +
+    `import pageModule from '${importPath}'\n` +
+    `import { pageToRouteOptions, PageBoundary } from '@ecomiq/storefront/internal/page'\n\n` +
+    `export const Route = createFileRoute('${routeId}')({\n` +
+    `  ...pageToRouteOptions(pageModule, appConfig),\n` +
+    `  component: PageComponent,\n` +
+    `})\n\n` +
+    `function PageComponent() {\n` +
+    `  const data = Route.useLoaderData()\n` +
+    `  const params = Route.useParams()\n` +
+    `  const search = Route.useSearch()\n` +
+    `  return <PageBoundary page={pageModule} data={data} params={params} search={search} />\n` +
+    `}\n`
+  )
+}
+
+/** Página cerrada del framework (import desde package, no desde pages/ del usuario). */
+function frameworkLockedPageRouteSource(routeId, importFrom, relPath) {
+  const appConfigImport = appConfigImportFrom(relPath)
+
+  return (
+    HEADER +
+    `import { createFileRoute } from '@tanstack/react-router'\n` +
+    `import appConfig from '${appConfigImport}'\n` +
+    `import pageModule from '${importFrom}'\n` +
+    `import { pageToRouteOptions, PageBoundary } from '@ecomiq/storefront/internal/page'\n\n` +
+    `export const Route = createFileRoute('${routeId}')({\n` +
+    `  ...pageToRouteOptions(pageModule, appConfig),\n` +
+    `  component: PageComponent,\n` +
+    `})\n\n` +
+    `function PageComponent() {\n` +
+    `  const data = Route.useLoaderData()\n` +
+    `  const params = Route.useParams()\n` +
+    `  const search = Route.useSearch()\n` +
+    `  return <PageBoundary page={pageModule} data={data} params={params} search={search} />\n` +
+    `}\n`
+  )
+}
+
+function assertNoFrameworkPageOverrides(pageEntries) {
+  const reserved = new Map(
+    FRAMEWORK_LOCKED_PAGES.map((page) => [page.routeId, page.rel]),
+  )
+  // Overrides / alias legados
+  reserved.set('/checkout', 'checkout.tsx')
+  reserved.set('/checkout/$cartId', 'checkout.$cartId.tsx')
+
+  for (const entry of pageEntries) {
+    const routeId = fileToRouteId(entry.rel)
+    if (!reserved.has(routeId)) continue
+    throw new Error(
+      `La ruta ${routeId} es reservada por Ecomiq (página cerrada). ` +
+        `Elimina pages/${entry.rel}; las páginas de checkout y thank-you viven en @ecomiq/storefront.`,
+    )
+  }
+}
+
+/** Server route: reexporta GET/POST/... del módulo del usuario. */
+function apiRouteFileSource(routeId, importPath) {
+  return (
+    HEADER +
+    `import { createFileRoute } from '@tanstack/react-router'\n` +
+    `import * as api from '${importPath}'\n\n` +
+    `export const Route = createFileRoute('${routeId}')({\n` +
+    `  server: {\n` +
+    `    handlers: {\n` +
+    `      ...(api.GET ? { GET: api.GET } : {}),\n` +
+    `      ...(api.POST ? { POST: api.POST } : {}),\n` +
+    `      ...(api.PUT ? { PUT: api.PUT } : {}),\n` +
+    `      ...(api.PATCH ? { PATCH: api.PATCH } : {}),\n` +
+    `      ...(api.DELETE ? { DELETE: api.DELETE } : {}),\n` +
+    `    },\n` +
+    `  },\n` +
+    `})\n`
+  )
+}
+
+function buildThemeOverrides(config) {
+  const theme = config.theme ?? {}
+  const map = {
+    primary: '--primary',
+    primaryForeground: '--primary-foreground',
+    radius: '--radius',
+    background: '--background',
+    foreground: '--foreground',
+    accent: '--accent',
+  }
+  const lines = Object.entries(map)
+    .filter(([key]) => theme[key])
+    .map(([key, cssVar]) => `  ${cssVar}: ${theme[key]};`)
+  if (lines.length === 0) return ''
+  return `:root {\n${lines.join('\n')}\n}`
+}
+
+function writeTemplate(frameworkRoot, targetDir, name) {
+  const src = resolve(frameworkRoot, 'templates', name)
+  writeGeneratedFile(join(targetDir, name), readFileSync(src, 'utf8'))
+}
+
+function writeGeneratedFile(path, contents) {
+  if (existsSync(path) && readFileSync(path, 'utf8') === contents) return
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, contents)
+}
+
+/**
+ * Crea `.ecomiq/node_modules` con symlinks a las dependencias del framework.
+ *
+ * Workerd (Cloudflare Vite plugin) resuelve desde la raíz `.ecomiq`, así que
+ * no basta con el hoisting del proyecto: hay que materializar los packages
+ * ahí. En installs npm/pnpm/yarn las deps suelen vivir en el node_modules del
+ * proyecto (o en el store de pnpm), no bajo `@ecomiq/storefront/node_modules`.
+ */
+function linkFrameworkDependencies(appDir, frameworkRoot, projectRoot = dirname(appDir)) {
+  const target = join(appDir, 'node_modules')
+  mkdirSync(target, { recursive: true })
+
+  linkInto(join(target, '@ecomiq'), 'storefront', frameworkRoot)
+  const legacyFramework = join(target, '@ecomiq', 'framework')
+  try {
+    if (lstatSync(legacyFramework).isSymbolicLink()) unlinkSync(legacyFramework)
+  } catch {
+    /* no existía */
+  }
+
+  const resolveFrom = [
+    join(frameworkRoot, 'package.json'),
+    join(projectRoot, 'package.json'),
+    join(frameworkRoot, 'src', 'codegen.mjs'),
+  ]
+
+  const manifestPath = join(frameworkRoot, 'package.json')
+  let depNames = []
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    depNames = [
+      ...Object.keys(manifest.dependencies ?? {}),
+      ...Object.keys(manifest.peerDependencies ?? {}),
+    ]
+  } catch {
+    depNames = []
+  }
+
+  // Transitive crítico que Vite/TanStack piden explícitamente en SSR.
+  for (const extra of ['@tanstack/react-store', '@tanstack/history', '@tanstack/router-core']) {
+    if (!depNames.includes(extra)) depNames.push(extra)
+  }
+
+  for (const name of depNames) {
+    const pkgDir = resolvePackageDir(name, resolveFrom)
+    if (!pkgDir) continue
+    linkPackage(target, name, pkgDir)
+  }
+
+  // Fallback: mirror de node_modules locales (monorepo / nested installs).
+  for (const source of [join(frameworkRoot, 'node_modules'), join(projectRoot, 'node_modules')]) {
+    linkNodeModulesTree(source, target)
+  }
+}
+
+function linkPackage(targetRoot, packageName, packageDir) {
+  if (packageName.startsWith('@')) {
+    const [scope, name] = packageName.split('/')
+    if (!scope || !name) return
+    linkInto(join(targetRoot, scope), name, packageDir)
+    return
+  }
+  linkInto(targetRoot, packageName, packageDir)
+}
+
+function linkNodeModulesTree(source, target) {
+  if (!existsSync(source)) return
+  for (const entry of readdirSync(source)) {
+    if (entry === '.bin' || entry.startsWith('.')) continue
+    if (entry.startsWith('@')) {
+      const scopeDir = join(source, entry)
+      if (!statSync(scopeDir).isDirectory()) continue
+      for (const scoped of readdirSync(scopeDir)) {
+        linkInto(join(target, entry), scoped, join(scopeDir, scoped))
+      }
+    } else {
+      linkInto(target, entry, join(source, entry))
+    }
+  }
+}
+
+/**
+ * Resuelve el directorio raíz de un package usando la resolución de Node
+ * (funciona con hoisting npm/yarn y el store de pnpm).
+ */
+function resolvePackageDir(packageName, fromFiles) {
+  for (const fromFile of fromFiles) {
+    if (!existsSync(fromFile)) continue
+    try {
+      const require = createRequire(fromFile)
+      try {
+        return dirname(realpathSync(require.resolve(`${packageName}/package.json`)))
+      } catch {
+        const entry = require.resolve(packageName)
+        return findPackageRoot(entry, packageName)
+      }
+    } catch {
+      /* probar siguiente origen */
+    }
+  }
+  return null
+}
+
+function findPackageRoot(startPath, packageName) {
+  let dir = dirname(startPath)
+  while (true) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        if (pkg.name === packageName) return realpathSync(dir)
+      } catch {
+        /* ignore */
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function linkInto(dir, name, targetPath) {
+  mkdirSync(dir, { recursive: true })
+  const linkPath = join(dir, name)
+  let desired
+  try {
+    desired = realpathSync(targetPath)
+  } catch {
+    desired = resolve(targetPath)
+  }
+  try {
+    const current = lstatSync(linkPath)
+    if (current.isSymbolicLink()) {
+      let resolved
+      try {
+        resolved = realpathSync(linkPath)
+      } catch {
+        resolved = resolve(dir, readlinkSync(linkPath))
+      }
+      if (resolved === desired) return
+      unlinkSync(linkPath)
+    } else if (current.isDirectory() || current.isFile()) {
+      return
+    }
+  } catch {
+    /* no existe aún */
+  }
+  try {
+    symlinkSync(desired, linkPath, 'junction')
+  } catch {
+    /* FS sin symlinks: la resolución cae al hoisting */
+  }
+}
+
+function slugify(s) {
+  return s
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}