@brust/core 2.0.0-alpha.15 → 2.0.0-alpha.16

package/src/dev.ts

@@ -3,7 +3,8 @@
 // process: a failed build keeps the old wrangler, and module caches never leak between builds.
 import { join, relative, resolve } from 'node:path'
 import { BuildError } from './build/errors'
-import { defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
+import { loadBuildConfig } from './build/config'
+import { broadRootWarnings, defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
 
 export interface DevOptions {
   appRoot: string
@@ -65,8 +66,11 @@ export async function runDev(o: DevOptions): Promise<number> {
   }
 
   // The shared watch/build loop (dev/watch.ts): one rebuild at a time, edits during a rebuild are kept for the next.
+  const extraRoots = await loadBuildConfig(appRoot).then((c) => c.sourceRoots.map((r) => resolve(appRoot, r)), () => [] as string[])
+  for (const w of broadRootWarnings(extraRoots, appRoot)) o.log(w)
   const loop: WatchLoop = watchLoop({
     root: appRoot,
+    extraRoots,
     ignored: (rel) => defaultIgnored(rel, relative(appRoot, dist)),
     debounceMs: DEBOUNCE_MS,
     async run() {

package/src/shadcn/init.ts

@@ -2,9 +2,14 @@
 // shadcn's own `init` does not detect brust, so this writes what `add` needs (components.json, the `@/*` path),
 // installs the four packages the components import, and runs ONE pinned shadcn CLI for the theme and the components.
 // Every child process is spawned from an argv array, never through a shell; the runner is injected for tests.
-import { existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs'
-import { isAbsolute, join, relative, resolve } from 'node:path'
+import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { createMatchPath } from 'tsconfig-paths'
+import { configLoader } from 'tsconfig-paths/lib/config-loader'
+import { tsConfigLoader } from 'tsconfig-paths/lib/tsconfig-loader'
 import { type ObjectNode, raw, readObject } from './jsonc'
+import { fetchRegistryItem, vetItem } from './registry'
 
 /** The shadcn CLI version this command runs (R41.6). A release that moves it re-runs the transcript. */
 export const SHADCN_VERSION = '4.21.4'
@@ -35,6 +40,8 @@ export interface InitOptions {
   shadcnVersion?: string
   run: Runner
   out: (line: string) => void
+  /** F228: fetches the JSON of a registry URL item (default: `fetchRegistryItem`, https only); injected for tests. */
+  fetchItem?: (url: string) => Promise<string>
 }
 
 const COMPONENT = /^[a-z0-9][a-z0-9-]*$/
@@ -51,6 +58,185 @@ function isLink(path: string): boolean {
   }
 }
 
+/** True when `rel` (project-relative), or any directory on the way to it, is a symlink. */
+function linkUnder(root: string, rel: string): boolean {
+  let cur = root
+  for (const seg of rel.split('/').filter(Boolean)) {
+    cur = join(cur, seg)
+    if (isLink(cur)) return true
+  }
+  return false
+}
+
+type PathsMap = Record<string, string[]>
+
+function readJsonc(file: string): { text: string; top: ObjectNode } | { error: string } {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return { error: `cannot read ${file}` }
+  }
+  try {
+    return { text, top: readObject(text) }
+  } catch (e) {
+    return { error: `cannot parse ${file} (${(e as Error).message})` }
+  }
+}
+
+/** The `tsconfig-paths` version the pinned shadcn CLI resolves its aliases with (`shadcn@4.21.4` → `@shadcn/registry`
+ *  0.1.3 → `tsconfig-paths ^4.2.0`, read from its lockfile and source). It is a dependency of this package at exactly this
+ *  version, and it moves together with `SHADCN_VERSION`: a release that moves the CLI re-checks the resolver. */
+export const TSCONFIG_PATHS_VERSION = '4.2.0'
+
+/** What the shadcn CLI sees of the tsconfig: it calls `tsconfig-paths` `loadConfig(cwd)` and then
+ *  `createMatchPath(absoluteBaseUrl, paths)` for each alias. This asks the same code, so the `extends` rules (the paths
+ *  base is the directory of the TOP file, an inherited `baseUrl` is rebased by the extends specifier string, a package
+ *  config is looked up only at `<dir>/node_modules/<spec>`, an unresolved parent counts as empty) are its rules, not
+ *  TypeScript's (F226, Mellow's review). `inherited` is true when the `paths` come from a parent file. */
+interface TsInfo {
+  absoluteBaseUrl: string
+  /** Whether the chain sets a `baseUrl` (then a bare alias like `components/ui` is TypeScript-legal). */
+  hasBaseUrl: boolean
+  paths: PathsMap
+  inherited: boolean
+}
+
+/** Undefined when `tsconfig-paths` finds no config at all (the CLI then fails by itself before writing anything). An
+ *  error when it throws (a parent that is not JSON, a cycle, a non-string `extends`): the CLI would throw the same way. */
+function tsconfigInfo(root: string, file: string): TsInfo | { error: string } | undefined {
+  let cfg: ReturnType<typeof configLoader>
+  try {
+    // `loadConfig(root)` with `TS_NODE_PROJECT` / `TS_NODE_BASEURL` ignored: the spawned CLI does not get them either (F253)
+    cfg = configLoader({ cwd: root, tsConfigLoader: (p) => tsConfigLoader({ ...p, getEnv: () => undefined }) })
+  } catch (e) {
+    return { error: `the shadcn CLI cannot read the tsconfig chain of ${file} (${(e as Error).message})` }
+  }
+  if (cfg.resultType !== 'success') return undefined
+  const own = existsSync(file) ? readJsonc(file) : undefined
+  const ownPaths = own && !('error' in own) ? own.top.members.find((m) => m.key === 'compilerOptions')?.object?.members.some((m) => m.key === 'paths') : undefined
+  const paths: PathsMap = {}
+  for (const [k, v] of Object.entries(cfg.paths ?? {})) paths[k] = Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+  return { absoluteBaseUrl: cfg.absoluteBaseUrl, hasBaseUrl: cfg.baseUrl !== undefined, paths, inherited: !ownPaths && Object.keys(paths).length > 0 }
+}
+
+/** The path the CLI writes an alias to, the way it resolves one (`resolveAlias` in `@shadcn/registry`: `createMatchPath`
+ *  over the tsconfig, first candidate), as a project-relative path; or `{ error }` when it cannot be judged here:
+ *  a `#` import (package.json `imports`), nothing matches, or the result is outside the project. A package-shaped alias
+ *  (`@scope/name`) is refused (F251), and so is any alias that is not `@/...` or `~/...` (F261). */
+function resolveAlias(alias: string, root: string, ts: { absoluteBaseUrl: string; hasBaseUrl: boolean; paths: PathsMap }): { rel: string } | { why: string } {
+  if (alias.startsWith('#')) return { why: 'is a package.json "imports" alias, which cannot be checked here' }
+  // F251: the CLI tries npm workspace packages (a `workspaces` root above the project, a package named like the alias)
+  // BEFORE the tsconfig, and that route is not modelled here. A package-shaped alias (`@scope/name...`) could land there,
+  // so it is refused whether or not a `paths` entry names it; the default `@/...` aliases are not package-shaped.
+  if (/^@[^/]+\/[^/]+(?:\/.*)?$/.test(alias)) return { why: 'looks like a package name (`@scope/name`); the shadcn CLI tries npm workspace packages before the tsconfig "paths", which cannot be checked here. Use an alias like "@/components" or "~/components"' }
+  // F261: the same workspace route takes the FIRST path segment of ANY alias as a package name, before the tsconfig and
+  // whatever its `paths` say, so even an exact `paths` key like `ui` is written through a workspace package named `ui`.
+  // Only `@/...` and `~/...` cannot be a package name (`@/components` and `~` are not valid ones): all else is refused.
+  if (!alias.startsWith('@/') && !alias.startsWith('~/')) {
+    return { why: 'is not "@/..." or "~/..."; the shadcn CLI takes the first segment of any other alias for an npm workspace package name and tries workspace packages before the tsconfig "paths" (an exact "paths" key does not change that), which cannot be checked here. Rename the alias to "@/..." or "~/..."' }
+  }
+  const named = Object.keys(ts.paths).some((k) => (k.includes('*') ? alias.startsWith(k.slice(0, k.indexOf('*'))) && alias.endsWith(k.slice(k.indexOf('*') + 1)) && alias.length >= k.length - 1 : k === alias))
+  // `createMatchPath` maps any alias under the base directory (it adds a match-all); TypeScript does that only with a
+  // `baseUrl`. An alias no `paths` key names and no `baseUrl` covers is a misconfiguration: refused, not written to `./<alias>`.
+  if (!named && !ts.hasBaseUrl) return { why: 'does not resolve by the tsconfig "paths" (no entry names it and there is no "baseUrl")' }
+  let hit: string | undefined
+  try {
+    hit = createMatchPath(ts.absoluteBaseUrl, ts.paths)(alias, undefined, () => true, ['.ts', '.tsx', '.jsx', '.js', '.css'])
+  } catch (e) {
+    return { why: `cannot be resolved by tsconfig-paths (${(e as Error).message})` }
+  }
+  if (hit === undefined) return { why: 'does not resolve by the tsconfig "paths"' }
+  const rel = relative(root, resolve(hit))
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { why: `resolves to ${hit}, which is outside the project` }
+  return { rel: rel.split(sep).join('/') }
+}
+
+/** F193: every path the shadcn CLI may write, project-relative, or an error. The CLI follows symlinks, so the caller
+ *  refuses when one is, or sits under, a symlink. Fails closed: an alias that cannot be resolved by the tsconfig `paths`
+ *  (read through `extends`, F226; `@/*` → `./*` is assumed only when no `@/*` is there and none is inherited: it is what
+ *  this command adds) is an error, not a skipped check. */
+function cliTargets(
+  componentsText: string | undefined,
+  ts: TsInfo | undefined,
+  css: string | undefined,
+  components: string[],
+  opts: { root: string },
+): { paths: string[]; dirs: string[] } | { error: string } {
+  let aliases: Record<string, string> = { components: '@/components', utils: '@/lib/utils', ui: '@/components/ui', lib: '@/lib', hooks: '@/hooks' }
+  if (componentsText !== undefined) {
+    try {
+      const a = (JSON.parse(componentsText) as { aliases?: unknown }).aliases
+      if (a !== undefined) {
+        if (typeof a !== 'object' || a === null || Array.isArray(a)) return { error: 'components.json "aliases" is not an object' }
+        aliases = {}
+        for (const [k, v] of Object.entries(a)) {
+          if (typeof v !== 'string') return { error: `components.json alias ${JSON.stringify(k)} is not a string` }
+          aliases[k] = v
+        }
+      }
+    } catch {
+      return { error: 'components.json is not valid JSON, so the shadcn CLI target paths cannot be checked' }
+    }
+  }
+  const root = opts.root
+  // With no tsconfig the command adds `paths: { "@/*": ["./*"] }` to nothing (the CLI fails by itself). `@/*` → `./*` is the
+  // mapping this command adds when the tsconfig has no `@/*` of its own. When the `paths` are inherited through `extends`
+  // nothing is added (an own `paths` would replace them), so only what the chain says counts.
+  const resolver = { absoluteBaseUrl: ts?.absoluteBaseUrl ?? root, hasBaseUrl: ts?.hasBaseUrl ?? false, paths: { ...(ts?.paths ?? {}) } }
+  if (!ts?.inherited && resolver.paths['@/*'] === undefined) resolver.paths['@/*'] = ['./*']
+  const paths: string[] = []
+  const dirs: string[] = []
+  const roots: Record<string, string> = {}
+  for (const [k, v] of Object.entries(aliases)) {
+    const r = resolveAlias(v, root, resolver)
+    if ('why' in r) return { error: `alias ${JSON.stringify(k)} (${JSON.stringify(v)}) in components.json ${r.why}; the shadcn CLI target cannot be checked` }
+    const rel = r.rel
+    roots[k] = rel
+    if (k === 'utils') paths.push(rel, `${rel}.ts`)
+    else {
+      paths.push(rel)
+      dirs.push(rel)
+    }
+  }
+  const ui = roots.ui ?? 'components/ui'
+  return { paths: [...paths, 'package.json', ...(css === undefined ? [] : [css]), ...components.filter((c) => COMPONENT.test(c)).map((c) => `${ui}/${c}.tsx`)], dirs }
+}
+
+/** F227: the most entries `cliLink` looks at under the alias directories before it refuses (no fixed depth: a link at
+ *  any depth is found; a tree this big is not a components directory). */
+export const SCAN_LIMIT = 10_000
+
+/** Where a path or directory entry the CLI could write through is a symlink (`link`), or the directory walk hit its
+ *  entry bound (`tooMany`); undefined when clean. */
+function cliLink(root: string, t: { paths: string[]; dirs: string[] }): { link: string } | { tooMany: string } | undefined {
+  const hit = t.paths.find((p) => linkUnder(root, p))
+  if (hit !== undefined) return { link: hit }
+  // dependency files of a registry item (hooks, lib helpers) land in these directories: no entry may be a link
+  let seen = 0
+  const scan = (rel: string): { link: string } | { tooMany: string } | undefined => {
+    let names: string[]
+    try {
+      names = readdirSync(join(root, rel))
+    } catch {
+      return undefined // not a directory, or it does not exist yet (the CLI creates it): nothing to follow
+    }
+    for (const e of names) {
+      const sub = `${rel}/${e}`
+      if (++seen > SCAN_LIMIT) return { tooMany: rel }
+      if (isLink(join(root, sub))) return { link: sub }
+      const found = scan(sub)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+  for (const d of t.dirs) {
+    const found = scan(d)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
 /** The name a registry URL installs: its last path segment without `.json`; undefined when it is not a plain name. */
 function urlItemName(url: string): string | undefined {
   try {
@@ -83,6 +269,15 @@ export type PathEdit =
 
 const ENTRY = '"@/*": ["./*"]'
 
+/** F226: the `paths` come from an extended file, so the file is not edited (an own `paths` would replace them whole):
+ *  the inherited `@/*` is judged like an own one. */
+function inheritedEdit(root: string, ts: TsInfo): PathEdit {
+  const hit = ts.paths['@/*']
+  if (!hit) return { kind: 'unparseable', why: 'its "paths" are inherited through "extends" and have no "@/*"; an own "paths" would replace them' }
+  const r = resolveAlias('@/x', root, { absoluteBaseUrl: ts.absoluteBaseUrl, hasBaseUrl: ts.hasBaseUrl, paths: { '@/*': hit } })
+  return 'rel' in r && r.rel === 'x' ? { kind: 'present' } : { kind: 'other', target: JSON.stringify(hit) }
+}
+
 /** The separator before a non-empty object's first member, so the new entry takes the same line and indent. */
 function lead(text: string, o: ObjectNode): string {
   const first = o.members[0]
@@ -175,8 +370,57 @@ export async function shadcnInit(o: InitOptions): Promise<number> {
   // refuse before the first write, even with --force; the reader edits the real file by hand.
   const cj = join(root, 'components.json')
   const tsPath = join(root, 'tsconfig.json')
-  if (isLink(tsPath)) return fail2('tsconfig.json is a symbolic link; refusing to write through it. Add "@/*": ["./*"] to compilerOptions.paths of the real file yourself, then run again')
+  // F192: a symlinked tsconfig.json is only a problem when the command would edit it (the `@/*` path is missing).
+  // F226: the `paths` the CLI will see are the ones of the whole `extends` chain; a chain that cannot be read is refused.
+  const ts = tsconfigInfo(root, tsPath)
+  if (ts && 'error' in ts) return fail2(`${ts.error}; fix the tsconfig.json chain, then run again`)
+  const tsEdit = existsSync(tsPath) ? (ts?.inherited ? inheritedEdit(root, ts) : addAliasPath(readFileSync(tsPath, 'utf8'))) : undefined
+  if (isLink(tsPath) && tsEdit?.kind === 'added') return fail2('tsconfig.json is a symbolic link; refusing to write through it. Add "@/*": ["./*"] to compilerOptions.paths of the real file yourself, then run again')
   if (isLink(cj) && (!existsSync(cj) || o.force)) return fail2('components.json is a symbolic link; refusing to write through it. Replace it with a real file or remove the link, then run again')
+  // F193: the shadcn CLI writes files itself (the theme, `lib/utils.ts`, each component, the CSS entry). It follows
+  // links, so refuse before spawning it when one of its target paths is, or sits under, a symlink.
+  const writing = !existsSync(cj) || o.force
+  const themeRuns = o.force || !readFileSync(join(root, entry.css), 'utf8').includes('shadcn/tailwind.css')
+  const targets = cliTargets(
+    writing ? undefined : readFileSync(cj, 'utf8'),
+    ts,
+    themeRuns ? entry.css : undefined,
+    o.components,
+    { root },
+  )
+  if ('error' in targets) return fail2(targets.error)
+  const hit = cliLink(root, targets)
+  if (hit && 'link' in hit) return fail2(`${hit.link} is, or is inside, a symbolic link; the shadcn CLI would write through it. Replace the link with a real directory or file, then run again`)
+  if (hit) return fail2(`${hit.tooMany} holds more than ${SCAN_LIMIT} entries, so it cannot be checked for symbolic links before the shadcn CLI writes into it; point the alias at a smaller directory, then run again`)
+
+  // A component whose file is already in components/ui is not added again (idempotent). A registry URL is judged by
+  // the item name in its path (`.../acme-card.json` → `acme-card`), looked up in components/ui and components.
+  const present = (c: string): boolean => {
+    const name = REGISTRY_URL.test(c) ? urlItemName(c) : c
+    if (name === undefined) return false
+    return existsSync(join(root, 'components/ui', `${name}.tsx`)) || (name !== c && existsSync(join(root, 'components', `${name}.tsx`)))
+  }
+  const todo = o.components.filter((c) => o.force || !present(c))
+
+  // F228: a registry URL item declares its own file targets, known only once it is fetched. Fetch it now, before the CLI
+  // runs, and refuse when a target is outside the project or is, or sits under, a symlink. The CLI is then given the file
+  // checked here (not the URL), so the item cannot change between the check and the write.
+  const fetchItem = o.fetchItem ?? ((url: string) => fetchRegistryItem(url))
+  const vetted = new Map<string, string>()
+  for (const c of todo) {
+    if (!REGISTRY_URL.test(c) || vetted.has(c)) continue
+    let text: string
+    try {
+      text = await fetchItem(c)
+    } catch (e) {
+      return fail2(`registry item ${c} was not fetched (${(e as Error).message}), so its file targets cannot be checked; nothing was added`)
+    }
+    const v = vetItem(text, entry.css)
+    if ('error' in v) return fail2(`registry item ${c} ${v.error}; nothing was added`)
+    const bad = v.paths.find((p) => linkUnder(root, p))
+    if (bad !== undefined) return fail2(`registry item ${c} would write ${bad}, which is, or is inside, a symbolic link; the shadcn CLI would write through it. Replace the link with a real file or directory, then run again`)
+    vetted.set(c, text)
+  }
 
   const report = (name: string, step: Step, why = ''): void => out(`${step === 'done' ? '✓' : step === 'skipped' ? '-' : '✗'} ${name}: ${step}${why ? ` (${why})` : ''}`)
   const stop = (name: string, code: number): number => {
@@ -195,7 +439,7 @@ export async function shadcnInit(o: InitOptions): Promise<number> {
   if (!existsSync(tsPath)) {
     report('tsconfig.json', 'skipped', `no tsconfig.json; add ${JSON.stringify({ compilerOptions: { paths: { '@/*': ['./*'] } } })}`)
   } else {
-    const edit = addAliasPath(readFileSync(tsPath, 'utf8'))
+    const edit = tsEdit!
     if (edit.kind === 'added') {
       writeFileSync(tsPath, edit.text)
       report('tsconfig.json', 'done', 'added "@/*": ["./*"] under compilerOptions.paths')
@@ -224,19 +468,24 @@ export async function shadcnInit(o: InitOptions): Promise<number> {
     if (code !== 0) return stop('shadcn add index', code)
     report('theme', 'done', `shadcn@${version} add index`)
   }
-  // A component whose file is already in components/ui is not added again (idempotent). A registry URL is judged by
-  // the item name in its path (`.../acme-card.json` → `acme-card`), looked up in components/ui and components.
-  const present = (c: string): boolean => {
-    const name = REGISTRY_URL.test(c) ? urlItemName(c) : c
-    if (name === undefined) return false
-    return existsSync(join(root, 'components/ui', `${name}.tsx`)) || (name !== c && existsSync(join(root, 'components', `${name}.tsx`)))
-  }
-  const todo = o.components.filter((c) => o.force || !present(c))
   for (const c of o.components) if (!todo.includes(c)) report(c, 'skipped', REGISTRY_URL.test(c) ? 'its item is already in components; --force adds it again' : 'components/ui already has it')
-  for (const c of todo) if (REGISTRY_URL.test(c)) out(`warning shadcn-init ${c} is third-party code: it is written into your project and runs in your build and in the browser. Read it before you ship`)
+  for (const c of todo) if (REGISTRY_URL.test(c)) out(`warning shadcn-init ${c} is third-party code: it is written into your project and runs in your build and in the browser. Read it before you ship. Only the item itself was checked (its file paths, and that none is a symlink); the shadcn components it names in registryDependencies and the npm packages it lists in dependencies are installed by the CLI and were not`)
   if (todo.length > 0) {
-    const code = await o.run(shadcn('add', ...todo, '-y'), root)
-    if (code !== 0) return stop(`shadcn add ${todo.join(' ')}`, code)
+    // a URL item is added from the copy that was checked above
+    const dir = vetted.size > 0 ? mkdtempSync(join(tmpdir(), 'brust-shadcn-item-')) : undefined
+    try {
+      const args = todo.map((c, i) => {
+        const text = vetted.get(c)
+        if (text === undefined || dir === undefined) return c
+        const file = join(dir, `${urlItemName(c) ?? 'item'}-${i}.json`)
+        writeFileSync(file, text)
+        return file
+      })
+      const code = await o.run(shadcn('add', ...args, '-y'), root)
+      if (code !== 0) return stop(`shadcn add ${todo.join(' ')}`, code)
+    } finally {
+      if (dir !== undefined) rmSync(dir, { recursive: true, force: true })
+    }
     for (const c of todo) report(c, 'done')
   }
 
@@ -247,8 +496,18 @@ export async function shadcnInit(o: InitOptions): Promise<number> {
   return 0
 }
 
+/** F253: the variables that make `tsconfig-paths` (the resolver the shadcn CLI uses) read another tsconfig than the
+ *  project's. The pre-check ignores them and the spawned CLI does not get them, so both see the same file. */
+export const RESOLVER_ENV = ['TS_NODE_PROJECT', 'TS_NODE_BASEURL'] as const
+
+export function cliEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  const out = { ...env }
+  for (const k of RESOLVER_ENV) delete out[k]
+  return out
+}
+
 /** The real runner: argv spawn with the terminal attached, no shell. */
 export const spawnRunner: Runner = async (argv, cwd) => {
-  const p = Bun.spawn(argv, { cwd, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+  const p = Bun.spawn(argv, { cwd, env: cliEnv(process.env), stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
   return await p.exited
 }

package/src/shadcn/registry.ts

@@ -0,0 +1,149 @@
+// F228: a registry URL given to `brust shadcn init` names a third-party item that declares its own file targets, known
+// only once the item is fetched. This fetches the item JSON BEFORE the shadcn CLI is spawned (https only, a size cap, a
+// timeout, redirects followed by hand and only to https) and checks every path it can make the CLI write. The command
+// then hands the CLI the file it checked, not the URL, so the item cannot change between the check and the write.
+
+/** The most bytes of item JSON read; a bigger answer is refused. */
+export const ITEM_MAX_BYTES = 1024 * 1024
+/** The whole fetch (redirects included) gets this long. */
+export const ITEM_TIMEOUT_MS = 15_000
+/** Redirects followed by hand; each target must be https. */
+export const MAX_REDIRECTS = 3
+
+export interface FetchOptions {
+  /** URL schemes allowed for the request and every redirect. Default `https:` only; a test passes `http:` for a local server. */
+  schemes?: string[]
+  maxBytes?: number
+  timeoutMs?: number
+}
+
+/** Fetches `url` and returns the body text, or throws an `Error` whose message is the reason it was refused. */
+export async function fetchRegistryItem(url: string, o: FetchOptions = {}): Promise<string> {
+  const schemes = o.schemes ?? ['https:']
+  const maxBytes = o.maxBytes ?? ITEM_MAX_BYTES
+  const signal = AbortSignal.timeout(o.timeoutMs ?? ITEM_TIMEOUT_MS)
+  let cur = url
+  try {
+    for (let hop = 0; ; hop++) {
+      let u: URL
+      try {
+        u = new URL(cur)
+      } catch {
+        throw new Error(`${cur} is not a URL`)
+      }
+      if (!schemes.includes(u.protocol)) throw new Error(`${cur} is not an ${schemes.join(' or ').replace(/:/g, '')} URL`)
+      if (u.username !== '' || u.password !== '') throw new Error(`${u.origin}${u.pathname} carries credentials in the URL`)
+      const res = await fetch(u, { redirect: 'manual', signal, headers: { accept: 'application/json' } })
+      if (res.status >= 300 && res.status < 400) {
+        const next = res.headers.get('location')
+        await res.body?.cancel()
+        if (!next) throw new Error(`${cur} answered ${res.status} with no Location`)
+        if (hop >= MAX_REDIRECTS) throw new Error(`${url} redirects more than ${MAX_REDIRECTS} times`)
+        cur = new URL(next, u).toString() // the next loop turn refuses a non-https target
+        continue
+      }
+      if (!res.ok) {
+        await res.body?.cancel()
+        throw new Error(`${cur} answered HTTP ${res.status}`)
+      }
+      const declared = Number(res.headers.get('content-length'))
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel()
+        throw new Error(`${cur} is ${declared} bytes; the limit is ${maxBytes}`)
+      }
+      const reader = res.body?.getReader()
+      if (!reader) return ''
+      const chunks: Uint8Array[] = []
+      let size = 0
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.length
+        if (size > maxBytes) {
+          await reader.cancel()
+          throw new Error(`${cur} is bigger than the limit of ${maxBytes} bytes`)
+        }
+        chunks.push(value)
+      }
+      return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))
+    }
+  } catch (e) {
+    if (signal.aborted) throw new Error(`${url} did not answer within ${(o.timeoutMs ?? ITEM_TIMEOUT_MS) / 1000} s`)
+    throw e instanceof Error ? e : new Error(String(e))
+  }
+}
+
+/** True for a path that is not a plain relative path: absolute, a drive, a backslash, a NUL, a control character or `..`. */
+export function unsafeRel(p: string): boolean {
+  return p === '' || p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.includes('\\') || /[\x00-\x1f]/.test(p) || p.split('/').some((s) => s === '..') || (p.includes('%') && /%2e|%2f|%5c|%00/i.test(p))
+}
+
+export interface VettedItem {
+  /** Project-relative paths the CLI may write for this item, beyond the alias directories (checked for symlinks). */
+  paths: string[]
+}
+
+const PLAIN_NAME = /^[a-z0-9][a-z0-9-]*$/
+
+/** The top-level keys of an item in the pinned registry schema (`@shadcn/registry` 0.1.3). Allowlist, not denylist: a key
+ *  this does not name (`font`, which makes the CLI write the CSS entry and a layout file, or one a later schema adds) is a
+ *  refusal, because the CLI could write something this never judged. */
+const ITEM_KEYS = new Set(['$schema', 'extends', 'name', 'type', 'title', 'author', 'description', 'dependencies', 'devDependencies', 'registryDependencies', 'files', 'tailwind', 'cssVars', 'css', 'envVars', 'meta', 'docs', 'categories'])
+/** Item types whose files the CLI rewrites to a framework path (`registry:page`) or whose write set is not judged (`registry:font`). */
+const REFUSED_TYPES = new Set(['registry:font', 'registry:page'])
+
+/**
+ * Judges item JSON: the file targets it declares and the other things it makes the CLI write or fetch. Returns the
+ * paths to check for symlinks, or the reason it is refused. Fail closed: anything it cannot judge is a refusal.
+ */
+export function vetItem(text: string, cssEntry: string): VettedItem | { error: string } {
+  let item: unknown
+  try {
+    item = JSON.parse(text)
+  } catch {
+    return { error: 'is not valid JSON' }
+  }
+  if (typeof item !== 'object' || item === null || Array.isArray(item)) return { error: 'is not a JSON object' }
+  const o = item as Record<string, unknown>
+  if (o.type !== undefined && (typeof o.type !== 'string' || REFUSED_TYPES.has(o.type))) return { error: `is of type ${JSON.stringify(o.type)}, whose files the CLI places by rules this check does not model` }
+  const unknown = Object.keys(o).find((k) => !ITEM_KEYS.has(k))
+  if (unknown !== undefined) return { error: `has the key ${JSON.stringify(unknown)}, which this check does not know; it may make the CLI write files that cannot be checked` }
+  const paths: string[] = []
+  if (o.files !== undefined) {
+    if (!Array.isArray(o.files)) return { error: '"files" is not an array' }
+    for (const f of o.files) {
+      if (typeof f !== 'object' || f === null) return { error: 'has a file entry that is not an object' }
+      const { path, target } = f as { path?: unknown; target?: unknown }
+      if (path !== undefined && typeof path !== 'string') return { error: 'has a file with a "path" that is not a string' }
+      if (target !== undefined && typeof target !== 'string') return { error: 'has a file with a "target" that is not a string' }
+      if (typeof path === 'string' && unsafeRel(path)) return { error: `declares the file path ${JSON.stringify(path)}, which is not a plain path inside the project` }
+      if (typeof target === 'string' && target !== '') {
+        // The CLI's own rules (resolveFilePath): `~/x` is project-relative; `@components|ui|lib|hooks/x` is inside that alias
+        // directory (scanned already); any other target is joined to the project root, once as written and, in a `src/`
+        // project, under `src/` (it drops one `src/` from the target either way). All of them are checked.
+        const t = target.startsWith('~/') ? target.slice(2) : target
+        const alias = /^@(components|ui|lib|hooks)\/(.+)$/.exec(t)
+        if (alias) {
+          if (unsafeRel(alias[2]!)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+        } else {
+          const rel = t.replace(/^@([^/]+)\//, '$1/')
+          if (unsafeRel(rel)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+          const bare = rel.replace('src/', '')
+          paths.push(rel, bare, `src/${bare}`)
+        }
+      }
+    }
+  }
+  // what else the CLI writes: the Tailwind CSS entry (css, cssVars), env files (envVars)
+  if (o.css !== undefined || o.cssVars !== undefined || o.tailwind !== undefined) paths.push(cssEntry)
+  if (o.envVars !== undefined) paths.push('.env', '.env.local')
+  // dependencies on other items the CLI would fetch after this check (a `config` that would merge into components.json is an unknown key, refused above)
+  const deps = [...(Array.isArray(o.registryDependencies) ? o.registryDependencies : o.registryDependencies === undefined ? [] : [null]), ...(o.extends === undefined ? [] : [o.extends])]
+  for (const d of deps) {
+    if (typeof d !== 'string') return { error: 'has a registryDependencies / extends entry that is not a string' }
+    if (!PLAIN_NAME.test(d)) {
+      return { error: `depends on ${JSON.stringify(d)}, which the CLI would fetch after this check; pass that URL to the command as its own argument so it is checked too` }
+    }
+  }
+  return { paths }
+}