@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/runtime/secret-guard.ts

@@ -0,0 +1,148 @@
+import { resolveSecretPolicy } from "./policy";
+import { globTargetsSecretFiles, isSecretFile } from "./secret-patterns";
+import { describeSecretFindings, scanContent, type SecretFinding } from "./secret-scan";
+import { HEREDOC_MARKER, stripHeredocBodies } from "./shell-heredoc";
+
+/**
+ * The secret check both runtimes run before a tool call: the Claude PreToolUse
+ * hook and the OpenCode middleware translate their own tool payloads into one
+ * of these shapes, so the two refuse the same calls for the same reasons.
+ */
+export type SecretToolCall =
+  | { kind: "read"; paths: string[] }
+  /** `content` is what the call would put into the file: a whole body or an edit's new text. */
+  | { kind: "write"; writes: { path: string; content: string }[] }
+  | { kind: "shell"; command: string }
+  /** A content search: refused when it names a secret file or a glob aimed at secret files. */
+  | { kind: "search"; paths: string[]; globs: string[] };
+
+export interface SecretGuardScope {
+  companionPath: string;
+  /** Whether a target lands in the Companion Repository, whose writes are content-scanned. */
+  isCompanionPath: (filePath: string) => boolean;
+}
+
+export interface SecretGuardDeps {
+  scan?: (filePath: string, content: string) => Promise<SecretFinding[]>;
+}
+
+const SWITCH_HINT =
+  "Secret guardrails are on. The user can add an allow pattern or opt out under `secrets` in the companion's framework.yaml; do not work around this block.";
+
+function secretFileRefusal(filePath: string): string {
+  return [
+    "Mate guardrail: secret files are off-limits to agents.",
+    ` target: ${filePath}`,
+    "Refer to the variable by name, read an example file such as .env.example, or ask the user to set the value.",
+    SWITCH_HINT,
+  ].join("\n");
+}
+
+const SHELL_SEPARATOR = /[\s;|&<>()`]/;
+
+/**
+ * Shell words with quotes removed, redirect operators as separators and
+ * heredoc bodies dropped. A heuristic, not a parser: it exists to find file
+ * names a command spells out, and a quoted string stays one word, so a
+ * commit message that mentions `.env` is not a reference to the file.
+ */
+export function shellWords(command: string): string[] {
+  const words: string[] = [];
+  for (const line of stripHeredocBodies(command).split("\n")) {
+    let word = "";
+    let quote: string | undefined;
+    let quoted = false;
+    const flush = () => {
+      if (word || quoted) words.push(word);
+      word = "";
+      quoted = false;
+    };
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i];
+      if (quote) {
+        if (char === quote) quote = undefined;
+        else if (char === "\\" && quote === '"' && i + 1 < line.length) word += line[++i];
+        else word += char;
+      } else if (char === "'" || char === '"') {
+        quote = char;
+        quoted = true;
+      } else if (char === "\\" && i + 1 < line.length) {
+        word += line[++i];
+      } else if (char === "<" && line[i + 1] === "<") {
+        flush();
+        const marker = HEREDOC_MARKER.exec(line.slice(i));
+        i += marker ? marker[0].length - 1 : 1;
+      } else if (SHELL_SEPARATOR.test(char)) {
+        flush();
+      } else {
+        word += char;
+      }
+    }
+    flush();
+  }
+  return words.filter(Boolean);
+}
+
+/** A word, plus the value of a `--flag=path` or `NAME=path` word. */
+function candidatePaths(word: string): string[] {
+  const equals = word.indexOf("=");
+  return equals > 0 ? [word, word.slice(equals + 1)] : [word];
+}
+
+/**
+ * Returns the refusal message for a call that touches a secret, or null. Reads
+ * the companion's `secrets` block live, so a toggle applies to the next call.
+ */
+export async function checkSecretAccess(
+  call: SecretToolCall,
+  scope: SecretGuardScope,
+  deps: SecretGuardDeps = {},
+): Promise<string | null> {
+  const policy = resolveSecretPolicy(scope.companionPath);
+  if (!policy.guardrails) return null;
+
+  if (call.kind === "shell") {
+    const named = shellWords(call.command)
+      .flatMap(candidatePaths)
+      .find((word) => isSecretFile(word, policy));
+    return named ? secretFileRefusal(named) : null;
+  }
+
+  if (call.kind === "search") {
+    const named =
+      call.paths.find((filePath) => filePath && isSecretFile(filePath, policy)) ??
+      call.globs.find((glob) => globTargetsSecretFiles(glob, policy));
+    return named ? secretFileRefusal(named) : null;
+  }
+
+  const paths = call.kind === "read" ? call.paths : call.writes.map((write) => write.path);
+  const secretPath = paths.find((filePath) => filePath && isSecretFile(filePath, policy));
+  if (secretPath) return secretFileRefusal(secretPath);
+  if (call.kind === "read") return null;
+
+  const scan = deps.scan ?? scanContent;
+  for (const write of call.writes) {
+    if (!write.path || !write.content || !scope.isCompanionPath(write.path)) continue;
+    let findings: SecretFinding[];
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- the first refusal wins
+      findings = await scan(write.path, write.content);
+    } catch {
+      return [
+        "Mate guardrail: content for the Companion Repository could not be scanned for secrets, so the write is blocked.",
+        ` target: ${write.path}`,
+        SWITCH_HINT,
+      ].join("\n");
+    }
+    if (findings.length > 0) {
+      return [
+        "Mate guardrail: this write would put a secret into the Companion Repository.",
+        ` target: ${write.path}`,
+        ...describeSecretFindings(findings).map((line) => ` finding: ${line}`),
+        "Replace the value with a placeholder or the variable name. For a deliberate fake, wrap it in secretlint-disable/secretlint-enable comments.",
+        SWITCH_HINT,
+      ].join("\n");
+    }
+  }
+  return null;
+}

package/src/runtime/secret-patterns.ts

@@ -0,0 +1,164 @@
+/**
+ * The one secret-file pattern set every guardrail layer reads: guidance,
+ * projected deny rules, hook and middleware enforcement, indexer exclusion and
+ * the publish scan. Keeping it in one module is what stops the layers from
+ * disagreeing about what a secret file is.
+ */
+
+export const DEFAULT_SECRET_DENY_PATTERNS: readonly string[] = [
+  ".env",
+  ".env.*",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "id_rsa",
+  "id_ecdsa",
+  "id_ed25519",
+  ".netrc",
+  ".pgpass",
+  ".npmrc",
+];
+
+/** Example files that document which variables exist; they never hold values. */
+export const DEFAULT_SECRET_ALLOW_PATTERNS: readonly string[] = [
+  ".env.example",
+  ".env.sample",
+  ".env.template",
+  ".env.dist",
+];
+
+export interface SecretPolicy {
+  /** False only when the companion explicitly opts out. */
+  guardrails: boolean;
+  /** Defaults plus the companion's extra `secrets.deny` patterns. */
+  deny: string[];
+  /** Defaults plus the companion's extra `secrets.allow` patterns. */
+  allow: string[];
+}
+
+export const defaultSecretPolicy = (): SecretPolicy => ({
+  guardrails: true,
+  deny: [...DEFAULT_SECRET_DENY_PATTERNS],
+  allow: [...DEFAULT_SECRET_ALLOW_PATTERNS],
+});
+
+function patternList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "");
+}
+
+/**
+ * Parses the `secrets` block of `framework.yaml`. Anything that is not an
+ * object yields the defaults with guardrails on, and only a literal `false`
+ * turns them off: a broken config never disables protection.
+ */
+export function parseSecretsConfig(value: unknown): SecretPolicy {
+  const policy = defaultSecretPolicy();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return policy;
+  const block = value as Record<string, unknown>;
+  return {
+    guardrails: block.guardrails !== false,
+    deny: [...policy.deny, ...patternList(block.deny)],
+    allow: [...policy.allow, ...patternList(block.allow)],
+  };
+}
+
+const compiled = new Map<string, RegExp>();
+
+/** Gitignore-style subset: `*` and `?` stay inside a segment, `**` crosses them. */
+function patternRegExp(pattern: string): RegExp {
+  const cached = compiled.get(pattern);
+  if (cached) return cached;
+  let source = "";
+  const body = pattern.replace(/^\/+/, "");
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    if (char === "*" && body[i + 1] === "*") {
+      // `**/` matches zero or more whole segments; a bare `**` matches anything.
+      if (body[i + 2] === "/") {
+        source += "(?:.*/)?";
+        i += 2;
+      } else {
+        source += ".*";
+        i += 1;
+      }
+    } else if (char === "*") {
+      source += "[^/]*";
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  // A slash-free pattern matches the basename; one with a slash matches the
+  // trailing segments of the path, since the repository root is not known here.
+  const regExp = body.includes("/") ? new RegExp(`(?:^|/)${source}$`) : new RegExp(`^${source}$`);
+  compiled.set(pattern, regExp);
+  return regExp;
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+
+export function matchesSecretPattern(filePath: string, patterns: readonly string[]): boolean {
+  const normalized = normalizePath(filePath);
+  if (!normalized) return false;
+  const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return patterns.some((pattern) => {
+    const regExp = patternRegExp(pattern);
+    return pattern.replace(/^\/+/, "").includes("/")
+      ? regExp.test(normalized)
+      : regExp.test(basename);
+  });
+}
+
+/** A path is a secret file when it matches a deny pattern and no allow pattern. */
+export function isSecretFile(filePath: string, policy: SecretPolicy): boolean {
+  return (
+    matchesSecretPattern(filePath, policy.deny) && !matchesSecretPattern(filePath, policy.allow)
+  );
+}
+
+/**
+ * Narrower stand-ins for a default deny pattern that also matches an allowed
+ * file. Runtime deny rules are evaluated before allow rules, so `.env.*` there
+ * would deny `.env.example` too; these cover the common environment files.
+ */
+const ALLOW_SAFE_EXPANSIONS: Readonly<Record<string, readonly string[]>> = {
+  ".env.*": [".env.local", ".env.development", ".env.production", ".env.test", ".env.*.local"],
+};
+
+/**
+ * The default deny patterns a runtime's own deny rules may carry: every
+ * default that can't match an allow-listed file, with an overlapping pattern
+ * replaced by its narrower stand-ins. Extra `secrets.deny` patterns are never
+ * projected: once removed from config, nothing would mark their rules as Mate's.
+ */
+export function projectableSecretDenyPatterns(): string[] {
+  const overlapsAllow = (pattern: string) =>
+    DEFAULT_SECRET_ALLOW_PATTERNS.some((allowed) => matchesSecretPattern(allowed, [pattern]));
+  return DEFAULT_SECRET_DENY_PATTERNS.flatMap((pattern) =>
+    overlapsAllow(pattern) ? (ALLOW_SAFE_EXPANSIONS[pattern] ?? []) : [pattern],
+  ).filter((pattern) => !overlapsAllow(pattern));
+}
+
+/** Ordinary files a broad glob also matches; a glob matching one is not aimed at secrets. */
+const ORDINARY_SAMPLES = ["index.ts", "README.md", "config.json"];
+
+/**
+ * Whether a search glob is aimed at secret files: it matches a sample name of
+ * some deny pattern that the policy still treats as secret, and no ordinary
+ * file. `.env*` and `*.key` are; `**\/*` and `*.ts` are not. A heuristic for
+ * search tools, which take a glob rather than a path.
+ */
+export function globTargetsSecretFiles(glob: string, policy: SecretPolicy): boolean {
+  const pattern = glob.trim();
+  if (!pattern) return false;
+  if (ORDINARY_SAMPLES.some((sample) => matchesSecretPattern(sample, [pattern]))) return false;
+  return policy.deny.some((deny) => {
+    const sample = deny.slice(deny.lastIndexOf("/") + 1).replace(/[*?]+/g, "x");
+    return isSecretFile(sample, policy) && matchesSecretPattern(sample, [pattern]);
+  });
+}

package/src/runtime/secret-scan.ts

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { lintSource as LintSourceFn } from "@secretlint/core";
+import type { SecretLintCoreConfig } from "@secretlint/types";
+
+/** One secretlint finding. Deliberately carries no message: messages quote the value. */
+export interface SecretFinding {
+  path: string;
+  line: number;
+  ruleId: string;
+}
+
+type LintSource = typeof LintSourceFn;
+
+let engine: Promise<{ lintSource: LintSource; config: SecretLintCoreConfig }> | undefined;
+
+/**
+ * Loaded on first use only, so hook calls that never scan don't pay for it.
+ * The config is fixed in memory: the recommended preset and nothing else. No
+ * `.secretlintrc` is ever read, so a repository can't weaken the scan.
+ */
+function loadEngine() {
+  engine ??= (async () => {
+    const [{ lintSource }, { creator }] = await Promise.all([
+      import("@secretlint/core"),
+      import("@secretlint/secretlint-rule-preset-recommend"),
+    ]);
+    const config: SecretLintCoreConfig = {
+      rules: [{ id: "@secretlint/secretlint-rule-preset-recommend", rule: creator }],
+    };
+    return { lintSource, config };
+  })();
+  return engine;
+}
+
+/** Scans in-memory content. Throws when the engine fails, so callers can fail closed. */
+export async function scanContent(filePath: string, content: string): Promise<SecretFinding[]> {
+  const { lintSource, config } = await loadEngine();
+  const result = await lintSource({
+    source: { content, filePath, contentType: "text" },
+    options: { config, maskSecrets: true, noPhysicFilePath: true },
+  });
+  return result.messages.map((message) => ({
+    path: filePath,
+    line: message.loc.start.line,
+    ruleId: message.ruleId,
+  }));
+}
+
+/** Every file under a path, in name order; a path that doesn't exist yields none. */
+export async function listFiles(target: string): Promise<string[]> {
+  let stat;
+  try {
+    stat = await fs.stat(target);
+  } catch {
+    return [];
+  }
+  if (stat.isFile()) return [target];
+  if (!stat.isDirectory()) return [];
+  const entries = await fs.readdir(target, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries
+      .toSorted((a, b) => a.name.localeCompare(b.name))
+      .map((entry) => listFiles(path.join(target, entry.name))),
+  );
+  return nested.flat();
+}
+
+/** Scans files and directories on disk; paths that don't exist are skipped. */
+export async function scanFiles(targets: readonly string[]): Promise<SecretFinding[]> {
+  const findings: SecretFinding[] = [];
+  for (const target of targets) {
+    // oxlint-disable-next-line no-await-in-loop -- findings keep the caller's order
+    for (const file of await listFiles(target)) {
+      // oxlint-disable-next-line no-await-in-loop -- one file at a time bounds memory
+      const content = await fs.readFile(file, "utf8");
+      // oxlint-disable-next-line no-await-in-loop -- see above
+      findings.push(...(await scanContent(file, content)));
+    }
+  }
+  return findings;
+}
+
+/** One line per finding, for refusal messages: never the value. Line 0 means the whole file. */
+export function describeSecretFindings(findings: readonly SecretFinding[]): string[] {
+  return findings.map(
+    (finding) => `${finding.path}${finding.line > 0 ? `:${finding.line}` : ""} (${finding.ruleId})`,
+  );
+}

package/src/runtime/session-kind.ts

@@ -0,0 +1,13 @@
+/**
+ * The kind of session a prepare or a delivery plan answers for, shared by every
+ * Agent Runtime. `managed-repo`: a managed launch with a Working Repository; its
+ * prepare just reconciled the wrap, which the launcher asserts.
+ * `managed-companion`: a companion-scoped managed launch. `unmanaged`: a
+ * session with no launch environment.
+ */
+export type SessionKind = "managed-repo" | "managed-companion" | "unmanaged";
+
+/** A managed launch's kind: with a Working Repository, or companion-scoped. */
+export function managedSessionKind(withRepository: boolean): SessionKind {
+  return withRepository ? "managed-repo" : "managed-companion";
+}

package/src/runtime/shell-heredoc.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a heredoc starts, matched at a `<<` outside quotes: an optional `-`,
+ * then the terminator word, optionally quoted. Shared by the secret guard's
+ * shell tokenizer and the artifact guard's redirect scan, so both agree on
+ * what is command text and what is a body.
+ */
+export const HEREDOC_MARKER = /^<<-?\s*(['"]?)([\w.-]+)\1/;
+
+/** The terminators a command line opens, in order; quoted text is skipped. */
+function heredocTerminators(line: string): string[] {
+  const terminators: string[] = [];
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else if (char === "\\" && quote === '"') i++;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "\\") {
+      i++;
+    } else if (char === "<" && line[i + 1] === "<") {
+      if (line[i + 2] === "<") {
+        i += 2;
+        continue;
+      }
+      const marker = HEREDOC_MARKER.exec(line.slice(i));
+      if (marker) {
+        terminators.push(marker[2]);
+        i += marker[0].length - 1;
+      } else {
+        i++;
+      }
+    }
+  }
+  return terminators;
+}
+
+/** A heredoc body and the line, in the stripped command, whose marker opened it. */
+export interface HeredocBody {
+  line: number;
+  text: string;
+}
+
+/** The command's own lines and each heredoc body, split in one pass. */
+function splitHeredocs(command: string): { kept: string[]; bodies: HeredocBody[] } {
+  const kept: string[] = [];
+  const bodies: HeredocBody[] = [];
+  const pending: string[] = [];
+  let body: string[] = [];
+  for (const line of command.split("\n")) {
+    if (pending.length > 0) {
+      if (line.trim() === pending[0]) {
+        pending.shift();
+        bodies.push({ line: kept.length - 1, text: body.join("\n") });
+        body = [];
+      } else {
+        body.push(line);
+      }
+      continue;
+    }
+    kept.push(line);
+    pending.push(...heredocTerminators(line));
+  }
+  if (pending.length > 0) bodies.push({ line: kept.length - 1, text: body.join("\n") });
+  return { kept, bodies };
+}
+
+/**
+ * The command with every heredoc body and terminator line removed. Marker
+ * lines stay: a redirect the command performs is spelled there, never in the
+ * body it writes. A heuristic, not a parser, like the tokenizer it mirrors.
+ */
+export function stripHeredocBodies(command: string): string {
+  return splitHeredocs(command).kept.join("\n");
+}
+
+/** Every heredoc body in the command, in order; an unterminated one runs to the end. */
+export function heredocBodies(command: string): HeredocBody[] {
+  return splitHeredocs(command).bodies;
+}

package/src/runtime/wrap-state.ts

@@ -9,12 +9,12 @@ import {
   copies,
   documents,
   links,
+  recordedMapEntries,
   manifestPath,
   parseManifest,
   parseManifestStrict,
   readManifestText,
   recordedListValues,
-  recordedAudience,
   recordedMapKeys,
   type Manifest,
   type WrapRuntime,
@@ -22,17 +22,18 @@ import {
 
 /**
  * Wrap State: the one read model over the runtime document manifest for "which
- * runtimes are wrapped" and "which Claude hook groups does the wrap carry".
+ * runtimes are wrapped" and "which Claude hook groups and plugin folders does
+ * the wrap carry".
  * Mate's own plugin groups are not folded in; `isMateGuardHookGroup` owns those.
  */
 export interface WrapState {
   readonly runtimes: ReadonlySet<WrapRuntime>;
   readonly carriedClaudeHookGroups: readonly ClaudeHookGroup[];
   carriesClaudeHookGroup(group: ClaudeHookGroup): boolean;
+  /** Capability plugin folders the wrap enables through a `directory` marketplace, as recorded. */
+  readonly carriedClaudePluginDirectories: readonly string[];
   /** MCP server names the wrap declared in `.opencode/opencode.json`; user servers are not listed. */
   readonly openCodeMcpServers: readonly string[];
-  /** The audience the checkout is wrapped for; `null` for base only. */
-  readonly audience: string | null;
 }
 
 export const WRAP_RUNTIMES: readonly WrapRuntime[] = ["claude", "opencode"];
@@ -46,10 +47,39 @@ function wrappedFor(manifest: Manifest, runtime: WrapRuntime): boolean {
   );
 }
 
-function isHookGroup(value: unknown): value is ClaudeHookGroup {
+/**
+ * The folders of the recorded `directory` marketplaces whose plugin the wrap
+ * also enables: one without the other loads nothing.
+ */
+function carriedPluginDirectories(manifest: Manifest): string[] {
+  const marketplaces = recordedMapEntries(manifest, CLAUDE_SETTINGS_DOCUMENT, [
+    "extraKnownMarketplaces",
+  ]);
+  const enabled = recordedMapEntries(manifest, CLAUDE_SETTINGS_DOCUMENT, ["enabledPlugins"]);
+  const enabledMarketplaces = new Set(
+    Object.entries(enabled)
+      .filter(([, value]) => value === true)
+      .map(([id]) => id.slice(id.lastIndexOf("@") + 1)),
+  );
+  return Object.entries(marketplaces).flatMap(([name, entry]) => {
+    const source = isRecord(entry) ? entry.source : undefined;
+    return enabledMarketplaces.has(name) &&
+      isRecord(source) &&
+      source.source === "directory" &&
+      typeof source.path === "string"
+      ? [source.path]
+      : [];
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isHookGroup(value: unknown): value is ClaudeHookGroup {
+  return isRecord(value);
+}
+
 export function wrapStateOf(manifest: Manifest): WrapState {
   const carried = recordedListValues(manifest, CLAUDE_SETTINGS_DOCUMENT, ["hooks"]).filter(
     isHookGroup,
@@ -59,12 +89,12 @@ export function wrapStateOf(manifest: Manifest): WrapState {
     runtimes: new Set(WRAP_RUNTIMES.filter((runtime) => wrappedFor(manifest, runtime))),
     carriedClaudeHookGroups: carried,
     carriesClaudeHookGroup: (group) => carriedKeys.has(hookGroupKey(group)),
+    carriedClaudePluginDirectories: carriedPluginDirectories(manifest),
     openCodeMcpServers: recordedMapKeys(
       manifest,
       OPENCODE_CONFIG_DOCUMENT,
       OPENCODE_MCP_SERVERS_AT,
     ),
-    audience: recordedAudience(manifest),
   };
 }
 

package/src/runtime/write-atomic.ts

@@ -1,5 +1,7 @@
+// oxlint-disable no-await-in-loop
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 
 /**
  * Writes via a sibling temp file + `fs.rename()` so an interrupted write cannot
@@ -11,17 +13,79 @@ export async function writeAtomic(
   target: string,
   contents: string | Buffer,
   mode?: number,
+): Promise<void> {
+  await replaceViaTemp(target, contents, mode, false);
+}
+
+/** `exactMode`: chmod past the umask, so a replaced file keeps the mode it had. */
+async function replaceViaTemp(
+  target: string,
+  contents: string | Buffer,
+  mode: number | undefined,
+  exactMode: boolean,
 ): Promise<void> {
   const tempPath = `${target}.${crypto.randomUUID()}.tmp`;
   try {
+    /** Created with the mode, so private contents are never readable at a wider one. */
     await fs.writeFile(
       tempPath,
       contents,
       mode === undefined ? "utf8" : { encoding: "utf8", mode },
     );
+    if (exactMode && mode !== undefined) await fs.chmod(tempPath, mode);
     await fs.rename(tempPath, target);
   } catch (error) {
     await fs.rm(tempPath, { force: true }).catch(() => {});
     throw error;
   }
 }
+
+const MAX_LINK_HOPS = 40;
+
+/**
+ * Follows a symlink chain to its end, which may not exist yet: a dangling link names where to create.
+ * Link text is never normalized lexically: `..` after a directory symlink means the real parent.
+ */
+async function resolveLinkEnd(filePath: string): Promise<string> {
+  let current = filePath;
+  for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+    const parent = await fs.realpath(path.dirname(current));
+    const entry = path.join(parent, path.basename(current));
+    const link = await fs.readlink(entry).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT" || error.code === "EINVAL") return null;
+      throw error;
+    });
+    if (link === null) return entry;
+    current = path.isAbsolute(link) ? link : `${parent}${path.sep}${link}`;
+  }
+  throw Object.assign(new Error(`too many levels of symbolic links: ${filePath}`), {
+    code: "ELOOP",
+  });
+}
+
+/**
+ * As `writeAtomic`, through a symlink: the link stays and its target is
+ * replaced, or created when the link dangles. An existing file keeps its mode.
+ * A read-only file is refused, as a plain write would refuse it. A hardlinked
+ * file is written in place: replacing it would split it from its other links.
+ */
+export async function writeAtomicThroughLink(
+  filePath: string,
+  contents: string | Buffer,
+): Promise<void> {
+  const target = await resolveLinkEnd(filePath);
+  const existing = await fs.stat(target).catch(() => null);
+  if (existing && existing.nlink > 1) return fs.writeFile(target, contents, "utf8");
+  if (existing) await fs.access(target, fs.constants.W_OK);
+  await replaceViaTemp(target, contents, existing ? existing.mode & 0o7777 : undefined, true);
+}
+
+/**
+ * Deletes a file its writer left without content. A symlink stays: deleting it
+ * would leave the old text in its target, so the target is emptied instead.
+ */
+export async function removeEmptiedFile(filePath: string): Promise<void> {
+  const entry = await fs.lstat(filePath);
+  if (entry.isSymbolicLink()) await writeAtomicThroughLink(filePath, "");
+  else await fs.unlink(filePath);
+}