peaks-loop 4.1.1 → 4.1.3

package/scripts/canonical-store.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+//
+// The peaks-loop canonical asset store — `~/.peaks/{skills,agents,output-styles}` (was
+// `~/.agents`; HISTORY — see `rd/evidence-root-switch.md` for why it moved).
+//
+// WHY. `install-skills.mjs` linked each IDE skills dir straight at
+// `<packageRoot>/skills/<name>`, a path that changes on every `npm i -g
+// peaks-loop@latest`: the links bound to a VERSION, not to a PATH peaks-loop owns.
+//
+// WIRED FOR SKILLS (slice 2) and PRUNED (slice 3); agents / output-styles are later.
+// `scripts/install-skills.mjs` is the only caller today. Idempotence is by CONTENT —
+// an asset whose bytes already match is not rewritten — and OWNERSHIP is by MARKER:
+// see `isManagedEntry`, which gates the replace path here and the delete path in
+// `scripts/canonical-store-prune.mjs`.
+
+import { randomUUID } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/** The three asset families, parallel under the canonical root. */
+export const CANONICAL_ASSET_KINDS = Object.freeze(['skills', 'agents', 'output-styles']);
+
+/** Redirects the canonical root; `PEAKS_HOME` is this repo's existing name for
+ *  `~/.peaks` (`src/services/sop/sop-paths.ts`). */
+export const CANONICAL_ROOT_ENV = 'PEAKS_HOME';
+
+/** Sidecar suffix, same convention `install-skills.mjs` already writes. */
+export const MANAGED_MARKER_SUFFIX = '.peaks-managed';
+
+/** Scratch prefix for the atomic write; never a valid name (assets do not start with a dot). */
+const TEMP_PREFIX = '.peaks-tmp-';
+
+function getPathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/** `\\?\C:\x` and `\\?\UNC\srv\share` are spellings of a path, not other paths. */
+function stripLongPathPrefix(value) {
+  const uncPrefix = '\\\\?\\UNC\\';
+  if (value.startsWith(uncPrefix)) return `\\\\${value.slice(uncPrefix.length)}`;
+  const prefix = '\\\\?\\';
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+
+/**
+ * The real, resolved, case-folded identity of a path, or null when it does not
+ * resolve (a dangling junction included).
+ */
+function resolveIdentity(path) {
+  let resolved;
+  try {
+    resolved = realpathSync(path);
+  } catch {
+    return null;
+  }
+  const normalized = stripLongPathPrefix(resolved);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+/**
+ * Whether `linkPath` resolves to the same directory as `expectedPath`. Both sides
+ * go through `realpath`, so a `\\?\` prefix, a `.` segment or a case difference
+ * cannot make one directory look like two.
+ */
+export function linkResolvesTo(linkPath, expectedPath) {
+  const actual = resolveIdentity(linkPath);
+  const expected = resolveIdentity(expectedPath);
+  return actual !== null && expected !== null && actual === expected;
+}
+
+/**
+ * Does peaks-loop own `targetPath`? Our `.peaks-managed` marker beside it is the
+ * only proof: a path the user authored carries none and must never be replaced or
+ * removed (a DANGLING link counts as ours).
+ */
+export function isManagedEntry(targetPath) {
+  const stats = getPathStats(targetPath);
+  if (!stats) return false;
+  if (stats.isSymbolicLink()) return isOurLink(targetPath, stats);
+  return readManagedTarget(targetPath) !== null;
+}
+
+/** Reject anything that is not one plain path segment; names reach the filesystem. */
+function assertAssetName(name, kind) {
+  if (
+    typeof name !== 'string' ||
+    name.length === 0 ||
+    name === '.' ||
+    name === '..' ||
+    name.includes('/') ||
+    name.includes('\\')
+  ) {
+    throw new Error(`Peaks canonical ${kind} name must be a single path segment`);
+  }
+}
+
+/**
+ * The canonical root: `options.root`, else `$PEAKS_HOME`, else `~/.peaks`.
+ * @param {{ root?: string }} [options]
+ */
+export function resolveCanonicalRoot(options = {}) {
+  const configured = options.root ?? process.env[CANONICAL_ROOT_ENV];
+  if (typeof configured === 'string' && configured.trim().length > 0) {
+    return resolve(configured);
+  }
+  return resolve(join(homedir(), '.peaks'));
+}
+
+/**
+ * One asset family's directory inside the canonical root.
+ * @param {'skills' | 'agents' | 'output-styles'} kind
+ * @param {{ root?: string }} [options]
+ */
+export function resolveKindRoot(kind, options = {}) {
+  if (!CANONICAL_ASSET_KINDS.includes(kind)) {
+    throw new Error(
+      `Peaks canonical asset kind must be one of ${CANONICAL_ASSET_KINDS.join(', ')}`
+    );
+  }
+  return join(resolveCanonicalRoot(options), kind);
+}
+
+/** A marker is a plain single-linked file — never a link, never a hardlink. */
+function validateMarkerPath(markerPath) {
+  const stats = getPathStats(markerPath);
+  if (!stats) return;
+  if (stats.isSymbolicLink()) throw new Error('Peaks managed marker path must not be a symlink');
+  if (!stats.isFile()) throw new Error('Peaks managed marker path must be a file');
+  if (stats.nlink !== 1) throw new Error('Peaks managed marker path must not be hardlinked');
+}
+
+/** The `.peaks-managed` sidecar beside `targetPath`, trimmed, or null — the same
+ *  convention `install-skills.mjs` writes (one line holding the producing path). */
+export function readManagedTarget(targetPath) {
+  const markerPath = `${targetPath}${MANAGED_MARKER_SUFFIX}`;
+  validateMarkerPath(markerPath);
+  if (!existsSync(markerPath)) return null;
+  return readFileSync(markerPath, 'utf8').trim();
+}
+
+/** Write the sidecar through a sibling temp file, so no reader sees it half-written. */
+export function writeManagedMarker(targetPath, provenance) {
+  const markerPath = `${targetPath}${MANAGED_MARKER_SUFFIX}`;
+  validateMarkerPath(markerPath);
+  mkdirSync(dirname(markerPath), { recursive: true });
+  const tempPath = `${markerPath}${TEMP_PREFIX}${randomUUID()}`;
+  writeFileSync(tempPath, `${provenance}\n`, 'utf8');
+  renameSync(tempPath, markerPath);
+}
+
+/** Every file and directory under `rootPath`, as sorted `/`-joined relative paths. */
+function listTreeEntries(rootPath) {
+  const entries = [];
+  const walk = (dir, prefix) => {
+    for (const name of readdirSync(dir).sort()) {
+      const relativePath = prefix === '' ? name : `${prefix}/${name}`;
+      const stats = lstatSync(join(dir, name));
+      if (stats.isDirectory()) {
+        entries.push(`${relativePath}/`);
+        walk(join(dir, name), relativePath);
+      } else if (stats.isFile()) {
+        entries.push(relativePath);
+      } else {
+        throw new Error(
+          `Peaks canonical store cannot read ${join(dir, name)}: not a file or directory`
+        );
+      }
+    }
+  };
+  walk(rootPath, '');
+  return entries;
+}
+
+/** True when `targetPath` already holds exactly the bytes `sourcePath` holds. */
+function contentMatches(sourcePath, targetPath) {
+  const targetStats = getPathStats(targetPath);
+  if (!targetStats || targetStats.isSymbolicLink()) return false;
+  if (!targetStats.isDirectory()) {
+    return targetStats.isFile() && readFileSync(sourcePath).equals(readFileSync(targetPath));
+  }
+  const sourceEntries = listTreeEntries(sourcePath);
+  const targetEntries = listTreeEntries(targetPath);
+  if (sourceEntries.length !== targetEntries.length) return false;
+  for (let index = 0; index < sourceEntries.length; index += 1) {
+    if (sourceEntries[index] !== targetEntries[index]) return false;
+    if (sourceEntries[index].endsWith('/')) continue;
+    const from = join(sourcePath, sourceEntries[index]);
+    const to = join(targetPath, targetEntries[index]);
+    if (!readFileSync(from).equals(readFileSync(to))) return false;
+  }
+  return true;
+}
+
+/**
+ * Materialise `sourcePath` as a REAL COPY at `<kindRoot>/<name>`: idempotent by
+ * content, and REFUSING when the landing path is not ours — an existing entry with
+ * no marker beside it gets `action: 'unmanaged'` instead of the `rmSync` that used
+ * to run unconditionally (the `~/.peaks/agents/ecc` shape).
+ *
+ * @param {{ sourcePath: string, name: string, kind: string, root?: string }} options
+ */
+export function ensureCanonicalCopy(options) {
+  const { sourcePath, name, kind } = options;
+  assertAssetName(name, kind);
+  const kindRoot = resolveKindRoot(kind, options);
+  const canonicalPath = join(kindRoot, name);
+
+  if (getPathStats(canonicalPath) && !isManagedEntry(canonicalPath)) {
+    return { canonicalPath, action: 'unmanaged' };
+  }
+  if (contentMatches(sourcePath, canonicalPath)) {
+    if (readManagedTarget(canonicalPath) !== sourcePath) {
+      writeManagedMarker(canonicalPath, sourcePath);
+    }
+    return { canonicalPath, action: 'unchanged' };
+  }
+
+  mkdirSync(kindRoot, { recursive: true });
+  const tempPath = join(kindRoot, `${TEMP_PREFIX}${randomUUID()}`);
+  try {
+    cpSync(sourcePath, tempPath, { recursive: true });
+    rmSync(canonicalPath, { recursive: true, force: true });
+    renameSync(tempPath, canonicalPath);
+  } catch (error) {
+    rmSync(tempPath, { recursive: true, force: true });
+    throw error;
+  }
+  writeManagedMarker(canonicalPath, sourcePath);
+  return { canonicalPath, action: 'installed' };
+}
+
+/**
+ * Is `linkPath` a link peaks-loop may replace? A link we own carries our sidecar
+ * whose recorded path really is what the link resolves to; a DANGLING one counts.
+ */
+function isOurLink(linkPath, stats) {
+  if (!stats.isSymbolicLink()) return false;
+  if (!existsSync(linkPath)) return true;
+  const recorded = readManagedTarget(linkPath);
+  return recorded !== null && linkResolvesTo(linkPath, recorded);
+}
+
+/**
+ * Point an IDE entry at the canonical copy, copying and repairing as needed. Only a
+ * link peaks-loop owns is ever replaced; a real directory the user authored is left
+ * alone and reported `skipped`. An `unmanaged` copy is never linked TO either.
+ *
+ * @param {{ sourcePath: string, name: string, kind: string, linkPath?: string, root?: string }} options
+ */
+export function reconcileCanonicalEntry(options) {
+  const { linkPath } = options;
+  const copied = ensureCanonicalCopy(options);
+  if (copied.action === 'unmanaged') return { ...copied, linkAction: 'skipped' };
+  if (typeof linkPath !== 'string' || linkPath.length === 0) {
+    return { ...copied, linkAction: 'skipped' };
+  }
+  if (linkResolvesTo(linkPath, copied.canonicalPath)) {
+    return { ...copied, linkAction: 'unchanged' };
+  }
+
+  let linkAction = 'linked';
+  const current = getPathStats(linkPath);
+  if (current) {
+    if (!isOurLink(linkPath, current)) return { ...copied, linkAction: 'skipped' };
+    unlinkSync(linkPath);
+    const markerPath = `${linkPath}${MANAGED_MARKER_SUFFIX}`;
+    if (existsSync(markerPath)) unlinkSync(markerPath);
+    linkAction = 'repaired';
+  }
+
+  mkdirSync(dirname(linkPath), { recursive: true });
+  const linkType = lstatSync(copied.canonicalPath).isDirectory()
+    ? process.platform === 'win32'
+      ? 'junction'
+      : 'dir'
+    : 'file';
+  symlinkSync(copied.canonicalPath, linkPath, linkType);
+  writeManagedMarker(linkPath, copied.canonicalPath);
+  return { ...copied, linkAction };
+}

package/scripts/install-skills-bundles.mjs

@@ -0,0 +1,233 @@
+// scripts/install-skills-bundles.mjs
+//
+// The two installers that read a directory of bundled assets out of the package and
+// reconcile each entry into an IDE directory: the DIRECTORY-shaped family (skills) and
+// the FILE-shaped one (agents). Each owns its dispatch precedence and its repair rule.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { reconcileCanonicalEntry } from './canonical-store.mjs';
+import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
+import { pruneBundledEntries } from './canonical-store-prune.mjs';
+import { createInstallResult } from './install-skills-report.mjs';
+import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
+import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
+
+/**
+ * THE INSTALL CANDIDATE LIST — every skill the package ships, as
+ * `{ skillName, sourcePath }`.
+ *
+ * After the v2.13.0 bee-demote (commit de0872b), the role skills (peaks-prd,
+ * peaks-rd, peaks-qa, peaks-ui, peaks-sc, peaks-txt) moved under
+ * `skills/bee/<role>/` while user-facing helpers stayed at `skills/<name>/`. So the
+ * list is built by walking top-level entries (user-facing helpers) AND
+ * `skills/bee/<role>` (demoted role skills). Each candidate is installed under its
+ * basename, so the postinstall links `~/.claude/skills/peaks-rd` to
+ * `skills/bee/peaks-rd` rather than to `skills/bee`.
+ *
+ * De-dupe rule: a top-level helper with the same name WINS, which preserves the
+ * existing install contract for any helper sharing a name with a demoted role skill
+ * (legacy overlap).
+ *
+ * @param {string} skillsRoot
+ * @returns {Array<{ skillName: string, sourcePath: string }>}
+ */
+function collectSkillCandidates(skillsRoot) {
+  const beeRoot = join(skillsRoot, 'bee');
+  /** @type {Array<{ skillName: string, sourcePath: string }>} */
+  const candidates = [];
+  for (const skillName of readdirSync(skillsRoot)) {
+    if (skillName === 'bee') continue;
+    const sourcePath = join(skillsRoot, skillName);
+    if (!isSkillSource(sourcePath)) continue;
+    candidates.push({ skillName, sourcePath });
+  }
+  if (existsSync(beeRoot) && isDirectoryEntry(beeRoot)) {
+    for (const skillName of readdirSync(beeRoot)) {
+      const sourcePath = join(beeRoot, skillName);
+      if (!isSkillSource(sourcePath)) continue;
+      if (candidates.some((c) => c.skillName === skillName)) continue;
+      candidates.push({ skillName, sourcePath });
+    }
+  }
+  return candidates;
+}
+
+/** A real directory entry — `lstat`, so a symlink to one is NOT one. */
+function isDirectoryEntry(entryPath) {
+  return lstatSync(entryPath).isDirectory();
+}
+
+/** A directory entry that is a skill: a real directory holding a `SKILL.md`. */
+function isSkillSource(sourcePath) {
+  return isDirectoryEntry(sourcePath) && existsSync(join(sourcePath, 'SKILL.md'));
+}
+
+export function installBundledSkills(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const skillsRoot = join(packageRoot, 'skills');
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — the precedence itself now lives in ONE place
+  // (`resolveBundleTargetRoot` in `install-skills-ide.mjs`), because all three
+  // families stated it and only this one also warns.
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'skillsDir',
+    envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
+    fallback: '.claude/skills',
+    warn: true
+  });
+
+  const installed = [];
+  const skipped = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateSkillsRoot = createInstallRootValidator(targetRoot, 'Peaks skills');
+
+  const candidates = collectSkillCandidates(skillsRoot);
+
+  for (const { skillName, sourcePath } of candidates) {
+    const targetPath = join(targetRoot, skillName);
+
+    // Slice 2 (`agents-canonical-store`) — the entry points at the CANONICAL
+    // STORE (`~/.peaks/skills/<name>`), not at `<packageRoot>/skills/<name>`,
+    // because `<packageRoot>` changes on every `npm i -g peaks-loop@latest` and
+    // the links must bind to a PATH peaks-loop owns, not to a VERSION. Repair is
+    // the only behaviour: an entry peaks-loop owns (sidecar matches, or the link
+    // dangles) is relinked onto the store; only a real directory the user authored
+    // is left alone and reported `skipped`. `options.reconcileJunctions` is
+    // therefore READ NOWHERE here — still accepted (`sync-service.ts` forwards it)
+    // so passing it changes nothing, and removing it is a CLI-surface change this
+    // slice does not own.
+    validateSkillsRoot();
+    const reconciled = reconcileCanonicalEntry({
+      kind: 'skills',
+      name: skillName,
+      sourcePath,
+      linkPath: targetPath
+    });
+    validateSkillsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(skillName);
+      continue;
+    }
+    installed.push(skillName);
+  }
+
+  // Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
+  // package left its canonical copy, every IDE link and every sidecar on the
+  // user's machine forever, because nothing walked the DESTINATIONS. This does,
+  // and deletes only what `isManagedEntry` proves is ours.
+  const { pruned } = pruneBundledEntries({
+    kind: 'skills',
+    keepNames: candidates.map((candidate) => candidate.skillName),
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned };
+}
+
+/**
+ * Slice 7/7 — bundled agents (Claude Code sub-agent prompts).
+ *
+ * Writes into the IDE's sub-agent loader directory (`~/.claude/agents/` for Claude
+ * Code, and whatever `agentsDir` the detected profile declares). The bytes live in
+ * the canonical store (`~/.peaks/agents/<name>`) and the IDE entry is a link to it.
+ *
+ * Ownership policy — ONE predicate, in `canonical-store-link.mjs::isOwnedFileEntry`,
+ * and it is deliberately not a string comparison:
+ *   - entry resolves to the canonical copy              → leave it (idempotent run)
+ *   - entry is a link we wrote (sidecar agrees, dangles) → relink onto the store
+ *   - entry is a real file with OUR sidecar beside it    → re-point it at the store
+ *   - entry is a real file with a LEGACY sidecar whose
+ *     recorded package path no longer resolves           → same: repair it
+ *   - entry is a real file we never wrote (no sidecar)   → skip (user-authored)
+ *   - entry is a real file whose sidecar names a path
+ *     that STILL resolves                                → skip (a second live install)
+ *
+ * The two "skip" arms above are the ones the old code got wrong in opposite
+ * directions: it skipped whenever the package path merely DIFFERED, which froze
+ * every entry on the first upgrade, silently and permanently. See
+ * `isOwnedFileEntry` for why a vanished package path is proof of an earlier install.
+ */
+export function installBundledAgents(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const agentsRoot = join(packageRoot, 'agents');
+
+  // Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
+  // Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
+  // PEAKS_SKIP_SKILL_INSTALL).
+  if (
+    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
+    process.env.PEAKS_SKIP_AGENT_INSTALL === '1' ||
+    !existsSync(agentsRoot)
+  ) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — same precedence as the other two families,
+  // resolved by the same helper (`resolveBundleTargetRoot`).
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'agentsDir',
+    envVar: 'PEAKS_CLAUDE_AGENTS_DIR',
+    fallback: '.claude/agents'
+  });
+
+  const installed = [];
+  const skipped = [];
+  const fallbacks = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateAgentsRoot = createInstallRootValidator(targetRoot, 'Peaks agents');
+
+  // Slice 4 (`agents-canonical-store`) — the canonical store owns the bytes and the
+  // IDE entry points at it. Everything this loop used to decide about ownership is
+  // now `reconcileCanonicalFileEntry`'s, and the reason is the defect the brief
+  // names as this slice's core: the old test was
+  // `resolve(marker.sourcePath) === resolve(sourcePath)`, a STRING comparison against
+  // the package path of the installing version — a path with a node version inside it
+  // (`…\nvm\v24.21.0\node_modules\peaks-loop\agents\…`). It went false the first time
+  // the package moved and stayed false, so the agent silently never updated again.
+  const bundledAgentNames = [];
+  for (const agentFileName of readdirSync(agentsRoot)) {
+    const sourcePath = join(agentsRoot, agentFileName);
+    if (!lstatSync(sourcePath).isFile() || !agentFileName.endsWith('.md')) continue;
+    bundledAgentNames.push(agentFileName);
+
+    validateAgentsRoot();
+    const reconciled = reconcileCanonicalFileEntry({
+      kind: 'agents',
+      name: agentFileName,
+      sourcePath,
+      linkPath: join(targetRoot, agentFileName),
+      createFileLink: options.createFileLink
+    });
+    validateAgentsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(agentFileName);
+      continue;
+    }
+    installed.push(agentFileName);
+    if (reconciled.fallback !== null) {
+      fallbacks.push({ name: agentFileName, ...reconciled.fallback });
+    }
+  }
+
+  // The delete half: an agent the package stops shipping used to leave its canonical
+  // copy, its IDE entry and both sidecars on the machine forever.
+  const { pruned } = pruneBundledEntries({
+    kind: 'agents',
+    keepNames: bundledAgentNames,
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned, fallbacks };
+}

package/scripts/install-skills-fs.mjs

@@ -0,0 +1,148 @@
+// scripts/install-skills-fs.mjs
+//
+// The guarded filesystem and path vocabulary the installers share: every read that must
+// not follow a symlink, every write that must be atomic, and the two containments
+// (a path stays inside a root; a lock root does not move under a write).
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function getPathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+export function validateOpenFile(fd, path, errorMessage) {
+  const fdStats = fstatSync(fd);
+  const pathStats = lstatSync(path);
+  if (
+    !fdStats.isFile() ||
+    !pathStats.isFile() ||
+    fdStats.dev !== pathStats.dev ||
+    fdStats.ino !== pathStats.ino
+  ) {
+    throw new Error(errorMessage);
+  }
+  if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
+    throw new Error(`${errorMessage}: hardlinked file`);
+  }
+}
+
+export function getSafeReadOpenFlags() {
+  return typeof constants.O_NOFOLLOW === 'number'
+    ? constants.O_RDONLY | constants.O_NOFOLLOW
+    : constants.O_RDONLY;
+}
+
+export function readFileSafely(path, errorMessage) {
+  const fd = openSync(path, getSafeReadOpenFlags());
+  try {
+    validateOpenFile(fd, path, errorMessage);
+    return readFileSync(fd, 'utf8');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function validateInstallRoot(targetRoot, label) {
+  const rootStats = lstatSync(targetRoot);
+  if (rootStats.isSymbolicLink()) {
+    throw new Error(`${label} install root must not be a symlink`);
+  }
+  if (!rootStats.isDirectory()) {
+    throw new Error(`${label} install root must be a directory`);
+  }
+  return rootStats;
+}
+
+export function createInstallRootValidator(targetRoot, label) {
+  const expectedStats = validateInstallRoot(targetRoot, label);
+  return () => {
+    const rootStats = validateInstallRoot(targetRoot, label);
+    if (rootStats.dev !== expectedStats.dev || rootStats.ino !== expectedStats.ino) {
+      throw new Error(`${label} install root changed during write`);
+    }
+  };
+}
+
+export function resolvePackageRoot(options = {}) {
+  return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+}
+
+export function isInsidePath(childPath, parentPath) {
+  const relativePath = relative(parentPath, childPath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function getSafeTempOpenFlags() {
+  const baseFlags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
+  return typeof constants.O_NOFOLLOW === 'number' ? baseFlags | constants.O_NOFOLLOW : baseFlags;
+}
+
+export function writeFileAtomically(configPath, content, errorMessage, validateBeforeWrite) {
+  validateBeforeWrite();
+
+  const tempPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  let fd = openSync(tempPath, getSafeTempOpenFlags(), 0o600);
+  let renamed = false;
+  let closeError = null;
+  try {
+    validateOpenFile(fd, tempPath, errorMessage);
+    fchmodSync(fd, 0o600);
+    writeFileSync(fd, content, 'utf8');
+    const writeFd = fd;
+    fd = null;
+    closeSync(writeFd);
+    validateBeforeWrite();
+    const readFd = openSync(tempPath, getSafeReadOpenFlags());
+    try {
+      validateOpenFile(readFd, tempPath, errorMessage);
+    } finally {
+      closeSync(readFd);
+    }
+    renameSync(tempPath, configPath);
+    renamed = true;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch (error) {
+        closeError = error;
+      }
+    }
+    try {
+      if (!renamed && existsSync(tempPath)) {
+        unlinkSync(tempPath);
+      }
+    } finally {
+      if (closeError) {
+        throw closeError;
+      }
+    }
+  }
+}