deepseek-web-retrieval 0.4.0 → 0.5.1

package/src/installer/operation-lock.ts

@@ -0,0 +1,54 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { canonicalPath } from "./ownership";
+import { pruneEmptyDir } from "./revert";
+
+/**
+ * Exclusive, fail-fast operation locks, distinct from persistent ownership claims.
+ * Never steal a stale lock automatically: an interrupted multi-file edit needs inspection.
+ */
+export function withOperationLock<T>(files: readonly string[], run: () => T): T {
+  const locks = [...new Set(files.map((file) => `${canonicalPath(file)}.deepseek-web-retrieval.lock`))].sort();
+  const acquired: string[] = [];
+  let outcome: { ok: true; value: T } | { ok: false; error: unknown };
+  try {
+    for (const lock of locks) {
+      mkdirSync(dirname(lock), { recursive: true });
+      try {
+        mkdirSync(lock, { mode: 0o700 });
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        throw new Error(
+          `Installer operation is locked at ${lock}. Wait for the other init/uninstall to finish. ` +
+            "If it was interrupted, verify the config and install record and ensure no installer is running before removing this lock directory; retry with a new plan.",
+        );
+      }
+      acquired.push(lock);
+      writeFileSync(`${lock}/owner.json`, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), {
+        mode: 0o600,
+      });
+    }
+    outcome = { ok: true, value: run() };
+  } catch (error) {
+    outcome = { ok: false, error };
+  }
+  {
+    const errors: string[] = [];
+    for (const lock of acquired.reverse()) {
+      try {
+        rmSync(lock, { recursive: true });
+        pruneEmptyDir(dirname(lock));
+      } catch (error) {
+        errors.push(`${lock}: ${String(error)}`);
+      }
+    }
+    if (errors.length > 0) {
+      throw new Error(
+        `${outcome.ok ? "Operation finished" : String(outcome.error)}; could not release operation lock(s): ${errors.join("; ")}`,
+        { cause: outcome.ok ? undefined : outcome.error },
+      );
+    }
+  }
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}

package/src/installer/ownership.ts

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { isPlainObject } from "../core/object";
+import { pruneEmptyDir } from "./revert";
+import { statePathFor } from "./state";
+import type { InstallerInput, RecordedFile, Scope } from "./types";
+
+type ClaimedFile = Pick<RecordedFile, "file" | "format" | "shared">;
+
+interface FileOwner {
+  readonly recordPath: string;
+  readonly scope: Scope;
+  readonly cwd: string;
+}
+
+/** Resolve existing symlinks, including the parents of a file not created yet. */
+export function canonicalPath(file: string): string {
+  const absolute = resolve(file);
+  if (existsSync(absolute)) return realpathSync(absolute);
+  return join(canonicalPath(dirname(absolute)), basename(absolute));
+}
+
+function ownerOf(input: InstallerInput): FileOwner {
+  return { recordPath: canonicalPath(statePathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
+}
+
+/**
+ * Put shared config claims beside the actual config, so another cwd or
+ * XDG_CONFIG_HOME cannot hide them. Project-local configs need no sidecars.
+ * The sidecar contains only the install record's location, never config values.
+ */
+function claimPaths(input: InstallerInput, files: readonly ClaimedFile[]): string[] {
+  return [
+    ...new Set(
+      files
+        .filter((file) => file.format !== "rules")
+        .map((file) => {
+          const target = canonicalPath(file.file);
+          return join(dirname(target), `.${basename(target)}.deepseek-web-retrieval.${input.host}.owner.json`);
+        }),
+    ),
+  ];
+}
+
+function readOwner(file: string): FileOwner | undefined {
+  if (!existsSync(file)) return undefined;
+  try {
+    const value: unknown = JSON.parse(readFileSync(file, "utf8"));
+    if (
+      isPlainObject(value) &&
+      typeof value.recordPath === "string" &&
+      typeof value.cwd === "string" &&
+      (value.scope === "project" || value.scope === "global")
+    ) {
+      return { recordPath: value.recordPath, cwd: value.cwd, scope: value.scope };
+    }
+  } catch {
+    // An unreadable claim must not permit another install to take the file.
+  }
+  throw new Error(`Cannot read config ownership in ${file}; repair the ownership record before retrying.`);
+}
+
+function assertOwner(input: InstallerInput, claim: string): void {
+  const owner = readOwner(claim);
+  if (owner === undefined || owner.recordPath === ownerOf(input).recordPath) return;
+  throw new Error(
+    `A ${input.host} install is already recorded at the ${owner.scope} scope (${owner.recordPath}) and claims the same config file. ` +
+      `Uninstall it first: deepseek-web-retrieval uninstall --host ${input.host} --scope ${owner.scope} --cwd ${JSON.stringify(owner.cwd)}. ` +
+      "Two install records must not edit one file.",
+  );
+}
+
+/** Read-only check used by planning, apply and uninstall, across all project roots. */
+export function assertFileOwnership(input: InstallerInput, files: readonly ClaimedFile[]): void {
+  for (const claim of claimPaths(input, files)) assertOwner(input, claim);
+}
+
+/** Include the new metadata write in the plan preview. */
+export function fileOwnershipNotes(input: InstallerInput, files: readonly ClaimedFile[]): string[] {
+  return claimPaths(
+    input,
+    files.filter((file) => file.shared),
+  ).map(
+    (claim) =>
+      `Shared config ownership is recorded in ${claim}; uninstall releases it. Keep this local metadata with the config.`,
+  );
+}
+
+/** Acquire before config writes; wx prevents two different installs taking an unclaimed file. */
+export function acquireFileOwnership(input: InstallerInput, files: readonly ClaimedFile[]): () => void {
+  const acquired: string[] = [];
+  const owner = ownerOf(input);
+  const releaseNew = () => {
+    for (const claim of acquired.reverse()) releaseClaim(input, claim);
+  };
+  try {
+    for (const claim of claimPaths(
+      input,
+      files.filter((file) => file.shared),
+    )) {
+      assertOwner(input, claim);
+      mkdirSync(dirname(claim), { recursive: true });
+      try {
+        writeFileSync(claim, `${JSON.stringify(owner)}\n`, { flag: "wx", mode: 0o600 });
+        acquired.push(claim);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        assertOwner(input, claim);
+      }
+    }
+    return releaseNew;
+  } catch (error) {
+    releaseNew();
+    throw error;
+  }
+}
+
+function releaseClaim(input: InstallerInput, claim: string): void {
+  const owner = readOwner(claim);
+  if (owner === undefined) return;
+  assertOwner(input, claim);
+  rmSync(claim);
+  pruneEmptyDir(dirname(claim));
+}
+
+/** Release only after successful uninstall or after reverting a whole-file orphan. */
+export function releaseFileOwnership(input: InstallerInput, files: readonly ClaimedFile[]): void {
+  for (const claim of claimPaths(input, files)) releaseClaim(input, claim);
+}

package/src/installer/paths.ts

@@ -1,18 +1,20 @@
-import type { FsRoots, Scope } from "./types"
+import { join as pathJoin } from "node:path";
+import type { FsRoots, Scope } from "./types";
 
-/** Joins path parts with "/", skipping empty segments. */
+/** Joins path parts with the platform separator, skipping empty segments. */
 export function join(...parts: readonly string[]): string {
-  return parts.filter((part) => part.length > 0).join("/")
+  const nonEmpty = parts.filter((part) => part.length > 0);
+  return nonEmpty.length === 0 ? "" : pathJoin(...nonEmpty);
 }
 
 /** 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")
+  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")
+    : join(roots.cwd, ".deepseek-web-retrieval");
 }

package/src/installer/persistence.ts

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** Replace one file, retaining valid symlinks and modes. This is not a multi-file transaction. */
+export function atomicWrite(file: string, text: string, mode?: number): void {
+  let target = file;
+  let existingMode: number | undefined;
+  try {
+    const entry = lstatSync(file);
+    // Resolve explicitly: never replace a dangling symlink with a new regular file.
+    if (entry.isSymbolicLink()) target = realpathSync(file);
+    existingMode = statSync(target).mode & 0o777;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    // A dangling link exists even though its target does not.
+    try {
+      if (lstatSync(file).isSymbolicLink()) throw new Error(`Cannot write dangling symlink ${file}`);
+    } catch (linkError) {
+      if ((linkError as NodeJS.ErrnoException).code !== "ENOENT") throw linkError;
+    }
+  }
+  const dir = dirname(target);
+  mkdirSync(dir, { recursive: true });
+  const temporary = join(dir, `.${basename(target)}.${randomUUID()}.tmp`);
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, text);
+    // Catch incomplete/silently dropped writes before replacing the original.
+    if (readFileSync(temporary, "utf8") !== text) throw new Error(`Incomplete write to ${file}`);
+    fchmodSync(fd, mode ?? existingMode ?? 0o666 & ~process.umask());
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(temporary, target);
+    syncDirectory(dir);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    rmSync(temporary, { force: true });
+  }
+}
+
+function syncDirectory(dir: string): void {
+  // Windows does not support opening directories for fsync.
+  if (process.platform === "win32") return;
+  const fd = openSync(dir, "r");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/installer/render.ts

@@ -1,38 +1,38 @@
-import type { InstallPlan } from "./types"
+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:")
+  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}`)
+    lines.push(`  ${edit.file}`);
     if (edit.format === "rules") {
-      lines.push("    upsert marked rules block")
-      continue
+      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})`)
+        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)}`)
+        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):")
+    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}`)
+      lines.push(`  ${revert.file}`);
       if (revert.format === "rules") {
-        lines.push("    remove rules block")
-        continue
+        lines.push("    remove rules block");
+        continue;
       }
       for (const op of revert.ops) {
         if (op.op === "set") {
@@ -40,23 +40,23 @@ export function renderPlan(plan: InstallPlan): string {
             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(".")}`)
+          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}`)
+    lines.push("");
+    lines.push("Notes:");
+    for (const note of plan.notes) lines.push(`  - ${note}`);
   }
-  return lines.join("\n")
+  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
+  const text = JSON.stringify(value) ?? String(value);
+  return text.length > 100 ? `${text.slice(0, 97)}...` : text;
 }

package/src/installer/revert.ts

@@ -1,12 +1,12 @@
-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"
+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)
+    rmdirSync(dir);
   } catch {
     // Not empty or already gone — nothing to prune.
   }
@@ -19,43 +19,47 @@ export function pruneEmptyDir(dir: string): void {
  * 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[] = []
+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
+    lines.push(`already absent: ${file.file}${opts.label}`);
+    return lines;
   }
-  const codec = codecFor(file.format, host)
-  const text = readFileSync(file.file, "utf8")
+  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 ?? "" }
+    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
+      lines.push(`no rules block${opts.label} in ${file.file}; left untouched`);
+      return lines;
     }
-    const updated = codec.revert(text, file).text
+    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)`)
+      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}`)
+      writeConfig(file.file, updated);
+      lines.push(`removed rules block${opts.label} from ${file.file}`);
     }
-    return lines
+    return lines;
   }
-  const reverted = codec.revert(text, file)
+  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)`)
+    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}`)
+    writeConfig(file.file, reverted.text);
+    lines.push(`reverted artifacts${opts.label} in ${file.file}`);
   }
-  lines.push(...reverted.notes.map((note) => `  note: ${note}`))
-  return lines
+  lines.push(...reverted.notes.map((note) => `  note: ${note}`));
+  return lines;
 }

package/src/installer/rulesContent.ts

@@ -1,32 +1,43 @@
-import type { Tier } from "./types"
+import type { Tier } from "./types";
 
 /** Full MCP tool ids, per the installer design's rules non-negotiables. */
-export const MCP_TOOL_IDS = { search: "mcp__deepseek__deepseek_web_search", fetch: "mcp__deepseek__deepseek_fetch" } as const
+export const MCP_TOOL_IDS = {
+  search: "mcp__deepseek__deepseek_web_search",
+  fetch: "mcp__deepseek__deepseek_fetch",
+} as const;
+
+/**
+ * Raw server-declared tool names (no `mcp__` prefix): what Pi's extension-style tool ids
+ * and host per-server tool keys (Codex's `disabled_tools`) match on, verbatim.
+ */
+export const RAW_MCP_TOOL_IDS = { search: "deepseek_web_search", fetch: "deepseek_fetch" } as const;
 
 /**
  * Builds the rules block lines for the preferred tier: names the full tool ids,
  * states trigger conditions rather than unconditional preference, and lists the
- * private-network exclusion. Only mentions capabilities that are not "off".
+ * private-network exclusion. Only steers capabilities whose tier is preferred.
  * Hosts whose tools are named differently pass their own ids.
  */
-export function rulesLines(ids: { readonly search: string; readonly fetch: string }, search: Tier, fetch: Tier): string[] {
-  const lines: string[] = ["DeepSeek retrieval guidance:"]
-  if (search !== "off") {
+export function rulesLines(
+  ids: { readonly search: string; readonly fetch: string },
+  search: Tier,
+  fetch: Tier,
+): string[] {
+  const lines: string[] = ["DeepSeek retrieval guidance:"];
+  if (search === "preferred") {
     lines.push(
       `- Use ${ids.search} when the task needs fresh external information: current docs, version numbers,`,
       "  changelogs, or anything you cannot know from the repository alone. Do not search for facts already",
       "  present locally.",
-    )
+    );
   }
-  if (fetch !== "off") {
-    lines.push(
-      `- Use ${ids.fetch} to read a specific public web page as Markdown when its content is needed.`,
-    )
+  if (fetch === "preferred") {
+    lines.push(`- Use ${ids.fetch} to read a specific public web page as Markdown when its content is needed.`);
   }
   lines.push(
     "- Never send localhost or private-network URLs to the DeepSeek tools; use local tools for those (the",
     "  server blocks private hosts by default).",
     "- DeepSeek requests are billed per successful call; retrieve only what the task needs.",
-  )
-  return lines
+  );
+  return lines;
 }