@azmxsa/cli 0.0.0-stage → 1.2.2

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# azmx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The AZM X Design System installer. It adds components, blocks and tokens from the private AZM X registry to a React and Tailwind project, pinned to one released version. Nothing to install: run it with npx.
+
+```bash
+gh auth login             # or set GITHUB_TOKEN to a token that can read the design system repository
+npx @azmxsa/cli init             # adds the AZM X registry to components.json
+npx @azmxsa/cli add tokens
+npx @azmxsa/cli add button dialog form-field
+npx @azmxsa/cli list
+```
+
+- `npx @azmxsa/cli add <name...> [flags]`: flags such as `-o` (overwrite) and `-y` pass through to shadcn.
+- `--ref <tag|main>`: install another version than this installer's own (`azmx@1.2.0` installs `v1.2.0`).
+- The components themselves stay private; only this installer is public.

package/bin/azmx.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { execFileSync, spawnSync } from "node:child_process"
+import { HELP, REPO, VERSION, defaultRef, childEnv, isValidRef, itemsFor, parseArgs, refFromUrl, shadcnArgs, tokenLeaks, unsafeFlags, withRegistry } from "../lib/cli.mjs"
+
+const CONFIG = "components.json"
+const npx = process.platform === "win32" ? "npx.cmd" : "npx"
+const fail = (message) => {
+  console.error(`azmx: ${message}`)
+  process.exit(1)
+}
+
+// The registry is private: the GitHub token comes from the environment, or from the GitHub CLI.
+function token() {
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN
+  try {
+    return execFileSync("gh", ["auth", "token"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined
+  } catch {
+    return undefined
+  }
+}
+
+const readConfig = () => (existsSync(CONFIG) ? JSON.parse(readFileSync(CONFIG, "utf8")) : undefined)
+const currentRef = (config) => refFromUrl(config?.registries?.["@azmx"]?.url)
+
+function init(ref) {
+  if (!isValidRef(ref)) fail(`"${ref}" is not a version tag or branch name.`)
+  let config = readConfig()
+  if (!config) {
+    console.log("No components.json yet: setting up the project first.")
+    const run = spawnSync(npx, shadcnArgs("init", [], []), { stdio: "inherit" })
+    if (run.status !== 0) process.exit(run.status ?? 1)
+    config = readConfig()
+    if (!config) fail("components.json was not created.")
+  }
+  writeFileSync(CONFIG, JSON.stringify(withRegistry(config, ref), null, 2) + "\n")
+  console.log(`AZM X registry set to ${ref} in ${CONFIG}.`)
+}
+
+function run(command, names, ref, pass) {
+  const flags = unsafeFlags(pass)
+  if (flags.length) fail(`run azmx inside the project folder instead of passing ${flags.join(", ")}.`)
+  // Anything but AZM X's exact address is rewritten, so the token only ever goes to GitHub.
+  if (ref || !currentRef(readConfig())) init(ref ?? defaultRef())
+  const leaks = tokenLeaks(readConfig())
+  if (leaks.length) fail(`components.json reads secrets for a registry outside https://raw.githubusercontent.com (${leaks.join(", ")}). Remove those placeholders, then try again.`)
+  const auth = token()
+  if (!auth) fail(`set GITHUB_TOKEN to a token that can read ${REPO}, or sign in with: gh auth login`)
+  const result = spawnSync(npx, shadcnArgs(command, itemsFor(names), pass), { stdio: "inherit", env: childEnv(process.env, auth) })
+  process.exit(result.status ?? 1)
+}
+
+async function list(ref) {
+  const auth = token()
+  if (!auth) fail(`set GITHUB_TOKEN to a token that can read ${REPO}, or sign in with: gh auth login`)
+  const at = ref ?? currentRef(readConfig()) ?? defaultRef()
+  if (!isValidRef(at)) fail(`"${at}" is not a version tag or branch name.`)
+  const res = await fetch(`https://raw.githubusercontent.com/${REPO}/${at}/registry.json`, { headers: { Authorization: `Bearer ${auth}` } })
+  if (!res.ok) fail(`could not read the registry at ${at} (${res.status}).`)
+  const { items } = await res.json()
+  const groups = { "registry:style": "Tokens", "registry:lib": "Libraries", "registry:ui": "Components", "registry:block": "Blocks" }
+  for (const [type, title] of Object.entries(groups)) {
+    const rows = items.filter((i) => i.type === type && !i.meta?.deprecated)
+    if (!rows.length) continue
+    console.log(`\n${title}`)
+    for (const i of rows) console.log(`  ${i.name.padEnd(22)} ${i.title ?? ""}`)
+  }
+  console.log(`\nAZM X Design System ${at}. Add one with: azmx add <name>`)
+}
+
+const { command, names, ref, pass } = parseArgs(process.argv.slice(2))
+if (command === "version") console.log(VERSION)
+else if (command === "help") console.log(HELP)
+else if (command === "init") init(ref ?? defaultRef())
+else if (command === "add") names.length ? run("add", names, ref, pass) : fail("name what to add, e.g. azmx add button")
+else if (command === "view") names.length ? run("view", names, ref, pass) : fail("name what to view, e.g. azmx view button")
+else if (command === "list") await list(ref)
+else fail(`unknown command "${command}". Run azmx --help.`)

package/lib/cli.mjs

@@ -0,0 +1,97 @@
+// The AZM X installer. It writes the private registry into components.json and runs the shadcn
+// CLI the system is built with, so a product types `azmx add button` and never shadcn's name.
+
+/** The installer's own version, the same as the system's (tests keep it equal to package.json). */
+export const VERSION = "1.2.2"
+/** The shadcn CLI the system's registry is built and tested with. */
+export const SHADCN_VERSION = "4.22.1"
+export const REPO = "Gamaleldientarek/azmx-design-system"
+
+/** The tag of the system this installer belongs to: azmx 1.1.0 installs v1.1.0. */
+export const defaultRef = () => `v${VERSION}`
+
+export function parseArgs(argv) {
+  const args = [...argv]
+  let command = args.shift() ?? "help"
+  if (command === "--version" || command === "-v") command = "version"
+  if (command === "--help" || command === "-h") command = "help"
+  const names = []
+  const pass = []
+  let ref
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === "--ref") ref = args[++i]
+    else if (a.startsWith("--ref=")) ref = a.slice(6)
+    else if (a.startsWith("-")) pass.push(a)
+    else names.push(a)
+  }
+  return { command, names, ref, pass }
+}
+
+export function registryEntry(ref) {
+  return {
+    url: `https://raw.githubusercontent.com/${REPO}/${ref}/public/r/{name}.json`,
+    headers: { Authorization: "Bearer ${GITHUB_TOKEN}" },
+  }
+}
+
+/** components.json with the AZM X registry added (or moved to `ref`), everything else kept. */
+export function withRegistry(config, ref) {
+  return { ...config, registries: { ...(config.registries ?? {}), "@azmx": registryEntry(ref) } }
+}
+
+const REF = /^[A-Za-z0-9._-]+$/
+const REGISTRY_URL = /^https:\/\/raw\.githubusercontent\.com\/Gamaleldientarek\/azmx-design-system\/([A-Za-z0-9._-]+)\/public\/r\/\{name\}\.json$/
+
+/** A tag or branch name, nothing that could change the address's path. */
+export const isValidRef = (ref) => typeof ref === "string" && REF.test(ref) && !ref.startsWith(".")
+
+/** The version in an @azmx registry address, only when the address is exactly AZM X's own. */
+export const refFromUrl = (url) => (typeof url === "string" ? url.match(REGISTRY_URL)?.[1] : undefined)
+
+/** Registries in components.json that read anything from the environment (a ${...} placeholder
+ *  anywhere in the entry) but don't point at https://raw.githubusercontent.com without credentials. */
+export function tokenLeaks(config) {
+  return Object.entries(config?.registries ?? {})
+    .filter(([, entry]) => {
+      if (!JSON.stringify(entry ?? {}).includes("${")) return false
+      try {
+        const u = new URL(String(typeof entry === "string" ? entry : entry?.url).replace("{name}", "x"))
+        return !(u.protocol === "https:" && u.host === "raw.githubusercontent.com" && !u.username && !u.password)
+      } catch {
+        return true
+      }
+    })
+    .map(([name]) => name)
+}
+
+/** shadcn flags that would point it at another folder's components.json, which azmx hasn't checked. */
+export const unsafeFlags = (pass) => pass.filter((f) => f === "--cwd" || f === "-c" || f.startsWith("--cwd=") || /^-c./.test(f))
+
+/** The environment shadcn runs with: no GitHub tokens but the one azmx checked, as GITHUB_TOKEN. */
+export function childEnv(env, token) {
+  const out = {}
+  for (const [k, v] of Object.entries(env)) if (!/^(GH_|GITHUB_)/.test(k) || !/TOKEN/.test(k)) out[k] = v
+  return { ...out, GITHUB_TOKEN: token }
+}
+
+export const itemsFor = (names) => names.map((n) => (n.startsWith("@azmx/") ? n : `@azmx/${n}`))
+
+/** Arguments for npx: the pinned shadcn CLI, the command, the items and the flags passed on. */
+export const shadcnArgs = (command, items, pass) => ["--yes", `shadcn@${SHADCN_VERSION}`, command, ...items, ...pass]
+
+export const HELP = `azmx ${VERSION}: the AZM X Design System installer
+
+Usage
+  npx @azmxsa/cli init [--ref v${VERSION}]   add the AZM X registry to components.json
+  npx @azmxsa/cli add <name...> [flags]      add components, blocks or tokens (flags go to shadcn, e.g. -o)
+  npx @azmxsa/cli list                       list everything the registry has
+  npx @azmxsa/cli --version
+
+The registry is private: set GITHUB_TOKEN to a token that can read ${REPO},
+or sign in with the GitHub CLI (gh auth login) and azmx uses its token.
+
+Examples
+  npx @azmxsa/cli add tokens
+  npx @azmxsa/cli add button dialog form-field
+  npx @azmxsa/cli add hero --ref main`

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@azmxsa/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.2",
+  "description": "Add AZM X Design System components, blocks and tokens to a React and Tailwind project.",
+  "type": "module",
+  "bin": {
+    "azmx": "bin/azmx.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}