@davidvornholt/standards 0.18.0 → 0.20.0

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,
   };
@@ -1006,7 +1216,7 @@ const runCheckCommand = async (consumer: string): Promise<boolean> => {
 };
 
 // The canonical workflow sets this only for its unprivileged quality job,
-// where a separate isolated job runs the same live check with the settings-read
+// where a separate isolated job runs the same live check with its own workflow
 // token. Absent that exact workflow seam, local and explicit checks remain
 // fail-closed.
 const runGithubCheckGate = (consumer: string): Promise<boolean> => {

package/src/creds-add-cloudflare-commit.ts

@@ -1,9 +1,6 @@
 import { deleteAccountToken } from './creds-cloudflare';
-import {
-  type SopsValueChange,
-  type SopsWriteResult,
-  verifySopsStoredValue,
-} from './creds-sops';
+import type { SopsValueChange, SopsWriteResult } from './creds-sops';
+import { verifySopsStoredValue } from './creds-sops-value';
 
 export const commitCreatedCloudflareToken = async (input: {
   readonly consumer: string;