@hollis-labs/surface-ui 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +17 -2
  2. package/package.json +28 -4
  3. package/ui.mjs +423 -0
package/README.md CHANGED
@@ -1,3 +1,18 @@
1
- # Temporary Holding Version
1
+ # @hollis-labs/surface-ui
2
2
 
3
- 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.
3
+ The `ui` tool for apps built on the [Surface](https://github.com/hollis-labs/surface) registry. It copies
4
+ components into the app's source, records them in `ui.lock.json`, and fails when a copy differs from the
5
+ registry: a look is changed in the registry and synced, never edited in the app.
6
+
7
+ ```sh
8
+ npx surface-ui init --ref v0.1.0 # ui.lock.json naming the registry on GitHub at a tag
9
+ npx surface-ui add button dialog # install items and what they depend on
10
+ npx surface-ui add --for <package> # the items an installed package draws with
11
+ npx surface-ui sync # reinstall everything locked (after moving ref)
12
+ npx surface-ui verify # CI: an edited, stale, missing or stray file fails
13
+ npx surface-ui status
14
+ npx surface-ui report <app dir...> # drift across several apps
15
+ ```
16
+
17
+ Options: `--app <dir>` (default the current directory), `--registry <dir or URL template>`. The registry and
18
+ its rules are in the repository's `registry/README.md`.
package/package.json CHANGED
@@ -1,6 +1,30 @@
1
1
  {
2
2
  "name": "@hollis-labs/surface-ui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Keep an app's copied components identical to the Surface registry: init, add, sync, verify, status and a drift report across apps.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/hollis-labs/surface.git",
9
+ "directory": "packages/ui"
10
+ },
11
+ "homepage": "https://github.com/hollis-labs/surface/tree/main/registry#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/hollis-labs/surface/issues"
14
+ },
15
+ "publishConfig": {
16
+ "access": "public",
17
+ "registry": "https://registry.npmjs.org/"
18
+ },
19
+ "type": "module",
20
+ "bin": {
21
+ "surface-ui": "ui.mjs"
22
+ },
23
+ "files": [
24
+ "ui.mjs",
25
+ "README.md"
26
+ ],
27
+ "engines": {
28
+ "node": ">=20"
29
+ }
30
+ }
package/ui.mjs ADDED
@@ -0,0 +1,423 @@
1
+ #!/usr/bin/env node
2
+ import { execFileSync } from "node:child_process"
3
+ // surface ui: keep an app's copied components identical to the @surface registry.
4
+ //
5
+ // Components are installed into an app's own source, where its build sees them and an agent
6
+ // can read them. They are not edited there. This tool installs them, records what it
7
+ // installed in ui.lock.json, and fails when a file differs from what the registry holds:
8
+ // a change is made in the registry, then synced.
9
+ //
10
+ // In this repository it is `node scripts/ui.mjs`; in an app, `npx @hollis-labs/surface-ui` (bin surface-ui).
11
+ //
12
+ // node scripts/ui.mjs init [--ref <tag>] [--dir <components dir>]
13
+ // write ui.lock.json naming the registry on GitHub at a tag
14
+ // node scripts/ui.mjs build registry maintainers: regenerate registry.json and registry/r
15
+ // node scripts/ui.mjs add <item...> install items (and what they depend on) into the app
16
+ // node scripts/ui.mjs add --all install every item the registry has
17
+ // node scripts/ui.mjs add --for <package>
18
+ // install the items an installed package draws with
19
+ // (@hollis-labs/surface-page lists its own)
20
+ // node scripts/ui.mjs sync reinstall every locked item from the registry
21
+ // node scripts/ui.mjs verify exit 1 if any installed file differs from the lock or the registry
22
+ // node scripts/ui.mjs status what is installed, from where
23
+ // node scripts/ui.mjs report <app dir...> [--from <file>] [--json]
24
+ // each app's registry, item count and drift: items missing,
25
+ // edited in place or behind the registry (--registry to compare
26
+ // every app with one registry). --from names a file listing app
27
+ // dirs, one per line (# starts a comment).
28
+ //
29
+ // Options: --app <dir> (default: the current directory), --registry <dir or URL template>.
30
+ // The lock names the registry: a directory holding <name>.json files, or a URL with {name}
31
+ // (and optionally {ref}), for example
32
+ // https://raw.githubusercontent.com/hollis-labs/surface/{ref}/registry/r/{name}.json
33
+ import { createHash } from "node:crypto"
34
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
35
+ import { createRequire } from "node:module"
36
+ import { basename, dirname, join, relative, resolve } from "node:path"
37
+
38
+ const args = process.argv.slice(2)
39
+ const cmd = args.shift()
40
+ const opt = (name) => {
41
+ const i = args.indexOf(`--${name}`)
42
+ if (i < 0) return undefined
43
+ const v = args[i + 1]
44
+ args.splice(i, 2)
45
+ return v
46
+ }
47
+ const appDir = resolve(opt("app") ?? ".")
48
+ const forPackage = opt("for")
49
+ const initRef = opt("ref")
50
+ const initDir = opt("dir")
51
+ const GITHUB_REGISTRY = "https://raw.githubusercontent.com/hollis-labs/surface/{ref}/registry/r/{name}.json"
52
+ const registryOverride = opt("registry")
53
+ const lockPath = join(appDir, "ui.lock.json")
54
+ const sha = (text) => createHash("sha256").update(text).digest("hex")
55
+ const fail = (msg) => {
56
+ console.error(`surface ui: ${msg}`)
57
+ process.exit(1)
58
+ }
59
+ const bare = (name) => name.replace(/^@surface\//, "")
60
+ // How this tool was started, for the commands its messages suggest.
61
+ const SELF = /scripts[\\/]ui\.mjs$/.test(process.argv[1] ?? "") ? "node scripts/ui.mjs" : "npx surface-ui"
62
+ const wantAll = (() => {
63
+ const i = args.indexOf("--all")
64
+ if (i < 0) return false
65
+ args.splice(i, 1)
66
+ return true
67
+ })()
68
+
69
+ function readLock() {
70
+ if (!existsSync(lockPath)) {
71
+ fail(`no ui.lock.json in ${appDir}. Create one with {"registry": "...", "uiDir": "src/components/ui", "items": {}}`)
72
+ }
73
+ const lock = JSON.parse(readFileSync(lockPath, "utf8"))
74
+ if (registryOverride) lock.registry = registryOverride
75
+ if (!lock.registry || !lock.uiDir) fail("ui.lock.json needs registry and uiDir")
76
+ lock.items ??= {}
77
+ return lock
78
+ }
79
+
80
+ function writeLock(lock) {
81
+ const items = Object.fromEntries(Object.entries(lock.items).sort(([a], [b]) => a.localeCompare(b)))
82
+ writeFileSync(lockPath, `${JSON.stringify({ ...lock, items }, null, 2)}\n`)
83
+ }
84
+
85
+ /** One registry item, from a directory or a URL template. */
86
+ async function fetchItem(lock, name, { base = appDir, soft = false } = {}) {
87
+ const src = lock.registry
88
+ if (/^https?:\/\//.test(src)) {
89
+ const url = src.replace("{name}", name).replace("{ref}", lock.ref ?? "main")
90
+ const res = await fetch(url)
91
+ if (!res.ok) {
92
+ if (soft && res.status === 404) return null
93
+ fail(`${url}: ${res.status} ${res.statusText}`)
94
+ }
95
+ return res.json()
96
+ }
97
+ const file = join(resolve(base, src), `${name}.json`)
98
+ if (!existsSync(file)) {
99
+ if (soft) return null
100
+ fail(`the registry at ${src} has no item "${name}"`)
101
+ }
102
+ return JSON.parse(readFileSync(file, "utf8"))
103
+ }
104
+
105
+ /** The named items and everything they depend on in the registry, dependencies first. */
106
+ async function closure(lock, names) {
107
+ const seen = new Map()
108
+ const visit = async (raw) => {
109
+ const name = bare(raw)
110
+ if (seen.has(name)) return
111
+ const item = await fetchItem(lock, name)
112
+ seen.set(name, null) // reserved: a cycle stops here
113
+ for (const dep of item.registryDependencies ?? []) await visit(dep)
114
+ seen.delete(name)
115
+ seen.set(name, item)
116
+ }
117
+ for (const n of names) await visit(n)
118
+ return seen
119
+ }
120
+
121
+ // Components go in uiDir; the theme (a registry:file) beside it, or in themeDir when the lock names one.
122
+ const targetOf = (lock, file) =>
123
+ join(file.type === "registry:file" ? (lock.themeDir ?? dirname(lock.uiDir)) : lock.uiDir, basename(file.path))
124
+
125
+ async function install(lock, names) {
126
+ const items = await closure(lock, names)
127
+ const npm = new Set()
128
+ for (const [name, item] of items) {
129
+ const files = {}
130
+ for (const f of item.files ?? []) {
131
+ const rel = targetOf(lock, f)
132
+ const abs = join(appDir, rel)
133
+ mkdirSync(dirname(abs), { recursive: true })
134
+ writeFileSync(abs, f.content)
135
+ files[rel] = sha(f.content)
136
+ }
137
+ lock.items[name] = { files }
138
+ for (const d of item.dependencies ?? []) npm.add(d)
139
+ }
140
+ writeLock(lock)
141
+ console.log(`installed ${[...items.keys()].join(", ")}`)
142
+ // The app must have the packages the components import.
143
+ const pkgPath = join(appDir, "package.json")
144
+ if (existsSync(pkgPath)) {
145
+ const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
146
+ const have = { ...pkg.dependencies, ...pkg.devDependencies }
147
+ const missing = [...npm].filter((d) => !have[d.replace(/(?<=.)@[^/]+$/, "")])
148
+ if (missing.length)
149
+ console.log(
150
+ `these packages are needed and not in package.json (at the versions this registry was built with):\n npm install --save-exact ${missing.join(" ")}`,
151
+ )
152
+ }
153
+ }
154
+
155
+ async function verify(lock) {
156
+ const problems = []
157
+ const locked = new Set()
158
+ for (const [name, entry] of Object.entries(lock.items)) {
159
+ const item = await fetchItem(lock, name)
160
+ const want = new Map((item.files ?? []).map((f) => [targetOf(lock, f), sha(f.content)]))
161
+ for (const [rel, hash] of Object.entries(entry.files)) {
162
+ locked.add(rel)
163
+ const abs = join(appDir, rel)
164
+ if (!existsSync(abs)) problems.push(`${rel}: missing (item ${name})`)
165
+ else if (sha(readFileSync(abs, "utf8")) !== hash)
166
+ problems.push(`${rel}: edited in place. Change it in the registry, then run "${SELF} sync"`)
167
+ else if (want.get(rel) !== hash) problems.push(`${rel}: behind the registry (item ${name}). Run "${SELF} sync"`)
168
+ }
169
+ for (const rel of want.keys())
170
+ if (!entry.files[rel])
171
+ problems.push(`${rel}: the registry's ${name} has a file the app lacks. Run "${SELF} sync"`)
172
+ }
173
+ // Nothing lives beside the copied components that the registry did not put there.
174
+ const dir = join(appDir, lock.uiDir)
175
+ if (existsSync(dir)) {
176
+ for (const f of readdirSync(dir)) {
177
+ const rel = join(lock.uiDir, f)
178
+ if (!locked.has(rel))
179
+ problems.push(`${rel}: not from the registry. Shared components come from @surface; an app's own go elsewhere`)
180
+ }
181
+ }
182
+ if (problems.length) {
183
+ console.error(`surface ui: ${problems.length} problem(s)\n ${problems.join("\n ")}`)
184
+ process.exit(1)
185
+ }
186
+ console.log(`surface ui: ${locked.size} file(s) in ${Object.keys(lock.items).length} item(s) match the registry`)
187
+ }
188
+
189
+ /**
190
+ * One app's drift against its registry (or the one given with --registry): for each locked
191
+ * item, whether a file is missing, edited in place, or behind the registry; files the
192
+ * registry has that the app lacks; and files in the components directory nothing put there.
193
+ */
194
+ async function inspect(dir) {
195
+ const lockFile = join(dir, "ui.lock.json")
196
+ if (!existsSync(lockFile)) return { dir, error: "no ui.lock.json" }
197
+ const lock = JSON.parse(readFileSync(lockFile, "utf8"))
198
+ lock.items ??= {}
199
+ // A registry given on the command line is read from where the command runs.
200
+ const base = registryOverride ? process.cwd() : dir
201
+ if (registryOverride) lock.registry = registryOverride
202
+ let app = basename(resolve(dir))
203
+ try {
204
+ app = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name ?? app
205
+ } catch {
206
+ // No package.json: the directory's name will do.
207
+ }
208
+ if (!/^https?:\/\//.test(lock.registry ?? "") && !existsSync(resolve(base, lock.registry ?? ""))) {
209
+ return { app, dir, error: `its registry ${lock.registry} is not there (give one with --registry)` }
210
+ }
211
+ const drift = []
212
+ const locked = new Set()
213
+ for (const [name, entry] of Object.entries(lock.items)) {
214
+ const item = await fetchItem(lock, name, { base, soft: true })
215
+ if (!item) {
216
+ for (const rel of Object.keys(entry.files ?? {})) locked.add(rel)
217
+ drift.push({ item: name, kind: "unknown", detail: "the registry has no such item" })
218
+ continue
219
+ }
220
+ const want = new Map((item.files ?? []).map((f) => [targetOf(lock, f), sha(f.content)]))
221
+ for (const [rel, hash] of Object.entries(entry.files ?? {})) {
222
+ locked.add(rel)
223
+ const abs = join(dir, rel)
224
+ if (!existsSync(abs)) drift.push({ item: name, file: rel, kind: "missing" })
225
+ else if (sha(readFileSync(abs, "utf8")) !== hash) drift.push({ item: name, file: rel, kind: "edited" })
226
+ else if (want.get(rel) !== hash) drift.push({ item: name, file: rel, kind: "behind" })
227
+ }
228
+ for (const rel of want.keys())
229
+ if (!entry.files?.[rel]) drift.push({ item: name, file: rel, kind: "behind", detail: "a file the app lacks" })
230
+ }
231
+ const ui = join(dir, lock.uiDir ?? "")
232
+ if (lock.uiDir && existsSync(ui)) {
233
+ for (const f of readdirSync(ui)) {
234
+ const rel = join(lock.uiDir, f)
235
+ if (!locked.has(rel)) drift.push({ item: "", file: rel, kind: "stray" })
236
+ }
237
+ }
238
+ return { app, dir, registry: lock.registry, ref: lock.ref ?? null, items: Object.keys(lock.items).length, drift }
239
+ }
240
+
241
+ const WORDS = {
242
+ missing: "missing",
243
+ edited: "edited in place",
244
+ behind: "behind the registry",
245
+ unknown: "not in the registry",
246
+ stray: "not from the registry",
247
+ }
248
+
249
+ async function report(dirs, asJson) {
250
+ const out = []
251
+ for (const d of dirs) out.push(await inspect(resolve(d)))
252
+ if (asJson) {
253
+ console.log(JSON.stringify(out, null, 2))
254
+ return
255
+ }
256
+ for (const r of out) {
257
+ if (r.error) {
258
+ console.log(`${r.app ?? r.dir} (${r.dir}): ${r.error}`)
259
+ continue
260
+ }
261
+ const rel = relative(process.cwd(), r.dir)
262
+ const where = rel.startsWith("..") ? r.dir : rel || "."
263
+ const state = r.drift.length ? `${r.drift.length} drifting` : "in step"
264
+ console.log(`${r.app} (${where}): ${r.registry}${r.ref ? ` @ ${r.ref}` : ""} · ${r.items} items · ${state}`)
265
+ for (const x of r.drift) {
266
+ const what = [x.item, x.file].filter(Boolean).join(": ")
267
+ console.log(` ${what}: ${WORDS[x.kind] ?? x.kind}${x.detail ? ` (${x.detail})` : ""}`)
268
+ }
269
+ }
270
+ }
271
+
272
+ /** Registry maintainers: derive registry.json from the sources, then let shadcn build the item files. */
273
+ function build() {
274
+ const root = resolve(appDir, "registry")
275
+ const uiDir = join(root, "ui")
276
+ const meta = existsSync(join(root, "items.json")) ? JSON.parse(readFileSync(join(root, "items.json"), "utf8")) : {}
277
+ // Every package an item imports is named at the version this repository has installed, so
278
+ // an app outside it installs the same one instead of guessing.
279
+ const lockFile = join(appDir, "package-lock.json")
280
+ const locked = existsSync(lockFile) ? (JSON.parse(readFileSync(lockFile, "utf8")).packages ?? {}) : {}
281
+ const versioned = (pkg, pin) => {
282
+ const version = pin ?? locked[`node_modules/${pkg}`]?.version
283
+ return version ? `${pkg}@${version}` : pkg
284
+ }
285
+ const items = []
286
+ for (const f of readdirSync(uiDir)
287
+ .filter((x) => x.endsWith(".tsx"))
288
+ .sort()) {
289
+ const name = f.replace(/\.tsx$/, "")
290
+ const text = readFileSync(join(uiDir, f), "utf8")
291
+ const npm = new Set()
292
+ const deps = new Set()
293
+ // Both `import x from "spec"` and a bare `import "spec"` (a stylesheet) count.
294
+ for (const m of text.matchAll(/(?:from|^import)\s+"([^"]+)"/gm)) {
295
+ const spec = m[1]
296
+ if (spec.startsWith("@/components/ui/")) deps.add(`@surface/${spec.slice("@/components/ui/".length)}`)
297
+ else if (!spec.startsWith(".") && !spec.startsWith("@/") && spec !== "react" && spec !== "react-dom") {
298
+ const pkg = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0]
299
+ // A package the item needs at one exact version says so in items.json ("pins").
300
+ npm.add(versioned(pkg, meta[name]?.pins?.[pkg]))
301
+ }
302
+ }
303
+ // An item is its .tsx and any file beside it of the same name (its stylesheet).
304
+ const beside = readdirSync(uiDir)
305
+ .filter((x) => x.startsWith(`${name}.`) && x !== f)
306
+ .sort()
307
+ items.push({
308
+ name,
309
+ type: "registry:ui",
310
+ title: meta[name]?.title ?? name.replace(/(^|-)(\w)/g, (_, d, c) => (d ? " " : "") + c.toUpperCase()),
311
+ ...(meta[name]?.description ? { description: meta[name].description } : {}),
312
+ ...(npm.size ? { dependencies: [...npm].sort() } : {}),
313
+ ...(deps.size ? { registryDependencies: [...deps].sort() } : {}),
314
+ files: [f, ...beside].map((x) => ({ path: `registry/ui/${x}`, type: "registry:ui" })),
315
+ })
316
+ }
317
+ // The theme is one item too, so an app outside this repository installs it at the same ref.
318
+ const themeDir = join(root, "theme")
319
+ for (const f of existsSync(themeDir) ? readdirSync(themeDir).filter((x) => x.endsWith(".css")) : []) {
320
+ const text = readFileSync(join(themeDir, f), "utf8")
321
+ const npm = new Set()
322
+ for (const m of text.matchAll(/^@import\s+"([^".][^"]*)"/gm)) {
323
+ if (m[1] !== "tailwindcss")
324
+ npm.add(versioned(m[1].startsWith("@") ? m[1].split("/").slice(0, 2).join("/") : m[1].split("/")[0]))
325
+ }
326
+ const name = f === "surface.css" ? "theme" : `theme-${f.replace(/\.css$/, "")}`
327
+ items.push({
328
+ name,
329
+ type: "registry:file",
330
+ title: meta[name]?.title ?? "Theme",
331
+ ...(meta[name]?.description ? { description: meta[name].description } : {}),
332
+ ...(npm.size ? { dependencies: [...npm].sort() } : {}),
333
+ files: [{ path: `registry/theme/${f}`, type: "registry:file", target: `src/${f}` }],
334
+ })
335
+ }
336
+ const registry = {
337
+ $schema: "https://ui.shadcn.com/schema/registry.json",
338
+ name: "surface",
339
+ homepage: "https://github.com/hollis-labs/surface",
340
+ items,
341
+ }
342
+ writeFileSync(join(root, "registry.json"), `${JSON.stringify(registry, null, 2)}\n`)
343
+ execFileSync("npx", ["shadcn", "build", "registry/registry.json", "-o", "registry/r"], {
344
+ cwd: appDir,
345
+ stdio: "inherit",
346
+ })
347
+ console.log(`built ${items.length} items into ${relative(appDir, join(root, "r"))}`)
348
+ }
349
+
350
+ /** The registry items an installed package says it draws with ("surface": {"registryItems": file}). */
351
+ function itemsFor(pkg) {
352
+ let manifest
353
+ try {
354
+ manifest = createRequire(join(appDir, "package.json")).resolve(`${pkg}/package.json`)
355
+ } catch {
356
+ fail(`${pkg} is not installed in ${appDir} (npm install it first)`)
357
+ }
358
+ const meta = JSON.parse(readFileSync(manifest, "utf8"))
359
+ const list = meta.surface?.registryItems
360
+ if (!list) fail(`${pkg} does not list the registry items it uses`)
361
+ return JSON.parse(readFileSync(join(dirname(manifest), list), "utf8"))
362
+ }
363
+
364
+ switch (cmd) {
365
+ case "init": {
366
+ if (existsSync(lockPath)) fail(`${lockPath} exists already`)
367
+ const lock = {
368
+ registry: registryOverride ?? GITHUB_REGISTRY,
369
+ ...(registryOverride ? {} : { ref: initRef ?? "main" }),
370
+ uiDir: initDir ?? "src/components/ui",
371
+ items: {},
372
+ }
373
+ writeLock(lock)
374
+ console.log(
375
+ `wrote ${relative(process.cwd(), lockPath) || lockPath}: ${lock.registry}${lock.ref ? ` @ ${lock.ref}` : ""}, components in ${lock.uiDir}`,
376
+ )
377
+ break
378
+ }
379
+ case "build":
380
+ build()
381
+ break
382
+ case "add": {
383
+ const lock = readLock()
384
+ // --all: every item the registry has, at the lock's ref (its index is the item "registry").
385
+ const all = wantAll ? ((await fetchItem(lock, "registry")).items ?? []).map((i) => i.name) : []
386
+ const names = [...args, ...(forPackage ? itemsFor(forPackage) : []), ...all]
387
+ if (!names.length) fail("add needs at least one item name (or --for <package>, or --all)")
388
+ await install(lock, names)
389
+ break
390
+ }
391
+ case "sync": {
392
+ const lock = readLock()
393
+ await install(lock, Object.keys(lock.items))
394
+ break
395
+ }
396
+ case "verify":
397
+ await verify(readLock())
398
+ break
399
+ case "report": {
400
+ const asJson = args.includes("--json")
401
+ const from = opt("from")
402
+ const dirs = args.filter((a) => a !== "--json")
403
+ if (from) {
404
+ for (const line of readFileSync(from, "utf8").split("\n")) {
405
+ const d = line.replace(/#.*/, "").trim()
406
+ if (d) dirs.push(resolve(dirname(resolve(from)), d))
407
+ }
408
+ }
409
+ if (!dirs.length) dirs.push(appDir)
410
+ await report(dirs, asJson)
411
+ break
412
+ }
413
+ case "status": {
414
+ const lock = readLock()
415
+ console.log(`registry: ${lock.registry}${lock.ref ? ` @ ${lock.ref}` : ""}\ninstalled into: ${lock.uiDir}`)
416
+ for (const [name, e] of Object.entries(lock.items)) console.log(` ${name} (${Object.keys(e.files).length} file)`)
417
+ break
418
+ }
419
+ default:
420
+ fail(
421
+ "usage: ui.mjs init [--ref <tag>] [--dir <dir>] | build | add <item...> [--for <package>] [--all] | sync | verify | status | report <app dir...> [--from <file>] [--json] [--app <dir>] [--registry <dir or URL>]",
422
+ )
423
+ }