@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/doctor.mjs

@@ -1,11 +1,8 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 
-import { SPEC_GENERATION_AUDIT_REF } from "../constants.mjs";
 import { getBootstrapSeedEntries } from "../seeds/bootstrap.mjs";
-import { inspectBootstrapCompatibility } from "./bootstrap.mjs";
-import { loadSpecGenerationInputsConfig } from "./contracts.mjs";
-import { pathExists, readTextIfFile } from "./fs-helpers.mjs";
+import { pathExists, preflightManagedProjectPaths } from "./fs-helpers.mjs";
 import { runSeedSync, SYNC_MODE } from "./sync.mjs";
 import { localize, styleHeading, styleLabel, styleStatus } from "./ui.mjs";
 
@@ -15,111 +12,47 @@ function check(id, ok, severity, detail) {
 
 async function directoryHasFiles(root) {
   const info = await pathExists(root);
-  if (!info || !info.isDirectory()) return false;
-  const entries = await readdir(root, { withFileTypes: true });
-  return entries.length > 0;
-}
-
-async function managedEntrypoints(projectRoot) {
-  const refs = [];
-  for (const ref of ["AGENTS.md", "CLAUDE.md"]) {
-    const text = await readTextIfFile(path.join(projectRoot, ref));
-    if (text?.includes("nimicoding:managed:")) refs.push(ref);
-  }
-  return refs;
+  if (!info?.isDirectory()) return false;
+  return (await readdir(root)).length > 0;
 }
 
 export async function inspectDoctorState(projectRoot) {
-  const checks = [];
-  const bootstrap = await inspectBootstrapCompatibility(projectRoot);
-  checks.push(check(
-    "bootstrap_contract",
-    bootstrap.status === "supported",
-    "error",
-    bootstrap.status === "supported"
-      ? "bootstrap contract is supported"
-      : "bootstrap contract is missing or unsupported",
-  ));
-
-  let seedSync = null;
-  if (bootstrap.status === "supported") {
-    seedSync = await runSeedSync(projectRoot, SYNC_MODE.CHECK);
-    checks.push(check(
-      "managed_projection",
-      seedSync.ok,
+  await preflightManagedProjectPaths(projectRoot, { includeSpec: true });
+  const managedProjection = await runSeedSync(projectRoot, SYNC_MODE.CHECK);
+  const specPresent = await directoryHasFiles(path.join(projectRoot, ".nimi/spec"));
+  const checks = [
+    check(
+      "managed_surfaces",
+      managedProjection.ok,
       "error",
-      seedSync.ok
-        ? `all ${seedSync.summary.total} package-managed files are aligned`
-        : `${seedSync.checkFailures.length} package-managed files are missing or drifted`,
+      managedProjection.ok
+        ? "exact package projection and managed instruction blocks are aligned"
+        : `${managedProjection.checkFailures.length} exact managed or deprecated surface issue(s) require attention`,
+    ),
+    check(
+      "canonical_authority",
+      true,
+      "info",
+      specPresent
+        ? "canonical authority is present; run nimicoding authority check .nimi/spec for admission"
+        : "canonical authority has not been authored; the project owns all product semantics under .nimi/spec",
+    ),
+  ];
+  if (process.platform === "win32") {
+    checks.push(check(
+      "snapshot_no_follow_capability",
+      false,
+      "info",
+      "win32 does not expose O_NOFOLLOW/O_DIRECTORY; snapshot no-follow hardening is downgraded to surrounding lstat/realpath validation",
     ));
   }
-
-  const generationInputs = await loadSpecGenerationInputsConfig(projectRoot);
-  checks.push(check(
-    "spec_generation_inputs",
-    generationInputs.ok && generationInputs.mode === "class_filtered",
-    "error",
-    generationInputs.ok && generationInputs.mode === "class_filtered"
-      ? "spec generation inputs use class-filtered authority"
-      : "spec generation inputs are missing or invalid",
-  ));
-
-  const specRoot = path.join(projectRoot, ".nimi", "spec");
-  const specPresent = await directoryHasFiles(specRoot);
-  checks.push(check(
-    "spec_tree",
-    true,
-    "info",
-    specPresent
-      ? "canonical spec tree is present; conformance is checked by validate-spec-tree or project-specific validators"
-      : "canonical spec tree has not been constructed yet",
-  ));
-
-  const auditPath = path.join(projectRoot, SPEC_GENERATION_AUDIT_REF);
-  const auditPresent = Boolean(await pathExists(auditPath));
-  checks.push(check(
-    "spec_generation_audit",
-    true,
-    "info",
-    auditPresent
-      ? "spec generation audit is present; conformance is checked by validate-spec-audit"
-      : "spec generation audit is not present",
-  ));
-
-  const entrypoints = await managedEntrypoints(projectRoot);
-  checks.push(check(
-    "entrypoint_integration",
-    true,
-    "info",
-    entrypoints.length > 0
-      ? `managed methodology guidance is present in ${entrypoints.join(", ")}`
-      : "managed methodology guidance is not installed",
-  ));
-
   const seedEntries = await getBootstrapSeedEntries();
-  const ok = checks.every((entry) => entry.severity !== "error");
-
   return {
-    ok,
+    ok: checks.every((entry) => entry.severity !== "error"),
     projectRoot,
-    bootstrap,
-    managedProjection: seedSync,
-    generationInputs: {
-      ok: generationInputs.ok,
-      mode: generationInputs.mode ?? null,
-      canonicalTargetRoot: generationInputs.canonicalTargetRoot ?? null,
-    },
-    spec: {
-      present: specPresent,
-      ok: null,
-      summary: null,
-    },
-    generationAudit: {
-      present: auditPresent,
-      ok: null,
-      summary: null,
-    },
-    entrypoints,
+    bootstrap: { status: "exact_projection_registry" },
+    managedProjection,
+    spec: { present: specPresent, ok: null, summary: null },
     managedFileCount: seedEntries.length,
     checks,
   };
@@ -131,33 +64,17 @@ export function formatDoctorResult(result, options = {}) {
     "",
     styleLabel(localize("Summary:", "摘要：")),
     `  - ${localize("status", "状态")}: ${styleStatus(result.ok ? "ok" : "needs_attention")}`,
-    `  - bootstrap: ${result.bootstrap.status}`,
-    `  - managed_projection: ${result.managedProjection?.ok === true ? "aligned" : "invalid"}`,
-    `  - spec: ${!result.spec.present ? "not_constructed" : "present_not_validated"}`,
-    `  - generation_audit: ${!result.generationAudit.present ? "not_present" : "present_not_validated"}`,
+    `  - projection_policy: ${result.bootstrap.status}`,
+    `  - managed_surfaces: ${result.managedProjection.ok ? "aligned" : "invalid"}`,
+    `  - canonical_authority: ${result.spec.present ? "present_not_validated" : "not_authored"}`,
     "",
     styleLabel(localize("Checks:", "检查项：")),
   ];
-
-  const visibleChecks = options.verbose
-    ? result.checks
-    : result.checks.filter((entry) => entry.severity !== "ok" || !entry.ok);
-  if (visibleChecks.length === 0) {
-    lines.push(`  - ${localize("No blocking issues found.", "没有发现阻塞问题。")}`);
-  } else {
-    for (const entry of visibleChecks) {
-      const marker = entry.ok ? "info" : entry.severity;
-      lines.push(`  - [${marker}] ${entry.detail}`);
-    }
-  }
-
+  const visible = options.verbose ? result.checks : result.checks.filter((entry) => entry.severity !== "ok" || !entry.ok);
+  if (visible.length === 0) lines.push(`  - ${localize("No blocking integration issues found.", "没有发现阻塞性的集成问题。")}`);
+  else for (const entry of visible) lines.push(`  - [${entry.ok ? "info" : entry.severity}] ${entry.detail}`);
   if (!result.spec.present) {
-    lines.push(
-      "",
-      styleLabel(localize("Next:", "下一步：")),
-      "  - Build canonical product authority under .nimi/spec, then run nimicoding validate-spec-tree.",
-    );
+    lines.push("", styleLabel(localize("Next:", "下一步：")), "  - Author canonical authority under .nimi/spec, format changed files, then run nimicoding authority check .nimi/spec.");
   }
-
   return `${lines.join("\n")}\n`;
 }

package/cli/lib/entrypoints.mjs

@@ -1,4 +1,4 @@
-import { readFile, rm, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import {
@@ -7,101 +7,80 @@ import {
   CLAUDE_BEGIN,
   CLAUDE_END,
 } from "../constants.mjs";
-import { pathExists } from "./fs-helpers.mjs";
+import { pathExists, preflightManagedProjectPaths, readUtf8FileFatal } from "./fs-helpers.mjs";
 
-function managedAgentsBlock() {
+export class ManagedBlockError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManagedBlockError";
+  }
+}
+
+function authorityAuthoringLines() {
   return [
-    AGENTS_BEGIN,
-    "# Nimi Coding Managed Block",
-    "",
-    "- Product and repository authority lives under `/.nimi/spec/**`.",
-    "- Read `/.nimi/spec/INDEX.md` first, then the affected kernel contracts and tables.",
-    "- Read `/.nimi/methodology/**` for reasoning principles and `/.nimi/contracts/**` for spec construction and validation contracts.",
-    "- Treat `/.nimi/{config,contracts,methodology}/**` as package-managed governance support, never as product authority.",
-    "- Keep generation evidence under `/.nimi/local/state/spec-generation/**`; it must not become product truth.",
-    "- Do not treat this managed block as a replacement for project-specific rules.",
-    AGENTS_END,
-  ].join("\n");
+    "- Product authority lives under `.nimi/spec/**`.",
+    "- For canonical authority authoring, read only `.nimi/methodology/authority-authoring.yaml`, the affected authority files or bounded task context, and CLI diagnostics.",
+    "- Use `nimicoding authority context <path> <id> --max-units <n> --max-bytes <n> --json` only for the complete declared outgoing interpretation closure; it is not complete task context, and failure never permits guessed or partial context.",
+    "- Use `nimicoding authority diff` and `authority impact` with explicit `--max-bytes`; impact reports declared review obligations and does not prove implementation, consumers, or tests are synchronized.",
+    "- Use `nimicoding authority change-candidates` only with explicit channels and budgets; its complete union is recall input, never conflict, retirement, absence, authority, or conformance judgment.",
+    "- Under `.nimi/spec/**`, author only closed multi-unit `*.authority.yaml` containers or single-unit `*.authority.md`; historical document formats are unsupported and never inferred.",
+    "- Run `nimicoding authority fmt` on each changed file, then `nimicoding authority check` on the complete authority input set.",
+    "- Never bypass a failure with inferred or fallback semantics; choose repair values only from product/task authority.",
+    "- Keep derived and local verification output under `.nimi/local/**`; it is never product authority.",
+  ];
+}
+
+function managedAgentsBlock() {
+  return [AGENTS_BEGIN, "# Nimi Coding Managed Block", "", ...authorityAuthoringLines(), AGENTS_END].join("\n");
 }
 function managedClaudeBlock() {
-  return [
-    CLAUDE_BEGIN,
-    "# Nimi Coding Managed Block",
-    "",
-    "Authority order:",
-    "1. `/.nimi/spec/**`",
-    "2. `/.nimi/methodology/**`",
-    "3. `/.nimi/contracts/**`",
-    "4. `/.nimi/config/**`",
-    "5. repository-local AI entry files",
-    "",
-    "Nimi Coding owns methodology, canonical spec construction, and deterministic validation only.",
-    "Keep local generation evidence outside product authority.",
-    CLAUDE_END,
-  ].join("\n");
-}
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^$()|[\]{}\\]/g, "\\$&");
-}
-
-function blockPattern(begin, end, leading = false) {
-  return new RegExp(
-    `${leading ? "(?:\\n\\n)?" : ""}${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}${leading ? "(?:\\n)?" : ""}`,
-  );
-}
-
-function upsertManagedBlock(existing, begin, end, block) {
-  const pattern = blockPattern(begin, end);
-  if (pattern.test(existing)) {
-    return existing.replace(pattern, block);
+  return [CLAUDE_BEGIN, "# Nimi Coding Managed Block", "", ...authorityAuthoringLines(), CLAUDE_END].join("\n");
+}
+
+function occurrenceIndexes(text, marker) {
+  const indexes = [];
+  let offset = 0;
+  while (offset <= text.length) {
+    const index = text.indexOf(marker, offset);
+    if (index === -1) break;
+    indexes.push(index);
+    offset = index + marker.length;
   }
-  const prefix = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  return `${existing}${prefix}${block}\n`;
+  return indexes;
 }
 
-function removeManagedBlock(existing, begin, end) {
-  const pattern = blockPattern(begin, end, true);
-  if (!pattern.test(existing)) {
-    return { changed: false, next: existing, deleteFile: false };
+export function analyzeManagedBlockText(existing, begin, end, expectedBlock, label = "managed block") {
+  const begins = occurrenceIndexes(existing, begin);
+  const ends = occurrenceIndexes(existing, end);
+  if (begins.length === 0 && ends.length === 0) return { state: "missing", begin: -1, end: -1, exact: false };
+  if (begins.length !== 1 || ends.length !== 1) {
+    throw new ManagedBlockError(`${label} markers must contain exactly one ordered, non-nested begin/end pair`);
   }
-  const next = existing
-    .replace(pattern, "\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .replace(/^\n+/, "")
-    .trimEnd();
+  if (begins[0] >= ends[0]) throw new ManagedBlockError(`${label} markers must contain exactly one ordered, non-nested begin/end pair`);
+  const endOffset = ends[0] + end.length;
+  const actualBlock = existing.slice(begins[0], endOffset);
   return {
-    changed: true,
-    next: next.length === 0 ? "" : `${next}\n`,
-    deleteFile: next.length === 0,
+    state: actualBlock === expectedBlock ? "exact" : "drifted",
+    begin: begins[0],
+    end: endOffset,
+    exact: actualBlock === expectedBlock,
   };
 }
 
-function computeTextFileUpdate(existing, block, begin, end, header) {
-  const base = existing ?? header;
-  const next = upsertManagedBlock(base, begin, end, block);
-  return { changed: next !== base, next };
-}
-
-async function upsertTextFile(filePath, block, begin, end, header) {
-  const existing = (await pathExists(filePath)) ? await readFile(filePath, "utf8") : header;
-  const computed = computeTextFileUpdate(existing, block, begin, end, header);
-  if (!computed.changed) return false;
-  await writeFile(filePath, computed.next, "utf8");
-  return true;
+function upsertManagedBlock(existing, analysis, block) {
+  if (analysis.state === "missing") {
+    const prefix = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${prefix}${block}\n`;
+  }
+  return `${existing.slice(0, analysis.begin)}${block}${existing.slice(analysis.end)}`;
 }
 
-async function removeManagedTextFile(filePath, begin, end, emptyFallbackHeader = null) {
-  const existing = (await pathExists(filePath)) ? await readFile(filePath, "utf8") : null;
-  if (existing === null) return { changed: false, removedFile: false };
-  const computed = removeManagedBlock(existing, begin, end);
-  if (!computed.changed) return { changed: false, removedFile: false };
-  if (computed.deleteFile || (emptyFallbackHeader && computed.next.trim() === emptyFallbackHeader.trim())) {
-    await rm(filePath, { force: true });
-    return { changed: true, removedFile: true };
-  }
-  await writeFile(filePath, computed.next, "utf8");
-  return { changed: true, removedFile: false };
+function removeManagedBlock(existing, analysis) {
+  if (analysis.state === "missing") return { changed: false, next: existing };
+  return {
+    changed: true,
+    next: `${existing.slice(0, analysis.begin)}${existing.slice(analysis.end)}`,
+  };
 }
 
 function entrypointDefinitions(projectRoot) {
@@ -125,46 +104,66 @@ function entrypointDefinitions(projectRoot) {
   ];
 }
 
+async function inspectDefinition(file) {
+  const info = await pathExists(file.path);
+  const existing = info?.isFile() ? await readUtf8FileFatal(file.path, file.relativePath) : null;
+  const base = existing ?? file.header;
+  const analysis = analyzeManagedBlockText(base, file.begin, file.end, file.block, `${file.relativePath} nimicoding managed block`);
+  const next = upsertManagedBlock(base, analysis, file.block);
+  return { ...file, existing, base, analysis, next, changed: next !== base };
+}
+
+export async function inspectEntrypointIntegration(projectRoot) {
+  await preflightManagedProjectPaths(projectRoot);
+  const states = [];
+  for (const file of entrypointDefinitions(projectRoot)) states.push(await inspectDefinition(file));
+  return states;
+}
+
 export async function previewEntrypointIntegration(projectRoot) {
-  const updates = [];
-  for (const file of entrypointDefinitions(projectRoot)) {
-    const existing = (await pathExists(file.path)) ? await readFile(file.path, "utf8") : null;
-    if (computeTextFileUpdate(existing, file.block, file.begin, file.end, file.header).changed) {
-      updates.push(file.relativePath);
-    }
-  }
-  return updates;
+  return (await inspectEntrypointIntegration(projectRoot)).filter((state) => state.changed).map((state) => state.relativePath);
 }
 
 export async function integrateEntrypoints(projectRoot) {
+  const states = await inspectEntrypointIntegration(projectRoot);
   const updated = [];
-  for (const file of entrypointDefinitions(projectRoot)) {
-    if (await upsertTextFile(file.path, file.block, file.begin, file.end, file.header)) {
-      updated.push(file.relativePath);
-    }
+  for (const state of states) {
+    if (!state.changed) continue;
+    await writeFile(state.path, state.next, "utf8");
+    updated.push(state.relativePath);
   }
   return updated;
 }
 
-export async function previewEntrypointRemoval(projectRoot) {
-  const updates = [];
+async function inspectEntrypointRemoval(projectRoot) {
+  await preflightManagedProjectPaths(projectRoot);
+  const states = [];
   for (const file of entrypointDefinitions(projectRoot)) {
-    const existing = (await pathExists(file.path)) ? await readFile(file.path, "utf8") : null;
-    if (existing !== null && removeManagedBlock(existing, file.begin, file.end).changed) {
-      updates.push(file.relativePath);
+    const info = await pathExists(file.path);
+    const existing = info?.isFile() ? await readUtf8FileFatal(file.path, file.relativePath) : null;
+    if (existing === null) {
+      states.push({ ...file, existing, removal: { changed: false, next: "" } });
+      continue;
     }
+    const analysis = analyzeManagedBlockText(existing, file.begin, file.end, file.block, `${file.relativePath} nimicoding managed block`);
+    const removal = removeManagedBlock(existing, analysis);
+    states.push({ ...file, existing, removal });
   }
-  return updates;
+  return states;
+}
+
+export async function previewEntrypointRemoval(projectRoot) {
+  return (await inspectEntrypointRemoval(projectRoot)).filter((state) => state.removal.changed).map((state) => state.relativePath);
 }
 
 export async function removeManagedEntrypoints(projectRoot) {
+  const states = await inspectEntrypointRemoval(projectRoot);
   const updatedFiles = [];
   const removedFiles = [];
-  for (const file of entrypointDefinitions(projectRoot)) {
-    const result = await removeManagedTextFile(file.path, file.begin, file.end, file.header.trim());
-    if (result.changed) {
-      (result.removedFile ? removedFiles : updatedFiles).push(file.relativePath);
-    }
+  for (const state of states) {
+    if (!state.removal.changed) continue;
+    await writeFile(state.path, state.removal.next, "utf8");
+    updatedFiles.push(state.relativePath);
   }
   return { updatedFiles, removedFiles };
 }

package/cli/lib/fs-helpers.mjs

@@ -1,33 +1,157 @@
-import { readFile, stat, writeFile } from "node:fs/promises";
+import { lstat, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const SHARED_INODE_FORBIDDEN_PATHS = new Set([
+  ".nimi/methodology/authority-authoring.yaml",
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".gitignore",
+  ".gitattributes",
+]);
+const FATAL_UTF8_HOST_PATHS = new Set(["AGENTS.md", "CLAUDE.md", ".gitignore", ".gitattributes"]);
+
+const BASE_MANAGED_PATHS = [
+  [".nimi", "directory"],
+  [".nimi/local", "directory"],
+  [".nimi/methodology", "directory"],
+  [".nimi/methodology/authority-authoring.yaml", "file"],
+  [".nimi/config", "directory"],
+  [".nimi/config/spec-generation-inputs.yaml", "file"],
+  [".nimi/contracts", "directory"],
+  [".nimi/contracts/domain-admission.schema.yaml", "file"],
+  ["AGENTS.md", "file"],
+  ["CLAUDE.md", "file"],
+  [".gitignore", "file"],
+  [".gitattributes", "file"],
+];
+
+export class ManagedPathError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManagedPathError";
+  }
+}
+
+export class ManagedTextError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManagedTextError";
+  }
+}
 
 export async function pathExists(targetPath) {
   try {
-    return await stat(targetPath);
+    return await lstat(targetPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function portable(value) {
+  return value.split(path.sep).join(path.posix.sep);
+}
+
+async function inspectManagedPath(projectRoot, relativePath, expectedType) {
+  const components = relativePath.split("/");
+  let current = projectRoot;
+  for (let index = 0; index < components.length; index += 1) {
+    current = path.join(current, components[index]);
+    let info;
+    try {
+      info = await lstat(current);
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw new ManagedPathError(`cannot inspect managed path ${portable(path.relative(projectRoot, current))}: ${error.message}`);
+    }
+    const ref = portable(path.relative(projectRoot, current));
+    if (info.isSymbolicLink()) throw new ManagedPathError(`managed path boundary refuses symbolic link: ${ref}`);
+    const isTarget = index === components.length - 1;
+    if (!isTarget && !info.isDirectory()) throw new ManagedPathError(`managed path ancestor must be a directory: ${ref}`);
+    if (isTarget && expectedType === "directory" && !info.isDirectory()) throw new ManagedPathError(`managed path must be a directory: ${ref}`);
+    if (isTarget && expectedType === "file" && !info.isFile()) throw new ManagedPathError(`managed path must be a regular file: ${ref}`);
+    if (isTarget && info.isFile() && SHARED_INODE_FORBIDDEN_PATHS.has(relativePath) && info.nlink > 1) {
+      throw new ManagedPathError(`managed regular file must not share an inode: ${ref}`);
+    }
+    if (isTarget && info.isFile() && FATAL_UTF8_HOST_PATHS.has(relativePath)) await readUtf8FileFatal(current, ref);
+  }
+}
+
+export async function preflightManagedProjectPaths(projectRoot, options = {}) {
+  const absoluteRoot = path.resolve(projectRoot);
+  let rootInfo;
+  try {
+    rootInfo = await lstat(absoluteRoot);
+  } catch (error) {
+    throw new ManagedPathError(`cannot inspect project root: ${error.message}`);
+  }
+  if (rootInfo.isSymbolicLink()) throw new ManagedPathError("managed path boundary refuses symbolic-link project root");
+  if (!rootInfo.isDirectory()) throw new ManagedPathError("project root must be a directory");
+  const specs = options.includeSpec
+    ? [...BASE_MANAGED_PATHS, [".nimi/spec", "directory"]]
+    : BASE_MANAGED_PATHS;
+  for (const [relativePath, expectedType] of specs) {
+    await inspectManagedPath(absoluteRoot, relativePath, expectedType);
+  }
+  return true;
+}
+
+export async function readUtf8FileFatal(filePath, label = filePath) {
+  const bytes = await readFile(filePath);
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   } catch {
-    return null;
+    throw new ManagedTextError(`managed host text is not valid UTF-8: ${label}`);
   }
 }
 
 export async function readTextIfFile(filePath) {
   const info = await pathExists(filePath);
-  if (!info || !info.isFile()) {
-    return null;
-  }
-
+  if (!info || !info.isFile() || info.isSymbolicLink()) return null;
   return readFile(filePath, "utf8");
 }
 
-export async function appendGitignoreEntries(gitignorePath, entries) {
-  const existing = (await pathExists(gitignorePath))
-    ? await readFile(gitignorePath, "utf8")
-    : "";
-  const missing = entries.filter((entry) => !existing.includes(entry));
+export function normalizeTextToLf(text) {
+  return String(text).replace(/\r\n?/gu, "\n");
+}
 
-  if (missing.length === 0) {
-    return false;
-  }
+function exactTextLines(text) {
+  return String(text ?? "")
+    .split(/\n/u)
+    .map((line) => line.endsWith("\r") ? line.slice(0, -1) : line);
+}
+
+export function hasExactTextLine(text, entry) {
+  return exactTextLines(text).includes(entry);
+}
+
+function effectiveGitignoreRuleLines(text) {
+  return String(text ?? "")
+    .split(/\n/u)
+    .map((line) => line.endsWith("\r") ? line.slice(0, -1) : line)
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+
+export function hasExactGitignoreRule(text, entry) {
+  return effectiveGitignoreRuleLines(text).at(-1) === entry;
+}
 
+export async function appendGitignoreEntries(gitignorePath, entries) {
+  const existingInfo = await pathExists(gitignorePath);
+  const existing = existingInfo?.isFile() ? await readUtf8FileFatal(gitignorePath, ".gitignore") : "";
+  const missing = entries.filter((entry) => !hasExactGitignoreRule(existing, entry));
+  if (missing.length === 0) return false;
   const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
   await writeFile(gitignorePath, `${existing}${prefix}${missing.join("\n")}\n`, "utf8");
   return true;
 }
+
+export async function appendGitattributesEntries(gitattributesPath, entries) {
+  const existingInfo = await pathExists(gitattributesPath);
+  const existing = existingInfo?.isFile() ? await readUtf8FileFatal(gitattributesPath, ".gitattributes") : "";
+  const missing = entries.filter((entry) => !hasExactTextLine(existing, entry));
+  if (missing.length === 0) return false;
+  const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  await writeFile(gitattributesPath, `${existing}${prefix}${missing.join("\n")}\n`, "utf8");
+  return true;
+}