hlmnhkl-ui 0.18.0 → 0.19.0

package/README.md

@@ -11,18 +11,20 @@ React components that move with meaning. Black, white and grey, accessible, and
 
 ## Install
 
-From your app's folder, copy the components you need:
+From your app's folder, set it up once, then copy the components you need:
 
 ```sh
+npx hlmnhkl-ui@latest init
 npx hlmnhkl-ui@latest add button dialog
 ```
 
-Also `pnpm dlx`, `yarn dlx` (Yarn 2 and up) or `bunx`. Files go to `src/ui`, or pass `--to <folder>`. The command also copies the components they use (Button needs Spinner), the shared files and `tokens.css`.
+Also `pnpm dlx`, `yarn dlx` (Yarn 2 and up) or `bunx`. `init` adds `tokens.css` and `base.css` to `src/ui` (or `--to <folder>`) and remembers the folder in `hlmnhkl-ui.json`. `add` also copies the components they use (Button needs Spinner) and the shared files.
 
-Then import the tokens once at your app root, and use a component:
+Then import the styles once at your app root, and use a component:
 
 ```tsx
 import './ui/tokens.css'
+import './ui/base.css'
 import { Button } from './ui/components/Button'
 
 <Button onClick={save}>Save</Button>
@@ -30,12 +32,25 @@ import { Button } from './ui/components/Button'
 
 Using Next.js or React Router? The [installation guide](https://ui.hlmnhkl.my/installation) has the steps for each.
 
+| Command | What it does |
+| --- | --- |
+| `init` | Set a project up: `tokens.css`, `base.css` and `hlmnhkl-ui.json` |
+| `add <name>...` | Copy components, with what they import |
+| `list` | Show everything there is, free and Pro. `--kind blocks` filters |
+| `diff <name>...` | Show what changed between your copy and the latest version |
+| `update <name>...` | Show the changes, then replace your copy after you say yes |
+
 | Option | What it does |
 | --- | --- |
-| `--to <folder>` | Where the files go. Default: `src/ui` |
-| `--dry-run` | Print what would be copied, write nothing |
-| `--overwrite` | Replace files that are already there. Without it, they are skipped and listed |
-| `--with-base` | Also copy `base.css`, the small reset |
+| `--to <folder>` | Where the files go. Default: the folder in `hlmnhkl-ui.json`, else `src/ui` |
+| `--dry-run` | Print what would happen, write nothing |
+| `--overwrite` | `add`: replace files that are already there. Without it, they are skipped and listed |
+| `--with-base` | `add`: also copy `base.css` (`init` always does) |
+| `--yes` | `update`: replace without asking |
+
+Every copied file starts with one line naming hlmnhkl/ui and the MIT licence, so the licence notice travels with the code. `diff` and `update` ignore that line.
+
+**With an AI assistant:** point it at [llms.txt](https://ui.hlmnhkl.my/llms.txt) (every component and the rules) or [llms-full.txt](https://ui.hlmnhkl.my/llms-full.txt) (props, keyboard notes and an example for each free component). There is also a [registry.json](https://ui.hlmnhkl.my/registry.json).
 
 ## What you get
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlmnhkl-ui",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "React components in a monochrome style. Copy them into your app with npx hlmnhkl-ui add <name>.",
   "license": "MIT",
   "homepage": "https://ui.hlmnhkl.my",

package/scripts/add.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-// Copies components, blocks, templates and themes, and everything they import, into another project.
-// Runs as `npx hlmnhkl-ui add <name>` from the npm package, or `npm run add -- <name>` in this repo.
+// The hlmnhkl/ui command line: sets a project up, lists what exists, and copies components, blocks,
+// templates and themes (with everything they import) into it, then shows and takes later changes.
+// Runs as `npx hlmnhkl-ui <command>` from the npm package, or `npm run add -- <command>` in this repo.
 // Plain JavaScript on purpose: the project has no Node type package.
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
@@ -11,8 +13,25 @@ const SRC = join(ROOT, 'src')
 const INTERNAL = join(SRC, 'internal')
 const EXCLUDED = /(\.(test|spec|stories|demo)\.[jt]sx?$)|(^|\/)(docs|demos|__tests__)\//
 const DEFAULT_TO = 'src/ui'
-const USAGE = `Usage: npx hlmnhkl-ui add <name> [<name>...] [--to <folder>] [--overwrite] [--dry-run] [--with-base]
-  --to defaults to ${DEFAULT_TO}. In this repo, run: npm run add -- <name> --to <folder>`
+const CONFIG = 'hlmnhkl-ui.json'
+const SITE = 'https://ui.hlmnhkl.my'
+const COMMANDS = ['init', 'add', 'list', 'diff', 'update']
+const USAGE = `Usage: npx hlmnhkl-ui <command> [options]
+
+  init                     Set a project up: tokens.css, base.css and ${CONFIG}
+  add <name> [<name>...]   Copy components, blocks, templates or themes, with what they import
+  list [--kind <kind>]     Show everything there is (kind: components, blocks, templates, themes)
+  diff <name> [<name>...]  Show what changed between your copy and the latest version
+  update <name> [...]      Show the changes, then replace your copy after you say yes
+
+Options:
+  --to <folder>   Where files go. Defaults to the folder in ${CONFIG}, else ${DEFAULT_TO}
+  --overwrite     add: replace files that are already there
+  --with-base     add: also copy base.css (init always does)
+  --yes           update: replace without asking
+  --dry-run       Show what would happen, write nothing
+
+In this repo, run: npm run add -- <command> ...`
 
 // A theme is one CSS file; every other kind is a folder per name. Each kind keeps its folder name in the target.
 const KINDS = [
@@ -22,35 +41,41 @@ const KINDS = [
   { key: 'theme', plural: 'Themes', folder: 'themes', pro: true, single: true },
 ].map((k) => ({ ...k, dir: join(SRC, k.folder) }))
 
-function fail(message) {
+function fail(message, usage = true) {
   console.error(`Error: ${message}`)
-  console.error(USAGE)
+  if (usage) console.error(`\n${USAGE}`)
   process.exit(1)
 }
 
 function parseArgs(argv) {
-  const opts = { names: [], to: '', overwrite: false, dryRun: false, withBase: false }
+  const opts = { command: 'add', names: [], to: '', kind: '', overwrite: false, dryRun: false, withBase: false, yes: false }
+  const rest = []
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
-    if (arg === '--help' || arg === '-h') {
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
       console.log(USAGE)
-      console.log('A name can be a component (Button), a block (Dashboard), a template or a theme (forest).')
+      console.log('\nA name can be a component (Button), a block (Dashboard), a template or a theme (forest).')
       console.log('When two kinds share a name, add the kind: blocks/Settings, templates/Settings.')
       process.exit(0)
-    } else if (arg === '--to') {
-      opts.to = argv[++i] ?? ''
-      if (!opts.to || opts.to.startsWith('--')) fail('--to needs a folder, for example --to ../my-app/src/ui')
+    } else if (arg === '--to' || arg === '--kind') {
+      const value = argv[++i] ?? ''
+      if (!value || value.startsWith('--')) fail(arg === '--to' ? '--to needs a folder, for example --to src/ui' : '--kind needs a kind, for example --kind blocks')
+      opts[arg.slice(2)] = value
     } else if (arg.startsWith('--to=')) opts.to = arg.slice(5)
+    else if (arg.startsWith('--kind=')) opts.kind = arg.slice(7)
     else if (arg === '--overwrite') opts.overwrite = true
     else if (arg === '--dry-run') opts.dryRun = true
     else if (arg === '--with-base') opts.withBase = true
+    else if (arg === '--yes' || arg === '-y') opts.yes = true
     else if (arg.startsWith('-')) fail(`Unknown option ${arg}.`)
-    else opts.names.push(arg)
+    else rest.push(arg)
+  }
+  // The command comes first, like shadcn. A bare name still means add, as before.
+  if (COMMANDS.includes(rest[0])) opts.command = rest.shift()
+  opts.names = rest
+  if (['add', 'diff', 'update'].includes(opts.command) && !opts.names.length) {
+    fail(`Name at least one component, block, template or theme, for example: npx hlmnhkl-ui ${opts.command} button`)
   }
-  // `npx hlmnhkl-ui add button` passes "add" first, like shadcn.
-  if (opts.names[0] === 'add') opts.names.shift()
-  if (!opts.names.length) fail('Name at least one component, block, template or theme, for example button.')
-  if (!opts.to) opts.to = DEFAULT_TO
   return opts
 }
 
@@ -88,6 +113,7 @@ const rel = (p) => relative(SRC, p).split(sep).join('/')
 const kindOf = (key) => KINDS.find((k) => k.key === key)
 const keyOf = (item) => `${item.kind}:${item.name}`
 const label = (item) => (item.kind === 'component' ? item.name : `${item.name} (${item.kind})`)
+const kebab = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
 
 // Every name that can be copied, in every kind.
 function listItems() {
@@ -114,9 +140,9 @@ function lookup(raw, all) {
     fail(`"${raw}" is more than one thing: ${hits.map(label).join(', ')}. Add the kind, for example ${kindOf(hits[1].kind).folder}/${hits[1].name}.`)
   }
   const pro = proComponents().find((p) => p.toLowerCase() === name.toLowerCase())
-  if (pro) fail(`${pro} is in hlmnhkl/ui Pro, so it is not in this package. See https://ui.hlmnhkl.my/${raw.toLowerCase()}`)
+  if (pro) fail(`${pro} is in hlmnhkl/ui Pro, so it is not in this package. See ${SITE}/${raw.toLowerCase()}`, false)
   const close = suggest(name, all)
-  fail(`There is no component, block, template or theme called "${raw}".${close.length ? ` Did you mean ${close.join(', ')}?` : ''}`)
+  fail(`There is no component, block, template or theme called "${raw}".${close.length ? ` Did you mean ${close.join(', ')}?` : ''}`, false)
 }
 
 // Only in the public package: the names of Pro components, so asking for one gets a clear answer.
@@ -125,6 +151,19 @@ function proComponents() {
   return isFile(file) ? JSON.parse(readFileSync(file, 'utf8')) : []
 }
 
+// Only in this repo: the Pro component ids from src/docs/tiers.ts, so a Pro file gets the Pro credit line.
+let proIds
+function isPro(item) {
+  if (kindOf(item.kind).pro) return true
+  if (proIds === undefined) {
+    const tiers = join(SRC, 'docs', 'tiers.ts')
+    const src = isFile(tiers) ? readFileSync(tiers, 'utf8') : ''
+    const set = src.match(/proComponentIds = new Set\(\[([\s\S]*?)\]\)/)?.[1] ?? ''
+    proIds = new Set([...set.matchAll(/'([a-z0-9-]+)'/g)].map((m) => m[1]))
+  }
+  return proIds.has(kebab(item.name))
+}
+
 function listFiles(dir) {
   return readdirSync(dir, { withFileTypes: true }).flatMap((d) => {
     const p = join(dir, d.name)
@@ -151,7 +190,7 @@ function resolveImport(from, spec) {
   const base = resolve(dirname(from), spec)
   const tries = [base, `${base}.ts`, `${base}.tsx`, join(base, 'index.ts'), join(base, 'index.tsx')]
   const hit = tries.find(isFile)
-  if (!hit) fail(`${rel(from)} imports "${spec}", but no such file exists.`)
+  if (!hit) fail(`${rel(from)} imports "${spec}", but no such file exists.`, false)
   return hit
 }
 
@@ -163,7 +202,7 @@ function ownerOf(file) {
     if (k.single) return { kind: k.key, name: basename(file, '.css') }
     return { kind: k.key, name: relative(k.dir, file).split(sep)[0] }
   }
-  fail(`${rel(file)} is outside src/components, src/blocks, src/templates, src/themes and src/internal, so it cannot be copied.`)
+  fail(`${rel(file)} is outside src/components, src/blocks, src/templates, src/themes and src/internal, so it cannot be copied.`, false)
 }
 
 function plan(items) {
@@ -198,74 +237,236 @@ function plan(items) {
   for (let i = 0; i < seenInternal.length; i++) {
     for (const spec of importsOf(seenInternal[i])) {
       const target = resolveImport(seenInternal[i], spec)
-      if (ownerOf(target) !== null) fail(`${rel(seenInternal[i])} imports from outside src/internal, which internal files must not do.`)
+      if (ownerOf(target) !== null) fail(`${rel(seenInternal[i])} imports from outside src/internal, which internal files must not do.`, false)
       visitInternal(target)
     }
   }
   return { items: [...picked.values()], internal: [...internal].sort(), needs }
 }
 
-const opts = parseArgs(process.argv.slice(2))
-const all = listItems()
-const asked = opts.names.map((n) => lookup(n, all))
+// Every copied file starts with one credit line, so the MIT licence's notice travels with the code.
+// It is left out when comparing, so it never counts as a change.
+function credit(file, pro) {
+  const text = pro ? `hlmnhkl/ui Pro, see LICENSE-PRO.md. ${SITE}` : `hlmnhkl/ui, MIT licence. ${SITE}`
+  return file.endsWith('.css') ? `/* ${text} */\n` : `// ${text}\n`
+}
+const withoutCredit = (text) => text.replace(/^(\/\/ hlmnhkl\/ui[^\n]*|\/\* hlmnhkl\/ui[^\n]*\*\/)\n/, '')
 
-// npm runs scripts from the repo root; INIT_CWD is the folder the command was typed in.
-const to = resolve(process.env.INIT_CWD ?? process.cwd(), opts.to)
-if (existsSync(to) && !isDir(to)) fail(`--to points at a file, not a folder: ${opts.to}`)
+// The project folder (npm runs scripts from the repo root; INIT_CWD is where the command was typed).
+const CWD = process.env.INIT_CWD ?? process.cwd()
 
-const { items, internal, needs } = plan(asked)
+function readConfig() {
+  const file = join(CWD, CONFIG)
+  if (!isFile(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    fail(`${CONFIG} is not valid JSON. Fix it or delete it, then run the command again.`, false)
+  }
+}
 
-const copies = []
-for (const item of items) {
-  const k = kindOf(item.kind)
-  for (const file of filesOf(item)) copies.push({ from: file, to: join(to, k.folder, relative(k.dir, file)) })
+function targetFolder(opts) {
+  const folder = opts.to || readConfig()?.to || DEFAULT_TO
+  const to = resolve(CWD, folder)
+  if (existsSync(to) && !isDir(to)) fail(`--to points at a file, not a folder: ${folder}`, false)
+  return { folder, to }
+}
+
+// Every file a set of items needs, with where it goes and which credit it gets.
+function copiesFor(items, internal, to) {
+  const copies = []
+  for (const item of items) {
+    const k = kindOf(item.kind)
+    const pro = isPro(item)
+    for (const file of filesOf(item)) copies.push({ from: file, to: join(to, k.folder, relative(k.dir, file)), pro })
+  }
+  for (const file of internal) copies.push({ from: file, to: join(to, 'internal', relative(INTERNAL, file)), pro: false })
+  return copies
+}
+
+const fresh = (c) => credit(c.to, c.pro) + readFileSync(c.from, 'utf8')
+const state = (c) => (!existsSync(c.to) ? 'missing' : withoutCredit(readFileSync(c.to, 'utf8')) === readFileSync(c.from, 'utf8') ? 'same' : 'changed')
+
+function writeCopy(c, dryRun) {
+  if (dryRun) return
+  mkdirSync(dirname(c.to), { recursive: true })
+  writeFileSync(c.to, fresh(c))
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
+const shown = (to, file) => relative(to, file).split(sep).join('/')
+
+// The smallest set of changed lines, with two lines around each, like `git diff`.
+function lineDiff(oldText, newText) {
+  const a = oldText.split('\n')
+  const b = newText.split('\n')
+  const n = a.length
+  const m = b.length
+  const lcs = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1))
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1])
+  const ops = []
+  let i = 0
+  let j = 0
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) ops.push([' ', a[i++], j++])
+    else if (j < m && (i === n || lcs[i][j + 1] >= lcs[i + 1][j])) ops.push(['+', b[j++]])
+    else ops.push(['-', a[i++]])
+  }
+  const keep = ops.map((op, k) => op[0] !== ' ' || ops.slice(Math.max(0, k - 2), k + 3).some((o) => o[0] !== ' '))
+  const out = []
+  ops.forEach((op, k) => {
+    if (keep[k]) out.push(`${op[0]} ${op[1]}`)
+    else if (keep[k - 1]) out.push('  ...')
+  })
+  return out
+}
+
+// --- Commands -------------------------------------------------------------------------------------
+
+function runInit(opts) {
+  const { folder, to } = targetFolder(opts)
+  const sheets = ['tokens.css', 'base.css'].map((name) => ({ from: join(SRC, name), to: join(to, name), pro: false }))
+  console.log(`${opts.dryRun ? 'Dry run, nothing written. ' : ''}Setting up hlmnhkl/ui in ${folder}`)
+  for (const s of sheets) {
+    if (existsSync(s.to)) console.log(`  ${basename(s.to)}: already there, kept (your theme edits stay)`)
+    else {
+      writeCopy(s, opts.dryRun)
+      console.log(`  ${basename(s.to)}: added`)
+    }
+  }
+  const config = join(CWD, CONFIG)
+  if (isFile(config)) console.log(`  ${CONFIG}: already there, kept`)
+  else {
+    if (!opts.dryRun) writeFileSync(config, `${JSON.stringify({ to: folder }, null, 2)}\n`)
+    console.log(`  ${CONFIG}: added, so later commands put files in ${folder}`)
+  }
+  console.log(`\nNext:\n  1. Import both once at your app root, tokens first:\n       import './${folder.replace(/^\.\//, '')}/tokens.css'\n       import './${folder.replace(/^\.\//, '')}/base.css'`)
+  console.log(`  2. Add your first component: npx hlmnhkl-ui add button`)
+  console.log(`  See everything there is: npx hlmnhkl-ui list, or ${SITE}`)
 }
-for (const file of internal) copies.push({ from: file, to: join(to, 'internal', relative(INTERNAL, file)) })
-
-const sheets = [{ from: join(SRC, 'tokens.css'), to: join(to, 'tokens.css') }]
-if (opts.withBase) sheets.push({ from: join(SRC, 'base.css'), to: join(to, 'base.css') })
-
-const written = []
-const skipped = []
-const write = ({ from, to: dest }, allowOverwrite) => {
-  const shown = relative(to, dest).split(sep).join('/')
-  if (existsSync(dest) && !allowOverwrite) {
-    const same = readFileSync(dest).equals(readFileSync(from))
-    skipped.push(`${shown} (${same ? 'already there, same' : 'already there, different'})`)
-    return false
+
+function runList(opts) {
+  const all = listItems()
+  const wanted = opts.kind ? KINDS.find((k) => k.folder === opts.kind.toLowerCase() || k.key === opts.kind.toLowerCase()) : null
+  if (opts.kind && !wanted) fail(`"${opts.kind}" is not a kind. Use components, blocks, templates or themes.`)
+  for (const k of KINDS) {
+    if (wanted && wanted !== k) continue
+    const names = all.filter((i) => i.kind === k.key)
+    const free = names.filter((i) => !isPro(i)).map((i) => i.name)
+    const pro = [...names.filter((i) => isPro(i)).map((i) => i.name), ...(k.key === 'component' ? proComponents() : [])]
+    if (!free.length && !pro.length) continue
+    console.log(`${k.plural} (${free.length + pro.length})`)
+    if (free.length) console.log(`  ${free.join(', ')}`)
+    if (pro.length) console.log(`  Pro: ${pro.join(', ')}`)
   }
-  if (!opts.dryRun) {
-    mkdirSync(dirname(dest), { recursive: true })
-    copyFileSync(from, dest)
+  console.log(`\nAdd one: npx hlmnhkl-ui add <name>. Every page: ${SITE}`)
+}
+
+function runAdd(opts) {
+  const all = listItems()
+  const { to } = targetFolder(opts)
+  const { items, internal, needs } = plan(opts.names.map((n) => lookup(n, all)))
+  const copies = copiesFor(items, internal, to)
+  const sheets = [{ from: join(SRC, 'tokens.css'), to: join(to, 'tokens.css'), pro: false }]
+  if (opts.withBase) sheets.push({ from: join(SRC, 'base.css'), to: join(to, 'base.css'), pro: false })
+
+  const written = []
+  const skipped = []
+  const put = (c, allowOverwrite) => {
+    const s = state(c)
+    if (s !== 'missing' && !allowOverwrite) {
+      skipped.push(`${shown(to, c.to)} (already there, ${s === 'same' ? 'same' : 'different'})`)
+      return false
+    }
+    writeCopy(c, opts.dryRun)
+    written.push(shown(to, c.to))
+    return true
+  }
+  for (const c of copies) put(c, opts.overwrite)
+  // Stylesheets hold the app's own theme edits, so they are never replaced.
+  const tokensNew = put(sheets[0], false)
+  if (sheets[1]) put(sheets[1], false)
+
+  console.log(`${opts.dryRun ? 'Dry run, nothing written. ' : ''}Target: ${to}`)
+  console.log(`${opts.dryRun ? 'Would copy' : 'Copied'} ${plural(written.length, 'file')}.`)
+  for (const k of KINDS) {
+    const names = items.filter((i) => i.kind === k.key).map((i) => i.name)
+    if (names.length || k.key === 'component') console.log(`${k.plural}: ${names.length ? names.join(', ') : 'none'}`)
   }
-  written.push(shown)
-  return true
+  console.log(`Internal files: ${internal.length ? internal.map((f) => relative(INTERNAL, f)).join(', ') : 'none'}`)
+  if (needs.size) {
+    console.log('Dependencies:')
+    for (const { item, deps } of needs.values()) console.log(`  ${item.name} needs ${[...deps.values()].map(label).join(', ')}`)
+  }
+  if (items.some(isPro)) console.log('Pro: part of hlmnhkl/ui Pro.')
+  if (skipped.length) {
+    console.log(`Skipped ${plural(skipped.length, 'existing file')}${opts.overwrite ? '' : ' (see what differs with diff, take the new version with update)'}:`)
+    for (const s of skipped) console.log(`  ${s}`)
+    if (skipped.some((s) => /^(tokens|base)\.css /.test(s))) console.log('  tokens.css and base.css are never replaced, so your theme edits stay.')
+  }
+  if (tokensNew) console.log(`Next: import ${join(opts.to || readConfig()?.to || DEFAULT_TO, 'tokens.css')} once at your app root (or run init).`)
+  if (items.some((i) => i.kind === 'theme')) console.log('Themes: import each one after tokens.css, then set data-theme-brand or data-density on <html>.')
 }
 
-for (const c of copies) write(c, opts.overwrite)
-// Stylesheets hold the app's own theme edits, so they are never replaced.
-const tokensNew = write(sheets[0], false)
-if (sheets[1]) write(sheets[1], false)
-
-const verb = opts.dryRun ? 'Would copy' : 'Copied'
-console.log(`${opts.dryRun ? 'Dry run, nothing written. ' : ''}Target: ${to}`)
-console.log(`${verb} ${written.length} file${written.length === 1 ? '' : 's'}.`)
-for (const k of KINDS) {
-  const names = items.filter((i) => i.kind === k.key).map((i) => i.name)
-  if (names.length || k.key === 'component') console.log(`${k.plural}: ${names.length ? names.join(', ') : 'none'}`)
+// Compares the asked items (and what they import) with the copies in the project.
+function compare(opts) {
+  const all = listItems()
+  const { to } = targetFolder(opts)
+  const { items, internal } = plan(opts.names.map((n) => lookup(n, all)))
+  const copies = copiesFor(items, internal, to).map((c) => ({ ...c, state: state(c) }))
+  return { to, items, copies }
 }
-console.log(`Internal files: ${internal.length ? internal.map((f) => relative(INTERNAL, f)).join(', ') : 'none'}`)
-if (needs.size) {
-  console.log('Dependencies:')
-  for (const { item, deps } of needs.values()) console.log(`  ${item.name} needs ${[...deps.values()].map(label).join(', ')}`)
+
+function report(to, copies, withLines) {
+  const changed = copies.filter((c) => c.state === 'changed')
+  const missing = copies.filter((c) => c.state === 'missing')
+  for (const c of changed) {
+    console.log(`\nChanged: ${shown(to, c.to)}`)
+    if (withLines) for (const line of lineDiff(withoutCredit(readFileSync(c.to, 'utf8')), readFileSync(c.from, 'utf8'))) console.log(`  ${line}`)
+  }
+  for (const c of missing) console.log(`New: ${shown(to, c.to)}`)
+  const same = copies.length - changed.length - missing.length
+  console.log(`\n${plural(changed.length, 'file')} changed, ${missing.length} new, ${same} up to date.`)
+  if (withLines && changed.length) console.log('Lines with "-" are in your copy, lines with "+" are in the latest version.')
+  return changed.length + missing.length
 }
-if (items.some((i) => kindOf(i.kind).pro)) console.log('Pro: part of hlmnhkl/ui Pro.')
-if (skipped.length) {
-  console.log(`Skipped ${skipped.length} existing file${skipped.length === 1 ? '' : 's'}${opts.overwrite ? '' : ' (use --overwrite to replace them)'}:`)
-  for (const s of skipped) console.log(`  ${s}`)
-  if (skipped.some((s) => /^(tokens|base)\.css /.test(s))) console.log('  tokens.css and base.css are never replaced, so your theme edits stay.')
+
+function runDiff(opts) {
+  const { to, copies } = compare(opts)
+  const count = report(to, copies, true)
+  if (count) console.log(`Take the latest version: npx hlmnhkl-ui update ${opts.names.join(' ')}`)
 }
-if (tokensNew) console.log(`Next: import ${join(opts.to, 'tokens.css')} once at your app root.`)
-if (items.some((i) => i.kind === 'theme')) {
-  console.log('Themes: import each one after tokens.css, then set data-theme-brand or data-density on <html>.')
+
+async function runUpdate(opts) {
+  const { to, copies } = compare(opts)
+  const todo = copies.filter((c) => c.state !== 'same')
+  if (!todo.length) {
+    console.log(`Everything is up to date (${plural(copies.length, 'file')}).`)
+    return
+  }
+  report(to, copies, false)
+  if (opts.dryRun) {
+    console.log('Dry run, nothing written.')
+    return
+  }
+  if (!opts.yes) {
+    if (!process.stdin.isTTY) fail('update asks before replacing files. Run it in a terminal, or add --yes.', false)
+    console.log('Your own edits in the changed files will be replaced. See them first with diff.')
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const answer = (await rl.question(`Replace ${plural(todo.length, 'file')}? (y/N) `)).trim().toLowerCase()
+    rl.close()
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log('Nothing changed.')
+      return
+    }
+  }
+  for (const c of todo) writeCopy(c, false)
+  console.log(`Updated ${plural(todo.length, 'file')}.`)
 }
+
+const opts = parseArgs(process.argv.slice(2))
+if (opts.command === 'init') runInit(opts)
+else if (opts.command === 'list') runList(opts)
+else if (opts.command === 'diff') runDiff(opts)
+else if (opts.command === 'update') await runUpdate(opts)
+else runAdd(opts)

package/src/components/Toast/Toast.module.css

@@ -1,7 +1,9 @@
+/* The negative margin keeps the announcers from adding a pixel of scroll under the page. */
 .srOnly {
   position: absolute;
   width: 1px;
   height: 1px;
+  margin: -1px;
   overflow: hidden;
   clip-path: inset(50%);
   white-space: nowrap;