deepseek-web-retrieval 0.4.0 → 0.5.0

package/src/installer/cli.ts

@@ -1,154 +1,174 @@
-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"]
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { applyPlan } from "./apply";
+import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
+import { renderPlan } from "./render";
+import { listRecords } from "./state";
+import type { HostName, InstallerInput, Scope, Tier } from "./types";
+import { uninstall } from "./uninstall";
+
+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]
+[--path <extension|mcp>] [--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.`
+until --apply is passed. uninstall restores what the plan applied. --path picks
+the integration mechanism for hosts with more than one (Pi: extension by
+default, mcp for the stdio MCP server). --package overrides the package ref
+written into host config; the Pi extension path turns it into the packages
+source (a bare name is prefixed with npm:, a ref that already starts with npm:
+is written as-is).`;
 
 interface Flags {
-  readonly values: Map<string, string>
-  readonly booleans: Set<string>
-  readonly problems: readonly string[]
+  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"])
+const VALUE_FLAGS = new Set(["host", "scope", "search", "fetch", "path", "package", "cwd"]);
+const BOOLEAN_FLAGS = new Set(["apply"]);
+const PATH_CHOICES: readonly ["extension", "mcp"] = ["extension", "mcp"];
 
 function parseFlags(args: readonly string[]): Flags {
-  const values = new Map<string, string>()
-  const booleans = new Set<string>()
-  const problems: string[] = []
+  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
+    const arg = args[i] as string;
     if (!arg.startsWith("--")) {
-      problems.push(`unexpected argument "${arg}" (flags only)`)
-      continue
+      problems.push(`unexpected argument "${arg}" (flags only)`);
+      continue;
     }
-    const eq = arg.indexOf("=")
-    const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq)
+    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 (eq !== -1) {
+        problems.push(`--${name} does not accept a value; use --${name} to enable it or omit it`);
+        continue;
+      }
+      booleans.add(name);
+      continue;
     }
     if (!VALUE_FLAGS.has(name)) {
-      problems.push(`unknown flag --${name}`)
-      continue
+      problems.push(`unknown flag --${name}`);
+      continue;
     }
     if (eq !== -1) {
-      values.set(name, arg.slice(eq + 1))
-      continue
+      values.set(name, arg.slice(eq + 1));
+      continue;
     }
-    const next = args[i + 1]
+    const next = args[i + 1];
     if (next === undefined || next.startsWith("--")) {
-      problems.push(`--${name} requires a value`)
-      continue
+      problems.push(`--${name} requires a value`);
+      continue;
     }
-    values.set(name, next)
-    i += 1
+    values.set(name, next);
+    i += 1;
   }
-  return { values, booleans, problems }
+  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
+  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
+  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
+    out(USAGE);
+    return command === undefined ? 1 : 0;
   }
-  const flags = parseFlags(rest)
+  const flags = parseFlags(rest);
   if (flags.problems.length > 0) {
-    for (const problem of flags.problems) err(`error: ${problem}`)
-    err(`\n${USAGE}`)
-    return 1
+    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)
+  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 })
+    let records: ReturnType<typeof listRecords>;
+    try {
+      records = listRecords({ home, cwd, configHome });
+    } catch (error) {
+      err(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
     if (records.length === 0) {
-      out("No installs recorded.")
-      return 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}`)
+      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
+    return 0;
   }
 
   if (command === "uninstall") {
-    const required = requireInput(flags, cwd, home, configHome, false)
-    if (!required.ok) return usageError(required.problems, err)
+    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
+      for (const line of uninstall(required.input)) out(line);
+      return 0;
     } catch (error) {
-      err(error instanceof Error ? error.message : String(error))
-      return 1
+      err(error instanceof Error ? error.message : String(error));
+      return 1;
     }
   }
 
   if (command !== "init") {
-    err(`Unknown command "${command}".\n\n${USAGE}`)
-    return 1
+    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)
+  const required = requireInput(flags, cwd, home, configHome, true);
+  if (!required.ok) return usageError(required.problems, err);
+  const { input } = required;
+  const probe = HOST_VERSION_PROBES[input.host];
+  const hostVersion = probe?.(err);
+  const plan = planForHost(input.host, hostVersion === undefined ? input : { ...input, hostVersion });
   if (plan.errors.length > 0) {
-    for (const error of plan.errors) err(`error: ${error.message}`)
-    err("Nothing was written.")
-    return 1
+    for (const error of plan.errors) err(`error: ${error.message}`);
+    err("Nothing was written.");
+    return 1;
   }
-  out(renderPlan(plan))
+  out(renderPlan(plan));
   if (!flags.booleans.has("apply")) {
-    out("\nPlan only — re-run with --apply to write these changes.")
-    return 0
+    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
+    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
+    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
+  for (const problem of problems) err(`error: ${problem}`);
+  err(`\n${USAGE}`);
+  return 1;
 }
 
 /**
@@ -156,14 +176,14 @@ function usageError(problems: readonly string[], err: (line: string) => void): n
  * 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
+  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[] }
+  | { readonly ok: false; readonly problems: readonly string[] };
 
 function requireInput(
   flags: Flags,
@@ -172,33 +192,43 @@ function requireInput(
   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(", ")})`)
+  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";
+  const path = flags.values.get("path");
+  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 (path !== undefined) {
+    if (host !== "pi") {
+      problems.push(`--path is only supported for host pi (${host ?? "no host"} has a single integration path)`);
+    } else if (!(PATH_CHOICES as readonly string[]).includes(path)) {
+      problems.push(`invalid --path value "${path}" (one of: ${PATH_CHOICES.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 }
+  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: {
@@ -210,6 +240,7 @@ function requireInput(
       home,
       cwd,
       configHome,
+      ...(path !== undefined ? { path: path as "extension" | "mcp" } : {}),
     },
-  }
+  };
 }

package/src/installer/detect.ts

@@ -1,10 +1,10 @@
-import { existsSync, readFileSync } from "node:fs"
-import { removeBlock } from "./formats/rules"
-import { isPlainObject } from "./formats/value"
-import type { HostName } from "./types"
+import { existsSync, readFileSync } from "node:fs";
+import { removeBlock } from "./formats/rules";
+import { isPlainObject } from "./formats/value";
+import type { HostName } from "./types";
 
 /** Shared plan error: both capabilities off leaves nothing to install. */
-export const BOTH_CAPABILITIES_OFF = "Both capabilities are off; nothing would be installed."
+export const BOTH_CAPABILITIES_OFF = "Both capabilities are off; nothing would be installed.";
 
 /**
  * Shared Forced-tier cost warning; the README's "Privacy and cost" section carries
@@ -12,20 +12,20 @@ export const BOTH_CAPABILITIES_OFF = "Both capabilities are off; nothing would b
  */
 export const FORCED_COST_NOTE =
   "Forced routing is deterministic, and Search and Fetch are billed per successful request — " +
-  'see the README\'s "Privacy and cost" section before applying.'
+  'see the README\'s "Privacy and cost" section before applying.';
 
 /** Shared note when a previous deepseek entry is being replaced. */
 export function replacingExistingEntryNote(path: string): string {
-  return `An existing ${path} entry is being replaced; its previous form is recorded for uninstall.`
+  return `An existing ${path} entry is being replaced; its previous form is recorded for uninstall.`;
 }
 
 /** Shared note for third-party servers left registered. */
 export function othersStayRegisteredNote(others: readonly string[]): string {
-  return `Other MCP servers stay registered (${others.join(", ")}); routing to DeepSeek is not exclusive while they offer web tools.`
+  return `Other MCP servers stay registered (${others.join(", ")}); routing to DeepSeek is not exclusive while they offer web tools.`;
 }
 
 const WEB_TOOL_HINT =
-  /(web[_ -]?(search|fetch)|search|fetch|browse|scrape|crawl|tavily|brave|exa|perplexity|firecrawl|jina|serp|duckduckgo|reader)/i
+  /(web[_ -]?(search|fetch)|search|fetch|browse|scrape|crawl|tavily|brave|exa|perplexity|firecrawl|jina|serp|duckduckgo|reader)/i;
 
 /**
  * Heuristic web-capability test for a registered third-party MCP server, matching
@@ -34,16 +34,30 @@ const WEB_TOOL_HINT =
  * "not exclusive while they offer web tools" note.
  */
 export function looksWebCapable(name: string, entry: unknown): boolean {
-  if (WEB_TOOL_HINT.test(name)) return true
-  if (!isPlainObject(entry)) return false
-  const command = typeof entry.command === "string" ? entry.command : ""
-  const url = typeof entry.url === "string" ? entry.url : ""
-  const args = Array.isArray(entry.args) ? entry.args.filter((arg): arg is string => typeof arg === "string").join(" ") : ""
-  return WEB_TOOL_HINT.test(`${command} ${args} ${url}`)
+  if (WEB_TOOL_HINT.test(name)) return true;
+  if (!isPlainObject(entry)) return false;
+  const command = typeof entry.command === "string" ? entry.command : "";
+  const url = typeof entry.url === "string" ? entry.url : "";
+  const args = Array.isArray(entry.args)
+    ? entry.args.filter((arg): arg is string => typeof arg === "string").join(" ")
+    : "";
+  return WEB_TOOL_HINT.test(`${command} ${args} ${url}`);
+}
+
+/**
+ * Matches a source or package ref that is this package in another form — a fork
+ * (`github:owner/deepseek-web-retrieval`), a pinned version
+ * (`npm:deepseek-web-retrieval@<version>`), a packed tarball
+ * (`npm:file:…/deepseek-web-retrieval-<version>.tgz`) — but not an unrelated
+ * package whose name merely contains ours (`deepseek-web-retrieval-extra`).
+ * The match is on the package-name boundary, not a raw substring.
+ */
+export function looksLikeOwnPackage(source: string): boolean {
+  return /(^|[/:@])deepseek-web-retrieval($|[@/]|-\d)/.test(source);
 }
 
 const STEERING_HINT =
-  /(web[_ ]?(search|fetch)|websearch|webfetch|tavily|exa|brave|perplexity|firecrawl|jina|serp|duckduckgo|google|bing)/i
+  /(web[_ ]?(search|fetch)|websearch|webfetch|tavily|exa|brave|perplexity|firecrawl|jina|serp|duckduckgo|google|bing)/i;
 
 /**
  * Detect-phase scan of the rules file the plan would write to: lines steering the
@@ -51,35 +65,36 @@ const STEERING_HINT =
  * deepseek mentions are ours to make, so both are ignored.
  */
 export function findCompetitorSteering(host: HostName, file: string): string[] {
-  if (!existsSync(file)) return []
-  let text: string
+  if (!existsSync(file)) return [];
+  let text: string;
   try {
-    text = readFileSync(file, "utf8")
+    text = readFileSync(file, "utf8");
   } catch {
-    return []
+    return [];
   }
   return removeBlock(host, text)
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line.length > 0 && STEERING_HINT.test(line) && !line.includes("deepseek"))
-    .slice(0, 2)
+    .slice(0, 2);
 }
 
 /** Shared note for steering the detect phase found; conflicts are surfaced, not resolved. */
 export function competitorSteeringNote(file: string, lines: readonly string[]): string {
-  const quoted = lines.map((line) => `"${line}"`).join(", ")
-  return `Existing rules in ${file} steer toward other web tools (${quoted}); the plan surfaces this conflict — it does not resolve it.`
+  const quoted = lines.map((line) => `"${line}"`).join(", ");
+  return `Existing rules in ${file} steer toward other web tools (${quoted}); the plan surfaces this conflict — it does not resolve it.`;
 }
 
 /** Splits other registered servers into web-capable competitors and bystanders. */
-export function splitCompetitors(
-  servers: Record<string, unknown>,
-): { readonly competitors: readonly string[]; readonly bystanders: readonly string[] } {
-  const competitors: string[] = []
-  const bystanders: string[] = []
+export function splitCompetitors(servers: Record<string, unknown>): {
+  readonly competitors: readonly string[];
+  readonly bystanders: readonly string[];
+} {
+  const competitors: string[] = [];
+  const bystanders: string[] = [];
   for (const [name, entry] of Object.entries(servers)) {
-    if (name === "deepseek") continue
-    ;(looksWebCapable(name, entry) ? competitors : bystanders).push(name)
+    if (name === "deepseek") continue;
+    (looksWebCapable(name, entry) ? competitors : bystanders).push(name);
   }
-  return { competitors, bystanders }
+  return { competitors, bystanders };
 }

package/src/installer/formats/index.ts

@@ -1,33 +1,32 @@
-import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname } from "node:path"
-import type { ConfigOp, FileEdit, HostName, RecordedFile, RecordedOp } from "../types"
-import { jsonCodec } from "./json"
-import { rulesCodec } from "./rules"
-import { tomlCodec } from "./toml"
+import { atomicWrite } from "../persistence";
+import type { ConfigOp, FileEdit, HostName, RecordedFile, RecordedOp } from "../types";
+import { jsonCodec } from "./json";
+import { rulesCodec } from "./rules";
+import { tomlCodec } from "./toml";
 
-export type ConfigFormat = FileEdit["format"]
+export type ConfigFormat = FileEdit["format"];
 
 /** A config file as the codec read it: parsed, or carrying the parse error. */
 export interface LoadedConfig {
-  readonly exists: boolean
-  readonly text: string
-  readonly value: Record<string, unknown>
+  readonly exists: boolean;
+  readonly text: string;
+  readonly value: Record<string, unknown>;
   /** True when serializing the parsed value would drop comments (TOML only; JSON edits preserve them). */
-  readonly lossy: boolean
-  readonly parseError?: string
+  readonly lossy: boolean;
+  readonly parseError?: string;
 }
 
 /** What applying one edit produced, beyond the new text: everything undo needs. */
 export interface AppliedText {
-  readonly text: string
-  readonly recorded: readonly RecordedOp[]
-  readonly createdParents: readonly (readonly string[])[]
+  readonly text: string;
+  readonly recorded: readonly RecordedOp[];
+  readonly createdParents: readonly (readonly string[])[];
 }
 
 /** What reverting one recorded file produced: the text plus notes about skipped work. */
 export interface RevertedText {
-  readonly text: string
-  readonly notes: readonly string[]
+  readonly text: string;
+  readonly notes: readonly string[];
 }
 
 /**
@@ -36,23 +35,22 @@ export interface RevertedText {
  * revert reverses a recorded file, and isEffectivelyEmpty gates whole-file deletion.
  */
 export interface FormatCodec {
-  readonly format: ConfigFormat
-  load(file: string): LoadedConfig
-  apply(text: string, edit: FileEdit): AppliedText
-  verify(text: string, edit: FileEdit, op?: ConfigOp): boolean
-  revert(text: string, recorded: RecordedFile): RevertedText
-  isEffectivelyEmpty(text: string): boolean
+  readonly format: ConfigFormat;
+  load(file: string): LoadedConfig;
+  apply(text: string, edit: FileEdit): AppliedText;
+  verify(text: string, edit: FileEdit, op?: ConfigOp): boolean;
+  revert(text: string, recorded: RecordedFile): RevertedText;
+  isEffectivelyEmpty(text: string): boolean;
 }
 
 /** Shared write step: every codec consumer writes config files through this. */
 export function writeConfig(file: string, serialized: string): void {
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, serialized)
+  atomicWrite(file, serialized);
 }
 
 /** The one entry point to a format's codec; only the rules codec cares about the host. */
 export function codecFor(format: ConfigFormat, host: HostName): FormatCodec {
-  if (format === "json") return jsonCodec
-  if (format === "toml") return tomlCodec
-  return rulesCodec(host)
+  if (format === "json") return jsonCodec;
+  if (format === "toml") return tomlCodec;
+  return rulesCodec(host);
 }