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

package/src/build/scan.ts

@@ -10,7 +10,9 @@ import { installServerOnlyRuntime } from './server-only'
 export async function scanRoutes(
   entryFile: string,
   appRoot?: string,
-): Promise<{ routes: Route[]; componentFile: Map<Function, string>; componentIssue: Map<Function, string> }> {
+  /** `[build] source_roots` (F256): app-root-relative directories outside the app; their modules are part of the graph (F276). */
+  sourceRoots: string[] = [],
+): Promise<{ routes: Route[]; componentFile: Map<Function, string>; componentIssue: Map<Function, string>; appModules: string[]; appGraph: Map<string, string[]> }> {
   // biome-ignore lint/suspicious/noExplicitAny: an arbitrary user module
   let mod: any
   installServerOnlyRuntime() // `server-only` resolves to an empty module: a loader may import server-only code
@@ -29,8 +31,13 @@ export async function scanRoutes(
   const componentIssue = new Map<Function, string>()
   const root = realpathSync(resolve(appRoot ?? dirname(entryFile)))
   const transpiler = new Bun.Transpiler({ loader: 'tsx' })
-  const inRoot = (f: string) => f.startsWith(root + sep) && !f.split(sep).includes('node_modules')
+  // F276: the app root and every `source_roots` directory: a module in `../shared` is as much part of the app as one in
+  // the root, so a load-time write it makes is seen by the F230 scan. Roots are real paths, as `f` is.
+  const scopes = [root, ...sourceRoots.map((r) => realpathSync(resolve(root, r)))]
+  const inRoot = (f: string) => scopes.some((s) => f.startsWith(s + sep)) && !f.split(sep).includes('node_modules')
   const visited = new Set<string>()
+  // F230: each in-root module's in-root static imports (absolute paths), for the island chunks' load-time writers.
+  const appGraph = new Map<string, string[]>()
   // Post-order: a file's imports are mapped before the file itself, and the first file to claim a function
   // keeps it, so the module that defines a Component beats a barrel that re-exports it.
   const visit = async (file: string): Promise<void> => {
@@ -58,6 +65,7 @@ export async function scanRoutes(
       if (inRoot(dep)) deps.push(dep)
       else if (dep.endsWith('.tsx')) await note(dep, dep.split(sep).includes('node_modules') ? 'in node_modules' : `outside the app root ${root}`)
     }
+    appGraph.set(file, deps)
     for (const dep of deps) await visit(dep)
     if (!file.endsWith('.tsx')) return
     const m = await import(file)
@@ -79,5 +87,7 @@ export async function scanRoutes(
   await visit(entryFile)
   // A function reachable as a default somewhere is fine; only an unmapped one keeps its explanation.
   for (const f of componentFile.keys()) componentIssue.delete(f)
-  return { routes, componentFile, componentIssue }
+  // F230: every app module of the static graph (`.ts`/`.tsx` inside the root, outside node_modules), for the scan of
+  // load-time writes into another module's exports (`scanLoadWrites`).
+  return { routes, componentFile, componentIssue, appModules: [...visited].filter(inRoot), appGraph }
 }

package/src/cli.ts

@@ -6,7 +6,6 @@ import { BuildError, runBuild } from './build'
 import { runBunDev } from './dev/bun'
 import { runDev } from './dev'
 import { run } from './run'
-import { shadcnInit, spawnRunner } from './shadcn/init'
 
 const USAGE = `usage:
   brust build [entry=routes.tsx] [--out-dir dist] [--force] [--target bun|cloudflare|static] [--actions-only] [--strict] [--wasm-from-source] [--dev]
@@ -135,6 +134,8 @@ export async function main(argv: string[]): Promise<void> {
   if (cmd === 'shadcn') {
     const [sub, ...components] = positionals
     if (sub !== 'init') usage(`shadcn takes a subcommand: init (got ${sub === undefined ? 'none' : JSON.stringify(sub)})`)
+    // F252: loaded here, so no other command pays for it (it pulls in tsconfig-paths)
+    const { shadcnInit, spawnRunner } = await import('./shadcn/init')
     const code = await shadcnInit({
       root: process.cwd(),
       components,

package/src/dev/bun.ts

@@ -10,7 +10,8 @@ import { type Diag, parseBuildError, parseWarnings } from './diag'
 import { tierCounts } from './devtools-data'
 import { type DevProxy, startProxy } from './proxy'
 import { HOTKEYS, Tui, type TuiOut, tuiMode } from './tui'
-import { defaultIgnored, watchLoop } from './watch'
+import { loadBuildConfig } from '../build/config'
+import { broadRootWarnings, defaultIgnored, watchLoop } from './watch'
 
 export interface BunDevOptions {
   appRoot: string
@@ -290,8 +291,12 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
 
   const isCss = (rel: string) => rel.startsWith('public/') && rel.endsWith('.css')
 
+  // F273: `[build] source_roots` are watched too (a bad config is the build's error to report, not the watcher's)
+  const extraRoots = await loadBuildConfig(appRoot).then((c) => c.sourceRoots.map((r) => resolve(appRoot, r)), () => [] as string[])
+  for (const w of broadRootWarnings(extraRoots, appRoot)) tui.log(w)
   const loop = watchLoop({
     root: appRoot,
+    extraRoots,
     ignored: (rel) => defaultIgnored(rel, 'dist'),
     debounceMs: DEBOUNCE_MS,
     async run(changed) {

package/src/dev/watch.ts

@@ -2,8 +2,8 @@
 // ONE run at a time, and every change that arrives while a run is in flight is kept for the next
 // run (post-mortem 8f29c26: an edit during a rebuild was dropped). `run` receives the app-relative
 // paths that changed since the previous run started.
-import { type FSWatcher, statSync, watch } from 'node:fs'
-import { join, sep } from 'node:path'
+import { type FSWatcher, readdirSync, statSync, watch } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
 
 export interface WatchLoop {
   /** Queue a run as if `rel` changed (the `r` hotkey, tests). */
@@ -14,7 +14,36 @@ export interface WatchLoop {
   idle(): Promise<void>
 }
 
-export function watchLoop(o: { root: string; ignored: (rel: string) => boolean; debounceMs: number; run: (changed: Set<string>) => Promise<void> }): WatchLoop {
+/** F273: a source root holding more files than this gets a warning (a root that broad slows every rebuild check). */
+export const ROOT_FILE_WARN = 5_000
+
+/** Files under `dir` (skipping dependency/VCS dirs), counting stops once past `limit`. */
+export function countFiles(dir: string, limit: number): number {
+  let n = 0
+  const walk = (d: string): void => {
+    let ents: import('node:fs').Dirent[]
+    try {
+      ents = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of ents) {
+      if (n > limit) return
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(join(d, e.name))
+      } else n++
+    }
+  }
+  walk(dir)
+  return n
+}
+
+/** Warning lines for source roots broader than `ROOT_FILE_WARN` files; `roots` are absolute. */
+export function broadRootWarnings(roots: string[], appRoot: string, limit = ROOT_FILE_WARN): string[] {
+  return roots.flatMap((r) => (countFiles(r, limit) > limit ? [`[brust] warning: source root ${relative(appRoot, r) || r} holds more than ${limit} files; watching it slows every change check. Point source_roots at a narrower directory`] : []))
+}
+
+export function watchLoop(o: { root: string; /** F273: `[build] source_roots`, absolute: watched too; their changes are reported app-relative (`../shared/x.ts`). */ extraRoots?: string[]; ignored: (rel: string) => boolean; debounceMs: number; run: (changed: Set<string>) => Promise<void> }): WatchLoop {
   let pending = new Set<string>()
   let timer: ReturnType<typeof setTimeout> | undefined
   let running = false
@@ -44,24 +73,36 @@ export function watchLoop(o: { root: string; ignored: (rel: string) => boolean;
     clearTimeout(timer)
     timer = setTimeout(() => void pump(), o.debounceMs)
   }
-  const watcher: FSWatcher = watch(o.root, { recursive: true }, (_ev, name) => {
+  const onEvent = (base: string) => (_ev: string, name: string | null) => {
     if (!name) return
-    const rel = String(name).split(sep).join('/')
+    const abs = join(base, String(name))
+    const rel = (base === o.root ? String(name) : relative(o.root, abs)).split(sep).join('/')
     if (o.ignored(rel)) return
     // A directory's own event is metadata noise (reading a dir bumps its atime, which FSEvents reports): a real
     // change inside it reports the file itself. A path that no longer exists is a delete, which counts.
     try {
-      if (statSync(join(o.root, rel)).isDirectory()) return
+      if (statSync(abs).isDirectory()) return
     } catch {}
     queue(rel)
-  })
+  }
+  const watchers: FSWatcher[] = [watch(o.root, { recursive: true }, onEvent(o.root))]
+  for (const r of o.extraRoots ?? []) {
+    const abs = resolve(r)
+    // a root inside the app is already watched; one that cannot be watched must not stop the session
+    if (abs === o.root || abs.startsWith(o.root + sep)) continue
+    try {
+      watchers.push(watch(abs, { recursive: true }, onEvent(abs)))
+    } catch (e) {
+      console.error(`[brust] cannot watch source root ${abs}: ${(e as Error).message}`)
+    }
+  }
   return {
     trigger: (rel = '.') => queue(rel),
     close() {
       closed = true
       clearTimeout(timer)
       pending.clear()
-      watcher.close()
+      for (const w of watchers) w.close()
       for (const w of idleWaiters.splice(0)) w()
     },
     idle: () => (!running && pending.size === 0 ? Promise.resolve() : new Promise<void>((r) => idleWaiters.push(r))),

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
 }