banhaten 0.1.2 → 0.1.3

package/schema/config.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:banhaten:schema:config",
+  "title": "Banhaten CLI config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "style": {
+      "type": "string",
+      "default": "default"
+    },
+    "tsx": {
+      "type": "boolean",
+      "default": true
+    },
+    "tailwind": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "css": {
+          "type": "string",
+          "description": "Path to the global CSS file that imports Tailwind and receives Banhaten tokens."
+        }
+      }
+    },
+    "aliases": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ui": {
+          "type": "string",
+          "description": "Import alias where Banhaten UI components are installed."
+        },
+        "utils": {
+          "type": "string",
+          "description": "Import alias for the cn utility file."
+        },
+        "hooks": {
+          "type": "string",
+          "description": "Import alias for generated hooks."
+        }
+      }
+    }
+  }
+}

package/schema/registry.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:banhaten:schema:registry",
+  "title": "Banhaten registry index",
+  "type": "object",
+  "required": ["name", "base", "components"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "base": {
+      "$ref": "#/$defs/registryEntry"
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/registryEntry"
+      }
+    }
+  },
+  "$defs": {
+    "registryEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "dependencies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "registryDependencies": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "parts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/registryFile"
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rtl": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "boolean"]
+          }
+        }
+      }
+    },
+    "registryFile": {
+      "type": "object",
+      "required": ["source", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "type": "string"
+        },
+        "target": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schema/tokens.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:banhaten:schema:tokens",
+  "title": "Banhaten design tokens",
+  "type": "object",
+  "required": ["name", "sourceStatus", "sourceFiles", "modes", "cssContract", "tokens"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "sourceStatus": {
+      "type": "string"
+    },
+    "sourceFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "modes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "cssContract": {
+      "type": "object",
+      "required": ["semanticPrefix", "fontFamily", "defaultTheme", "defaultRadius"],
+      "additionalProperties": true,
+      "properties": {
+        "semanticPrefix": {
+          "type": "string"
+        },
+        "fontFamily": {
+          "type": "string"
+        },
+        "defaultTheme": {
+          "type": "string"
+        },
+        "defaultRadius": {
+          "type": "string"
+        },
+        "shadcnAliases": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/src/cli/index.js

@@ -12,6 +12,8 @@ const packageRoot = path.resolve(
 )
 const registryRoot = path.join(packageRoot, "registry")
 const registryIndexPath = path.join(registryRoot, "index.json")
+const packageJsonPath = path.join(packageRoot, "package.json")
+const schemaRoot = path.join(packageRoot, "schema")
 
 const CONFIG_FILE = "banhaten.config.json"
 const FONT_IMPORTS = [
@@ -30,9 +32,14 @@ const VITE_DEV_DEPENDENCIES = {
 const CSS_START = "/* Banhaten design system tokens:"
 const CSS_END = "/* End Banhaten design system tokens. */"
 const syncExistsCache = new Map()
+const VALUE_FLAGS = new Set(["cwd", "file", "format"])
+let runtimeOptions = {
+  json: false,
+  silent: false,
+}
 
 const DEFAULT_CONFIG = {
-  $schema: "https://banhaten.dev/schema.json",
+  $schema: ".banhaten/schema/config.schema.json",
   style: "default",
   tsx: true,
   tailwind: {
@@ -46,6 +53,7 @@ const DEFAULT_CONFIG = {
 }
 
 const registry = await readJson(registryIndexPath)
+const packageManifest = await readJson(packageJsonPath)
 
 main().catch((error) => {
   console.error(`banhaten: ${error.message}`)
@@ -54,6 +62,15 @@ main().catch((error) => {
 
 async function main() {
   const { command, positionals, flags } = parseArgs(process.argv.slice(2))
+  runtimeOptions = {
+    json: Boolean(flags.json),
+    silent: Boolean(flags.silent || flags.s),
+  }
+
+  if (command === "version" || flags.version || flags.v) {
+    console.log(packageManifest.version)
+    return
+  }
 
   if (!command || command === "help" || flags.help || flags.h) {
     printHelp()
@@ -61,7 +78,22 @@ async function main() {
   }
 
   if (command === "list") {
-    listComponents()
+    listComponents(flags)
+    return
+  }
+
+  if (command === "search") {
+    searchComponents(positionals, flags)
+    return
+  }
+
+  if (command === "docs") {
+    showComponentDocs(positionals, flags)
+    return
+  }
+
+  if (command === "view") {
+    await viewComponent(positionals, flags)
     return
   }
 
@@ -100,6 +132,21 @@ function parseArgs(argv) {
       continue
     }
 
+    if (arg === "-s") {
+      flags.s = true
+      continue
+    }
+
+    if (arg === "-v") {
+      flags.v = true
+      continue
+    }
+
+    if (arg === "-y") {
+      flags.yes = true
+      continue
+    }
+
     if (!arg.startsWith("--")) {
       positionals.push(arg)
       continue
@@ -114,7 +161,7 @@ function parseArgs(argv) {
     }
 
     const next = argv[index + 1]
-    if ((key === "cwd" || key === "out") && next && !next.startsWith("-")) {
+    if (VALUE_FLAGS.has(key) && next && !next.startsWith("-")) {
       flags[key] = next
       index += 1
       continue
@@ -135,24 +182,196 @@ Usage:
   banhaten add <component...> [--cwd <path>] [--force] [--dry-run]
   banhaten diff [component...] [--cwd <path>] [--force]
   banhaten update [component...] [--cwd <path>] [--force] [--dry-run]
-  banhaten list
+  banhaten list [--json]
+  banhaten search <query> [--json]
+  banhaten docs <component> [--json]
+  banhaten view <component> [--file <registry-source>] [--json]
+  banhaten version
 
 Examples:
   npx banhaten init
   npx banhaten add button
   npx banhaten diff
   npx banhaten update button
+  npx banhaten search input
+  npx banhaten docs button
+  npx banhaten view button
+
+Global flags:
+  --cwd <path>     Run against a project directory.
+  --dry-run        Preview writes without changing files.
+  --force          Rewrite generated files even when already current.
+  --json           Print machine-readable output where supported.
+  --silent, -s     Suppress normal command output.
+  --yes, -y        Accepted for non-interactive scripts.
+  --version, -v    Print the installed CLI version.
 `)
 }
 
 function listComponents() {
-  const names = Object.keys(registry.components)
+  const components = Object.entries(registry.components).map(([name, component]) => ({
+    name,
+    description: component.description || "",
+    dependencies: Object.keys(component.dependencies || {}),
+    registryDependencies: component.registryDependencies || [],
+  }))
+
+  if (runtimeOptions.json) {
+    writeJson({ components })
+    return
+  }
+
+  if (runtimeOptions.silent) return
 
   console.log("Available Banhaten design system components:")
-  for (const name of names) {
-    const component = registry.components[name]
-    console.log(`- ${name}: ${component.description}`)
+  for (const { name, description } of components) {
+    console.log(`- ${name}: ${description}`)
+  }
+}
+
+function searchComponents(positionals) {
+  const query = positionals.join(" ").trim().toLowerCase()
+  if (!query) {
+    throw new Error("missing search query. Try `banhaten search input`.")
+  }
+
+  const matches = Object.entries(registry.components)
+    .filter(([name, component]) => {
+      const haystack = [
+        name,
+        component.description,
+        ...(component.parts || []),
+        ...(component.registryDependencies || []),
+      ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase()
+
+      return haystack.includes(query)
+    })
+    .map(([name, component]) => ({
+      name,
+      description: component.description || "",
+      parts: component.parts || [],
+    }))
+
+  if (runtimeOptions.json) {
+    writeJson({ query, matches })
+    return
+  }
+
+  if (runtimeOptions.silent) return
+
+  if (matches.length === 0) {
+    console.log(`No Banhaten components matched "${query}".`)
+    return
+  }
+
+  console.log(`Banhaten components matching "${query}":`)
+  for (const match of matches) {
+    console.log(`- ${match.name}: ${match.description}`)
+  }
+}
+
+function showComponentDocs(positionals) {
+  const [name] = positionals
+  const component = getComponentOrThrow(name)
+  const docsPath = getComponentDocPath(name)
+  const result = {
+    name,
+    description: component.description || "",
+    install: `npx banhaten add ${name}`,
+    docsPath,
+    files: component.files || [],
+    examples: component.examples || [],
+  }
+
+  if (runtimeOptions.json) {
+    writeJson(result)
+    return
+  }
+
+  if (runtimeOptions.silent) return
+
+  console.log(`${name}: ${result.description}`)
+  console.log(`Install: ${result.install}`)
+  console.log(`Docs: ${docsPath}`)
+
+  if (result.files.length > 0) {
+    console.log("Files:")
+    for (const file of result.files) {
+      console.log(`- ${file.source} -> ${file.target}`)
+    }
+  }
+
+  if (result.examples.length > 0) {
+    console.log("Examples:")
+    for (const example of result.examples) {
+      console.log(`- ${example}`)
+    }
+  }
+}
+
+async function viewComponent(positionals, flags) {
+  const [name] = positionals
+  const component = getComponentOrThrow(name)
+  const files = component.files || []
+  const requestedFile = typeof flags.file === "string" ? flags.file : null
+  const file =
+    (requestedFile
+      ? files.find((entry) => entry.source === requestedFile)
+      : files.find((entry) => /\.(ts|tsx|css)$/.test(entry.source)) || files[0]) ||
+    null
+
+  if (!file) {
+    throw new Error(`component "${name}" has no viewable registry files.`)
+  }
+
+  const sourcePath = path.join(registryRoot, file.source)
+  const content = await fs.readFile(
+    sourcePath,
+    isTextRegistryFile(file.source) ? "utf8" : undefined
+  )
+
+  if (runtimeOptions.json) {
+    writeJson({
+      name,
+      file,
+      content: Buffer.isBuffer(content) ? content.toString("base64") : content,
+      encoding: Buffer.isBuffer(content) ? "base64" : "utf8",
+    })
+    return
   }
+
+  if (runtimeOptions.silent) return
+
+  console.log(Buffer.isBuffer(content) ? content.toString("base64") : content)
+}
+
+function getComponentOrThrow(name) {
+  if (!name) {
+    throw new Error("missing component name. Try `banhaten docs button`.")
+  }
+
+  const component = registry.components[name]
+  if (!component) {
+    throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
+  }
+
+  return component
+}
+
+function getComponentDocPath(name) {
+  const docAliases = {
+    "onboarding-step": "onboarding-step-list-item",
+  }
+  const docId = docAliases[name] || name
+
+  return `docs/design-system/components/${docId}.md`
+}
+
+function writeJson(value) {
+  console.log(JSON.stringify(value, null, 2))
 }
 
 async function initProject(flags) {
@@ -165,6 +384,7 @@ async function initProject(flags) {
 
   writes.push(
     ...(await writeConfig(cwd, config, { dryRun, force })),
+    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
     ...(await writeBaseFiles(cwd, config, { dryRun, force })),
     ...(await writeGlobalCss(cwd, config, { dryRun, force })),
     ...(await writeAliasConfig(cwd, config, { dryRun, force }))
@@ -178,7 +398,7 @@ async function initProject(flags) {
   writes.push(...dependencyWrites)
 
   printResult("Initialized Banhaten design system", writes, dryRun)
-  printInstallHint(writes, dryRun)
+  await printInstallHint(cwd, writes, dryRun)
 }
 
 async function addComponents(names, flags) {
@@ -236,7 +456,9 @@ async function writeComponents(requestedNames, flags, options) {
 
   writes.push(
     ...(await writeConfig(cwd, config, { dryRun, force })),
+    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
     ...(await writeBaseFiles(cwd, config, { dryRun, force })),
+    ...(await writeGlobalCss(cwd, config, { dryRun, force })),
     ...(await writeAliasConfig(cwd, config, { dryRun, force }))
   )
 
@@ -262,7 +484,7 @@ async function writeComponents(requestedNames, flags, options) {
   )))
 
   printResult(options.title, writes, dryRun)
-  printInstallHint(writes, dryRun)
+  await printInstallHint(cwd, writes, dryRun)
 }
 
 async function findInstalledComponents(cwd, config) {
@@ -371,6 +593,24 @@ async function detectCssPath(cwd, fallback) {
 async function writeConfig(cwd, config, options) {
   const configPath = path.join(cwd, CONFIG_FILE)
   if ((await exists(configPath)) && !options.force) {
+    const current = await fs.readFile(configPath, "utf8")
+    const currentConfig = JSON.parse(current)
+
+    if (currentConfig.$schema !== DEFAULT_CONFIG.$schema) {
+      const nextConfig = {
+        $schema: DEFAULT_CONFIG.$schema,
+        ...currentConfig,
+      }
+      nextConfig.$schema = DEFAULT_CONFIG.$schema
+      const status = await writeFile(
+        configPath,
+        `${JSON.stringify(nextConfig, null, 2)}\n`,
+        { dryRun: options.dryRun }
+      )
+
+      return [`${status} ${relative(cwd, configPath)}`]
+    }
+
     return [`kept ${relative(cwd, configPath)}`]
   }
 
@@ -382,6 +622,26 @@ async function writeConfig(cwd, config, options) {
   return [`${status} ${relative(cwd, configPath)}`]
 }
 
+async function writeProjectSchemaFiles(cwd, options) {
+  const schemaFiles = [
+    "config.schema.json",
+    "registry.schema.json",
+    "tokens.schema.json",
+  ]
+  const writes = []
+
+  for (const schemaFile of schemaFiles) {
+    const sourcePath = path.join(schemaRoot, schemaFile)
+    const targetPath = path.join(cwd, ".banhaten", "schema", schemaFile)
+    const source = await fs.readFile(sourcePath, "utf8")
+    const status = await writeFile(targetPath, source, options)
+
+    writes.push(`${status} ${relative(cwd, targetPath)}`)
+  }
+
+  return writes
+}
+
 async function writeBaseFiles(cwd, config, options) {
   return writeRegistryFiles(cwd, config, registry.base.files || [], options)
 }
@@ -413,16 +673,12 @@ async function writeGlobalCss(cwd, config, options) {
     ? removeExistingTokenBlock(current, relative(cwd, cssPath))
     : { content: "", found: false }
 
-  if (tokenBlock.found && !options.force) {
-    return [`kept ${relative(cwd, cssPath)}`]
-  }
-
   const nextCss = current
     ? `${tokenBlock.content.trimEnd()}\n\n${tokenCss}\n`
     : `${tokenCss}\n`
   const next = ensureGlobalCssImports(nextCss)
 
-  const status = await writeFile(cssPath, next, { ...options, force: true })
+  const status = await writeFile(cssPath, next, options)
   return [`${status} ${relative(cwd, cssPath)}`]
 }
 
@@ -1742,20 +1998,58 @@ function relative(cwd, targetPath) {
 }
 
 function printResult(title, writes, dryRun) {
+  if (runtimeOptions.json) {
+    writeJson({ dryRun, title, writes })
+    return
+  }
+
+  if (runtimeOptions.silent) return
+
   console.log(`${dryRun ? "Dry run: " : ""}${title}`)
   for (const write of writes) {
     console.log(`- ${write}`)
   }
 }
 
-function printInstallHint(writes, dryRun) {
-  if (dryRun) return
+async function printInstallHint(cwd, writes, dryRun) {
+  if (dryRun || runtimeOptions.json || runtimeOptions.silent) return
 
   const packageJsonChanged = writes.some((write) =>
     /^(wrote|updated) package\.json$/.test(write)
   )
 
   if (packageJsonChanged) {
-    console.log("\nNext: run npm install to install the added dependencies.")
+    console.log(`\nNext: run ${await getInstallCommand(cwd)} to install the added dependencies.`)
+  }
+}
+
+async function getInstallCommand(cwd) {
+  const packageJson = await readJsonIfExists(path.join(cwd, "package.json"))
+  const declaredPackageManager = parsePackageManager(packageJson?.packageManager)
+
+  if (declaredPackageManager) return `${declaredPackageManager} install`
+
+  const lockfileManagers = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lockb", "bun"],
+    ["bun.lock", "bun"],
+    ["package-lock.json", "npm"],
+    ["npm-shrinkwrap.json", "npm"],
+  ]
+
+  for (const [lockfile, manager] of lockfileManagers) {
+    if (await exists(path.join(cwd, lockfile))) return `${manager} install`
   }
+
+  return "npm install"
+}
+
+function parsePackageManager(packageManager) {
+  if (typeof packageManager !== "string") return null
+
+  const name = packageManager.split("@")[0]
+  if (["npm", "pnpm", "yarn", "bun"].includes(name)) return name
+
+  return null
 }

package/tokens/banhaten.tokens.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://banhaten.dev/tokens.schema.json",
+  "$schema": "../schema/tokens.schema.json",
   "name": "Banhaten design system",
   "sourceStatus": "zip-derived",
   "sourceFiles": [