@davidvornholt/standards 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -85,6 +85,7 @@
     "src/github-settings-parse.ts",
     "src/github-settings.ts",
     "src/managed-files.ts",
+    "src/managed-path-ownership.ts",
     "src/poller-approval.ts",
     "src/poller-acknowledgements.ts",
     "src/poller-claim.ts",

package/src/cli.ts

@@ -13,7 +13,7 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
-import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
 import process from 'node:process';
@@ -32,8 +32,16 @@ import { loadGithubSettings } from './github-settings';
 import { isNonEmptyString, isRecord } from './github-settings-parse';
 import {
   findManagedFilesContainingBiomeDirectiveToken,
+  inspectManagedPath,
   listManagedFiles,
+  type ManagedEntry,
+  managedEntryDigestInput,
+  writeManagedEntry,
 } from './managed-files';
+import {
+  interposedAncestor,
+  unlockedPathsUnder,
+} from './managed-path-ownership';
 import { runPollerCommand } from './poller-commands';
 import { collectStructureProblems } from './structure-check';
 import type { StructureProfile } from './structure-profile';
@@ -44,6 +52,10 @@ const DEFAULT_UPSTREAM = 'github:davidvornholt/standards';
 // Characters of a sha256 hex digest shown in drift reports; enough to identify.
 const HASH_PREVIEW_LENGTH = 12;
 
+// Unmanaged paths named as examples in a collision refusal, which also reports
+// the full count.
+const COLLISION_SAMPLE = 3;
+
 const GITHUB_PREFIX = 'github:';
 const SKIP_GITHUB_CHECK_ENV = 'STANDARDS_SKIP_GITHUB_CHECK';
 
@@ -112,6 +124,38 @@ const assertSafeRelativePath = (path: string, label: string): void => {
   }
 };
 
+// `C:/Windows` is absolute on Windows and relative to POSIX `isAbsolute`, so a
+// drive-qualified target written with forward slashes would escape a consumer
+// synced on Linux. Managed targets are POSIX-relative on every platform.
+const DRIVE_QUALIFIED = /^[A-Za-z]:/u;
+
+// A managed symlink is mirrored verbatim into every consumer, so its target
+// must resolve inside the consumer repository rather than at the host
+// filesystem around it. Returns the problem instead of throwing, so a command
+// can report every offending link before it writes anything.
+const symlinkTargetProblem = (rel: string, target: string): string | null => {
+  const resolved = posix.normalize(posix.join(posix.dirname(rel), target));
+  if (
+    target.length === 0 ||
+    posix.isAbsolute(target) ||
+    DRIVE_QUALIFIED.test(target) ||
+    target.includes('\\') ||
+    resolved.split('/').includes('..')
+  ) {
+    return `canonical symlink ${rel} must point inside the repository: ${target}`;
+  }
+  return null;
+};
+
+const symlinkTargetProblems = (
+  entries: ReadonlyMap<string, ManagedEntry>,
+): ReadonlyArray<string> =>
+  [...entries]
+    .map(([rel, entry]) =>
+      entry.kind === 'symlink' ? symlinkTargetProblem(rel, entry.target) : null,
+    )
+    .filter((problem): problem is string => problem !== null);
+
 const parseManifest = (raw: unknown): Manifest => {
   if (typeof raw !== 'object' || raw === null) {
     throw new Error('sync-standards.json must be a JSON object');
@@ -249,22 +293,147 @@ type MirrorResult = {
   readonly updated: ReadonlyArray<string>;
   readonly deleted: ReadonlyArray<string>;
   readonly tampered: ReadonlyArray<string>;
+  // Locked paths the prune pass deliberately left on disk, each with the reason
+  // the operator needs in order to finish the job by hand.
+  readonly retained: ReadonlyArray<string>;
+  // Locked paths that sit below a managed symlink once this run has finished.
+  // Nothing is left on disk for the operator to act on: the lock entry is
+  // dropped, and the name now resolves through the link into content this run
+  // must not delete. Reported so the drop is not silent, never as an instruction.
+  readonly stale: ReadonlyArray<string>;
 };
 
 type MirrorOptions = {
-  readonly manifest: Manifest;
-  readonly srcDir: string;
+  readonly upstream: ReadonlyMap<string, ManagedEntry>;
   readonly consumer: string;
   readonly previous: Record<string, string>;
   readonly dryRun: boolean;
 };
 
+// Two things init/sync must settle before their first write: an escaping
+// canonical link target, and a managed destination that is a directory holding
+// paths the lock does not record. The lock is the only record of what this
+// engine put in a consumer, so whether the destination itself is locked decides
+// nothing — a consumer can replace a locked link with a directory of its own
+// skills, and that directory is still consumer work. Both problems are decided
+// from data already in hand, and both are reported together so one run surfaces
+// every offending managed path.
+const mirrorPreconditionProblems = async (
+  consumer: string,
+  upstream: ReadonlyMap<string, ManagedEntry>,
+  previous: Record<string, string>,
+): Promise<ReadonlyArray<string>> => {
+  const locked = new Set(Object.keys(previous));
+  const collisions = await Promise.all(
+    [...upstream.keys()].map(async (rel) => {
+      const current = await inspectManagedPath(join(consumer, rel));
+      if (current?.kind !== 'directory') {
+        return null;
+      }
+      const unlocked = await unlockedPathsUnder(consumer, rel, locked);
+      return unlocked.length === 0
+        ? null
+        : `${rel} is a directory holding ${unlocked.length} path(s) this repository does not manage (${unlocked.slice(0, COLLISION_SAMPLE).join(', ')}); move or delete them, then re-run`;
+    }),
+  );
+  return [
+    ...symlinkTargetProblems(upstream),
+    ...collisions.filter((problem): problem is string => problem !== null),
+  ];
+};
+
+const assertNoProblems = (
+  problems: ReadonlyArray<string>,
+  headline: string,
+): void => {
+  if (problems.length > 0) {
+    throw new Error(
+      [`${headline}:`, ...problems.map((problem) => `  - ${problem}`)].join(
+        '\n',
+      ),
+    );
+  }
+};
+
+type PruneOutcome =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'delete'; readonly rel: string }
+  | { readonly kind: 'retain'; readonly note: string }
+  | { readonly kind: 'stale'; readonly note: string };
+
+// Two things the prune pass must never do: resolve through a symlink it (or an
+// older CLI's lock) put in the parent chain, and recursively delete a
+// destination the consumer turned into a directory. Every answer is decided
+// against the shape the mirror leaves behind, not the shape on disk right now,
+// so `--dry-run` predicts what the matching real run does.
+const pruneOutcome = async (
+  consumer: string,
+  rel: string,
+  planned: ReadonlyMap<string, ManagedEntry>,
+): Promise<PruneOutcome> => {
+  const ancestor = await interposedAncestor(consumer, rel, planned);
+  if (ancestor?.kind === 'symlink') {
+    return {
+      kind: 'stale',
+      note: `${rel} (below the symlink ${ancestor.rel}; nothing was deleted through it)`,
+    };
+  }
+  // Below a managed file the name resolves to nothing once the mirror has run,
+  // whether or not a directory still stands there while a dry run looks.
+  const current =
+    ancestor === null ? await inspectManagedPath(join(consumer, rel)) : null;
+  if (current === null) {
+    return { kind: 'absent' };
+  }
+  if (current.kind === 'directory') {
+    return {
+      kind: 'retain',
+      note: `${rel}: removed upstream but now a directory this repository does not manage; delete it yourself if you no longer want it`,
+    };
+  }
+  return { kind: 'delete', rel };
+};
+
+// Remove the locked paths that vanished upstream. Retained paths are reported
+// and left alone; the lock drops every removable key either way, so the next
+// run is clean.
+const prune = async (
+  consumer: string,
+  removable: ReadonlyArray<string>,
+  planned: ReadonlyMap<string, ManagedEntry>,
+  dryRun: boolean,
+): Promise<{
+  readonly deleted: ReadonlyArray<string>;
+  readonly retained: ReadonlyArray<string>;
+  readonly stale: ReadonlyArray<string>;
+}> => {
+  const outcomes = await Promise.all(
+    removable.map((rel) => pruneOutcome(consumer, rel, planned)),
+  );
+  const deleted = outcomes.flatMap((outcome) =>
+    outcome.kind === 'delete' ? [outcome.rel] : [],
+  );
+  const retained = outcomes.flatMap((outcome) =>
+    outcome.kind === 'retain' ? [outcome.note] : [],
+  );
+  const stale = outcomes.flatMap((outcome) =>
+    outcome.kind === 'stale' ? [outcome.note] : [],
+  );
+  if (!dryRun) {
+    // `pruneOutcome` decides what may be deleted; a directory takes the retain
+    // branch there and never reaches this call.
+    await Promise.all(
+      deleted.map((rel) => rm(join(consumer, rel), { force: true })),
+    );
+  }
+  return { deleted, retained, stale };
+};
+
 // Mirror managed files into the consumer, deleting any previously-locked file
 // that no longer exists upstream (three-way reconcile against the lock). When
 // `dryRun` is set nothing is written or deleted; the returned plan is reported.
 const mirror = async ({
-  manifest,
-  srcDir,
+  upstream,
   consumer,
   previous,
   dryRun,
@@ -272,19 +441,23 @@ const mirror = async ({
   for (const rel of Object.keys(previous)) {
     assertSafeRelativePath(rel, 'sync-standards.lock file');
   }
-  const upstream = await listManagedFiles(srcDir, manifest.paths);
+  assertNoProblems(
+    await mirrorPreconditionProblems(consumer, upstream, previous),
+    'cannot mirror canonical files',
+  );
   const next: Record<string, string> = {};
   const created: Array<string> = [];
   const updated: Array<string> = [];
   const tampered: Array<string> = [];
   await Promise.all(
-    [...upstream].map(async ([rel, abs]) => {
+    [...upstream].map(async ([rel, entry]) => {
       const dest = join(consumer, rel);
-      const buf = await readFile(abs);
-      const hash = sha256(buf);
-      const currentHash = existsSync(dest)
-        ? sha256(await readFile(dest))
-        : null;
+      const hash = sha256(await managedEntryDigestInput(entry));
+      const current = await inspectManagedPath(dest);
+      const currentHash =
+        current === null
+          ? null
+          : sha256(await managedEntryDigestInput(current));
       const prev = previous[rel];
       if (prev !== undefined && currentHash !== null && currentHash !== prev) {
         tampered.push(rel);
@@ -296,70 +469,95 @@ const mirror = async ({
       }
       if (!dryRun) {
         await mkdir(dirname(dest), { recursive: true });
-        await writeFile(dest, buf);
+        // The precondition above proved every path inside this directory is one
+        // the lock already records, so replacing it restores the managed shape
+        // rather than destroying consumer work.
+        if (current?.kind === 'directory') {
+          await rm(dest, { recursive: true, force: true });
+        }
+        await writeManagedEntry(dest, entry);
       }
       next[rel] = hash;
     }),
   );
-  const deleted = Object.keys(previous).filter(
-    (rel) => !(rel in next) && existsSync(join(consumer, rel)),
+  // `existsSync` would miss a broken link, so the prune pass lstats instead.
+  const { deleted, retained, stale } = await prune(
+    consumer,
+    Object.keys(previous).filter((rel) => !(rel in next)),
+    upstream,
+    dryRun,
   );
-  if (!dryRun) {
-    await Promise.all(deleted.map((rel) => rm(join(consumer, rel))));
-  }
-  return { files: next, created, updated, deleted, tampered };
+  return { files: next, created, updated, deleted, tampered, retained, stale };
+};
+
+// What a mirror reports, in the tense the run calls for: a dry run also
+// announces the writes ahead of it, while a real sync stays quiet about them and
+// speaks only of removals, lock entries it drops, and clobbered local edits. One
+// list in both tenses so a dry run cannot describe an outcome differently from
+// the real run it predicts.
+const mirrorLines = (
+  result: MirrorResult,
+  dryRun: boolean,
+): ReadonlyArray<string> => {
+  const tense = (would: string, did: string): string => (dryRun ? would : did);
+  const writes = dryRun
+    ? [
+        ...result.created.map((rel) => `would create ${rel}`),
+        ...result.updated.map((rel) => `would update ${rel}`),
+      ]
+    : [];
+  const tampered =
+    result.tampered.length === 0
+      ? []
+      : [
+          `${tense('would overwrite', 'overwrote')} ${result.tampered.length} locally-modified canonical path(s): ${result.tampered.join(', ')}`,
+        ];
+  return [
+    ...writes,
+    ...result.deleted.map(
+      (rel) => `${tense('would delete', 'deleted')} ${rel} (removed upstream)`,
+    ),
+    ...result.retained.map(
+      (note) => `${tense('would leave in place', 'left in place')} ${note}`,
+    ),
+    ...result.stale.map(
+      (note) =>
+        `${tense('would drop', 'dropped')} the stale lock entry ${note}`,
+    ),
+    ...tampered,
+  ];
 };
 
-// Print what a mirror did (or, for a dry run, would do). Real syncs stay quiet
-// about unchanged files and only announce deletions and clobbered local edits.
 const reportMirror = (result: MirrorResult, dryRun: boolean): void => {
-  if (dryRun) {
-    for (const rel of result.created) {
-      console.log(`  would create ${rel}`);
-    }
-    for (const rel of result.updated) {
-      console.log(`  would update ${rel}`);
-    }
-    for (const rel of result.deleted) {
-      console.log(`  would delete ${rel} (removed upstream)`);
-    }
-    if (result.tampered.length > 0) {
-      console.log(
-        `  would overwrite ${result.tampered.length} locally-modified canonical file(s): ${result.tampered.join(', ')}`,
-      );
-    }
-    return;
-  }
-  for (const rel of result.deleted) {
-    console.log(`  deleted ${rel} (removed upstream)`);
-  }
-  if (result.tampered.length > 0) {
-    console.log(
-      `  overwrote ${result.tampered.length} locally-modified canonical file(s): ${result.tampered.join(', ')}`,
-    );
+  for (const line of mirrorLines(result, dryRun)) {
+    console.log(`  ${line}`);
   }
 };
 
+// A retained or stale key leaves the lock, so the run rewrites `sync-standards.lock`
+// even when it touches nothing on disk; neither may be summed into "no changes".
 const reportDryRunSummary = (
   result: MirrorResult,
   generated: boolean,
 ): void => {
+  const unlocked = result.retained.length + result.stale.length;
   const changes =
     result.created.length +
     result.updated.length +
     result.deleted.length +
+    unlocked +
     Number(generated);
   console.log(
     changes === 0
       ? 'dry run: already in sync; no changes'
-      : `dry run: ${result.created.length} to create, ${result.updated.length} to update, ${result.deleted.length} to delete, ${Number(generated)} to generate`,
+      : `dry run: ${result.created.length} to create, ${result.updated.length} to update, ${result.deleted.length} to delete, ${Number(generated)} to generate, ${unlocked} to drop from the lock without deleting`,
   );
 };
 
 const seedTargets = (
   srcDir: string,
   seedDir: string,
-): Promise<ReadonlyMap<string, string>> => {
+): Promise<ReadonlyMap<string, ManagedEntry>> => {
   const root = join(srcDir, seedDir);
   return listManagedFiles(root, ['.']);
 };
@@ -371,27 +569,39 @@ const runInit = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const upstream = await listManagedFiles(src.dir, manifest.paths);
+  // Seeds are written before the mirror, so both halves of the payload must
+  // clear their preconditions here for `init` to refuse before writing anything.
+  assertNoProblems(
+    [
+      ...symlinkTargetProblems(seeds),
+      ...(await mirrorPreconditionProblems(consumer, upstream, {})),
+    ],
+    'cannot initialize from this source',
+  );
   const prospectiveDependabot = await prepareProspectiveDependabot(
-    manifest,
-    src.dir,
+    upstream,
     consumer,
     seeds.get(DEPENDABOT_LOCAL_FILE) ?? null,
   );
   await Promise.all(
-    [...seeds].map(async ([rel, abs]) => {
+    [...seeds].map(async ([rel, entry]) => {
       const dest = join(consumer, rel);
-      if (existsSync(dest)) {
+      // A seed destination is kept whenever anything at all occupies it.
+      // `existsSync` reports a broken link as absent, so it would call this
+      // destination free and let the seed replace a link the consumer put
+      // there; `lstat` sees the link and keeps it.
+      if ((await inspectManagedPath(dest)) !== null) {
         console.log(`  kept ${rel} (already present)`);
         return;
       }
       await mkdir(dirname(dest), { recursive: true });
-      await cp(abs, dest);
+      await writeManagedEntry(dest, entry);
       console.log(`  seeded ${rel}`);
     }),
   );
   const result = await mirror({
-    manifest,
-    srcDir: src.dir,
+    upstream,
     consumer,
     previous: {},
     dryRun: false,
@@ -404,7 +614,7 @@ const runInit = async (
     files: result.files,
   });
   console.log(
-    `init complete: ${Object.keys(result.files).length} managed file(s) at ${src.sha}`,
+    `init complete: ${Object.keys(result.files).length} managed path(s) at ${src.sha}`,
   );
 };
 
@@ -416,16 +626,15 @@ const runSync = async (
 ): Promise<void> => {
   const seeds = await seedTargets(src.dir, manifest.seedDir);
   assertDisjoint(manifest.paths, [...seeds.keys()]);
+  const upstream = await listManagedFiles(src.dir, manifest.paths);
   const prospectiveDependabot = await prepareProspectiveDependabot(
-    manifest,
-    src.dir,
+    upstream,
     consumer,
     null,
   );
   const lock = await readLock(consumer);
   const result = await mirror({
-    manifest,
-    srcDir: src.dir,
+    upstream,
     consumer,
     previous: lock?.files ?? {},
     dryRun,
@@ -446,7 +655,7 @@ const runSync = async (
     files: result.files,
   });
   console.log(
-    `sync complete: ${Object.keys(result.files).length} managed file(s) at ${src.sha}`,
+    `sync complete: ${Object.keys(result.files).length} managed path(s) at ${src.sha}`,
   );
 };
 
@@ -468,10 +677,11 @@ const runCheck = async (consumer: string): Promise<boolean> => {
   const results = await Promise.all(
     Object.entries(lock.files).map(async ([rel, hash]) => {
       const dest = join(consumer, rel);
-      if (!existsSync(dest)) {
+      const entry = await inspectManagedPath(dest);
+      if (entry === null) {
         return `  missing:  ${rel}`;
       }
-      const current = sha256(await readFile(dest));
+      const current = sha256(await managedEntryDigestInput(entry));
       if (current !== hash) {
         return `  modified: ${rel} (expected ${hash.slice(0, HASH_PREVIEW_LENGTH)}, found ${current.slice(0, HASH_PREVIEW_LENGTH)})`;
       }
@@ -483,7 +693,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
     await findManagedFilesContainingBiomeDirectiveToken(lockedFiles);
   if (problems.length > 0) {
     console.error(
-      `standards: ${problems.length} canonical file(s) drifted from the last synced state:`,
+      `standards: ${problems.length} canonical path(s) drifted from the last synced state:`,
     );
     console.error(problems.join('\n'));
     console.error(
@@ -501,7 +711,7 @@ const runCheck = async (consumer: string): Promise<boolean> => {
   }
   if (problems.length === 0) {
     console.log(
-      `standards: ${Object.keys(lock.files).length} canonical file(s) match the last synced state`,
+      `standards: ${Object.keys(lock.files).length} canonical path(s) match the last synced state`,
     );
   }
   return problems.length === 0 && directiveFiles.length === 0;
@@ -591,14 +801,12 @@ type ProspectiveDependabot = {
 // file. For init, an existing overlay wins; otherwise the overlay seed is what
 // the command is about to install.
 const prepareProspectiveDependabot = async (
-  manifest: Manifest,
-  srcDir: string,
+  incoming: ReadonlyMap<string, ManagedEntry>,
   consumer: string,
-  localSeed: string | null,
+  localSeed: ManagedEntry | null,
 ): Promise<ProspectiveDependabot> => {
-  const incoming = await listManagedFiles(srcDir, manifest.paths);
-  const basePath = incoming.get(DEPENDABOT_BASE_FILE);
-  if (basePath === undefined) {
+  const base = incoming.get(DEPENDABOT_BASE_FILE);
+  if (base === undefined || base.kind !== 'file') {
     throw new Error(
       `source content must manage ${DEPENDABOT_BASE_FILE}; @davidvornholt/standards 0.10.1 requires a 0.10.1-compatible content ref`,
     );
@@ -608,10 +816,12 @@ const prepareProspectiveDependabot = async (
   );
   const local =
     existingLocal ??
-    (localSeed === null ? null : await readFile(localSeed, 'utf8'));
+    (localSeed === null || localSeed.kind !== 'file'
+      ? null
+      : await readFile(localSeed.absolutePath, 'utf8'));
   const current = await readTextIfPresent(join(consumer, DEPENDABOT_FILE));
   const sources = {
-    base: await readFile(basePath, 'utf8'),
+    base: await readFile(base.absolutePath, 'utf8'),
     local,
     current,
   };

package/src/managed-files.ts

@@ -1,4 +1,12 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
+import {
+  lstat,
+  readdir,
+  readFile,
+  readlink,
+  rm,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 
 // Never mirrored, even under a managed directory path: build output, VCS
@@ -16,34 +24,76 @@ const directiveToken = Buffer.from(['biome', 'ignore'].join('-'));
 
 const toPosix = (path: string): string => path.split(sep).join('/');
 
+// A managed path is a file or a symlink. A symlink's identity is its target,
+// never the content it resolves to: mirroring must reproduce the link itself,
+// and following it would copy the whole target tree into every consumer.
+export type ManagedEntry =
+  | { readonly kind: 'file'; readonly absolutePath: string }
+  | {
+      readonly kind: 'symlink';
+      readonly absolutePath: string;
+      readonly target: string;
+    }
+  // Only ever observed when inspecting a destination a consumer replaced; the
+  // upstream walk descends into directories instead of recording them.
+  | { readonly kind: 'directory'; readonly absolutePath: string };
+
+// Built rather than written as an escape so this source file stays plain ASCII
+// and greppable. File digests remain plain content hashes, so existing consumer
+// locks keep validating; the markers only need to be unreachable content for a
+// canonical file, and no text file begins with a NUL byte.
+const nul = String.fromCharCode(0);
+const SYMLINK_DIGEST_PREFIX = `${nul}standards-symlink${nul}`;
+const DIRECTORY_DIGEST = `${nul}standards-directory${nul}`;
+
+export const inspectManagedPath = async (
+  path: string,
+): Promise<ManagedEntry | null> => {
+  const info = await lstat(path).catch(() => null);
+  if (info === null) {
+    return null;
+  }
+  if (info.isSymbolicLink()) {
+    return {
+      kind: 'symlink',
+      absolutePath: path,
+      target: toPosix(await readlink(path)),
+    };
+  }
+  if (info.isDirectory()) {
+    return { kind: 'directory', absolutePath: path };
+  }
+  return { kind: 'file', absolutePath: path };
+};
+
 const walkManagedFiles = async (
   path: string,
   repositoryRoot: string,
-  files: Map<string, string>,
+  files: Map<string, ManagedEntry>,
 ): Promise<void> => {
-  const info = await stat(path).catch(() => null);
-  if (info === null) {
+  const entry = await inspectManagedPath(path);
+  if (entry === null) {
     return;
   }
-  if (info.isDirectory()) {
+  if (entry.kind === 'directory') {
     const entries = await readdir(path);
     await Promise.all(
       entries
-        .filter((entry) => !IGNORED_DIRECTORIES.has(entry))
-        .map((entry) =>
-          walkManagedFiles(join(path, entry), repositoryRoot, files),
+        .filter((name) => !IGNORED_DIRECTORIES.has(name))
+        .map((name) =>
+          walkManagedFiles(join(path, name), repositoryRoot, files),
         ),
     );
     return;
   }
-  files.set(toPosix(relative(repositoryRoot, path)), path);
+  files.set(toPosix(relative(repositoryRoot, path)), entry);
 };
 
 export const listManagedFiles = async (
   repositoryRoot: string,
   paths: ReadonlyArray<string>,
-): Promise<ReadonlyMap<string, string>> => {
-  const files = new Map<string, string>();
+): Promise<ReadonlyMap<string, ManagedEntry>> => {
+  const files = new Map<string, ManagedEntry>();
   await Promise.all(
     paths.map((path) =>
       walkManagedFiles(join(repositoryRoot, path), repositoryRoot, files),
@@ -52,12 +102,64 @@ export const listManagedFiles = async (
   return files;
 };
 
+// What the lock hashes for an entry: file content, or the marker-prefixed link
+// target. Retargeting a link therefore reads as drift the same way an edited
+// file does.
+export const managedEntryDigestInput = (
+  entry: ManagedEntry,
+): Promise<Buffer> => {
+  if (entry.kind === 'symlink') {
+    return Promise.resolve(
+      Buffer.from(`${SYMLINK_DIGEST_PREFIX}${entry.target}`),
+    );
+  }
+  if (entry.kind === 'directory') {
+    return Promise.resolve(Buffer.from(DIRECTORY_DIGEST));
+  }
+  return readFile(entry.absolutePath);
+};
+
+// Plant one managed entry, replacing a file or a link that occupies the
+// destination. Never recursive: a directory at the destination is unbounded
+// consumer content, so removing it is the caller's decision to make explicitly
+// once it has proven the path was engine-owned.
+export const writeManagedEntry = async (
+  dest: string,
+  entry: ManagedEntry,
+): Promise<void> => {
+  if (entry.kind === 'directory') {
+    throw new Error(`cannot mirror a directory as a managed path: ${dest}`);
+  }
+  const existing = await inspectManagedPath(dest);
+  if (existing?.kind === 'directory') {
+    throw new Error(
+      `refusing to replace the directory ${dest} with a managed ${entry.kind}; move or delete it first`,
+    );
+  }
+  // `symlink` refuses an existing path, and writing a file through a stale link
+  // would clobber that link's target instead of replacing the managed path.
+  if (
+    existing !== null &&
+    (entry.kind === 'symlink' || existing.kind === 'symlink')
+  ) {
+    await rm(dest, { force: true });
+  }
+  if (entry.kind === 'symlink') {
+    await symlink(entry.target, dest);
+    return;
+  }
+  await writeFile(dest, await readFile(entry.absolutePath));
+};
+
 export const findManagedFilesContainingBiomeDirectiveToken = async (
-  files: ReadonlyMap<string, string>,
+  files: ReadonlyMap<string, ManagedEntry>,
 ): Promise<ReadonlyArray<string>> => {
   const matches = await Promise.all(
-    [...files].map(async ([path, absolutePath]) =>
-      (await readFile(absolutePath)).includes(directiveToken) ? path : null,
+    [...files].map(async ([path, entry]) =>
+      entry.kind === 'file' &&
+      (await readFile(entry.absolutePath)).includes(directiveToken)
+        ? path
+        : null,
     ),
   );
   return matches.filter((path): path is string => path !== null).sort();

package/src/managed-path-ownership.ts

@@ -0,0 +1,85 @@
+// Ownership questions about a destination path, asked before init/sync writes
+// to it or deletes it. Both answers come from the lock: it is the only record of
+// what this engine put in a consumer, so anything absent from it is consumer
+// work that a mirror must never destroy.
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspectManagedPath, type ManagedEntry } from './managed-files';
+
+const collectPaths = async (
+  root: string,
+  rel: string,
+  found: Array<string>,
+): Promise<void> => {
+  const entry = await inspectManagedPath(join(root, rel));
+  if (entry === null) {
+    return;
+  }
+  if (entry.kind === 'directory') {
+    const names = await readdir(join(root, rel));
+    await Promise.all(
+      names.map((name) => collectPaths(root, `${rel}/${name}`, found)),
+    );
+    return;
+  }
+  found.push(rel);
+};
+
+// Paths inside `rel` that the lock never recorded, so a caller can tell an
+// engine-owned tree from consumer work. An older CLI that followed a canonical
+// link materialized its whole target tree and locked every path in it; a
+// consumer's own file under the same directory is absent from the lock. Nothing
+// here follows a symlink: every entry is judged where it sits.
+export const unlockedPathsUnder = async (
+  root: string,
+  rel: string,
+  locked: ReadonlySet<string>,
+): Promise<ReadonlyArray<string>> => {
+  const found: Array<string> = [];
+  await collectPaths(root, rel, found);
+  return found.filter((path) => !locked.has(path)).sort();
+};
+
+// An ancestor that is not a directory, so nothing can sit below it under the
+// name the lock recorded. The kind is part of the answer: below a symlink the
+// name still resolves, to somebody else's content, while below a file it
+// resolves to nothing at all.
+export type InterposedAncestor = {
+  readonly rel: string;
+  readonly kind: 'file' | 'symlink';
+};
+
+// The shallowest ancestor of `rel` inside `root` that is not a directory, or
+// null when the whole parent chain is directories.
+//
+// `planned` is the payload this run mirrors, and it wins over the disk: every
+// path in it has the kind upstream gives it once the mirror has finished, and
+// the caller runs after the mirror. A dry run, which writes nothing, therefore
+// reaches the same answer the matching real run does.
+//
+// A path whose parent chain crosses a link does not name what the caller thinks
+// it names: reading or removing it reaches into the link's target tree, which
+// is somebody else's content.
+export const interposedAncestor = async (
+  root: string,
+  rel: string,
+  planned: ReadonlyMap<string, ManagedEntry>,
+): Promise<InterposedAncestor | null> => {
+  const segments = rel.split('/').slice(0, -1);
+  const prefixes = segments.map((_, depth) =>
+    segments.slice(0, depth + 1).join('/'),
+  );
+  const entries = await Promise.all(
+    prefixes.map(
+      (prefix) => planned.get(prefix) ?? inspectManagedPath(join(root, prefix)),
+    ),
+  );
+  for (const [index, prefix] of prefixes.entries()) {
+    const entry = entries[index] ?? null;
+    if (entry !== null && entry.kind !== 'directory') {
+      return { rel: prefix, kind: entry.kind };
+    }
+  }
+  return null;
+};