deepseek-web-retrieval 0.2.0 → 0.4.0

package/src/core/transport.ts

@@ -0,0 +1,253 @@
+import { MAX_ERROR_BODY_CHARS, MAX_RESPONSE_BYTES, MAX_RETRY_DELAY_MS } from "./constants"
+import { formatApiError, formatTimeoutError, redactSecrets, truncate } from "./format"
+import type { RequestAuth, RetryOptions } from "./types"
+
+/** Everything one POST needs; `fetchImpl` is injectable so tests need no monkey-patching. */
+export interface TransportOptions {
+  readonly signal: AbortSignal
+  readonly auth: RequestAuth
+  readonly retry: RetryOptions
+  readonly timeoutMs: number
+  readonly fetchImpl?: typeof fetch
+}
+
+export class DeepSeekApiError extends Error {
+  readonly operation: string
+  readonly status: number
+  readonly body: string
+  readonly retryable: boolean
+  readonly retryAfterMs?: number
+
+  constructor(input: {
+    operation: string
+    status: number
+    body: string
+    retryAfterMs?: number
+  }) {
+    const body = redactSecrets(input.body)
+    super(formatApiError(input.operation, input.status, body))
+    this.name = "DeepSeekApiError"
+    this.operation = input.operation
+    this.status = input.status
+    this.body = body
+    this.retryable =
+      input.status === 408 ||
+      input.status === 425 ||
+      input.status === 429 ||
+      (input.status >= 500 && input.status <= 599)
+    this.retryAfterMs = input.retryAfterMs
+  }
+}
+
+export async function postJson<T>(
+  endpoint: string,
+  body: unknown,
+  operation: string,
+  opts: TransportOptions,
+): Promise<T> {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch
+  const attempts = opts.retry.maxRetries + 1
+  let lastError: unknown
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await requestOnce<T>(endpoint, body, operation, opts, fetchImpl)
+    } catch (error) {
+      lastError = error
+      if (!(error instanceof DeepSeekApiError) || !error.retryable || attempt === attempts - 1) {
+        throw error
+      }
+      await sleep(retryDelay(error.retryAfterMs, opts.retry.baseDelayMs, attempt), opts.signal)
+    }
+  }
+
+  throw lastError
+}
+
+async function requestOnce<T>(
+  endpoint: string,
+  body: unknown,
+  operation: string,
+  opts: TransportOptions,
+  fetchImpl: typeof fetch,
+): Promise<T> {
+  return fetchWithTimeout(
+    endpoint,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${opts.auth.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    },
+    opts.signal,
+    opts.timeoutMs,
+    operation,
+    fetchImpl,
+    async (response) => {
+      if (!response.ok) {
+        const text = await readBoundedText(response, MAX_ERROR_BODY_CHARS)
+        throw new DeepSeekApiError({
+          operation,
+          status: response.status,
+          body: text,
+          retryAfterMs: parseRetryAfter(response.headers.get("retry-after")),
+        })
+      }
+
+      const text = await readResponseText(response, MAX_RESPONSE_BYTES, operation)
+      if (!text.trim()) throw new Error(`${operation} returned an empty response body`)
+
+      try {
+        return JSON.parse(text) as T
+      } catch {
+        throw new Error(`${operation} returned invalid JSON: ${truncate(redactSecrets(text), 500)}`)
+      }
+    },
+  )
+}
+
+/**
+ * Runs the request and the callback that consumes its body inside one
+ * timeout/abort scope. The timer must stay active while the response body is
+ * read, otherwise a slow or stalled body can outlive the configured timeout.
+ */
+async function fetchWithTimeout<T>(
+  endpoint: string,
+  init: RequestInit,
+  signal: AbortSignal,
+  timeoutMs: number,
+  operation: string,
+  fetchImpl: typeof fetch,
+  handleResponse: (response: Response) => Promise<T>,
+): Promise<T> {
+  const controller = new AbortController()
+  let timedOut = false
+  const forwardAbort = () => controller.abort(signal.reason)
+  if (signal.aborted) forwardAbort()
+  else signal.addEventListener("abort", forwardAbort, { once: true })
+
+  const timer = signal.aborted
+    ? undefined
+    : setTimeout(() => {
+        timedOut = true
+        controller.abort(new Error("timeout"))
+      }, timeoutMs)
+
+  try {
+    const response = await fetchImpl(endpoint, { ...init, signal: controller.signal })
+    return await handleResponse(response)
+  } catch (error) {
+    if (timedOut) throw new Error(formatTimeoutError(operation, timeoutMs))
+    if (signal.aborted) throw abortReason(signal, operation)
+    throw error
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+    signal.removeEventListener("abort", forwardAbort)
+  }
+}
+
+export function parseRetryAfter(value: string | null): number | undefined {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  if (!trimmed) return undefined
+
+  if (/^\d+$/.test(trimmed)) {
+    return Math.min(MAX_RETRY_DELAY_MS, Number(trimmed) * 1000)
+  }
+
+  const timestamp = Date.parse(trimmed)
+  if (!Number.isFinite(timestamp)) return undefined
+  return Math.min(MAX_RETRY_DELAY_MS, Math.max(0, timestamp - Date.now()))
+}
+
+export function retryDelay(retryAfterMs: number | undefined, baseDelayMs: number, attempt: number): number {
+  if (retryAfterMs !== undefined) return retryAfterMs
+  return Math.min(MAX_RETRY_DELAY_MS, baseDelayMs * 2 ** attempt)
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(abortReason(signal, "DeepSeek request"))
+    }
+    if (signal.aborted) {
+      clearTimeout(timer)
+      reject(abortReason(signal, "DeepSeek request"))
+      return
+    }
+    signal.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+function abortReason(signal: AbortSignal, operation: string): unknown {
+  return signal.reason instanceof Error ? signal.reason : new Error(`${operation} request aborted`)
+}
+
+/** Reads at most `maxChars + 1` characters, enough for formatApiError to add its marker. */
+async function readBoundedText(response: Response, maxChars: number): Promise<string> {
+  if (!response.body) return truncate(await response.text(), maxChars + 1)
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  const limit = maxChars + 1
+  let text = ""
+  let chars = 0
+  try {
+    while (chars < limit) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = decoder.decode(value, { stream: true })
+      text += chunk
+      chars += Array.from(chunk).length
+    }
+    text += decoder.decode()
+  } finally {
+    await reader.cancel().catch(() => undefined)
+    reader.releaseLock()
+  }
+  return truncate(text, limit)
+}
+
+/** Reads a successful response body, rejecting payloads above `maxBytes`. */
+async function readResponseText(
+  response: Response,
+  maxBytes: number,
+  operation: string,
+): Promise<string> {
+  if (!response.body) {
+    const text = await response.text()
+    if (new TextEncoder().encode(text).byteLength > maxBytes) {
+      throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
+    }
+    return text
+  }
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let text = ""
+  let bytes = 0
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      bytes += value.byteLength
+      if (bytes > maxBytes) {
+        throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
+      }
+      text += decoder.decode(value, { stream: true })
+    }
+    text += decoder.decode()
+  } finally {
+    await reader.cancel().catch(() => undefined)
+    reader.releaseLock()
+  }
+  return text
+}

package/src/core/types.ts

@@ -15,7 +15,7 @@ export interface SearchOptions {
   readonly language?: string
   readonly maxSummaryChars: number
   readonly timeoutMs: number
-  readonly setDefault: boolean
+  readonly enabled: boolean
 }
 
 export interface FetchOptions {
@@ -23,9 +23,8 @@ export interface FetchOptions {
   readonly allowedDomains: readonly string[]
   readonly blockedDomains: readonly string[]
   readonly timeoutMs: number
-  readonly overrideWebfetch: boolean
-  readonly registerTool: boolean
   readonly blockPrivateHosts: boolean
+  readonly enabled: boolean
 }
 
 export interface AuthOptions {
@@ -54,12 +53,12 @@ export interface DeepSeekSearchResult {
   readonly date?: string | null
 }
 
-/** Matches the OpenCode v2 WebSearch.Result shape. */
-export interface WebSearchResult {
+/** A neutral, host-agnostic search result. */
+export interface SearchResult {
   readonly url: string
   readonly title?: string
   readonly content?: string
-  readonly time: { readonly published?: number }
+  readonly published?: number
 }
 
 export interface FetchedPage {
@@ -73,11 +72,14 @@ export interface FormattedFetchContent {
   readonly truncated: boolean
 }
 
-export interface RequestAuth {
-  readonly apiKey: string
+/** A fetched page formatted for the model, with truncation reported. */
+export interface FetchedDocument {
+  readonly url: string
+  readonly title: string
+  readonly content: string
+  readonly truncated: boolean
 }
 
-export interface RetryConfig {
-  readonly maxRetries: number
-  readonly baseDelayMs: number
+export interface RequestAuth {
+  readonly apiKey: string
 }

package/src/installer/apply.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from "node:fs"
+import { codecFor, writeConfig } from "./formats"
+import { deepEqual, valueAt } from "./formats/value"
+import { revertRecordedFile } from "./revert"
+import { readRecord, writeRecord } from "./state"
+import type { ConfigOp, FileEdit, InstallPlan, InstallRecord, InstallerInput, RecordedFile } from "./types"
+
+export interface ApplyResult {
+  readonly lines: string[]
+  readonly ok: boolean
+}
+
+interface PreparedEdit {
+  readonly edit: FileEdit
+  readonly recorded: RecordedFile
+  readonly write: () => void
+}
+
+/**
+ * Applies a plan: refuses first when the config drifted since the plan was
+ * rendered (the plan and the record must describe one plan-time snapshot —
+ * ADR-0001), prepares every edit in memory (a malformed existing config fails
+ * before any file is written), writes the files, reverts artifacts orphaned by
+ * a tier change, records surgical-undo state, and verifies the result.
+ */
+export function applyPlan(plan: InstallPlan, input: InstallerInput): ApplyResult {
+  if (plan.errors.length > 0) {
+    throw new Error(`refusing to apply a plan with errors: ${plan.errors.map((error) => error.message).join("; ")}`)
+  }
+  assertNoDrift(plan)
+  const previous = readRecord(input)
+  const prepared = plan.edits.map((edit) => prepareEdit(edit, plan.host))
+  const files: RecordedFile[] = []
+  const lines: string[] = []
+  for (const item of prepared) {
+    item.write()
+    files.push(mergeRecorded(item.recorded, previous?.files.find((file) => file.file === item.edit.file)))
+    lines.push(`${item.recorded.created ? "created" : "updated"} ${item.edit.file}`)
+  }
+  if ((plan.reverts ?? []).length > 0) {
+    lines.push(...applyReverts(plan))
+  }
+  const record: InstallRecord = {
+    version: 1,
+    host: plan.host,
+    scope: plan.scope,
+    tiers: plan.tiers,
+    createdAt: new Date().toISOString(),
+    files,
+  }
+  writeRecord(input, record)
+  const verification = verifyEdits(plan.edits, plan.host)
+  lines.push(...verification.lines)
+  return { lines, ok: verification.ok }
+}
+
+/**
+ * ADR-0001: every set op the plan previewed must still find the value it showed.
+ * A file that changed between plan review and apply refuses the whole apply with
+ * re-run guidance, so an interim user edit is never silently overwritten and the
+ * record's snapshots stay provably equal to what the user approved.
+ */
+function assertNoDrift(plan: InstallPlan): void {
+  const drifts: string[] = []
+  for (const edit of plan.edits) {
+    if (edit.format === "rules") continue
+    const loaded = codecFor(edit.format, plan.host).load(edit.file)
+    if (loaded.parseError) {
+      drifts.push(`${edit.file} no longer parses (${loaded.parseError})`)
+      continue
+    }
+    for (const op of edit.ops) {
+      if (op.op !== "set") continue
+      const current = valueAt(loaded.value, op.path)
+      if (!deepEqual(current, op.previous)) {
+        drifts.push(`${edit.file}: ${op.path.join(".")} changed since the plan was rendered`)
+      }
+    }
+  }
+  if (drifts.length > 0) {
+    throw new Error(
+      `refusing to apply — the config changed since the plan was rendered: ${drifts.join("; ")}. ` +
+        "Re-run init to re-plan against the current files.",
+    )
+  }
+}
+
+function prepareEdit(edit: FileEdit, host: InstallPlan["host"]): PreparedEdit {
+  const codec = codecFor(edit.format, host)
+  const loaded = codec.load(edit.file)
+  if (loaded.parseError) {
+    throw new Error(`${edit.file} does not parse: ${loaded.parseError}`)
+  }
+  const applied = codec.apply(loaded.text, edit)
+  const recorded: RecordedFile =
+    edit.format === "rules"
+      ? { file: edit.file, format: "rules", created: !loaded.exists, ops: [], blockApplied: edit.block }
+      : { file: edit.file, format: edit.format, created: !loaded.exists, ops: applied.recorded, createdParents: applied.createdParents }
+  return {
+    edit,
+    recorded,
+    write: () => writeConfig(edit.file, applied.text),
+  }
+}
+
+/**
+ * Reverts artifacts from a superseded init: shown in the plan, undone here, gone
+ * from the record. Files the new plan still claims revert partially (never
+ * deleted); files it no longer wants revert wholly and are deleted when the
+ * installer created them and they are left empty.
+ */
+function applyReverts(plan: InstallPlan): string[] {
+  const lines: string[] = []
+  for (const revert of plan.reverts ?? []) {
+    const whole = !plan.edits.some((edit) => edit.file === revert.file)
+    lines.push(...revertRecordedFile(revert, plan.host, { label: " (previous init)", whole }))
+  }
+  return lines
+}
+
+/**
+ * Merges a re-apply with the record it supersedes: a set op whose previous value is
+ * what an earlier run applied inherits that run's snapshot, appended arrays
+ * accumulate, and the created flag keeps the first install's truth.
+ */
+function mergeRecorded(current: RecordedFile, before: RecordedFile | undefined): RecordedFile {
+  if (before === undefined) return current
+  const ops = current.ops.map((op) => {
+    const old = before.ops.find((candidate) => candidate.op === op.op && candidate.path.join("\u0000") === op.path.join("\u0000"))
+    if (old === undefined) return op
+    if (op.op === "set" && old.op === "set" && deepEqual(op.previous, old.applied)) {
+      return { ...op, previous: old.previous }
+    }
+    if (op.op === "append-array" && old.op === "append-array") {
+      return { ...op, applied: [...(old.applied as unknown[]), ...(op.applied as unknown[])] }
+    }
+    return op
+  })
+  return {
+    ...current,
+    created: before.created,
+    ops,
+    createdParents: [...(before.createdParents ?? []), ...(current.createdParents ?? [])],
+  }
+}
+
+function verifyEdits(edits: readonly FileEdit[], host: InstallPlan["host"]): { lines: string[]; ok: boolean } {
+  const lines: string[] = []
+  let ok = true
+  for (const edit of edits) {
+    if (!existsSync(edit.file)) {
+      lines.push(`FAIL ${edit.file} does not exist after apply`)
+      ok = false
+      continue
+    }
+    const codec = codecFor(edit.format, host)
+    const text = readFileSync(edit.file, "utf8")
+    if (edit.format === "rules") {
+      const good = codec.verify(text, edit)
+      lines.push(`${good ? "pass" : "FAIL"} ${edit.file}: rules block ${good ? "present" : "missing"}`)
+      ok = ok && good
+      continue
+    }
+    for (const op of edit.ops) {
+      const good = codec.verify(text, edit, op)
+      lines.push(`${good ? "pass" : "FAIL"} ${edit.file}: ${describeOp(op)} ${good ? "holds" : "missing"}`)
+      ok = ok && good
+    }
+  }
+  return { lines, ok }
+}
+
+function describeOp(op: ConfigOp): string {
+  if (op.op === "set") return `set ${op.path.join(".")}`
+  return `append ${op.path.join(".")}`
+}

package/src/installer/cli.ts

@@ -0,0 +1,215 @@
+import { homedir } from "node:os"
+import { resolve } from "node:path"
+import { HOST_PLANNERS, planForHost } from "./hosts"
+import { applyPlan } from "./apply"
+import { renderPlan } from "./render"
+import { listRecords } from "./state"
+import { uninstall } from "./uninstall"
+import type { HostName, InstallerInput, Scope, Tier } from "./types"
+
+const HOSTS = Object.keys(HOST_PLANNERS) as readonly HostName[]
+const HOST_CHOICES = `<${HOSTS.join("|")}>`
+const SCOPES: readonly Scope[] = ["project", "global"]
+const TIERS: readonly Tier[] = ["optional", "preferred", "forced", "off"]
+
+const USAGE = `Usage:
+  deepseek-web-retrieval init --host ${HOST_CHOICES} --scope <project|global> \
+--search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off> \
+[--package <npm ref>] [--cwd <dir>] [--apply]
+  deepseek-web-retrieval uninstall --host ${HOST_CHOICES} --scope <project|global> [--cwd <dir>]
+  deepseek-web-retrieval list [--cwd <dir>]
+
+init prints the full plan (every file, old value → new value) and writes nothing
+until --apply is passed. uninstall restores what the plan applied.`
+
+interface Flags {
+  readonly values: Map<string, string>
+  readonly booleans: Set<string>
+  readonly problems: readonly string[]
+}
+
+const VALUE_FLAGS = new Set(["host", "scope", "search", "fetch", "package", "cwd"])
+const BOOLEAN_FLAGS = new Set(["apply"])
+
+function parseFlags(args: readonly string[]): Flags {
+  const values = new Map<string, string>()
+  const booleans = new Set<string>()
+  const problems: string[] = []
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] as string
+    if (!arg.startsWith("--")) {
+      problems.push(`unexpected argument "${arg}" (flags only)`)
+      continue
+    }
+    const eq = arg.indexOf("=")
+    const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+    if (BOOLEAN_FLAGS.has(name)) {
+      booleans.add(name)
+      continue
+    }
+    if (!VALUE_FLAGS.has(name)) {
+      problems.push(`unknown flag --${name}`)
+      continue
+    }
+    if (eq !== -1) {
+      values.set(name, arg.slice(eq + 1))
+      continue
+    }
+    const next = args[i + 1]
+    if (next === undefined || next.startsWith("--")) {
+      problems.push(`--${name} requires a value`)
+      continue
+    }
+    values.set(name, next)
+    i += 1
+  }
+  return { values, booleans, problems }
+}
+
+/** Where the CLI writes; injectable so tests can assert command output. */
+export interface CliIo {
+  readonly out?: (line: string) => void
+  readonly err?: (line: string) => void
+}
+
+/** CLI entry for the init/uninstall/list subcommands; returns the process exit code. */
+export async function runInstallerCli(argv: readonly string[], io: CliIo = {}): Promise<number> {
+  const out = io.out ?? ((line: string) => console.log(line))
+  const err = io.err ?? ((line: string) => console.error(line))
+  const [command, ...rest] = argv
+  if (command === undefined || command === "help" || command === "--help") {
+    out(USAGE)
+    return command === undefined ? 1 : 0
+  }
+  const flags = parseFlags(rest)
+  if (flags.problems.length > 0) {
+    for (const problem of flags.problems) err(`error: ${problem}`)
+    err(`\n${USAGE}`)
+    return 1
+  }
+  const cwd = resolve(flags.values.get("cwd") ?? process.cwd())
+  const home = process.env.HOME ?? homedir()
+  const configHome = resolveConfigHome(home)
+
+  if (command === "list") {
+    const records = listRecords({ home, cwd, configHome })
+    if (records.length === 0) {
+      out("No installs recorded.")
+      return 0
+    }
+    for (const record of records) {
+      out(`${record.host} (${record.scope}) — search=${record.tiers.search}, fetch=${record.tiers.fetch}, installed ${record.createdAt}`)
+      for (const file of record.files) out(`  ${file.created ? "created" : "modified"} ${file.file}`)
+    }
+    return 0
+  }
+
+  if (command === "uninstall") {
+    const required = requireInput(flags, cwd, home, configHome, false)
+    if (!required.ok) return usageError(required.problems, err)
+    try {
+      for (const line of uninstall(required.input)) out(line)
+      return 0
+    } catch (error) {
+      err(error instanceof Error ? error.message : String(error))
+      return 1
+    }
+  }
+
+  if (command !== "init") {
+    err(`Unknown command "${command}".\n\n${USAGE}`)
+    return 1
+  }
+
+  const required = requireInput(flags, cwd, home, configHome, true)
+  if (!required.ok) return usageError(required.problems, err)
+  const { input } = required
+  const plan = planForHost(input.host, input)
+  if (plan.errors.length > 0) {
+    for (const error of plan.errors) err(`error: ${error.message}`)
+    err("Nothing was written.")
+    return 1
+  }
+  out(renderPlan(plan))
+  if (!flags.booleans.has("apply")) {
+    out("\nPlan only — re-run with --apply to write these changes.")
+    return 0
+  }
+  try {
+    const result = applyPlan(plan, input)
+    for (const line of result.lines) out(line)
+    return result.ok ? 0 : 1
+  } catch (error) {
+    err(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}
+
+function usageError(problems: readonly string[], err: (line: string) => void): number {
+  for (const problem of problems) err(`error: ${problem}`)
+  err(`\n${USAGE}`)
+  return 1
+}
+
+/**
+ * XDG_CONFIG_HOME is honored only when it belongs to the real home; the one
+ * environment read happens here, at the edge, and flows down as explicit input.
+ */
+function resolveConfigHome(home: string): string | undefined {
+  const xdg = process.env.XDG_CONFIG_HOME
+  if (xdg && home === (process.env.HOME ?? "")) return xdg
+  return undefined
+}
+
+type RequireInputResult =
+  | { readonly ok: true; readonly input: InstallerInput }
+  | { readonly ok: false; readonly problems: readonly string[] }
+
+function requireInput(
+  flags: Flags,
+  cwd: string,
+  home: string,
+  configHome: string | undefined,
+  needsTiers: boolean,
+): RequireInputResult {
+  const problems: string[] = []
+  const host = flags.values.get("host")
+  const scope = flags.values.get("scope")
+  const search = needsTiers ? (flags.values.get("search") ?? "") : "optional"
+  const fetch = needsTiers ? (flags.values.get("fetch") ?? "") : "optional"
+  if (host === undefined) problems.push(`--host is required (one of: ${HOSTS.join(", ")})`)
+  else if (!HOSTS.includes(host as HostName)) problems.push(`invalid --host value "${host}" (one of: ${HOSTS.join(", ")})`)
+  if (scope === undefined) problems.push(`--scope is required (one of: ${SCOPES.join(", ")})`)
+  else if (!SCOPES.includes(scope as Scope)) problems.push(`invalid --scope value "${scope}" (one of: ${SCOPES.join(", ")})`)
+  if (needsTiers) {
+    if (!TIERS.includes(search as Tier)) {
+      problems.push(
+        flags.values.has("search")
+          ? `invalid --search value "${search}" (one of: ${TIERS.join(", ")})`
+          : `--search is required (one of: ${TIERS.join(", ")})`,
+      )
+    }
+    if (!TIERS.includes(fetch as Tier)) {
+      problems.push(
+        flags.values.has("fetch")
+          ? `invalid --fetch value "${fetch}" (one of: ${TIERS.join(", ")})`
+          : `--fetch is required (one of: ${TIERS.join(", ")})`,
+      )
+    }
+  }
+  if (home === "") problems.push("HOME is not set and the user home cannot be resolved; cannot proceed")
+  if (problems.length > 0) return { ok: false, problems }
+  return {
+    ok: true,
+    input: {
+      host: host as HostName,
+      scope: scope as Scope,
+      search: search as Tier,
+      fetch: fetch as Tier,
+      packageRef: flags.values.get("package") ?? "deepseek-web-retrieval",
+      home,
+      cwd,
+      configHome,
+    },
+  }
+}