@sntlr/registry-shell 1.0.0

package/src/adapter/default.ts

@@ -0,0 +1,241 @@
+/**
+ * Default convention-based RegistryAdapter implementation.
+ *
+ * Builds a RegistryAdapter from a `ResolvedShellConfig`: scans the filesystem
+ * paths declared in the user's config, parses MDX frontmatter, and reads
+ * registry JSON. The `previewLoader` and `homePage` are wired separately via
+ * Next.js aliases (see next-app/next.config.ts) because Next's `dynamic()`
+ * needs string literal imports.
+ */
+import "server-only"
+import fs from "node:fs"
+import path from "node:path"
+import matter from "gray-matter"
+import type { ResolvedShellConfig } from "../config-loader.js"
+
+// The RegistryAdapter interface lives inside the Next app (next-app/lib).
+// This file is compiled to dist/ separately and consumed at Next runtime,
+// so we re-declare the types it needs here.
+
+export interface ComponentMeta {
+  name: string
+  label: string
+  kind: "component" | "block"
+}
+
+export interface DocMeta {
+  slug: string
+  title: string
+  description: string
+  order: number
+  titles: Record<string, string>
+}
+
+export interface DocContent {
+  meta: Omit<DocMeta, "titles">
+  content: string
+}
+
+function titleCase(slug: string) {
+  return slug
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ")
+}
+
+export function createDefaultAdapter(resolved: ResolvedShellConfig) {
+  const { paths } = resolved
+  const isMulti = resolved.multilocale
+  const defaultLocale = resolved.defaultLocale
+
+  /** In multilocale mode, return all locale subfolder names. */
+  function listLocales(): string[] {
+    if (!isMulti || !fs.existsSync(paths.docs)) return []
+    return fs
+      .readdirSync(paths.docs, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+  }
+
+  /** Path to the directory holding `.mdx` files for a given locale (multi mode). */
+  function localeDir(locale: string): string {
+    return path.join(paths.docs, locale)
+  }
+
+  function getAllComponents(): ComponentMeta[] {
+    const items: ComponentMeta[] = []
+
+    if (fs.existsSync(paths.components)) {
+      for (const filename of fs.readdirSync(paths.components).filter((f) => f.endsWith(".tsx"))) {
+        const name = filename.replace(/\.tsx$/, "")
+        items.push({ name, label: titleCase(name), kind: "component" })
+      }
+    }
+
+    if (fs.existsSync(paths.blocks)) {
+      for (const dir of fs.readdirSync(paths.blocks, { withFileTypes: true })) {
+        if (!dir.isDirectory() || paths.skipBlocks.has(dir.name)) continue
+        items.push({ name: dir.name, label: titleCase(dir.name), kind: "block" })
+      }
+    }
+
+    return items.sort((a, b) => a.label.localeCompare(b.label))
+  }
+
+  function getAllDocs(): DocMeta[] {
+    if (!fs.existsSync(paths.docs)) return []
+
+    if (isMulti) {
+      const dir = localeDir(defaultLocale)
+      if (!fs.existsSync(dir)) return []
+      const otherLocales = listLocales().filter((l) => l !== defaultLocale)
+
+      return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".mdx"))
+        .map((filename) => {
+          const slug = filename.replace(/\.mdx$/, "")
+          const { data } = matter(fs.readFileSync(path.join(dir, filename), "utf-8"))
+          const titles: Record<string, string> = { [defaultLocale]: data.title ?? slug }
+
+          for (const loc of otherLocales) {
+            const p = path.join(localeDir(loc), filename)
+            if (!fs.existsSync(p)) continue
+            const { data: locData } = matter(fs.readFileSync(p, "utf-8"))
+            if (locData.title) titles[loc] = locData.title
+          }
+
+          return {
+            slug,
+            title: data.title ?? slug,
+            description: data.description ?? "",
+            order: data.order ?? 999,
+            titles,
+          }
+        })
+        .sort((a, b) => a.order - b.order)
+    }
+
+    // Single-folder mode: one locale, no variant scanning.
+    return fs
+      .readdirSync(paths.docs)
+      .filter((f) => f.endsWith(".mdx"))
+      .map((filename) => {
+        const slug = filename.replace(/\.mdx$/, "")
+        const { data } = matter(fs.readFileSync(path.join(paths.docs, filename), "utf-8"))
+        return {
+          slug,
+          title: data.title ?? slug,
+          description: data.description ?? "",
+          order: data.order ?? 999,
+          titles: { en: data.title ?? slug },
+        }
+      })
+      .sort((a, b) => a.order - b.order)
+  }
+
+  function getDocBySlug(slug: string, locale?: string): DocContent | null {
+    if (isMulti) {
+      const want = locale && locale !== defaultLocale ? locale : defaultLocale
+      const candidates = [
+        path.join(localeDir(want), `${slug}.mdx`),
+        path.join(localeDir(defaultLocale), `${slug}.mdx`),
+      ]
+      return readDocFile(slug, candidates)
+    }
+
+    // Single-folder mode: `locale` is ignored, only `{slug}.mdx` matters.
+    return readDocFile(slug, [path.join(paths.docs, `${slug}.mdx`)])
+  }
+
+  function getDocAllLocales(slug: string): Record<string, string> {
+    if (!fs.existsSync(paths.docs)) return {}
+
+    if (isMulti) {
+      const out: Record<string, string> = {}
+      for (const loc of listLocales()) {
+        const p = path.join(localeDir(loc), `${slug}.mdx`)
+        if (fs.existsSync(p)) {
+          out[loc] = matter(fs.readFileSync(p, "utf-8")).content
+        }
+      }
+      return out
+    }
+
+    // Single-folder mode: exactly one file, keyed under `en` so the client
+    // renderer's fallback chain works without needing a special case.
+    const p = path.join(paths.docs, `${slug}.mdx`)
+    if (!fs.existsSync(p)) return {}
+    return { en: matter(fs.readFileSync(p, "utf-8")).content }
+  }
+
+  function getComponentSource(name: string): string | null {
+    const candidates = [
+      path.join(paths.components, `${name}.tsx`),
+      path.join(paths.blocks, name, `${name}.tsx`),
+    ]
+    for (const p of candidates) {
+      if (fs.existsSync(p)) return fs.readFileSync(p, "utf-8")
+    }
+    return null
+  }
+
+  async function getRegistryItem(name: string): Promise<unknown | null> {
+    return readJson(paths.registryJson, name)
+  }
+
+  async function getA11yData(name: string): Promise<unknown | null> {
+    return readJson(paths.a11y, name)
+  }
+
+  async function getTestData(name: string): Promise<unknown | null> {
+    return readJson(paths.tests, name)
+  }
+
+  async function getPropsData(name: string): Promise<unknown | null> {
+    return readJson(paths.props, name)
+  }
+
+  return {
+    getAllComponents,
+    getAllDocs,
+    getDocBySlug,
+    getDocAllLocales,
+    getComponentSource,
+    getRegistryItem,
+    getA11yData,
+    getTestData,
+    getPropsData,
+    branding: resolved.branding,
+    extraTranslations: resolved.extraTranslations,
+  }
+}
+
+async function readJson(dir: string, name: string): Promise<unknown | null> {
+  const base = name.replace(/\.json$/, "")
+  const filePath = path.join(dir, `${base}.json`)
+  try {
+    const data = await fs.promises.readFile(filePath, "utf-8")
+    return JSON.parse(data)
+  } catch {
+    return null
+  }
+}
+
+/** Try each candidate path; return the first that parses to a DocContent. */
+function readDocFile(slug: string, candidates: string[]): DocContent | null {
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue
+    const { data, content } = matter(fs.readFileSync(p, "utf-8"))
+    return {
+      meta: {
+        slug,
+        title: data.title ?? slug,
+        description: data.description ?? "",
+        order: data.order ?? 999,
+      },
+      content,
+    }
+  }
+  return null
+}

package/src/cli/build.ts

@@ -0,0 +1,38 @@
+/**
+ * `registry-shell build` — run `next build` against the user's project.
+ *
+ * Writes the Next build output to `<user-project>/.next` via `distDir` so
+ * generic Next.js hosts (Vercel, self-hosted) find it where they expect.
+ * Without this, the output would land inside
+ * `node_modules/@sntlr/registry-shell/src/next-app/.next` and no external
+ * host could discover it.
+ */
+import path from "node:path"
+import { spawn } from "node:child_process"
+import {
+  NEXT_BIN,
+  buildEnvVars,
+  clearStaleNextCacheIfModeChanged,
+  loadUserConfig,
+  nextAppDir,
+  writeUserSourcesCss,
+} from "./shared.js"
+
+export async function run(args: string[]): Promise<void> {
+  const loaded = loadUserConfig()
+  clearStaleNextCacheIfModeChanged(loaded)
+  writeUserSourcesCss(loaded)
+  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 child = spawn(process.execPath, [NEXT_BIN, "build", nextAppDir(), ...args], {
+    stdio: "inherit",
+    env,
+  })
+  child.on("exit", (code) => process.exit(code ?? 0))
+}

package/src/cli/dev.ts

@@ -0,0 +1,38 @@
+/**
+ * `registry-shell dev` — run `next dev` against the user's project.
+ */
+import { spawn } from "node:child_process"
+import {
+  NEXT_BIN,
+  buildEnvVars,
+  clearStaleNextCacheIfModeChanged,
+  loadUserConfig,
+  nextAppDir,
+  writeUserSourcesCss,
+} from "./shared.js"
+
+export async function run(args: string[]): Promise<void> {
+  const loaded = loadUserConfig()
+  if (loaded) {
+    console.log(`[registry-shell] Using config: ${loaded.configPath}`)
+  } else {
+    console.log(`[registry-shell] No registry-shell.config.ts found — running in shell-only mode.`)
+  }
+
+  clearStaleNextCacheIfModeChanged(loaded)
+  writeUserSourcesCss(loaded)
+  const env = { ...process.env, ...buildEnvVars(loaded) }
+  const portArgs = loaded?.config.port ? ["-p", String(loaded.config.port)] : []
+  // Webpack by default. Turbopack currently can't compile files reached via
+  // the `@user/*` cross-project aliases — it treats them as native Node ESM
+  // and crashes on `next/dynamic`. Set UI_SHELL_TURBOPACK=1 to opt in once
+  // Turbopack supports this (track https://github.com/vercel/next.js).
+  const turbopackArgs = process.env.UI_SHELL_TURBOPACK ? ["--turbopack"] : []
+  const child = spawn(
+    process.execPath,
+    [NEXT_BIN, "dev", nextAppDir(), ...turbopackArgs, ...portArgs, ...args],
+    { stdio: "inherit", env },
+  )
+
+  child.on("exit", (code) => process.exit(code ?? 0))
+}

package/src/cli/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * @sntlr/registry-shell CLI entry.
+ *
+ * Commands:
+ *   init    Scaffold registry-shell.config.ts and add a script to package.json.
+ *   dev     Run `next dev` pointed at the user's current directory.
+ *   build   Run `next build` pointed at the user's current directory.
+ *   start   Run `next start` for a built shell.
+ */
+
+const USAGE = `Usage: registry-shell <command> [args]
+
+Commands:
+  init            Scaffold registry-shell.config.ts in the current project.
+  dev             Start the shell in dev mode on http://localhost:3000.
+  build           Build the shell for production.
+  start           Start the production server against a prior build.
+`
+
+async function main() {
+  const [, , cmd, ...args] = process.argv
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(USAGE)
+    process.exit(0)
+  }
+
+  switch (cmd) {
+    case "init":
+      await (await import("./init.js")).run(args)
+      break
+    case "dev":
+      await (await import("./dev.js")).run(args)
+      break
+    case "build":
+      await (await import("./build.js")).run(args)
+      break
+    case "start":
+      await (await import("./start.js")).run(args)
+      break
+    default:
+      console.error(`Unknown command: ${cmd}\n`)
+      console.log(USAGE)
+      process.exit(1)
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err)
+  process.exit(1)
+})

package/src/cli/init.ts

@@ -0,0 +1,76 @@
+/**
+ * `registry-shell init` — scaffold `registry-shell.config.ts` in the current
+ * directory and add a `shell` script to the project's package.json.
+ */
+import fs from "node:fs"
+import path from "node:path"
+
+const TEMPLATE = `import { defineConfig } from "@sntlr/registry-shell"
+
+export default defineConfig({
+  branding: {
+    siteName: "My UI",
+    shortName: "UI",
+    // siteUrl: "https://ui.example.com",
+    // github: { owner: "my-org", repo: "my-ui" },
+  },
+
+  // All path overrides are optional — these are the defaults:
+  // paths: {
+  //   components: "components/ui",
+  //   blocks: "registry/new-york/blocks",
+  //   previews: "components/previews/index.ts",
+  //   docs: "content/docs",
+  //   registryJson: "public/r",
+  //   skipBlocks: [],
+  //   // Optional: your own global CSS (brand fonts, token overrides,
+  //   // extra @source directives). Imported after the shell's globals so
+  //   // your :root { --primary: ... } wins the cascade.
+  //   // globalCss: "./styles/theme.css",
+  // },
+
+  // Custom homepage component (optional):
+  // homePage: "./components/homepage",
+})
+`
+
+export async function run(_args: string[]): Promise<void> {
+  const cwd = process.cwd()
+  const configPath = path.join(cwd, "registry-shell.config.ts")
+
+  if (fs.existsSync(configPath)) {
+    console.log(`[registry-shell] Config already exists: ${configPath}`)
+  } else {
+    fs.writeFileSync(configPath, TEMPLATE, "utf-8")
+    console.log(`[registry-shell] Wrote ${configPath}`)
+  }
+
+  // Add "shell" script to package.json if missing.
+  const pkgPath = path.join(cwd, "package.json")
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as Record<string, unknown>
+    pkg.scripts = (pkg.scripts as Record<string, string> | undefined) ?? {}
+    const scripts = pkg.scripts as Record<string, string>
+    let changed = false
+    if (!scripts.shell) {
+      scripts.shell = "registry-shell dev"
+      changed = true
+    }
+    if (!scripts["shell:build"]) {
+      scripts["shell:build"] = "registry-shell build"
+      changed = true
+    }
+    if (changed) {
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8")
+      console.log(`[registry-shell] Added "shell" / "shell:build" scripts to package.json`)
+    }
+  } else {
+    console.log(
+      `[registry-shell] No package.json found — skipped script injection. Run \`npm init\` first.`,
+    )
+  }
+
+  console.log(
+    `\nNext steps:\n  1. Edit registry-shell.config.ts (branding at minimum)\n  2. Run: npm run shell`,
+  )
+}