@sntlr/registry-shell 1.0.0

package/src/cli/shared.ts

@@ -0,0 +1,306 @@
+/**
+ * Helpers shared across CLI commands: locating the shell's bundled Next app,
+ * finding the user's config file, and injecting the env vars the Next app
+ * reads at boot.
+ */
+import fs from "node:fs"
+import path from "node:path"
+import { createRequire } from "node:module"
+import { fileURLToPath } from "node:url"
+import { createJiti } from "jiti"
+import type { ShellConfig } from "../define-config.js"
+
+/**
+ * Absolute path to the Next.js CLI binary shipped with the shell package.
+ * Resolves against the shell's own node_modules so a consumer doesn't need
+ * to declare Next as a direct dep — they depend on `@sntlr/registry-shell`
+ * and transitively get Next.
+ */
+const requireFromHere = createRequire(import.meta.url)
+export const NEXT_BIN = requireFromHere.resolve("next/dist/bin/next")
+
+// `path` / `fs` already imported above; ensure both stay usable below.
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+
+const CONFIG_FILE_CANDIDATES = [
+  "registry-shell.config.ts",
+  "registry-shell.config.js",
+  "registry-shell.config.mjs",
+]
+
+/** Walk upward from cwd looking for a config file. Returns null if none. */
+export function findConfigFile(cwd: string = process.cwd()): string | null {
+  let dir = cwd
+  while (true) {
+    for (const name of CONFIG_FILE_CANDIDATES) {
+      const candidate = path.join(dir, name)
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** Absolute path to the Next.js app bundled inside the shell package. */
+export function nextAppDir(): string {
+  // When running from dist (published), this file is at dist/cli/shared.js.
+  // When running from source via tsx, it's at src/cli/shared.ts.
+  // In both cases, next-app lives at ../next-app relative to the cli dir.
+  const distNextApp = path.resolve(HERE, "../next-app")
+  if (fs.existsSync(distNextApp)) return distNextApp
+
+  const srcNextApp = path.resolve(HERE, "../../src/next-app")
+  if (fs.existsSync(srcNextApp)) return srcNextApp
+
+  throw new Error(
+    `[registry-shell] Couldn't locate the bundled Next app. Looked in:\n  ${distNextApp}\n  ${srcNextApp}`,
+  )
+}
+
+export interface LoadedConfig {
+  configPath: string
+  root: string
+  config: ShellConfig
+}
+
+/**
+ * Read + parse the user's config file via jiti (zero-build TS). Returns null
+ * when no config is found (shell-only mode).
+ */
+export function loadUserConfig(): LoadedConfig | null {
+  const configPath = findConfigFile()
+  if (!configPath) return null
+
+  const jiti = createJiti(import.meta.url, { interopDefault: true })
+  const loaded = jiti(configPath) as unknown
+  const config = (
+    loaded && typeof loaded === "object" && "default" in loaded
+      ? (loaded as { default: ShellConfig }).default
+      : (loaded as ShellConfig)
+  )
+
+  if (!config?.branding) {
+    throw new Error(
+      `[registry-shell] Invalid config at ${configPath}: missing required \`branding\`.`,
+    )
+  }
+
+  return {
+    configPath,
+    root: path.dirname(configPath),
+    config,
+  }
+}
+
+/**
+ * Generate a CSS file containing `@source` directives that tell Tailwind v4
+ * to scan the user's component/block/doc files for utility classes. Without
+ * this, classes used only in the user's files don't end up in the bundled
+ * stylesheet. Rewritten every time the CLI boots so path changes in the
+ * user's config take effect immediately.
+ */
+/**
+ * The shell's `.next/` build output is keyed to the active config. When the
+ * user switches from a wired registry to shell-only (or swaps registries
+ * altogether), the old build has eager references to files that may no
+ * longer resolve. Detect that by stamping the current mode and clearing
+ * `.next/` when it changes.
+ */
+export function clearStaleNextCacheIfModeChanged(loaded: LoadedConfig | null): void {
+  const nextApp = nextAppDir()
+  const nextDir = path.join(nextApp, ".next")
+  const stampPath = path.join(nextApp, ".registry-shell-mode")
+  const currentMode = loaded?.configPath ?? "<shell-only>"
+
+  let previousMode = "<never>"
+  if (fs.existsSync(stampPath)) {
+    try {
+      previousMode = fs.readFileSync(stampPath, "utf-8").trim()
+    } catch {
+      /* ignore */
+    }
+  }
+
+  if (fs.existsSync(nextDir) && previousMode !== currentMode) {
+    console.log(
+      `[registry-shell] Mode changed (${previousMode} → ${currentMode}) — clearing .next cache.`,
+    )
+    // Windows can hold file locks (antivirus, IDE indexers) for a moment
+    // after the previous Next process exits. Retry a few times; if the
+    // directory still won't remove, clear its contents in place instead.
+    const tryRemove = (attempt = 0): boolean => {
+      try {
+        fs.rmSync(nextDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })
+        return true
+      } catch {
+        if (attempt < 5) return tryRemove(attempt + 1)
+        return false
+      }
+    }
+    if (!tryRemove()) {
+      try {
+        for (const entry of fs.readdirSync(nextDir)) {
+          fs.rmSync(path.join(nextDir, entry), {
+            recursive: true,
+            force: true,
+            maxRetries: 5,
+            retryDelay: 200,
+          })
+        }
+        console.log("[registry-shell] Directory locked — cleared contents instead.")
+      } catch (err) {
+        console.warn(
+          `[registry-shell] Couldn't clear .next cache cleanly (${(err as Error).message}). ` +
+            `Continuing; you may see stale-build warnings.`,
+        )
+      }
+    }
+  }
+
+  fs.writeFileSync(stampPath, currentMode + "\n", "utf-8")
+}
+
+export function writeUserSourcesCss(loaded: LoadedConfig | null): void {
+  const nextApp = nextAppDir()
+  const appDir = path.join(nextApp, "app")
+  const sourcesTarget = path.join(appDir, "_user-sources.css")
+  const globalTarget = path.join(appDir, "_user-global.css")
+
+  // Tailwind 4 resolves `@source` paths relative to the CSS file on disk and
+  // handles platform-specific separators. Use relative paths so Windows
+  // drive-letter handling doesn't trip the scanner.
+  const rel = (abs: string) => {
+    const r = path.relative(appDir, abs).replace(/\\/g, "/")
+    return r.startsWith(".") ? r : `./${r}`
+  }
+
+  // ── _user-sources.css — `@source` directives only ──────────────────
+  // Imported near the TOP of globals.css so Tailwind's class scanner
+  // picks up utility usage from the listed dirs.
+  const sources = ["/* Auto-generated by @sntlr/registry-shell. Do not edit. */"]
+  sources.push(`@source "${rel(path.join(nextApp, "app"))}";`)
+  sources.push(`@source "${rel(path.join(nextApp, "components"))}";`)
+  sources.push(`@source "${rel(path.join(nextApp, "lib"))}";`)
+  sources.push(`@source "${rel(path.join(nextApp, "hooks"))}";`)
+  sources.push(`@source "${rel(path.join(nextApp, "fallback"))}";`)
+
+  if (loaded) {
+    const paths = loaded.config.paths ?? {}
+    const resolve = (r: string | undefined, fallback: string) =>
+      path.resolve(loaded.root, r ?? fallback)
+
+    sources.push(`@source "${rel(resolve(paths.components, "components/ui"))}";`)
+    sources.push(`@source "${rel(resolve(paths.blocks, "registry/new-york/blocks"))}";`)
+    sources.push(
+      `@source "${rel(resolve(paths.previews?.replace(/\/index\.[tj]sx?$/, ""), "components/previews"))}";`,
+    )
+    if (loaded.config.homePage) {
+      sources.push(`@source "${rel(resolve(loaded.config.homePage, ""))}";`)
+    }
+  }
+  fs.writeFileSync(sourcesTarget, sources.join("\n") + "\n", "utf-8")
+
+  // ── _user-global.css — user's extra theme/tokens ──────────────────
+  // Imported at the BOTTOM of globals.css so `:root { --primary: ... }`
+  // style overrides win the cascade over the shell's defaults. Absent
+  // when paths.globalCss is not configured (file is written as a no-op
+  // so the `@import` in globals.css never 404s).
+  const globalLines = ["/* Auto-generated by @sntlr/registry-shell. Do not edit. */"]
+  if (loaded) {
+    const userGlobal = loaded.config.paths?.globalCss
+    if (userGlobal) {
+      const abs = path.resolve(loaded.root, userGlobal)
+      if (!fs.existsSync(abs)) {
+        console.warn(
+          `[registry-shell] paths.globalCss points at ${abs} but the file doesn't exist — skipping.`,
+        )
+      } else {
+        globalLines.push(`@import "${rel(abs)}";`)
+      }
+    }
+  }
+  fs.writeFileSync(globalTarget, globalLines.join("\n") + "\n", "utf-8")
+}
+
+/**
+ * Build the env-var bag the Next app reads at startup. The CLI spreads this
+ * into child `next` processes.
+ */
+/**
+ * Resolve the locale list the client's locale toggle should offer. Uses the
+ * explicit `locales` array if provided, otherwise auto-scans subfolders of
+ * the registry's docs path. Mirrors the logic in the server config-loader
+ * but runs client-side via inlined env vars.
+ */
+function resolveLocaleList(root: string, config: ShellConfig): string[] {
+  if (!config.multilocale) return []
+  if (config.locales && config.locales.length > 0) return [...config.locales]
+
+  const docsAbs = path.resolve(root, config.paths?.docs ?? "content/docs")
+  if (!fs.existsSync(docsAbs)) {
+    return config.defaultLocale ? [config.defaultLocale] : []
+  }
+  const found = fs
+    .readdirSync(docsAbs, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+
+  if (config.defaultLocale && found.includes(config.defaultLocale)) {
+    return [config.defaultLocale, ...found.filter((l) => l !== config.defaultLocale)]
+  }
+  return found
+}
+
+export function buildEnvVars(loaded: LoadedConfig | null): Record<string, string> {
+  // Always set SHELL_APP_ROOT so the Next app can resolve its own bundled
+  // files (fallbacks, globals.css) independently of process.cwd().
+  const base: Record<string, string> = { SHELL_APP_ROOT: nextAppDir() }
+  if (!loaded) return base
+
+  const { configPath, root, config } = loaded
+  const b = config.branding
+
+  const env: Record<string, string> = {
+    ...base,
+    USER_CONFIG_PATH: configPath,
+    USER_REGISTRY_ROOT: root,
+    NEXT_PUBLIC_SHELL_SITE_NAME: b.siteName,
+    NEXT_PUBLIC_SHELL_SHORT_NAME: b.shortName,
+  }
+
+  if (b.siteUrl) env.NEXT_PUBLIC_SHELL_SITE_URL = b.siteUrl
+  if (b.description) env.NEXT_PUBLIC_SHELL_DESCRIPTION = b.description
+  if (b.ogImage) env.NEXT_PUBLIC_SHELL_OG_IMAGE = b.ogImage
+  if (b.twitterHandle) env.NEXT_PUBLIC_SHELL_TWITTER_HANDLE = b.twitterHandle
+  if (b.github?.owner) env.NEXT_PUBLIC_SHELL_GITHUB_OWNER = b.github.owner
+  if (b.github?.repo) env.NEXT_PUBLIC_SHELL_GITHUB_REPO = b.github.repo
+  if (b.github?.label) env.NEXT_PUBLIC_SHELL_GITHUB_LABEL = b.github.label
+  if (b.github && b.github.showStars === false) {
+    env.NEXT_PUBLIC_SHELL_GITHUB_SHOW_STARS = "false"
+  }
+  if (b.logoAlt) env.NEXT_PUBLIC_SHELL_LOGO_ALT = b.logoAlt
+  if (b.faviconDark) env.NEXT_PUBLIC_SHELL_FAVICON_DARK = b.faviconDark
+  if (b.faviconLight) env.NEXT_PUBLIC_SHELL_FAVICON_LIGHT = b.faviconLight
+  if (b.faviconIco) env.NEXT_PUBLIC_SHELL_FAVICON_ICO = b.faviconIco
+
+  if (config.homePage) env.USER_HOMEPAGE_PATH = config.homePage
+  if (config.installCommandTemplate !== undefined) {
+    env.NEXT_PUBLIC_SHELL_INSTALL_CMD = config.installCommandTemplate
+  }
+  if (config.transpilePackages && config.transpilePackages.length > 0) {
+    env.USER_TRANSPILE_PACKAGES = config.transpilePackages.join(",")
+  }
+
+  // Multilocale signalling for the locale toggle. Resolves the toggle's
+  // locale set from explicit config or auto-scan of doc subfolders so the
+  // client has a complete list at build time.
+  if (config.multilocale && config.defaultLocale) {
+    env.NEXT_PUBLIC_SHELL_DEFAULT_LOCALE = config.defaultLocale
+    const locales = resolveLocaleList(loaded.root, config)
+    env.NEXT_PUBLIC_SHELL_LOCALES = locales.join(",")
+  }
+
+  return env
+}

package/src/cli/start.ts

@@ -0,0 +1,28 @@
+/**
+ * `registry-shell start` — run `next start` for a prior `registry-shell build`.
+ *
+ * Mirrors build.ts: passes `USER_DIST_DIR` pointing at `<user-project>/.next`
+ * so `next start` reads the build output from where build.ts wrote it.
+ */
+import path from "node:path"
+import { spawn } from "node:child_process"
+import { NEXT_BIN, buildEnvVars, loadUserConfig, nextAppDir } from "./shared.js"
+
+export async function run(args: string[]): Promise<void> {
+  const loaded = loadUserConfig()
+  const userDistDir = loaded
+    ? path.resolve(loaded.root, loaded.config.paths?.buildOutput ?? ".next")
+    : undefined
+  const env = {
+    ...process.env,
+    ...buildEnvVars(loaded),
+    ...(userDistDir ? { USER_DIST_DIR: userDistDir } : {}),
+  }
+  const portArgs = loaded?.config.port ? ["-p", String(loaded.config.port)] : []
+  const child = spawn(
+    process.execPath,
+    [NEXT_BIN, "start", nextAppDir(), ...portArgs, ...args],
+    { stdio: "inherit", env },
+  )
+  child.on("exit", (code) => process.exit(code ?? 0))
+}

package/src/config-loader.ts

@@ -0,0 +1,190 @@
+/**
+ * Loads the user's `registry-shell.config.ts` at server boot. Uses `jiti` so
+ * the user doesn't need a build step or TS tooling of their own — the shell
+ * parses TS on the fly.
+ *
+ * Called once at Next.js server startup (see src/next-app/registry.config.ts).
+ * The returned `ResolvedShellConfig` contains absolute paths and defaults
+ * applied.
+ */
+import "server-only"
+import path from "node:path"
+import fs from "node:fs"
+import { createJiti } from "jiti"
+import type { ShellConfig, ShellPaths, BrandingConfig } from "./define-config.js"
+
+// `skipBlocks`, `globalCss`, and `buildOutput` are excluded from the
+// "must have a default" shape: skipBlocks is always an array (empty
+// default); globalCss is purely opt-in; buildOutput is read by the CLI
+// directly (with its own `.next` default) and doesn't flow through the
+// server-side resolver.
+const DEFAULT_PATHS: Required<
+  Omit<ShellPaths, "skipBlocks" | "globalCss" | "buildOutput">
+> & { skipBlocks: string[] } = {
+  components: "components/ui",
+  blocks: "registry/new-york/blocks",
+  previews: "components/previews/index.ts",
+  docs: "content/docs",
+  registryJson: "public/r",
+  a11y: "public/a11y",
+  tests: "public/tests",
+  props: "public/props",
+  skipBlocks: [],
+}
+
+const DEFAULT_BRANDING: BrandingConfig = {
+  siteName: "UI Registry",
+  shortName: "UI",
+  siteUrl: "",
+  logoAlt: "UI",
+  faviconDark: "/favicon_dark.svg",
+  faviconLight: "/favicon_light.svg",
+  faviconIco: "/favicon.ico",
+}
+
+export interface ResolvedShellConfig {
+  /** Absolute path to the user's registry root (dir containing the config). */
+  root: string
+  /** Absolute path to the config file itself. */
+  configPath: string
+  branding: Required<BrandingConfig>
+  /** All paths resolved to absolute locations. */
+  paths: {
+    components: string
+    blocks: string
+    previews: string
+    docs: string
+    registryJson: string
+    a11y: string
+    tests: string
+    props: string
+    skipBlocks: Set<string>
+    /** Absolute path to user's extra global CSS, or null when not configured. */
+    globalCss: string | null
+  }
+  /** Absolute path to a custom homepage module, or null. */
+  homePage: string | null
+  /** Absolute path to a custom adapter module, or null. */
+  adapter: string | null
+  extraTranslations: Record<string, Record<string, string>>
+  /** When true, docs live under per-locale subfolders. */
+  multilocale: boolean
+  /** Locale subfolder containing the canonical doc set. Empty when multilocale is off. */
+  defaultLocale: string
+  /** Explicit locale list (resolved — may be empty in single-locale mode). */
+  locales: string[]
+}
+
+/**
+ * Read env vars set by the CLI, load the config file, resolve paths. Returns
+ * `null` when no config is set (shell-only dev mode) — the Next app falls
+ * back to built-in shell docs.
+ */
+export function loadResolvedConfig(): ResolvedShellConfig | null {
+  const configPath = process.env.USER_CONFIG_PATH
+  const root = process.env.USER_REGISTRY_ROOT
+  if (!configPath || !root) return null
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `[registry-shell] Config file not found: ${configPath}. ` +
+        `Check USER_CONFIG_PATH.`,
+    )
+  }
+
+  const jiti = createJiti(import.meta.url, { interopDefault: true })
+  const loaded = jiti(configPath) as unknown
+  const config = extractDefault(loaded) as ShellConfig
+
+  if (!config?.branding) {
+    throw new Error(
+      `[registry-shell] Invalid config at ${configPath}: missing required \`branding\`.`,
+    )
+  }
+  if (config.multilocale && !config.defaultLocale) {
+    throw new Error(
+      `[registry-shell] Invalid config at ${configPath}: \`multilocale\` is true but \`defaultLocale\` is missing.`,
+    )
+  }
+
+  const rootAbs = path.resolve(root)
+  const cfgPaths = config.paths ?? {}
+
+  return {
+    root: rootAbs,
+    configPath,
+    branding: applyBrandingDefaults(config.branding),
+    paths: {
+      components: path.resolve(rootAbs, cfgPaths.components ?? DEFAULT_PATHS.components),
+      blocks: path.resolve(rootAbs, cfgPaths.blocks ?? DEFAULT_PATHS.blocks),
+      previews: path.resolve(rootAbs, cfgPaths.previews ?? DEFAULT_PATHS.previews),
+      docs: path.resolve(rootAbs, cfgPaths.docs ?? DEFAULT_PATHS.docs),
+      registryJson: path.resolve(rootAbs, cfgPaths.registryJson ?? DEFAULT_PATHS.registryJson),
+      a11y: path.resolve(rootAbs, cfgPaths.a11y ?? DEFAULT_PATHS.a11y),
+      tests: path.resolve(rootAbs, cfgPaths.tests ?? DEFAULT_PATHS.tests),
+      props: path.resolve(rootAbs, cfgPaths.props ?? DEFAULT_PATHS.props),
+      skipBlocks: new Set(cfgPaths.skipBlocks ?? []),
+      globalCss: cfgPaths.globalCss ? path.resolve(rootAbs, cfgPaths.globalCss) : null,
+    },
+    homePage: config.homePage ? path.resolve(rootAbs, config.homePage) : null,
+    adapter: config.adapter ? path.resolve(rootAbs, config.adapter) : null,
+    extraTranslations: config.extraTranslations ?? {},
+    multilocale: Boolean(config.multilocale),
+    defaultLocale: config.defaultLocale ?? "",
+    locales: resolveLocales(rootAbs, cfgPaths.docs ?? DEFAULT_PATHS.docs, config),
+  }
+}
+
+/**
+ * Resolve the locale list for the locale toggle. In single-locale mode we
+ * return an empty array (the toggle hides itself). In multilocale mode we
+ * use the explicit `locales` config if present, otherwise auto-scan
+ * subfolders under `paths.docs`.
+ */
+function resolveLocales(rootAbs: string, docsRel: string, config: ShellConfig): string[] {
+  if (!config.multilocale) return []
+  if (config.locales && config.locales.length > 0) return [...config.locales]
+
+  const docsAbs = path.resolve(rootAbs, docsRel)
+  if (!fs.existsSync(docsAbs)) return config.defaultLocale ? [config.defaultLocale] : []
+  const found = fs
+    .readdirSync(docsAbs, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+
+  // Put the default locale first so the toggle cycles predictably.
+  if (config.defaultLocale && found.includes(config.defaultLocale)) {
+    return [config.defaultLocale, ...found.filter((l) => l !== config.defaultLocale)]
+  }
+  return found
+}
+
+function extractDefault(loaded: unknown): unknown {
+  if (loaded && typeof loaded === "object" && "default" in loaded) {
+    return (loaded as { default: unknown }).default
+  }
+  return loaded
+}
+
+function applyBrandingDefaults(b: BrandingConfig): Required<BrandingConfig> {
+  return {
+    siteName: b.siteName,
+    shortName: b.shortName,
+    siteUrl: b.siteUrl ?? "",
+    description: b.description ?? "",
+    ogImage: b.ogImage ?? "",
+    twitterHandle: b.twitterHandle ?? "",
+    github: b.github
+      ? {
+          owner: b.github.owner,
+          repo: b.github.repo,
+          label: b.github.label ?? "Github",
+          showStars: b.github.showStars ?? true,
+        }
+      : { owner: "", repo: "", label: "", showStars: false },
+    logoAlt: b.logoAlt ?? b.siteName,
+    faviconDark: b.faviconDark ?? DEFAULT_BRANDING.faviconDark!,
+    faviconLight: b.faviconLight ?? DEFAULT_BRANDING.faviconLight!,
+    faviconIco: b.faviconIco ?? DEFAULT_BRANDING.faviconIco!,
+  }
+}