banhaten 0.1.3 → 0.2.0

package/schema/registry.schema.json

@@ -6,80 +6,185 @@
   "required": ["name", "base", "components"],
   "additionalProperties": false,
   "properties": {
-    "$schema": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    },
-    "base": {
-      "$ref": "#/$defs/registryEntry"
-    },
+    "$schema": { "type": "string" },
+    "name": { "type": "string", "minLength": 1 },
+    "base": { "$ref": "#/$defs/baseEntry" },
     "components": {
       "type": "object",
-      "additionalProperties": {
-        "$ref": "#/$defs/registryEntry"
-      }
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/componentEntry" }
     }
   },
   "$defs": {
-    "registryEntry": {
+    "baseEntry": {
       "type": "object",
-      "additionalProperties": true,
+      "required": ["dependencies", "files"],
+      "additionalProperties": false,
       "properties": {
-        "description": {
-          "type": "string"
-        },
-        "dependencies": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          }
-        },
-        "registryDependencies": {
+        "dependencies": { "$ref": "#/$defs/dependencies" },
+        "files": {
           "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/registryFile" }
+        }
+      }
+    },
+    "componentEntry": {
+      "type": "object",
+      "required": [
+        "description",
+        "dependencies",
+        "parts",
+        "supportedExports",
+        "files",
+        "examples"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["expanded"] },
+        "dependencies": { "$ref": "#/$defs/dependencies" },
+        "registryDependencies": { "$ref": "#/$defs/stringArray" },
         "parts": {
+          "description": "Ordered, non-exhaustive component anatomy. The first value is the primary renderable part; every value must also appear in supportedExports.",
           "type": "array",
-          "items": {
-            "type": "string"
-          }
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/componentPartName" }
+        },
+        "supportedExports": {
+          "description": "Exhaustive runtime value exports, grouped by the installed source module that owns each import path. Type-only exports are intentionally excluded.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/supportedExportModule" }
         },
         "files": {
           "type": "array",
-          "items": {
-            "$ref": "#/$defs/registryFile"
-          }
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/registryFile" }
         },
         "examples": {
           "type": "array",
-          "items": {
-            "type": "string"
-          }
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
         },
-        "rtl": {
+        "props": {
+          "description": "Machine-readable public prop behavior, including rendered defaults for optional visual slots.",
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "$ref": "#/$defs/componentProp" }
+        },
+        "defaults": {
+          "description": "Explicit defaults for array-valued capabilities. Keys must name a capability on the same component and values must belong to that capability list.",
           "type": "object",
+          "minProperties": 1,
           "additionalProperties": {
-            "type": ["string", "boolean"]
+            "type": ["string", "number", "boolean", "null"]
           }
-        }
+        },
+        "recommendedFor": { "$ref": "#/$defs/stringArray" },
+        "avoidWhen": { "$ref": "#/$defs/stringArray" },
+        "recipes": { "$ref": "#/$defs/stringArray" },
+        "rtl": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "type": ["string", "boolean"] }
+        },
+        "actions": { "$ref": "#/$defs/stringArray" },
+        "alignments": { "$ref": "#/$defs/stringArray" },
+        "breakpoints": { "$ref": "#/$defs/stringArray" },
+        "cardPositions": { "$ref": "#/$defs/stringArray" },
+        "colors": { "$ref": "#/$defs/stringArray" },
+        "controlPositions": { "$ref": "#/$defs/stringArray" },
+        "densities": { "$ref": "#/$defs/stringArray" },
+        "directions": { "$ref": "#/$defs/stringArray" },
+        "features": { "$ref": "#/$defs/stringArray" },
+        "forms": { "$ref": "#/$defs/stringArray" },
+        "indicators": { "$ref": "#/$defs/stringArray" },
+        "intents": { "$ref": "#/$defs/stringArray" },
+        "itemKinds": { "$ref": "#/$defs/stringArray" },
+        "itemTypes": { "$ref": "#/$defs/stringArray" },
+        "kinds": { "$ref": "#/$defs/stringArray" },
+        "labelPositions": { "$ref": "#/$defs/stringArray" },
+        "layouts": { "$ref": "#/$defs/stringArray" },
+        "modes": { "$ref": "#/$defs/stringArray" },
+        "offsets": { "$ref": "#/$defs/stringArray" },
+        "options": { "$ref": "#/$defs/stringArray" },
+        "orientations": { "$ref": "#/$defs/stringArray" },
+        "platforms": { "$ref": "#/$defs/stringArray" },
+        "pointerPositions": { "$ref": "#/$defs/stringArray" },
+        "selectionTypes": { "$ref": "#/$defs/stringArray" },
+        "shapes": { "$ref": "#/$defs/stringArray" },
+        "sides": { "$ref": "#/$defs/stringArray" },
+        "sizes": { "$ref": "#/$defs/stringArray" },
+        "states": { "$ref": "#/$defs/stringArray" },
+        "statusColors": { "$ref": "#/$defs/stringArray" },
+        "styles": { "$ref": "#/$defs/stringArray" },
+        "tokens": { "$ref": "#/$defs/stringArray" },
+        "tones": { "$ref": "#/$defs/stringArray" },
+        "types": { "$ref": "#/$defs/stringArray" },
+        "valueModes": { "$ref": "#/$defs/stringArray" },
+        "variants": { "$ref": "#/$defs/stringArray" },
+        "widths": { "$ref": "#/$defs/stringArray" }
       }
     },
-    "registryFile": {
+    "dependencies": {
       "type": "object",
-      "required": ["source", "target"],
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "stringArray": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "exportName": {
+      "type": "string",
+      "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$"
+    },
+    "componentPartName": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9_$]*$"
+    },
+    "componentProp": {
+      "type": "object",
+      "required": ["type", "default", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "default": {
+          "type": ["string", "number", "boolean", "null"]
+        },
+        "description": { "type": "string", "minLength": 1 },
+        "deprecated": { "type": "boolean" }
+      }
+    },
+    "supportedExportModule": {
+      "type": "object",
+      "required": ["source", "values"],
       "additionalProperties": false,
       "properties": {
         "source": {
-          "type": "string"
+          "description": "Exact TypeScript source path from this component's files array.",
+          "type": "string",
+          "pattern": "^(?!.*\\.d\\.[cm]?[jt]sx?$).+\\.[cm]?[jt]sx?$"
         },
-        "target": {
-          "type": "string"
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/exportName" }
         }
       }
+    },
+    "registryFile": {
+      "type": "object",
+      "required": ["source", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }

package/schema/tokens.schema.json

@@ -3,61 +3,161 @@
   "$id": "urn:banhaten:schema:tokens",
   "title": "Banhaten design tokens",
   "type": "object",
-  "required": ["name", "sourceStatus", "sourceFiles", "modes", "cssContract", "tokens"],
+  "required": ["name", "sourceStatus", "sourceFiles", "provenance", "modes", "cssContract", "tokens", "cssVariables"],
   "additionalProperties": false,
   "properties": {
-    "$schema": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    },
-    "sourceStatus": {
-      "type": "string"
-    },
+    "$schema": { "type": "string" },
+    "name": { "type": "string", "minLength": 1 },
+    "sourceStatus": { "const": "manually-curated-from-reference-archives" },
     "sourceFiles": {
       "type": "array",
-      "items": {
-        "type": "string"
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["method", "lastReviewed", "themeSources", "notes"],
+      "additionalProperties": false,
+      "properties": {
+        "method": { "type": "string", "minLength": 1 },
+        "lastReviewed": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+        "themeSources": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
+        "notes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
       }
     },
     "modes": {
       "type": "object",
-      "additionalProperties": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        }
+      "required": ["color", "theme", "radius", "numbers"],
+      "additionalProperties": false,
+      "properties": {
+        "color": { "$ref": "#/$defs/stringArray" },
+        "theme": { "$ref": "#/$defs/stringArray" },
+        "radius": { "$ref": "#/$defs/stringArray" },
+        "numbers": { "$ref": "#/$defs/stringArray" }
       }
     },
     "cssContract": {
       "type": "object",
-      "required": ["semanticPrefix", "fontFamily", "defaultTheme", "defaultRadius"],
-      "additionalProperties": true,
+      "required": ["semanticPrefix", "fontFamily", "fontFamilies", "defaultTheme", "defaultNeutralTheme", "defaultRadius", "shadcnAliases", "shadowTokens"],
+      "additionalProperties": false,
       "properties": {
-        "semanticPrefix": {
-          "type": "string"
-        },
-        "fontFamily": {
-          "type": "string"
-        },
-        "defaultTheme": {
-          "type": "string"
-        },
-        "defaultRadius": {
-          "type": "string"
+        "semanticPrefix": { "type": "string", "minLength": 1 },
+        "fontFamily": { "type": "string", "minLength": 1 },
+        "fontFamilies": {
+          "type": "object",
+          "required": ["english", "arabic", "fallback"],
+          "additionalProperties": false,
+          "properties": {
+            "english": { "type": "string", "minLength": 1 },
+            "arabic": { "type": "string", "minLength": 1 },
+            "fallback": { "type": "string", "minLength": 1 }
+          }
         },
+        "defaultTheme": { "type": "string", "minLength": 1 },
+        "defaultNeutralTheme": { "type": "string", "minLength": 1 },
+        "defaultRadius": { "type": "string", "minLength": 1 },
+        "shadowTokens": { "type": "string" },
         "shadcnAliases": {
           "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          }
+          "minProperties": 1,
+          "additionalProperties": { "type": "string", "pattern": "^--" }
         }
       }
     },
     "tokens": {
       "type": "object",
-      "additionalProperties": true
+      "required": ["colorMode", "theme", "numbers", "radius"],
+      "additionalProperties": false,
+      "properties": {
+        "colorMode": { "$ref": "#/$defs/modeTokenMaps" },
+        "theme": { "$ref": "#/$defs/modeTokenMaps" },
+        "numbers": { "$ref": "#/$defs/tokenMap" },
+        "radius": { "$ref": "#/$defs/modeTokenMaps" }
+      }
+    },
+    "cssVariables": {
+      "type": "object",
+      "required": ["system", "typography", "effects", "components", "darkEffects", "scopedAliases"],
+      "additionalProperties": false,
+      "properties": {
+        "system": { "$ref": "#/$defs/cssVariableMap" },
+        "typography": { "$ref": "#/$defs/cssVariableMap" },
+        "effects": { "$ref": "#/$defs/cssVariableMap" },
+        "components": { "$ref": "#/$defs/cssVariableMap" },
+        "darkEffects": { "$ref": "#/$defs/cssVariableMap" },
+        "scopedAliases": { "$ref": "#/$defs/cssVariableMap" }
+      }
+    }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "modeTokenMaps": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/tokenMap" }
+    },
+    "tokenMap": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/token" }
+    },
+    "token": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "color" },
+            "value": {
+              "type": "string",
+              "pattern": "^(?:#[0-9A-Fa-f]{6,8}|rgb\\([^\\n]+\\))$"
+            },
+            "alias": { "type": ["string", "null"], "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "number" },
+            "value": { "type": "number" },
+            "alias": { "type": ["string", "null"], "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "cssVariableMap": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^--(?:bh|shadow)-[a-z0-9-]+$" },
+      "additionalProperties": { "$ref": "#/$defs/cssVariableToken" }
+    },
+    "cssVariableToken": {
+      "type": "object",
+      "required": ["type", "value"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": ["alias", "cubicBezier", "dimension", "duration", "number", "shadow", "string"]
+        },
+        "value": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }

package/src/cli/command-line.js

@@ -0,0 +1,194 @@
+import { parseArgs as parseNodeArgs } from "node:util"
+
+const OPTION_DEFINITIONS = {
+  cwd: { type: "string" },
+  file: { type: "string" },
+  "dry-run": { type: "boolean" },
+  force: { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+  json: { type: "boolean" },
+  silent: { type: "boolean", short: "s" },
+  version: { type: "boolean", short: "v" },
+  yes: { type: "boolean", short: "y" },
+}
+
+const GLOBAL_OPTIONS = ["help", "silent", "version", "yes"]
+
+const COMMAND_SCHEMAS = {
+  add: commandSchema({
+    minPositionals: 1,
+    maxPositionals: Number.POSITIVE_INFINITY,
+    options: ["cwd", "dry-run", "force", "json"],
+  }),
+  diff: commandSchema({
+    maxPositionals: Number.POSITIVE_INFINITY,
+    options: ["cwd", "json"],
+  }),
+  docs: commandSchema({
+    minPositionals: 1,
+    maxPositionals: 1,
+    options: ["json"],
+  }),
+  doctor: commandSchema({
+    maxPositionals: 0,
+    options: ["cwd", "json"],
+  }),
+  help: commandSchema(),
+  init: commandSchema({
+    maxPositionals: 0,
+    options: ["cwd", "dry-run", "force", "json"],
+  }),
+  list: commandSchema({ maxPositionals: 0, options: ["json"] }),
+  search: commandSchema({
+    minPositionals: 1,
+    maxPositionals: Number.POSITIVE_INFINITY,
+    options: ["json"],
+  }),
+  update: commandSchema({
+    maxPositionals: Number.POSITIVE_INFINITY,
+    options: ["cwd", "dry-run", "force", "json"],
+  }),
+  version: commandSchema({ maxPositionals: 0 }),
+  view: commandSchema({
+    minPositionals: 1,
+    maxPositionals: 1,
+    options: ["file", "json"],
+  }),
+}
+
+export function parseCommandLine(argv) {
+  let parsed
+
+  try {
+    parsed = parseNodeArgs({
+      allowPositionals: true,
+      args: argv,
+      options: OPTION_DEFINITIONS,
+      strict: true,
+      tokens: true,
+    })
+  } catch (error) {
+    throw new Error(normalizeParseError(error))
+  }
+
+  assertNoDuplicateOptions(parsed.tokens)
+  assertNonEmptyValueOptions(parsed.values)
+
+  const [command, ...positionals] = parsed.positionals
+  const flags = { ...parsed.values }
+
+  if (command === undefined) {
+    assertRootOptions(flags)
+    return { command: undefined, flags, positionals }
+  }
+
+  const schema = COMMAND_SCHEMAS[command]
+  if (!schema) {
+    throw new Error(`unknown command "${command}"`)
+  }
+
+  assertAllowedOptions(command, flags, schema)
+
+  if (!flags.help && !flags.version) {
+    assertPositionalCount(command, positionals, schema)
+  }
+
+  return { command, flags, positionals }
+}
+
+function commandSchema({
+  minPositionals = 0,
+  maxPositionals = 0,
+  options = [],
+} = {}) {
+  return {
+    minPositionals,
+    maxPositionals,
+    options: new Set([...GLOBAL_OPTIONS, ...options]),
+  }
+}
+
+function assertRootOptions(flags) {
+  const allowed = new Set(GLOBAL_OPTIONS)
+  for (const name of Object.keys(flags)) {
+    if (!allowed.has(name)) {
+      throw new Error(`option "--${name}" requires a command`)
+    }
+  }
+}
+
+function assertAllowedOptions(command, flags, schema) {
+  for (const name of Object.keys(flags)) {
+    if (!schema.options.has(name)) {
+      throw new Error(`option "--${name}" is not valid for command "${command}"`)
+    }
+  }
+}
+
+function assertPositionalCount(command, positionals, schema) {
+  if (positionals.length < schema.minPositionals) {
+    if (command === "add") {
+      throw new Error("missing component name. Try `banhaten add button`.")
+    }
+    if (command === "search") {
+      throw new Error("missing search query. Try `banhaten search input`.")
+    }
+    throw new Error(
+      `missing argument for command "${command}"`
+    )
+  }
+
+  if (positionals.length > schema.maxPositionals) {
+    const unexpected = positionals[schema.maxPositionals]
+    throw new Error(
+      `unexpected argument "${unexpected}" for command "${command}"`
+    )
+  }
+}
+
+function assertNoDuplicateOptions(tokens) {
+  const seen = new Set()
+
+  for (const token of tokens) {
+    if (token.kind !== "option") continue
+    if (seen.has(token.name)) {
+      throw new Error(`option "--${token.name}" was provided more than once`)
+    }
+    seen.add(token.name)
+  }
+}
+
+function assertNonEmptyValueOptions(values) {
+  for (const name of ["cwd", "file"]) {
+    if (name in values && values[name].trim() === "") {
+      throw new Error(`option "--${name}" requires a non-empty value`)
+    }
+  }
+}
+
+function normalizeParseError(error) {
+  if (error?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+    const match = error.message.match(/Unknown option '([^']+)'/)
+    return match ? `unknown option "${match[1]}"` : error.message
+  }
+
+  if (error?.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+    const missing = error.message.match(/Option '([^']+)' argument missing/)
+    if (missing) {
+      const optionName = missing[1]
+        .split(", ")
+        .at(-1)
+        .replace(/\s*<value>\s*$/, "")
+        .trim()
+      return `option "${optionName}" requires a value`
+    }
+
+    const ambiguous = error.message.match(/Option '([^']+)' argument is ambiguous/)
+    if (ambiguous) return `option "${ambiguous[1]}" requires a value`
+
+    const booleanValue = error.message.match(/Option '([^']+)' does not take an argument/)
+    if (booleanValue) return `option "${booleanValue[1]}" does not take a value`
+  }
+
+  return error?.message || String(error)
+}

package/src/cli/config-editors.js

@@ -0,0 +1,9 @@
+// Facade over the config editors. Kept so callers have one import site while
+// the JSONC, Vite, and scanner concerns stay in separate modules.
+
+export { parseJsonc, updateJsoncAliasSource } from "./jsonc.js"
+export {
+  readViteAliasKeys,
+  readViteAliasSourceRoot,
+  updateViteConfigSource,
+} from "./vite-config.js"