deepseek-web-retrieval 0.2.0 → 0.3.0

package/src/installer/hosts/codex.ts

@@ -0,0 +1,128 @@
+import { codecFor } from "../formats"
+import { isPlainObject } from "../formats/value"
+import {
+  FORCED_COST_NOTE,
+  othersStayRegisteredNote,
+  replacingExistingEntryNote,
+  splitCompetitors,
+} from "../detect"
+import { join } from "../paths"
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../../core/constants"
+import { buildRulesBlock } from "../formats/rules"
+import { MCP_TOOL_IDS, rulesLines } from "../rulesContent"
+import { planHeader } from "./shared"
+import type { ConfigOp, FileEdit, HostPaths, InstallRecord, InstallerInput, InstallPlan } from "../types"
+
+/** Codex config is user-level only; project scope keeps the rules file project-local. */
+function codexPaths(input: InstallerInput): HostPaths {
+  return {
+    config: join(input.home, ".codex/config.toml"),
+    rules: input.scope === "global" ? join(input.home, ".codex/AGENTS.md") : join(input.cwd, "AGENTS.md"),
+  }
+}
+
+export function planCodex(input: InstallerInput, _previous: InstallRecord | undefined): InstallPlan {
+  const paths = codexPaths(input)
+  const loaded = codecFor("toml", input.host).load(paths.config)
+  const tiers = { search: input.search, fetch: input.fetch }
+  const header = planHeader(input, paths, loaded, "TOML")
+  if (header.abort) {
+    return { host: "codex", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors }
+  }
+  const notes = [...header.notes]
+  const errors = [...header.errors]
+  const edits: FileEdit[] = []
+
+  const tools = loaded.value.tools
+  if (isPlainObject(tools) && "web_search" in tools) {
+    errors.push({
+      message:
+        `${paths.config} sets [tools] web_search, which is a silent no-op at Codex 0.163.0 (only the top-level ` +
+        "web_search key controls the tool). Remove it first so the config cannot mislead.",
+    })
+  }
+
+  const servers = loaded.value.mcp_servers
+  if (isPlainObject(servers)) {
+    if ("deepseek" in servers) notes.push(replacingExistingEntryNote("mcp_servers.deepseek"))
+    const { competitors, bystanders } = splitCompetitors(servers)
+    if ((input.search === "forced" || input.fetch === "forced") && competitors.length > 0) {
+      // Codex has no per-server kill switch (only per-tool enabled_tools/disabled_tools
+      // inside a server), so a web-capable competitor cannot be excluded from the plan —
+      // refuse the tier instead of promising routing that is not actually forced.
+      errors.push({
+        message:
+          `Forced cannot deliver exclusive routing: [mcp_servers.${competitors.join("], [mcp_servers.")}] look(s) web-capable, ` +
+          "and Codex offers no per-server kill switch. Remove the server(s), disable their tools by hand via their " +
+          "disabled_tools key, or choose a lower tier.",
+      })
+    }
+    const stayRegistered = input.search === "forced" || input.fetch === "forced" ? bystanders : [...competitors, ...bystanders]
+    if (stayRegistered.length > 0) notes.push(othersStayRegisteredNote(stayRegistered))
+  }
+
+  const env: Record<string, string> = {}
+  if (input.search === "off") env[ENABLE_SEARCH_ENV] = "false"
+  if (input.fetch === "off") env[ENABLE_FETCH_ENV] = "false"
+  const entry = {
+    command: "npx",
+    args: ["-y", input.packageRef],
+    ...(Object.keys(env).length > 0 ? { env } : {}),
+    env_vars: [API_KEY_ENV],
+  }
+
+  const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined
+  const ops: ConfigOp[] = [
+    { op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry },
+  ]
+  if (input.search === "forced") {
+    const previous = typeof loaded.value.web_search === "string" ? loaded.value.web_search : undefined
+    ops.push({ op: "set", path: ["web_search"], value: "disabled", previous })
+    notes.push(
+      previous === undefined
+        ? "web_search is being set to \"disabled\" (no previous value existed; the default is \"cached\")."
+        : `web_search is being set to "disabled"; the previous value "${previous}" is snapshotted for uninstall.`,
+    )
+  }
+  edits.push({ file: paths.config, format: "toml", ops })
+
+  notes.push(
+    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} explicitly ` +
+      "via env_vars; the key must be set in the shell that launches Codex.",
+  )
+  if (input.scope === "project") {
+    notes.push(
+      "Codex config lives in ~/.codex/config.toml only (user level), so the server registration and kill switch are " +
+        "written there even for a project-scope install; the rules file stays project-local.",
+    )
+  }
+  if (loaded.lossy) {
+    notes.push(`${paths.config} contains comments; the TOML rewrite will drop them.`)
+  }
+  if (input.search === "forced" || input.fetch === "forced") {
+    notes.push(
+      'Forced search is exclusion: the built-in web_search tool is disabled ("disabled" mode). ' + FORCED_COST_NOTE,
+    )
+  }
+  if (input.search === "optional" || input.fetch === "optional") {
+    notes.push(
+      'Note: Codex ships a built-in web_search tool (default "cached" mode, an OpenAI index) that stays available ' +
+        "alongside the DeepSeek tools under the optional tier.",
+    )
+  }
+
+  if (input.search === "preferred" || input.fetch === "preferred") {
+    edits.push({
+      file: paths.rules,
+      format: "rules",
+      block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
+    })
+    notes.push(
+      input.scope === "global"
+        ? `Rules block upserted in ${paths.rules}; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.`
+        : `Rules block upserted in ${paths.rules}; Codex reads every AGENTS.md from the project root to the cwd.`,
+    )
+  }
+
+  return { host: "codex", scope: input.scope, tiers, edits, notes, errors }
+}

package/src/installer/hosts/index.ts

@@ -0,0 +1,134 @@
+import { planCodex } from "./codex"
+import { planOpenCode } from "./opencode"
+import { planPi } from "./pi"
+import { API_KEY_ENV } from "../../core/constants"
+import { claimedByOtherScope, readRecord } from "../state"
+import type { HostName, InstallRecord, InstallerInput, InstallPlan, RecordedFile } from "../types"
+
+/**
+ * A host planner sees the previous install record for its scope, so it never reads
+ * install state itself; planForHost is the one place a record read happens per plan.
+ */
+export type HostPlanner = (input: InstallerInput, previous: InstallRecord | undefined) => InstallPlan
+
+/**
+ * The host registry. Key order feeds the CLI's usage string; a new host is one
+ * module, one line here, one HostName union member, and one hosts.jsonc row
+ * carrying the installer field — the two guards in test/hosts.test.ts hold all
+ * four in sync.
+ */
+export const HOST_PLANNERS: Readonly<Record<HostName, HostPlanner>> = {
+  opencode: planOpenCode,
+  pi: planPi,
+  codex: planCodex,
+}
+
+export function planForHost(host: HostName, input: InstallerInput): InstallPlan {
+  const previous = readRecord(input)
+  const planned = withCrossScopeGuard(HOST_PLANNERS[host](input, previous), input)
+  return withSecretGuard(withOrphanReverts(planned, input, previous))
+}
+
+/**
+ * One file must never be claimed by two scopes of the same host: Codex project-scope
+ * config falls back to ~/.codex/config.toml, so a project install beside a global one
+ * would let either uninstall clobber the other's registration. Refuse with guidance
+ * instead. Hosts whose scope pairs map to disjoint files (Pi, OpenCode) pass through.
+ */
+function withCrossScopeGuard(plan: InstallPlan, input: InstallerInput): InstallPlan {
+  if (plan.errors.length > 0) return plan
+  const other = input.scope === "global" ? "project" : "global"
+  const overlap = claimedByOtherScope(input, plan.edits.map((edit) => edit.file))
+  if (overlap.length === 0) return plan
+  return {
+    ...plan,
+    edits: [],
+    reverts: undefined,
+    errors: [
+      {
+        message:
+          `A ${plan.host} install is already recorded at the ${other} scope and claims the same file(s): ${overlap.join(", ")}. ` +
+          `Uninstall it first (deepseek-web-retrieval uninstall --host ${plan.host} --scope ${other}), ` +
+          `or re-run with --scope ${other} to update it in place — two scopes must not edit one file.`,
+      },
+    ],
+  }
+}
+
+/**
+ * Refuses to snapshot values that look like credentials: replacing an existing entry
+ * that carries a literal API key would copy that secret into the install record, so
+ * the plan errors and asks the user to move the key to environment indirection first.
+ * A pure `${VAR}` expansion is that indirection — including the form this installer
+ * itself writes — so it is allowed through and re-init over our own output works.
+ */
+function withSecretGuard(plan: InstallPlan): InstallPlan {
+  for (const edit of plan.edits) {
+    if (edit.format === "rules") continue // rules edits carry no values to snapshot
+    for (const op of edit.ops) {
+      if (op.op !== "set" || op.previous === undefined) continue
+      const offender = findSecretLike(op.previous, op.path.join("."))
+      if (offender !== undefined) {
+        return {
+          ...plan,
+          edits: [],
+          reverts: undefined,
+          errors: [
+            {
+              message:
+                `${edit.file}: the existing value at ${op.path.join(".")} contains a credential-looking key ` +
+                `(${offender}). The installer refuses to snapshot secrets into its state file. Move the key to ` +
+                `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`,
+            },
+          ],
+        }
+      }
+    }
+  }
+  return plan
+}
+
+function findSecretLike(value: unknown, at: string): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const path = `${at}.${key}`
+    if (
+      /(api[_-]?key|token|secret|password|credential)/i.test(key) &&
+      typeof child === "string" &&
+      child.length > 0 &&
+      !/^\$\{[^}]+\}$/.test(child)
+    ) {
+      return path
+    }
+    const nested = findSecretLike(child, path)
+    if (nested !== undefined) return nested
+  }
+  return undefined
+}
+
+/**
+ * A re-init supersedes the previous record, so anything the previous init applied
+ * that the new plan no longer wants must be reverted explicitly — otherwise it is
+ * silently orphaned (and uninstall could never restore it). Whole files missing
+ * from the new plan revert entirely; files shared with the new plan revert only
+ * the ops whose paths the new plan does not touch.
+ */
+function withOrphanReverts(plan: InstallPlan, input: InstallerInput, previous: InstallRecord | undefined): InstallPlan {
+  if (plan.errors.length > 0) return plan
+  if (previous === undefined) return plan
+  const reverts: RecordedFile[] = []
+  for (const file of previous.files) {
+    const edit = plan.edits.find((candidate) => candidate.file === file.file)
+    if (edit === undefined) {
+      reverts.push(file)
+      continue
+    }
+    if (edit.format === "rules" || file.format === "rules") continue // the new plan's block supersedes ours
+    const orphanOps = file.ops.filter(
+      (op) => !edit.ops.some((candidate) => candidate.op === op.op && candidate.path.join("\u0000") === op.path.join("\u0000")),
+    )
+    if (orphanOps.length > 0) reverts.push({ ...file, ops: orphanOps })
+  }
+  if (reverts.length === 0) return plan
+  return { ...plan, reverts }
+}

package/src/installer/hosts/opencode.ts

@@ -0,0 +1,118 @@
+import { codecFor } from "../formats"
+import { isPlainObject } from "../formats/value"
+import { FORCED_COST_NOTE } from "../detect"
+import { configHome, join } from "../paths"
+import { buildRulesBlock } from "../formats/rules"
+import { rulesLines } from "../rulesContent"
+import { planHeader } from "./shared"
+import type { ConfigOp, FileEdit, HostPaths, InstallRecord, InstallerInput, InstallPlan } from "../types"
+
+/** OpenCode's tools are named differently from the raw MCP ids. */
+const OPENCODE_TOOL_IDS = { search: "websearch (provider deepseek)", fetch: "deepseek_fetch" } as const
+
+/** OpenCode config and rules files per scope; the host module owns this mapping. */
+function opencodePaths(input: InstallerInput): HostPaths {
+  return input.scope === "global"
+    ? { config: join(configHome(input), "opencode/opencode.jsonc"), rules: join(configHome(input), "opencode/AGENTS.md") }
+    : { config: join(input.cwd, "opencode.jsonc"), rules: join(input.cwd, "AGENTS.md") }
+}
+
+export function planOpenCode(input: InstallerInput, previous: InstallRecord | undefined): InstallPlan {
+  const paths = opencodePaths(input)
+  const loaded = codecFor("json", input.host).load(paths.config)
+  const tiers = { search: input.search, fetch: input.fetch }
+  const header = planHeader(input, paths, loaded, "JSONC")
+  if (header.abort) {
+    return { host: "opencode", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors }
+  }
+  const notes = [...header.notes]
+  const errors = [...header.errors]
+  const edits: FileEdit[] = []
+
+  if (input.search === "preferred") {
+    errors.push({
+      message:
+        "OpenCode search has no preferred tier: the websearch provider is host-level config, so the model never " +
+        "chooses between engines. Use --search optional (provider registered, built-in stays default), " +
+        "--search forced (replace the engine), or --search off.",
+    })
+  }
+
+  const plugins = Array.isArray(loaded.value.plugins) ? loaded.value.plugins : []
+  const alreadyInstalled = plugins.some(
+    (entry) => isPlainObject(entry) && typeof entry.package === "string" && entry.package.includes("deepseek-web-retrieval"),
+  )
+  if (alreadyInstalled && previous === undefined) {
+    errors.push({
+      message:
+        `${paths.config} already has a plugins entry referencing deepseek-web-retrieval that this installer did not ` +
+        "write. Remove it (or run uninstall if it came from a previous init), then retry.",
+    })
+  }
+  if (alreadyInstalled && errors.length === 0) {
+    notes.push("A previous init wrote the plugins entry; re-applying updates it and carries the original snapshots over.")
+  }
+  if (errors.length > 0) {
+    return { host: "opencode", scope: input.scope, tiers, edits, notes, errors }
+  }
+
+  const options: Record<string, unknown> = {}
+  if (input.search === "forced") options.setDefaultWebsearch = true
+  if (input.search === "off") options.searchEnabled = false
+  if (input.fetch === "forced") options.fetchOverrideWebfetch = true
+  if (input.fetch === "off") options.fetchEnabled = false
+
+  const ops: ConfigOp[] = [
+    {
+      op: "append-array",
+      path: ["plugins"],
+      entries: [{ package: input.packageRef, options }],
+      existingCount: plugins.length,
+    },
+  ]
+
+  const permissions: Record<string, unknown>[] = []
+  if (input.search !== "off") permissions.push({ action: "websearch", resource: "*", effect: "allow" })
+  if (input.fetch !== "off") permissions.push({ action: "deepseek_fetch", resource: "*", effect: "allow" })
+  if (input.fetch === "forced") permissions.push({ action: "webfetch", resource: "*", effect: "allow" })
+  const existingPermissions = Array.isArray(loaded.value.permissions) ? loaded.value.permissions.length : 0
+  if (permissions.length > 0) {
+    ops.push({ op: "append-array", path: ["permissions"], entries: permissions, existingCount: existingPermissions })
+  }
+
+  if (input.search === "forced") {
+    const currentProvider = isPlainObject(loaded.value.websearch) ? loaded.value.websearch.provider : undefined
+    ops.push({ op: "set", path: ["websearch", "provider"], value: "deepseek", previous: currentProvider })
+    notes.push(
+      currentProvider === undefined
+        ? "websearch.provider is being set to deepseek (no previous value existed)."
+        : `websearch.provider is being set to deepseek; the previous value "${String(currentProvider)}" is snapshotted for uninstall.`,
+    )
+  }
+
+  edits.push({ file: paths.config, format: "json", ops })
+
+  notes.push(
+    "The plugin entry uses the object form so options are honored; auto-discovered plugins cannot receive options.",
+  )
+  if (input.search === "optional") {
+    notes.push(
+      "Search tier optional: the deepseek provider is registered but the built-in provider stays the default engine; " +
+        "set websearch.provider to deepseek (or rerun with --search forced) to route search through DeepSeek.",
+    )
+  }
+  if (input.search === "forced" || input.fetch === "forced") {
+    notes.push("Forced tier replaces built-in routing. " + FORCED_COST_NOTE)
+  }
+
+  if (input.fetch === "preferred") {
+    edits.push({
+      file: paths.rules,
+      format: "rules",
+      block: buildRulesBlock(input.host, rulesLines(OPENCODE_TOOL_IDS, input.search, input.fetch)),
+    })
+    notes.push(`Rules block upserted in ${paths.rules}; OpenCode loads AGENTS.md only (no CLAUDE.md fallback in v2).`)
+  }
+
+  return { host: "opencode", scope: input.scope, tiers, edits, notes, errors }
+}

package/src/installer/hosts/pi.ts

@@ -0,0 +1,115 @@
+import { codecFor } from "../formats"
+import { isPlainObject } from "../formats/value"
+import {
+  FORCED_COST_NOTE,
+  othersStayRegisteredNote,
+  replacingExistingEntryNote,
+  splitCompetitors,
+} from "../detect"
+import { join } from "../paths"
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../../core/constants"
+import { buildRulesBlock } from "../formats/rules"
+import { MCP_TOOL_IDS, rulesLines } from "../rulesContent"
+import { planHeader } from "./shared"
+import type { ConfigOp, FileEdit, HostPaths, InstallRecord, InstallerInput, InstallPlan } from "../types"
+
+/** Pi config and rules files per scope; the host module owns this mapping. */
+function piPaths(input: InstallerInput): HostPaths {
+  return input.scope === "global"
+    ? { config: join(input.home, ".pi/agent/mcp.json"), rules: join(input.home, ".pi/agent/AGENTS.md") }
+    : { config: join(input.cwd, ".pi/mcp.json"), rules: join(input.cwd, "AGENTS.md") }
+}
+
+export function planPi(input: InstallerInput, _previous: InstallRecord | undefined): InstallPlan {
+  const paths = piPaths(input)
+  const loaded = codecFor("json", input.host).load(paths.config)
+  const tiers = { search: input.search, fetch: input.fetch }
+  const header = planHeader(input, paths, loaded, "JSON")
+  if (header.abort) {
+    return { host: "pi", scope: input.scope, tiers, edits: [], notes: header.notes, errors: header.errors }
+  }
+  const notes = [...header.notes]
+  const errors = [...header.errors]
+  const edits: FileEdit[] = []
+
+  const env: Record<string, string> = { [API_KEY_ENV]: `\${${API_KEY_ENV}}` }
+  if (input.search === "off") env[ENABLE_SEARCH_ENV] = "false"
+  if (input.fetch === "off") env[ENABLE_FETCH_ENV] = "false"
+  const entry = {
+    command: "npx",
+    args: ["-y", input.packageRef],
+    env,
+    exposure: "direct",
+    enabled: true,
+  }
+
+  const servers = loaded.value.mcpServers
+  const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined
+  const ops: ConfigOp[] = [
+    { op: "set", path: ["mcpServers", "deepseek"], value: entry, previous: existingEntry },
+  ]
+  edits.push({ file: paths.config, format: "json", ops })
+
+  if (isPlainObject(servers)) {
+    if (servers.deepseek !== undefined) notes.push(replacingExistingEntryNote("mcpServers.deepseek"))
+    const { competitors, bystanders } = splitCompetitors(servers)
+    const forced = input.search === "forced" || input.fetch === "forced"
+    if (forced) {
+      // Forced demands exclusivity: disable the web-capable competitors (Pi entries
+      // carry an `enabled` key), snapshotting each prior value for uninstall.
+      const excluded: string[] = []
+      const unexcludable: string[] = []
+      for (const name of competitors) {
+        const current = servers[name]
+        if (!isPlainObject(current)) {
+          unexcludable.push(name)
+          continue
+        }
+        const previous = typeof current.enabled === "boolean" ? current.enabled : undefined
+        if (previous === false) continue // already excluded
+        ops.push({ op: "set", path: ["mcpServers", name, "enabled"], value: false, previous })
+        excluded.push(name)
+      }
+      if (excluded.length > 0) {
+        notes.push(
+          `Forced tier: web-capable MCP servers are disabled so DeepSeek routing is exclusive (${excluded.join(", ")}; ` +
+            "prior enabled values are snapshotted for uninstall).",
+        )
+      }
+      if (unexcludable.length > 0) {
+        errors.push({
+          message:
+            `Forced cannot deliver exclusive routing: mcpServers entries ${unexcludable.join(", ")} look web-capable ` +
+            "but are not objects, so the plan cannot set their enabled key. Fix or remove them, or choose a lower tier.",
+        })
+      }
+    }
+    const stayRegistered = forced ? bystanders : [...competitors, ...bystanders]
+    if (stayRegistered.length > 0) notes.push(othersStayRegisteredNote(stayRegistered))
+  }
+  notes.push('"exposure": "direct" is required: Pi 1.3.0 defaults MCP tools to codemode, which hides them from the model.')
+  notes.push(
+    `\`${API_KEY_ENV}\` is written as "\${${API_KEY_ENV}}" so the key expands from the shell that launches Pi and stays out of the file.`,
+  )
+  if (loaded.lossy) {
+    notes.push(`${paths.config} contains comments; the JSON edit preserves them.`)
+  }
+
+  if (input.search === "preferred" || input.fetch === "preferred") {
+    edits.push({
+      file: paths.rules,
+      format: "rules",
+      block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
+    })
+    notes.push(`Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`)
+  }
+
+  if (input.search === "forced" || input.fetch === "forced") {
+    notes.push(
+      "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
+        FORCED_COST_NOTE,
+    )
+  }
+
+  return { host: "pi", scope: input.scope, tiers, edits, notes, errors }
+}

package/src/installer/hosts/shared.ts

@@ -0,0 +1,31 @@
+import { BOTH_CAPABILITIES_OFF, competitorSteeringNote, findCompetitorSteering } from "../detect"
+import type { LoadedConfig } from "../formats"
+import type { HostPaths, InstallerInput, PlanError } from "../types"
+
+/** What the shared plan header accumulated: notes and errors so far, and whether to stop. */
+export interface PlanHeader {
+  readonly notes: string[]
+  readonly errors: PlanError[]
+  /** True when the caller must return the (empty-edits) plan as-is. */
+  readonly abort: boolean
+}
+
+/**
+ * The plan header every host planner starts with, so the three steps cannot drift:
+ * refuse an unparsable config (aborting), refuse both capabilities off, and surface
+ * competitor steering in the rules file. Host-specific checks follow in the module.
+ */
+export function planHeader(input: InstallerInput, paths: HostPaths, loaded: LoadedConfig, dialect: string): PlanHeader {
+  const notes: string[] = []
+  const errors: PlanError[] = []
+  if (loaded.parseError) {
+    errors.push({ message: `${paths.config} exists but does not parse as ${dialect}: ${loaded.parseError}` })
+    return { notes, errors, abort: true }
+  }
+  if (input.search === "off" && input.fetch === "off") {
+    errors.push({ message: BOTH_CAPABILITIES_OFF })
+  }
+  const steering = findCompetitorSteering(input.host, paths.rules)
+  if (steering.length > 0) notes.push(competitorSteeringNote(paths.rules, steering))
+  return { notes, errors, abort: false }
+}

package/src/installer/paths.ts

@@ -0,0 +1,18 @@
+import type { FsRoots, Scope } from "./types"
+
+/** Joins path parts with "/", skipping empty segments. */
+export function join(...parts: readonly string[]): string {
+  return parts.filter((part) => part.length > 0).join("/")
+}
+
+/** Config home: an explicit root wins; otherwise ~/.config. The CLI resolves XDG at the edge. */
+export function configHome(roots: FsRoots): string {
+  return roots.configHome ?? join(roots.home, ".config")
+}
+
+/** State records live with their scope: global installs under the config home, project installs in the checkout. */
+export function stateDir(roots: FsRoots, scope: Scope): string {
+  return scope === "global"
+    ? join(configHome(roots), "deepseek-web-retrieval")
+    : join(roots.cwd, ".deepseek-web-retrieval")
+}

package/src/installer/render.ts

@@ -0,0 +1,62 @@
+import type { InstallPlan } from "./types"
+
+/** Renders a plan for review: files, ops with old→new previews, and notes. */
+export function renderPlan(plan: InstallPlan): string {
+  const lines: string[] = []
+  lines.push(`Install plan: ${plan.host} (${plan.scope} scope)`)
+  lines.push(`Tiers: search=${plan.tiers.search}, fetch=${plan.tiers.fetch}`)
+  lines.push("")
+  lines.push("Files:")
+  for (const edit of plan.edits) {
+    lines.push(`  ${edit.file}`)
+    if (edit.format === "rules") {
+      lines.push("    upsert marked rules block")
+      continue
+    }
+    for (const op of edit.ops) {
+      if (op.op === "set") {
+        const was = op.previous === undefined ? "(absent)" : preview(op.previous)
+        lines.push(`    set ${op.path.join(".")} = ${preview(op.value)} (was ${was})`)
+      } else {
+        const count = (op.entries ?? []).length
+        const kept = op.existingCount !== undefined ? ` (${op.existingCount} existing kept)` : ""
+        lines.push(`    append ${count} entr${count === 1 ? "y" : "ies"} to ${op.path.join(".")}${kept}`)
+        for (const entry of op.entries ?? []) lines.push(`      + ${preview(entry)}`)
+      }
+    }
+  }
+  if (plan.reverts && plan.reverts.length > 0) {
+    lines.push("")
+    lines.push("Reverts (artifacts from the previous init that this plan no longer wants):")
+    for (const revert of plan.reverts) {
+      lines.push(`  ${revert.file}`)
+      if (revert.format === "rules") {
+        lines.push("    remove rules block")
+        continue
+      }
+      for (const op of revert.ops) {
+        if (op.op === "set") {
+          lines.push(
+            op.previous === undefined
+              ? `    remove ${op.path.join(".")} (was not set before this install)`
+              : `    restore ${op.path.join(".")} = ${preview(op.previous)}`,
+          )
+        } else {
+          const count = Array.isArray(op.applied) ? op.applied.length : 0
+          lines.push(`    remove ${count} appended entr${count === 1 ? "y" : "ies"} from ${op.path.join(".")}`)
+        }
+      }
+    }
+  }
+  if (plan.notes.length > 0) {
+    lines.push("")
+    lines.push("Notes:")
+    for (const note of plan.notes) lines.push(`  - ${note}`)
+  }
+  return lines.join("\n")
+}
+
+function preview(value: unknown): string {
+  const text = JSON.stringify(value) ?? String(value)
+  return text.length > 100 ? `${text.slice(0, 97)}...` : text
+}

package/src/installer/revert.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync, rmdirSync, unlinkSync } from "node:fs"
+import { dirname } from "node:path"
+import { codecFor, writeConfig } from "./formats"
+import type { HostName, RecordedFile, RulesEdit } from "./types"
+
+/** Removes a directory only when it is empty, so pre-existing dirs with content stay. */
+export function pruneEmptyDir(dir: string): void {
+  try {
+    rmdirSync(dir)
+  } catch {
+    // Not empty or already gone — nothing to prune.
+  }
+}
+
+/**
+ * The single per-file revert, shared by uninstall (whole files, no label) and by
+ * a superseding plan's orphan reverts (label names the previous init; `whole` is
+ * false while the new plan still claims the file, so partial reverts never delete).
+ * Per-format work belongs to the codecs; this skeleton owns the early-outs, the
+ * deletion decisions, the pruning, and the messages.
+ */
+export function revertRecordedFile(file: RecordedFile, host: HostName, opts: { label: string; whole: boolean }): string[] {
+  const lines: string[] = []
+  if (!existsSync(file.file)) {
+    lines.push(`already absent: ${file.file}${opts.label}`)
+    return lines
+  }
+  const codec = codecFor(file.format, host)
+  const text = readFileSync(file.file, "utf8")
+  if (file.format === "rules") {
+    const edit: RulesEdit = { file: file.file, format: "rules", block: file.blockApplied ?? "" }
+    if (!codec.verify(text, edit)) {
+      lines.push(`no rules block${opts.label} in ${file.file}; left untouched`)
+      return lines
+    }
+    const updated = codec.revert(text, file).text
+    // Empty after removal proves every line in the file was an installer block;
+    // the whole-file gate keeps a still-claimed file safe even if a future
+    // planner ever produced a partial rules revert.
+    if (opts.whole && codec.isEffectivelyEmpty(updated)) {
+      unlinkSync(file.file)
+      pruneEmptyDir(dirname(file.file))
+      lines.push(`deleted ${file.file} (installer-created, now empty)`)
+    } else {
+      writeConfig(file.file, updated)
+      lines.push(`removed rules block${opts.label} from ${file.file}`)
+    }
+    return lines
+  }
+  const reverted = codec.revert(text, file)
+  if (opts.whole && file.created && codec.isEffectivelyEmpty(reverted.text)) {
+    unlinkSync(file.file)
+    pruneEmptyDir(dirname(file.file))
+    lines.push(`deleted ${file.file} (installer-created, now empty)`)
+  } else {
+    writeConfig(file.file, reverted.text)
+    lines.push(`reverted artifacts${opts.label} in ${file.file}`)
+  }
+  lines.push(...reverted.notes.map((note) => `  note: ${note}`))
+  return lines
+}