@sanity/ui 4.2.0 → 5.0.0-alpha.10

package/src/cli/detect.ts

@@ -0,0 +1,205 @@
+import {existsSync, readFileSync} from 'node:fs'
+import {join} from 'node:path'
+
+import type {
+  Detected,
+  EntryInfo,
+  Framework,
+  PackageJson,
+  PackageManager,
+  ReactInfo,
+} from './types.js'
+import {parseVersion} from './versions.js'
+
+export const PACKAGE_NAME = '@sanity/ui'
+
+export const LEGACY_COEXISTENCE_HINT =
+  'To add v5 alongside an existing @sanity/ui install, use a package alias — see the README section "For apps using Sanity UI v3".'
+
+/**
+ * Framework ids map 1:1 to the `framework` field written into sanity-ui.json.
+ * Each carries the ordered list of candidate entry files where the stylesheet
+ * import belongs.
+ */
+const FRAMEWORK_ENTRIES: Record<Framework, string[]> = {
+  'next-app': ['app/layout.tsx', 'app/layout.jsx', 'src/app/layout.tsx', 'src/app/layout.jsx'],
+  'next-pages': ['pages/_app.tsx', 'pages/_app.jsx', 'src/pages/_app.tsx', 'src/pages/_app.jsx'],
+  'react-router': ['app/root.tsx', 'app/root.jsx'],
+  'remix': ['app/root.tsx', 'app/root.jsx'],
+  'vite': ['src/main.tsx', 'src/main.jsx', 'src/main.ts'],
+  'astro': [],
+  'react': ['src/index.tsx', 'src/main.tsx', 'src/index.jsx', 'src/main.jsx'],
+}
+
+export function readPackageJson(cwd: string): PackageJson | null {
+  const file = join(cwd, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as PackageJson
+  } catch {
+    return null
+  }
+}
+
+export function allDeps(pkg: PackageJson | null): Record<string, string | undefined> {
+  if (!pkg) return {}
+  return {...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies}
+}
+
+export function detectPackageManager(cwd: string): PackageManager {
+  if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) return 'bun'
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(cwd, 'package-lock.json'))) return 'npm'
+
+  const declared = readPackageJson(cwd)?.packageManager
+  if (typeof declared === 'string') {
+    const name = declared.split('@')[0]
+    if (name === 'pnpm' || name === 'yarn' || name === 'npm' || name === 'bun') return name
+  }
+  return 'npm'
+}
+
+export function detectFramework(
+  cwd: string,
+  pkg: PackageJson | null = readPackageJson(cwd),
+): Framework {
+  const deps = allDeps(pkg)
+  const has = (name: string): boolean => Boolean(deps[name])
+  const dir = (relative: string): boolean => existsSync(join(cwd, relative))
+
+  if (has('next')) {
+    if (dir('app') || dir('src/app')) return 'next-app'
+    if (dir('pages') || dir('src/pages')) return 'next-pages'
+    return 'next-app'
+  }
+  if (has('@remix-run/react') || has('@remix-run/dev')) return 'remix'
+  if (has('@react-router/dev') || has('react-router')) return 'react-router'
+  if (has('astro')) return 'astro'
+  if (has('vite')) return 'vite'
+  return 'react'
+}
+
+export function detectTypeScript(
+  cwd: string,
+  pkg: PackageJson | null = readPackageJson(cwd),
+): boolean {
+  return existsSync(join(cwd, 'tsconfig.json')) || Boolean(allDeps(pkg)['typescript'])
+}
+
+/**
+ * Returns the first existing candidate entry file, otherwise the first
+ * candidate as the place to create one. Astro has no fixed entry, so we look
+ * for a layout component.
+ */
+export function detectEntry(cwd: string, framework: Framework): EntryInfo {
+  if (framework === 'astro') return detectAstroLayout(cwd)
+
+  const candidates = FRAMEWORK_ENTRIES[framework]
+  const existing = candidates.find((rel) => existsSync(join(cwd, rel)))
+  return {entry: existing ?? candidates[0] ?? 'src/index.tsx', exists: Boolean(existing)}
+}
+
+function detectAstroLayout(cwd: string): EntryInfo {
+  const candidates = [
+    'src/layouts/Layout.astro',
+    'src/layouts/BaseLayout.astro',
+    'src/layouts/index.astro',
+    'src/pages/index.astro',
+  ]
+  const existing = candidates.find((rel) => existsSync(join(cwd, rel)))
+  return {entry: existing ?? candidates[0] ?? 'src/layouts/Layout.astro', exists: Boolean(existing)}
+}
+
+/**
+ * Resolves the installed React version from node_modules, falling back to the
+ * declared range in package.json (carets/tildes stripped).
+ */
+export function detectReactVersion(
+  cwd: string,
+  pkg: PackageJson | null = readPackageJson(cwd),
+): ReactInfo {
+  const installed = readInstalledVersion(cwd, 'react')
+  if (installed) return {version: installed, source: 'installed'}
+
+  const declared = allDeps(pkg)['react']
+  if (typeof declared === 'string') {
+    return {version: declared.replace(/^[\^~>=<\s]+/, ''), source: 'declared'}
+  }
+  return {version: null, source: 'missing'}
+}
+
+function readInstalledVersion(cwd: string, name: string): string | null {
+  const file = join(cwd, 'node_modules', name, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    const pkg = JSON.parse(readFileSync(file, 'utf8')) as PackageJson
+    return pkg.version ?? null
+  } catch {
+    return null
+  }
+}
+
+export function isPackageInstalled(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'node_modules', name, 'package.json'))
+}
+
+export function readInstalledPackageVersion(cwd: string, name: string): string | null {
+  return readInstalledVersion(cwd, name)
+}
+
+export function isLegacyUiVersion(version: unknown): boolean {
+  const major = parseVersion(version)?.[0]
+  return major !== undefined && major < 5
+}
+
+function detectAliasedInstall(deps: Record<string, string | undefined>): string | null {
+  for (const [name, spec] of Object.entries(deps)) {
+    if (typeof spec === 'string' && /^npm:@sanity\/ui@(5(?:\..*)?|alpha)$/.test(spec)) return name
+  }
+  return null
+}
+
+/** Reads the major from a declared range, skipping workspace/catalog/link specs. */
+function declaredMajor(spec: string | undefined): number | null {
+  if (typeof spec !== 'string') return null
+  if (/^(workspace:|catalog:|link:|file:)/.test(spec)) return null
+
+  const npmAlias = spec.match(/^npm:@sanity\/ui@(\d+)/)
+  if (npmAlias) return Number(npmAlias[1])
+
+  return parseVersion(spec.replace(/^[\^~>=<\s]+/, ''))?.[0] ?? null
+}
+
+function detectLegacyInstall(cwd: string, deps: Record<string, string | undefined>): string | null {
+  const installed = readInstalledPackageVersion(cwd, PACKAGE_NAME)
+  if (installed && isLegacyUiVersion(installed)) {
+    return installed
+  }
+
+  const declared = deps[PACKAGE_NAME]
+  const major = declaredMajor(declared)
+  if (major !== null && major < 5) {
+    return declared ?? 'unknown'
+  }
+
+  return null
+}
+
+export function detect(cwd: string): Detected {
+  const pkg = readPackageJson(cwd)
+  const deps = allDeps(pkg)
+  const framework = detectFramework(cwd, pkg)
+  const entry = detectEntry(cwd, framework)
+  const typescript = detectTypeScript(cwd, pkg) || (entry.exists && /\.tsx?$/.test(entry.entry))
+  return {
+    pkg,
+    packageManager: detectPackageManager(cwd),
+    framework,
+    typescript,
+    ...entry,
+    react: detectReactVersion(cwd, pkg),
+    aliasedInstall: detectAliasedInstall(deps),
+    legacyInstall: detectLegacyInstall(cwd, deps),
+  }
+}

package/src/cli/doctor.test.ts

@@ -0,0 +1,52 @@
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import * as checks from './checks.js'
+import {runDoctor} from './doctor.js'
+import {writeInstalledUiVersion} from './test-utils.js'
+
+describe('runDoctor', () => {
+  let dir: string
+  let output: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'sui-doctor-'))
+    output = ''
+    vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+      output += String(chunk)
+      return true
+    })
+  })
+
+  afterEach(() => {
+    rmSync(dir, {recursive: true, force: true})
+    vi.restoreAllMocks()
+  })
+
+  it('warns and skips checks when @sanity/ui is pre-v5', () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({dependencies: {}}))
+    writeInstalledUiVersion(dir, '3.5.1')
+    const collectChecks = vi.spyOn(checks, 'collectChecks')
+
+    expect(runDoctor({cwd: dir})).toBe(0)
+    expect(output).toMatch(/@sanity\/ui@\^?3\.5\.1 \(pre-v5\)/)
+    expect(output).toMatch(/doctor checks v5 installs only/)
+    expect(collectChecks).not.toHaveBeenCalled()
+  })
+
+  it('warns and skips checks when v5 is installed under an alias', () => {
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({dependencies: {ui5: 'npm:@sanity/ui@alpha'}}),
+    )
+    const collectChecks = vi.spyOn(checks, 'collectChecks')
+
+    expect(runDoctor({cwd: dir})).toBe(0)
+    expect(output).toMatch(/alias "ui5"/)
+    expect(output).toMatch(/doctor checks direct @sanity\/ui v5 installs only/)
+    expect(collectChecks).not.toHaveBeenCalled()
+  })
+})

package/src/cli/doctor.ts

@@ -0,0 +1,65 @@
+import {collectChecks} from './checks.js'
+import {detect, LEGACY_COEXISTENCE_HINT, PACKAGE_NAME} from './detect.js'
+import {color, fail, heading, info, success, warn} from './log.js'
+import type {Check, CliOptions} from './types.js'
+
+export function printChecks(checks: Check[]): void {
+  for (const c of checks) {
+    const label = `${color.bold(c.title)}${c.detail ? ` ${color.dim(`— ${c.detail}`)}` : ''}`
+    if (c.status === 'pass') success(label)
+    else if (c.status === 'warn') warn(label)
+    else fail(label)
+
+    if (c.status !== 'pass' && c.fix) {
+      info(`  ${color.dim('fix:')} ${c.fix}`)
+    }
+  }
+}
+
+/** Runs every check and prints it. Returns 1 only when something fails; warnings still pass. */
+export function runDoctor({cwd}: Pick<CliOptions, 'cwd'>): number {
+  const detected = detect(cwd)
+
+  heading('Sanity UI doctor')
+
+  if (detected.aliasedInstall) {
+    warn(
+      `This project installs v5 under the alias "${detected.aliasedInstall}". doctor checks direct @sanity/ui v5 installs only.`,
+    )
+    info(`  ${color.dim('hint:')} ${LEGACY_COEXISTENCE_HINT}`)
+    return 0
+  }
+
+  if (detected.legacyInstall) {
+    warn(
+      `This project has ${PACKAGE_NAME}@${detected.legacyInstall} (pre-v5). doctor checks v5 installs only.`,
+    )
+    info(`  ${color.dim('hint:')} ${LEGACY_COEXISTENCE_HINT}`)
+    return 0
+  }
+
+  const {checks} = collectChecks(cwd)
+  info(
+    color.dim(
+      `framework: ${detected.framework} · package manager: ${detected.packageManager} · entry: ${detected.entry}`,
+    ),
+  )
+  info('')
+
+  printChecks(checks)
+
+  const failed = checks.filter((c) => c.status === 'fail')
+  const warned = checks.filter((c) => c.status === 'warn')
+
+  info('')
+  if (failed.length === 0 && warned.length === 0) {
+    success('Everything looks good.')
+    return 0
+  }
+  if (failed.length === 0) {
+    warn(`${warned.length} warning${warned.length === 1 ? '' : 's'}, no blocking issues.`)
+    return 0
+  }
+  fail(`${failed.length} issue${failed.length === 1 ? '' : 's'} found. See fixes above.`)
+  return 1
+}

package/src/cli/index.ts

@@ -0,0 +1,77 @@
+import {resolve} from 'node:path'
+import process from 'node:process'
+import {parseArgs} from 'node:util'
+
+import {runDoctor} from './doctor.js'
+import {runInit} from './init.js'
+import {color, fail, info} from './log.js'
+import {readSelfPackage} from './selfPackage.js'
+
+const HELP = `${color.bold('@sanity/ui')} setup CLI
+
+${color.bold('Usage')}
+  npx @sanity/ui@alpha <command> [options]
+
+${color.bold('Commands')}
+  init      Scaffold a correct Sanity UI install (deps, stylesheet, tsconfig)
+  doctor    Check an existing setup and report fixes
+
+${color.bold('Options')}
+  --dry        Print the plan and exit without changing anything (init)
+  --yes, -y    Accept every prompt with its default (non-interactive)
+  --cwd <dir>  Run against another directory (default: current directory)
+  --version    Print the CLI version
+  --help, -h   Show this help
+`
+
+/**
+ * Parses arguments and dispatches to a command. `parseArgs` runs in strict mode,
+ * so an unknown flag throws from here and is caught by the bin wrapper. Exit
+ * codes: 0 on success or an explicit `--help`, 1 on misuse (no or unknown command).
+ */
+export async function main(argv: string[]): Promise<number> {
+  const {values, positionals} = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      dry: {type: 'boolean', default: false},
+      yes: {type: 'boolean', short: 'y', default: false},
+      cwd: {type: 'string'},
+      version: {type: 'boolean', default: false},
+      help: {type: 'boolean', short: 'h', default: false},
+    },
+  })
+
+  if (values.version) {
+    info(readSelfPackage().version ?? 'unknown')
+    return 0
+  }
+
+  const command = positionals[0]
+
+  if (values.help) {
+    info(HELP)
+    return 0
+  }
+  if (!command) {
+    info(HELP)
+    return 1
+  }
+
+  const options = {
+    dry: values.dry ?? false,
+    yes: values.yes ?? false,
+    cwd: values.cwd ? resolve(process.cwd(), values.cwd) : process.cwd(),
+  }
+
+  switch (command) {
+    case 'init':
+      return runInit(options)
+    case 'doctor':
+      return runDoctor(options)
+    default:
+      fail(`Unknown command: ${command}`)
+      info(HELP)
+      return 1
+  }
+}

package/src/cli/init.ts

@@ -0,0 +1,225 @@
+import {basename} from 'node:path'
+import process from 'node:process'
+
+import {verifyAfterInit} from './checks.js'
+import {buildConfig, CONFIG_FILE, configExists, writeConfig} from './config.js'
+import {detect, LEGACY_COEXISTENCE_HINT, PACKAGE_NAME} from './detect.js'
+import {printChecks} from './doctor.js'
+import {installCommand, resolveInstallSpecs, resolveTypeSpecs, runInstall} from './install.js'
+import {color, confirm, fail, heading, info, step, success, warn} from './log.js'
+import {inspectStylesheet, STYLES_SPECIFIER, wireStylesheet} from './styles.js'
+import type {StylesheetInfo} from './styles.js'
+import {inspectTsconfig, reconcileTsconfig} from './tsconfig.js'
+import type {TsconfigInspection} from './tsconfig.js'
+import type {CliOptions, Detected} from './types.js'
+import {meetsNode, meetsReact, NODE_REQUIREMENT, REACT_MIN} from './versions.js'
+
+interface Plan {
+  specs: string[]
+  typeSpecs: string[]
+  install: string
+  stylesheet: StylesheetInfo
+  tsconfig: TsconfigInspection | null
+}
+
+/**
+ * Prints the React and Node checks. Missing React only warns, since the user may
+ * be scaffolding before installing it; an out-of-range React or Node sets
+ * `blocking`. `blocking` never hard-stops init. It only triggers a louder warning
+ * before the apply confirmation, so the user stays in control either way.
+ */
+function reportPrereqs({react}: Detected): {blocking: boolean} {
+  let blocking = false
+
+  const reactVersion = react.version
+  if (!reactVersion) {
+    warn(`React not detected. This package needs React >= ${REACT_MIN}.`)
+  } else if (meetsReact(reactVersion)) {
+    success(`React ${reactVersion} meets the >= ${REACT_MIN} requirement.`)
+  } else {
+    warn(`React ${reactVersion} is below ${REACT_MIN}. Components may not render correctly.`)
+    info(`  ${color.dim('fix:')} Upgrade React to >= ${REACT_MIN}`)
+    blocking = true
+  }
+
+  const nodeVersion = process.versions.node
+  if (meetsNode(nodeVersion)) {
+    success(`Node ${nodeVersion} meets the ${NODE_REQUIREMENT} requirement.`)
+  } else {
+    warn(`Node ${nodeVersion} is outside ${NODE_REQUIREMENT}. Install may behave unexpectedly.`)
+    info(`  ${color.dim('fix:')} Use Node ${NODE_REQUIREMENT}`)
+    blocking = true
+  }
+
+  return {blocking}
+}
+
+function parseReactMajor(version: string | null): number {
+  const match = typeof version === 'string' ? version.match(/\d+/) : null
+  return match ? Number(match[0]) : 19
+}
+
+function buildPlan(cwd: string, detected: Detected): Plan {
+  const specs = resolveInstallSpecs()
+  const {command, args} = installCommand(detected.packageManager, specs)
+  const reactMajor = parseReactMajor(detected.react.version)
+  const typeSpecs = detected.typescript ? resolveTypeSpecs(cwd, {reactMajor}) : []
+  const stylesheet = inspectStylesheet(cwd, detected.entry)
+  const tsconfig = detected.typescript ? inspectTsconfig(cwd) : null
+
+  return {specs, typeSpecs, install: `${command} ${args.join(' ')}`, stylesheet, tsconfig}
+}
+
+function printPlan(cwd: string, detected: Detected, plan: Plan): void {
+  heading('Plan')
+
+  step(`Install: ${color.bold(plan.install)}`)
+
+  if (plan.typeSpecs.length > 0) {
+    step(`Dev types: ${color.bold(plan.typeSpecs.join(' '))}`)
+  }
+
+  if (plan.stylesheet.imported) {
+    step(`Stylesheet: already imported in ${plan.stylesheet.importedIn ?? detected.entry}`)
+  } else if (plan.stylesheet.exists) {
+    step(`Stylesheet: add ${color.bold(`import '${STYLES_SPECIFIER}'`)} to ${detected.entry}`)
+  } else {
+    step(`Stylesheet: entry ${detected.entry} not found, will skip (add the import manually)`)
+  }
+
+  if (!detected.typescript || !plan.tsconfig) {
+    step('tsconfig: no TypeScript detected, skipping')
+  } else if (!plan.tsconfig.exists) {
+    step('tsconfig: create tsconfig.json with required options')
+  } else if (plan.tsconfig.changes.length === 0) {
+    step('tsconfig: already has required options')
+  } else {
+    const summary = plan.tsconfig.changes.map((c) => c.key).join(', ')
+    step(`tsconfig: update ${basename(plan.tsconfig.file)} (${summary})`)
+  }
+
+  step(configExists(cwd) ? `${CONFIG_FILE}: overwrite` : `${CONFIG_FILE}: create`)
+}
+
+/**
+ * The init lifecycle: detect the project, report prerequisites, build and print
+ * the plan, confirm, apply each step, then verify. `--dry` stops after the plan;
+ * `--yes` accepts the confirmation without prompting.
+ */
+export async function runInit(options: CliOptions): Promise<number> {
+  const {cwd, dry, yes} = options
+  const detected = detect(cwd)
+
+  heading('Sanity UI init')
+  info(
+    color.dim(
+      `framework: ${detected.framework} · package manager: ${detected.packageManager} · entry: ${detected.entry} · typescript: ${detected.typescript}`,
+    ),
+  )
+
+  if (detected.aliasedInstall) {
+    fail(
+      `This project installs v5 under the alias "${detected.aliasedInstall}". init is for new apps only.`,
+    )
+    info(`  ${color.dim('fix:')} ${LEGACY_COEXISTENCE_HINT}`)
+    return 1
+  }
+
+  if (detected.legacyInstall) {
+    fail(
+      `This project already has ${PACKAGE_NAME}@${detected.legacyInstall} (pre-v5). init is for new apps only.`,
+    )
+    info(`  ${color.dim('fix:')} ${LEGACY_COEXISTENCE_HINT}`)
+    return 1
+  }
+
+  heading('Requirements')
+  const {blocking} = reportPrereqs(detected)
+
+  const plan = buildPlan(cwd, detected)
+  printPlan(cwd, detected, plan)
+
+  if (dry) {
+    info('')
+    info(color.dim('Dry run: no changes made.'))
+    return 0
+  }
+
+  if (blocking) {
+    info('')
+    warn('Some requirements are unmet (see above). Continuing may not work.')
+  }
+
+  // Without a TTY there's no one to answer the prompt, so confirm() falls back to
+  // the default (apply). Say so explicitly rather than appearing to act silently;
+  // --dry is the preview-only path for anyone who doesn't want writes.
+  if (!yes && !process.stdin.isTTY) {
+    info('')
+    info(color.dim('Non-interactive (no TTY): applying automatically. Use --dry to preview.'))
+  }
+
+  const proceed = await confirm('\nApply these changes?', {defaultValue: true, assumeYes: yes})
+  if (!proceed) {
+    info('Aborted. No changes made.')
+    return 0
+  }
+
+  heading('Applying')
+
+  step(`Installing with ${detected.packageManager}…`)
+  const install = runInstall(cwd, detected.packageManager, plan.specs)
+  if (install.ok) {
+    success('Dependencies installed.')
+  } else if (install.reason === 'spawn') {
+    warn(`Could not run ${detected.packageManager}: ${install.message ?? 'unknown error'}`)
+    info(`  ${color.dim('fix:')} Install manually: ${install.command} ${install.args.join(' ')}`)
+  } else {
+    warn(`Install exited with code ${install.status ?? 'unknown'}.`)
+    info(
+      `  ${color.dim('hint:')} This is usually a peer-dependency conflict. Re-run the install and read the conflict, or retry with your package manager's legacy peer-deps flag.`,
+    )
+  }
+
+  if (plan.typeSpecs.length > 0) {
+    step('Installing React type definitions…')
+    const typeInstall = runInstall(cwd, detected.packageManager, plan.typeSpecs, {dev: true})
+    if (typeInstall.ok) success('Type definitions installed.')
+    else warn(`Could not install ${plan.typeSpecs.join(' ')}. Add them manually.`)
+  }
+
+  if (plan.stylesheet.exists && !plan.stylesheet.imported) {
+    const wired = wireStylesheet(cwd, detected.entry, {dryRun: false})
+    if (wired.wrote) success(`Imported the stylesheet in ${detected.entry}.`)
+  } else if (plan.stylesheet.imported) {
+    success('Stylesheet already imported.')
+  } else {
+    warn(`Could not find ${detected.entry}. Add \`import '${STYLES_SPECIFIER}'\` manually.`)
+  }
+
+  if (detected.typescript) {
+    const result = reconcileTsconfig(cwd, {dryRun: false})
+    if (result.created) success('Created tsconfig.json with required options.')
+    else if (result.unreadable) warn('tsconfig.json could not be parsed; left untouched.')
+    else if (result.changes.length === 0) success('tsconfig already has the required options.')
+    else success(`Updated tsconfig: ${result.changes.map((c) => c.key).join(', ')}.`)
+  }
+
+  const config = buildConfig({framework: detected.framework, entry: detected.entry})
+  writeConfig(cwd, config)
+  success(`Wrote ${CONFIG_FILE}.`)
+
+  heading('Verifying')
+  const results = verifyAfterInit(cwd)
+  printChecks(results)
+
+  const failed = results.filter((c) => c.status === 'fail')
+  info('')
+  if (failed.length === 0) {
+    success('Setup verified. Import components from @sanity/ui and start building.')
+    return 0
+  }
+  fail(
+    `${failed.length} check${failed.length === 1 ? '' : 's'} failed. Run \`npx ${PACKAGE_NAME}@alpha doctor\` for details.`,
+  )
+  return 1
+}

package/src/cli/install.test.ts

@@ -0,0 +1,52 @@
+import {mkdtempSync, rmSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest'
+
+import {installCommand, resolveInstallSpecs, resolveTypeSpecs} from './install.js'
+
+describe('resolveInstallSpecs', () => {
+  it('pins the package to its shipped version and icons to the declared version', () => {
+    const specs = resolveInstallSpecs()
+    expect(specs[0]).toMatch(/^@sanity\/ui@\d+\.\d+\.\d+/)
+    expect(specs.some((s) => s.startsWith('@sanity/icons@'))).toBe(true)
+  })
+
+  it('leaves dependencies the app never imports itself to the package manager', () => {
+    const specs = resolveInstallSpecs()
+    expect(specs.some((s) => s.startsWith('react-refractor'))).toBe(false)
+    expect(specs.some((s) => s.startsWith('clsx'))).toBe(false)
+  })
+})
+
+describe('installCommand', () => {
+  it('uses install for npm and add for others', () => {
+    expect(installCommand('npm', ['x']).args).toEqual(['install', 'x'])
+    expect(installCommand('pnpm', ['x']).args).toEqual(['add', 'x'])
+  })
+
+  it('applies the right dev flag per package manager', () => {
+    expect(installCommand('npm', ['x'], {dev: true}).args).toEqual(['install', '--save-dev', 'x'])
+    expect(installCommand('pnpm', ['x'], {dev: true}).args).toEqual(['add', '-D', 'x'])
+    expect(installCommand('yarn', ['x'], {dev: true}).args).toEqual(['add', '-D', 'x'])
+    expect(installCommand('bun', ['x'], {dev: true}).args).toEqual(['add', '-d', 'x'])
+  })
+})
+
+describe('resolveTypeSpecs', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'sui-types-'))
+  })
+  afterEach(() => {
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  it('returns React type packages pinned to the major when none are installed', () => {
+    expect(resolveTypeSpecs(dir, {reactMajor: 19})).toEqual([
+      '@types/react@^19',
+      '@types/react-dom@^19',
+    ])
+  })
+})