dsh-code 1.0.6 → 1.0.7

package/src/terminal-title.ts

@@ -0,0 +1,173 @@
+/**
+ * Terminal tab/window title management for the TUI.
+ *
+ * Terminals label their tab from the window title, which an application sets
+ * with an OSC 0 sequence; without one the tab shows the process name ("node").
+ * The title text is untrusted display content (session names arrive through
+ * events and user input), so it is sanitized before emission: control
+ * characters and bidi/invisible formatting codepoints are stripped, whitespace
+ * runs collapse to single spaces, and the result is bounded. Clearing writes
+ * an empty OSC payload and the terminal falls back to its own default; the
+ * previously set title is not portable to read back and is never restored.
+ *
+ * @module @deepseek-ai/dsh-code/terminal-title
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { useLayoutEffect, useRef } from 'react'
+import { useStdout } from 'ink'
+
+/** The host process title at module load, restored on unmount. On Windows
+ * this reaches the tab through SetConsoleTitleW (ConPTY reflects it to VS
+ * Code and friends without any user setting); on POSIX it becomes the ps
+ * name. Node replaces the argv memory, so the original must be saved before
+ * the first assignment. */
+const initialProcessTitle = process.title
+
+/** Tab label before a session carries a name. */
+export const DEFAULT_TERMINAL_TITLE = 'deepseek'
+
+/** Practical upper bound on title length, in visible characters: long enough
+ * for session names, short enough for tab bars and window managers. */
+export const MAX_TERMINAL_TITLE_CHARS = 240
+
+/** Control characters, DEL/C1 range, and bidi or invisible formatting
+ * codepoints that could terminate the OSC sequence or visually reorder the
+ * title relative to its underlying text. */
+const DISALLOWED_TITLE_CHARS = /[\u0000-\u001F\u007F-\u009F\u00AD\u034F\u061C\u180E\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/
+
+/** Normalize untrusted title text into one bounded display line: disallowed
+ * codepoints dropped, whitespace runs collapsed to single spaces, leading and
+ * trailing whitespace removed, length bounded. */
+export function sanitizeTerminalTitle(text: string): string {
+  const chars: string[] = []
+  let pendingSpace = false
+  for (const ch of text) {
+    if (DISALLOWED_TITLE_CHARS.test(ch)) continue
+    if (ch.trim() === '') {
+      if (chars.length > 0) pendingSpace = true
+      continue
+    }
+    if (pendingSpace) {
+      if (chars.length + 1 >= MAX_TERMINAL_TITLE_CHARS) break
+      chars.push(' ')
+      pendingSpace = false
+    }
+    if (chars.length >= MAX_TERMINAL_TITLE_CHARS) break
+    chars.push(ch)
+  }
+  return chars.join('')
+}
+
+/** Build one OSC 0 title sequence. An empty sanitized title yields an empty
+ * string: emitting nothing is distinct from clearing, which is a separate
+ * policy decision made by the caller. */
+export function terminalTitleSequence(text: string): string {
+  const title = sanitizeTerminalTitle(text)
+  return title === '' ? '' : `\x1b]0;${title}\x07`
+}
+
+/** Clear the managed title with an empty OSC payload; the terminal falls back
+ * to its own default label. */
+export function clearTerminalTitleSequence(): string {
+  return '\x1b]0;\x07'
+}
+
+/** Outcome of the VS Code settings alignment. */
+export interface VsCodeTitleSettingResult {
+  wrote: boolean
+  reason?: 'not-vscode' | 'unparseable' | 'key-present' | 'error'
+}
+
+/** VS Code renders an application-set tab title only when
+ * "terminal.integrated.tabs.title" maps to the sequence variable; the editor
+ * default shows the process name instead ("node" for a Node CLI). Inside a VS
+ * Code integrated terminal, align the user settings once: if the key is
+ * absent, insert it and keep a one-shot backup of the original file. A value
+ * the user already set is never overwritten, an unparseable file is never
+ * touched, and every failure degrades to a no-op - the OSC and process-title
+ * channels keep working everywhere else. */
+export function ensureVsCodeTabTitleSetting(options: {
+  env?: NodeJS.ProcessEnv
+  settingsFile?: string
+  isTTY?: boolean
+} = {}): VsCodeTitleSettingResult {
+  const env = options.env ?? process.env
+  if (env['TERM_PROGRAM'] !== 'vscode') return { wrote: false, reason: 'not-vscode' }
+  if ((options.isTTY ?? process.stdout.isTTY) !== true) return { wrote: false, reason: 'not-vscode' }
+  let file = options.settingsFile
+  if (file === undefined) {
+    const base = process.platform === 'win32' ? env['APPDATA'] : env['HOME']
+    if (base === undefined || base === '') return { wrote: false, reason: 'error' }
+    file = process.platform === 'win32'
+      ? join(base, 'Code', 'User', 'settings.json')
+      : join(base, '.config', 'Code', 'User', 'settings.json')
+  }
+  try {
+    if (!existsSync(file)) {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, '{\n  "terminal.integrated.tabs.title": "${sequence}"\n}\n', 'utf8')
+      return { wrote: true }
+    }
+    const text = readFileSync(file, 'utf8')
+    if (text.includes('"terminal.integrated.tabs.title"')) return { wrote: false, reason: 'key-present' }
+    try {
+      JSON.parse(text)
+    } catch {
+      return { wrote: false, reason: 'unparseable' }
+    }
+    const close = text.lastIndexOf('}')
+    if (close < 0) return { wrote: false, reason: 'unparseable' }
+    const before = text.slice(0, close)
+    const trimmedBefore = before.replace(/[ \t\r\n]+$/, '')
+    const tail = before.slice(trimmedBefore.length)
+    const needsComma = trimmedBefore.trim() !== '' && !trimmedBefore.trimEnd().endsWith('{')
+    const inserted = (needsComma ? ',' : '') + '\n    "terminal.integrated.tabs.title": "${sequence}"\n'
+    writeFileSync(file + '.dsh-backup', text, 'utf8')
+    writeFileSync(file, trimmedBefore + inserted + tail + text.slice(close), 'utf8')
+    return { wrote: true }
+  } catch {
+    return { wrote: false, reason: 'error' }
+  }
+}
+
+/**
+ * Keep the terminal tab label on `title` (sanitized; empty titles leave the
+ * current label alone). Two delivery channels run in parallel: the OSC 0
+ * sequence to stdout, and the host process title. Writes are deduplicated by
+ * title, and on unmount the managed title is cleared and the process title
+ * restored so the host shell regains its default label.
+ */
+export function useTerminalTitle(title: string, options: { clearOnUnmount?: boolean } = {}): void {
+  const { clearOnUnmount = true } = options
+  const { stdout } = useStdout()
+  const writtenRef = useRef<string | undefined>(undefined)
+  const processTitleRef = useRef(false)
+  // Layout effects: the clear must run synchronously at unmount (passive
+  // cleanups are not flushed synchronously when Ink tears the tree down).
+  useLayoutEffect(() => {
+    if (stdout === undefined) return undefined
+    return () => {
+      if (processTitleRef.current) {
+        processTitleRef.current = false
+        process.title = initialProcessTitle
+      }
+      if (clearOnUnmount && writtenRef.current !== undefined) stdout.write(clearTerminalTitleSequence())
+    }
+  }, [stdout, clearOnUnmount])
+  useLayoutEffect(() => {
+    if (stdout === undefined) return
+    if (title === writtenRef.current) return
+    const sequence = terminalTitleSequence(title)
+    if (sequence === '') return
+    stdout.write(sequence)
+    // The process title is the second delivery channel: on Windows it drives
+    // the console title that ConPTY reflects onto the tab without any user
+    // setting, where the OSC channel alone only shows once the host maps
+    // "terminal.integrated.tabs.title" to the sequence variable.
+    process.title = sanitizeTerminalTitle(title)
+    processTitleRef.current = true
+    writtenRef.current = title
+  }, [stdout, title])
+}

package/src/update-panel.ts

@@ -0,0 +1,246 @@
+/**
+ * The /update panel: one bounded surface over the launcher update
+ * pipeline. The panel never decides versions itself — it renders the
+ * launcher `update --json` probe (plan plus refusals), takes one
+ * confirmation, then streams `update --apply` progress and reports the
+ * result with a restart hint. Every alignment guarantee (host pinned to
+ * the release peers line, companion plugins carried, downgrade and
+ * local-checkout refusals) lives in the launcher and is only displayed
+ * here.
+ */
+
+import { createElement, useEffect, useState, type ReactElement } from 'react'
+import { Box, Text, useInput, useStdout } from 'ink'
+import type { LauncherUpdateStatus } from './update.ts'
+import { clampScroll, panelViewport } from './render/inspector.ts'
+import { singleLineText, truncateColumns } from './render/text.ts'
+import { getPalette, inkColor } from './theme.ts'
+
+/** Retained apply-progress lines (ring tail; npm output is ephemeral). */
+export const UPDATE_OUTPUT_CAP = 800
+
+/** Keep the newest UPDATE_OUTPUT_CAP lines of streamed update output. */
+export function clipUpdateLines(lines: readonly string[]): readonly string[] {
+  return lines.length <= UPDATE_OUTPUT_CAP ? lines : lines.slice(lines.length - UPDATE_OUTPUT_CAP)
+}
+
+/** One display row of the update surface. */
+export interface UpdateRow {
+  readonly key: string
+  readonly text: string
+  readonly tone?: 'ok' | 'warn' | 'error' | 'dim'
+}
+
+/** The plan view derived from one probe: facts to show and whether apply may run. */
+export interface UpdatePlanView {
+  readonly rows: readonly UpdateRow[]
+  readonly runnable: boolean
+}
+
+/** Rendered facts of one probe: current/target versions, actions, refusals. */
+export function updatePlanView(status: LauncherUpdateStatus): UpdatePlanView {
+  const rows: UpdateRow[] = []
+  const latest = status.code.latest ?? 'unknown'
+  rows.push(status.code.latest !== null && status.code.latest === status.code.running
+    ? { key: 'code', text: `dsh-code    ${status.code.running} (latest)` }
+    : { key: 'code', text: `dsh-code    ${status.code.running} → ${latest}` })
+  if (status.host.targetLine === null) {
+    rows.push({ key: 'host', text: 'harness     pinned line unreadable — update would install @deepseek-ai/dsh@latest', tone: 'warn' })
+  } else if (status.host.installed === null) {
+    rows.push({ key: 'host', text: `harness     not installed → ${status.host.targetLine}` })
+  } else if (status.host.installed === status.host.targetLine) {
+    rows.push({ key: 'host', text: `harness     ${status.host.installed} (on pinned line)` })
+  } else {
+    rows.push({ key: 'host', text: `harness     ${status.host.installed} → ${status.host.targetLine}` })
+  }
+  const mounted = status.profile.mounted === null
+    ? status.profile.spec ?? 'not mounted'
+    : `dsh-code ${status.profile.mounted}`
+  rows.push({
+    key: 'profile',
+    text: `profile     ${mounted}${status.profile.localCheckout ? ' · local checkout' : ''}`,
+    tone: status.profile.localCheckout ? 'dim' : undefined,
+  })
+  for (const plugin of status.plan.pluginSpecs) {
+    rows.push({ key: `plugin:${plugin}`, text: `plugin      ${plugin}`, tone: 'dim' })
+  }
+  // A blocker key may be absent entirely (JSON.stringify drops undefined);
+  // a missing value reads as "no blocker", never as an undefined row body.
+  const registryBlocker = status.blockers.registry ?? null
+  if (registryBlocker !== null) {
+    rows.push({ key: 'blocker:registry', text: registryBlocker, tone: 'error' })
+  }
+  if (status.blockers.downgrade) {
+    rows.push({
+      key: 'blocker:downgrade',
+      text: `refusing to downgrade the host: dsh-code@${latest} needs ${status.host.targetLine ?? 'the pinned line'}, but ${status.host.installed ?? 'the installed host'} is newer — wait for the next dsh-code release`,
+      tone: 'error',
+    })
+  }
+  const checkoutBlocker = status.blockers.localCheckout ?? null
+  if (checkoutBlocker !== null) {
+    for (const [index, line] of checkoutBlocker.entries()) {
+      rows.push({ key: `blocker:checkout:${index}`, text: line, tone: 'error' })
+    }
+  }
+  if (status.upToDate) {
+    rows.push({ key: 'uptodate', text: 'everything is already on the pinned line — nothing to update', tone: 'ok' })
+  }
+  const runnable = status.upToDate !== true
+    && registryBlocker === null
+    && status.blockers.downgrade !== true
+    && checkoutBlocker === null
+  return { rows, runnable }
+}
+
+/** Panel lifecycle phases; the footer names the keys each phase accepts. */
+export type UpdatePhase = 'probe' | 'error' | 'plan' | 'apply' | 'done'
+
+/** Footer hint line per phase; the plan phase names the confirm key only when runnable. */
+export function updateFooter(phase: UpdatePhase, runnable: boolean, upToDate: boolean): string {
+  if (phase === 'probe') return 'checking… · esc close'
+  if (phase === 'error') return 'r recheck · esc close'
+  if (phase === 'apply') return 'updating… · ↑↓ scroll · esc waits'
+  if (phase === 'done') return 'r recheck · esc close'
+  if (upToDate) return 'up to date · r recheck · esc close'
+  return runnable ? 'enter update · r recheck · esc close' : 'blocked · r recheck · esc close'
+}
+
+/**
+ * The /update surface: probe on open (and on r), confirm with enter/y,
+ * stream the aligned apply, and land on a bounded result view. Escape is
+ * locked while the apply child runs — killing npm mid-install is exactly
+ * the half-updated state this command exists to prevent.
+ */
+export function UpdatePanel({ probe, apply, close, notify }: {
+  /** Read-only probe of the launcher update status (never installs). */
+  probe(): Promise<LauncherUpdateStatus>
+  /** Run the aligned update; streams sanitized progress lines. */
+  apply(onLine: (line: string) => void): Promise<number>
+  /** Close the panel (App keeps ownership of the flag). */
+  close(): void
+  /** One bounded cross-surface notice (phase completions). */
+  notify(text: string, tone?: 'info' | 'warning' | 'error'): void
+}): ReactElement {
+  const [phase, setPhase] = useState<UpdatePhase>('probe')
+  const [status, setStatus] = useState<LauncherUpdateStatus>()
+  const [probeError, setProbeError] = useState<string>()
+  const [lines, setLines] = useState<readonly string[]>([])
+  const [exit, setExit] = useState<number>()
+  const [applyError, setApplyError] = useState<string>()
+  // Viewport anchor: 'tail' follows new output; a number pins the first
+  // visible row (up moves away from the tail, down onto it re-follows).
+  const [anchor, setAnchor] = useState<'tail' | number>('tail')
+  const [epoch, setEpoch] = useState(0)
+  useEffect(() => {
+    let disposed = false
+    setPhase('probe')
+    setStatus(undefined)
+    setProbeError(undefined)
+    setAnchor('tail')
+    probe().then(value => {
+      if (disposed) return
+      setStatus(value)
+      setPhase('plan')
+    }, reason => {
+      if (disposed) return
+      setProbeError(reason instanceof Error ? reason.message : String(reason))
+      setPhase('error')
+    })
+    return () => { disposed = true }
+  }, [epoch, probe])
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  const start = (): void => {
+    if (phase !== 'plan' || status === undefined) return
+    if (!updatePlanView(status).runnable) return
+    setPhase('apply')
+    setLines([])
+    setExit(undefined)
+    setApplyError(undefined)
+    setAnchor('tail')
+    apply(line => {
+      setLines(previous => clipUpdateLines([...previous, singleLineText(line)]))
+    }).then(code => {
+      setExit(code)
+      setPhase('done')
+      notify(code === 0 ? 'update installed — restart dsh to activate' : `update failed (exit ${code})`, code === 0 ? 'info' : 'error')
+    }, reason => {
+      const message = reason instanceof Error ? reason.message : String(reason)
+      setApplyError(message)
+      setPhase('done')
+      notify(`update failed: ${message}`, 'error')
+    })
+  }
+  const planView = status === undefined ? undefined : updatePlanView(status)
+  const rows: readonly UpdateRow[] = phase === 'probe'
+    ? [{ key: 'probe', text: 'checking npm for the aligned update…', tone: 'dim' }]
+    : phase === 'error'
+      ? [{ key: 'error', text: singleLineText(probeError ?? 'probe failed'), tone: 'error' }]
+      : phase === 'plan' && planView !== undefined
+        ? planView.rows
+        : phase === 'apply'
+          ? lines.map((line, index) => ({ key: `out:${index}`, text: line, tone: 'dim' as const }))
+          : [
+            ...(exit === 0 ? [{ key: 'ok', text: 'update installed — restart dsh to load the new version (/quit or ctrl+c)', tone: 'ok' as const }] : []),
+            ...(exit !== undefined && exit !== 0 ? [{ key: 'fail', text: `update failed (exit ${exit})`, tone: 'error' as const }] : []),
+            ...(applyError !== undefined ? [{ key: 'fail:start', text: singleLineText(applyError), tone: 'error' as const }] : []),
+            ...lines.map((line, index) => ({ key: `out:${index}`, text: line, tone: 'dim' as const })),
+          ]
+  const budget = Math.max(1, viewport.bodyRows)
+  const tailOffset = clampScroll(Math.max(0, rows.length - budget), rows.length, budget)
+  const offset = anchor === 'tail' ? tailOffset : clampScroll(anchor, rows.length, budget)
+  useInput((input, key) => {
+    if (phase === 'apply') {
+      // Scroll-only while the installer runs: escape stays locked.
+      if (key.upArrow) setAnchor(offset <= 0 ? 0 : offset - 1)
+      if (key.downArrow && offset >= tailOffset) setAnchor('tail')
+      else if (key.downArrow) setAnchor(offset + 1)
+      return
+    }
+    if (key.escape || input === 'q') return close()
+    if (input === 'r') {
+      setEpoch(value => value + 1)
+      return
+    }
+    if (key.return || input === 'y') {
+      void start()
+      return
+    }
+    if (key.upArrow) setAnchor(offset <= 0 ? 0 : offset - 1)
+    if (key.downArrow && offset >= tailOffset) setAnchor('tail')
+    else if (key.downArrow) setAnchor(offset + 1)
+  })
+  if (viewport.maxHeight === 0 || viewport.compact) {
+    const summary = phase === 'probe' ? 'checking…'
+      : phase === 'error' ? 'probe failed'
+      : phase === 'apply' ? singleLineText(lines[lines.length - 1] ?? 'updating…')
+      : phase === 'done' ? (exit === 0 ? 'installed — restart to activate' : 'failed')
+      : status?.upToDate === true ? 'up to date' : planView?.runnable === true ? 'enter updates' : 'blocked'
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns(singleLineText(`/update · ${summary}`), viewport.contentColumns))
+  }
+  const visible = rows.slice(offset, offset + budget)
+  const toneColor = (tone: UpdateRow['tone']): ReturnType<typeof inkColor> | undefined => tone === 'ok'
+    ? inkColor(getPalette().success)
+    : tone === 'error'
+    ? inkColor(getPalette().error)
+    : tone === 'warn'
+    ? inkColor(getPalette().warn)
+    : tone === 'dim'
+    ? inkColor(getPalette().dim)
+    : undefined
+  const title = status === undefined
+    ? '/update · aligned upgrade'
+    : `/update · dsh-code ${status.code.running}${status.code.latest !== null && status.code.latest !== status.code.running ? ` → ${status.code.latest}` : ''}`
+  return createElement(
+    Box,
+    { width: viewport.outerColumns, borderStyle: 'round', borderColor: inkColor(getPalette().dim), flexDirection: 'column', paddingX: 1 },
+    createElement(Text, { color: inkColor(getPalette().brandBright), wrap: 'truncate-end' }, truncateColumns(singleLineText(title), viewport.contentColumns)),
+    ...visible.map(row => createElement(Text, {
+      key: row.key,
+      color: toneColor(row.tone),
+      wrap: 'truncate-end',
+    }, truncateColumns(`  ${singleLineText(row.text)}`, viewport.contentColumns))),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(singleLineText(updateFooter(phase, planView?.runnable ?? false, status?.upToDate === true)), viewport.contentColumns)),
+  )
+}

package/src/update.ts

@@ -0,0 +1,110 @@
+/**
+ * Child-process adapter for the launcher update pipeline. The launcher
+ * (bin/deepseek.mjs) stays the single owner of update semantics — plan,
+ * guards, and the aligned install sequence — so the TUI only spawns
+ * `update --json` (read-only probe) and `update --apply` (streamed run)
+ * and never re-implements version-line decisions.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+/** Spawn double acceptable to the adapter (tests inject an EventEmitter). */
+export type SpawnLike = (command: string, args: readonly string[], options: { readonly stdio: readonly string[]; readonly windowsHide: boolean }) => ChildProcess
+
+/** Structured `update --json` payload; mirrors the launcher buildUpdateStatus. */
+export interface LauncherUpdateStatus {
+  readonly code: { readonly running: string; readonly latest: string | null }
+  readonly host: { readonly installed: string | null; readonly targetLine: string | null }
+  readonly profile: { readonly spec: string | null; readonly mounted: string | null; readonly localCheckout: boolean }
+  readonly plan: { readonly dshSpec: string; readonly codeSpec: string; readonly pluginSpecs: readonly string[] }
+  readonly blockers: { readonly registry: string | null; readonly downgrade: boolean; readonly localCheckout: readonly string[] | null }
+  readonly upToDate: boolean
+}
+
+/** The launcher entrypoint that ships beside this bundle (lib/../bin). */
+export function launcherUpdateCommand(args: readonly string[], moduleUrl: string = import.meta.url): { readonly command: string; readonly args: string[] } {
+  return { command: process.execPath, args: [fileURLToPath(new URL('../bin/deepseek.mjs', moduleUrl)), ...args] }
+}
+
+/**
+ * Split a streamed chunk sequence into complete display lines: CR is
+ * stripped, a chunk boundary may split a line, and the trailing partial
+ * stays pending until its newline arrives (npm writes whole lines, but a
+ * pipe may cut anywhere). Blank lines carry no progress information and
+ * are dropped so the panel budget is not spent on gaps.
+ */
+export function createLineSplitter(onLine: (line: string) => void): (chunk: string) => void {
+  let pending = ''
+  return chunk => {
+    pending += chunk
+    for (let index = pending.indexOf('\n'); index >= 0; index = pending.indexOf('\n')) {
+      const line = pending.slice(0, index).replace(/\r$/u, '')
+      pending = pending.slice(index + 1)
+      if (line !== '') onLine(line)
+    }
+  }
+}
+
+/**
+ * Probe the aligned update status. Read-only: `update --json` never
+ * installs anything. The probe is bounded (npm view may hang on a broken
+ * network) and resolves with the parsed status.
+ */
+export async function probeLauncherUpdate(spawnProcess: SpawnLike = spawn as SpawnLike): Promise<LauncherUpdateStatus> {
+  const command = launcherUpdateCommand(['update', '--json'])
+  return await new Promise((resolve, reject) => {
+    const child = spawnProcess(command.command, command.args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    const timer = setTimeout(() => {
+      child.kill()
+      reject(new Error('update probe timed out'))
+    }, 30_000)
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+    child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+    child.once('error', error => {
+      clearTimeout(timer)
+      reject(new Error(`update probe failed to start: ${error.message}`))
+    })
+    child.once('exit', code => {
+      clearTimeout(timer)
+      if (code === 0) {
+        try {
+          resolve(JSON.parse(stdout) as LauncherUpdateStatus)
+        } catch {
+          reject(new Error('update probe returned an unreadable status'))
+        }
+        return
+      }
+      const tail = stderr.trim().split(/\r?\n/u).pop() ?? ''
+      reject(new Error(`update probe failed${tail === '' ? '' : `: ${tail}`}`))
+    })
+  })
+}
+
+/**
+ * Run the aligned update (`update --apply`) as a child process and stream
+ * its sanitized progress lines to the caller. Resolves with the child
+ * exit code (0 success); rejects only when the process could not start.
+ * No timeout: an npm install may legitimately take minutes.
+ */
+export function applyLauncherUpdate(onLine: (line: string) => void, spawnProcess: SpawnLike = spawn as SpawnLike): Promise<number> {
+  const command = launcherUpdateCommand(['update', '--apply'])
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(command.command, command.args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    const split = createLineSplitter(onLine)
+    child.stdout?.on('data', (chunk: Buffer) => { split(chunk.toString()) })
+    child.stderr?.on('data', (chunk: Buffer) => { split(chunk.toString()) })
+    child.once('error', error => {
+      reject(new Error(`update failed to start: ${error.message}`))
+    })
+    // 'close' fires once the stdio streams have ended, so a final line the
+    // child left without its newline still reaches the panel; a bare '\n'
+    // flushes any pending partial without adding a blank row.
+    child.once('close', (code, signal) => {
+      split('\n')
+      resolve(code ?? (signal === null ? 0 : 1))
+    })
+  })
+}