@davidvornholt/standards 0.20.0 → 0.21.0

package/src/dev-env-reconciliation.ts

@@ -0,0 +1,170 @@
+import {
+  closeSync,
+  constants,
+  type Dirent,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+} from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { DevEnvRemoval, DevEnvWrite } from './dev-env-destination';
+import { hasDevEnvGeneratedHeader } from './dev-env-dotenv';
+
+const WORKSPACE_GROUPS = ['apps', 'packages'] as const;
+
+export type DevEnvRemovalPlan = {
+  readonly removals: ReadonlyArray<DevEnvRemoval>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const message = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+export const devEnvStatOrNull = async (path: string) => {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+};
+
+type WorkspaceDiscovery = {
+  readonly workspaces: ReadonlyArray<Dirent>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const discoverWorkspaces = (
+  consumer: string,
+  group: (typeof WORKSPACE_GROUPS)[number],
+): WorkspaceDiscovery => {
+  const groupPath = join(consumer, group);
+  try {
+    const stats = lstatSync(groupPath);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      return { workspaces: [], problems: [] };
+    }
+    return {
+      workspaces: readdirSync(groupPath, { withFileTypes: true })
+        .filter((workspace) => workspace.isDirectory())
+        .sort((left, right) => left.name.localeCompare(right.name)),
+      problems: [],
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { workspaces: [], problems: [] };
+    }
+    return {
+      workspaces: [],
+      problems: [`could not inspect ${group} workspaces: ${message(error)}`],
+    };
+  }
+};
+
+type RemovalInspection = {
+  readonly removal: DevEnvRemoval | null;
+  readonly problem: string | null;
+};
+
+const inspectRemoval = (
+  consumer: string,
+  envRel: string,
+): RemovalInspection => {
+  const envPath = join(consumer, envRel);
+  let file: number | null = null;
+  try {
+    file = openSync(
+      envPath,
+      constants.O_RDONLY + constants.O_NOFOLLOW + constants.O_NONBLOCK,
+    );
+    const stats = fstatSync(file);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+      return { removal: null, problem: null };
+    }
+    const owned = hasDevEnvGeneratedHeader(readFileSync(file, 'utf8'));
+    return {
+      removal: owned
+        ? {
+            rel: envRel,
+            identity: { device: stats.dev, inode: stats.ino },
+          }
+        : null,
+      problem: null,
+    };
+  } catch (error) {
+    if (
+      ['ELOOP', 'ENOENT'].includes((error as NodeJS.ErrnoException).code ?? '')
+    ) {
+      return { removal: null, problem: null };
+    }
+    return {
+      removal: null,
+      problem: `could not inspect ${envRel}: ${message(error)}`,
+    };
+  } finally {
+    if (file !== null) {
+      closeSync(file);
+    }
+  }
+};
+
+export const matchesDevEnvRemoval = async (
+  path: string,
+  removal: DevEnvRemoval,
+): Promise<boolean> => {
+  try {
+    const file = await open(
+      path,
+      constants.O_RDONLY + constants.O_NOFOLLOW + constants.O_NONBLOCK,
+    );
+    try {
+      const stats = await file.stat();
+      return (
+        stats.isFile() &&
+        stats.dev === removal.identity.device &&
+        stats.ino === removal.identity.inode &&
+        hasDevEnvGeneratedHeader(await file.readFile('utf8'))
+      );
+    } finally {
+      await file.close();
+    }
+  } catch {
+    return false;
+  }
+};
+
+export const planDevEnvRemovals = (
+  consumer: string,
+  writes: ReadonlyArray<DevEnvWrite>,
+): DevEnvRemovalPlan => {
+  const plannedWrites = new Set(writes.map((write) => write.rel));
+  const removals: Array<DevEnvRemoval> = [];
+  const problems: Array<string> = [];
+  for (const group of WORKSPACE_GROUPS) {
+    const discovery = discoverWorkspaces(consumer, group);
+    problems.push(...discovery.problems);
+    for (const workspace of discovery.workspaces) {
+      const workspaceRel = `${group}/${workspace.name}`;
+      const envRel = `${workspaceRel}/.env.local`;
+      if (
+        !plannedWrites.has(envRel) &&
+        existsSync(join(consumer, workspaceRel, 'package.json'))
+      ) {
+        const inspected = inspectRemoval(consumer, envRel);
+        if (inspected.removal !== null) {
+          removals.push(inspected.removal);
+        }
+        if (inspected.problem !== null) {
+          problems.push(inspected.problem);
+        }
+      }
+    }
+  }
+  return { removals, problems };
+};

package/src/dev-env-secrets.ts

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runSops } from './sops-exec';
+
+export const DEV_SECRETS_FILE = 'secrets/dev.yaml';
+
+const SOPS_ARGS = ['--decrypt', '--output-type', 'json', DEV_SECRETS_FILE];
+
+export type DevSecretsResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly problem: string };
+
+// sops emits JSON here so the CLI never parses the encrypted YAML itself.
+export const readDevSecrets = (consumer: string): DevSecretsResult => {
+  if (!existsSync(join(consumer, DEV_SECRETS_FILE))) {
+    return {
+      ok: false,
+      problem: `${DEV_SECRETS_FILE} not found; create it with \`just secrets edit dev\``,
+    };
+  }
+  const result = runSops(SOPS_ARGS, consumer);
+  if (result.status !== 0) {
+    const detail = result.errorMessage ?? result.stderr.trim();
+    return {
+      ok: false,
+      problem: detail
+        ? `could not decrypt ${DEV_SECRETS_FILE}: ${detail}`
+        : `could not decrypt ${DEV_SECRETS_FILE}`,
+    };
+  }
+  try {
+    return { ok: true, value: JSON.parse(result.stdout) as unknown };
+  } catch (error) {
+    return {
+      ok: false,
+      problem: `could not parse decrypted ${DEV_SECRETS_FILE} as JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+};

package/src/dev-env-transaction-recovery.ts

@@ -1,8 +1,9 @@
-import { rename, rm } from 'node:fs/promises';
+import { link, rm } from 'node:fs/promises';
 import {
   type DevEnvDestination,
   devEnvParentProblem,
 } from './dev-env-destination';
+import { devEnvStatOrNull } from './dev-env-reconciliation';
 
 const message = (error: unknown): string =>
   error instanceof Error ? error.message : String(error);
@@ -11,20 +12,81 @@ const requireParent = async (
   destination: DevEnvDestination,
 ): Promise<string | null> => devEnvParentProblem(destination);
 
+const isWrite = (destination: DevEnvDestination): boolean =>
+  'content' in destination.mutation;
+
+const rollbackBlockedProblem = (destination: DevEnvDestination): string =>
+  `${destination.mutation.rel}: rollback blocked because destination changed`;
+
+const restoreBackupNoReplace = async (
+  destination: DevEnvDestination,
+): Promise<boolean> => {
+  try {
+    await link(destination.backup, destination.dest);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      destination.rollbackBlocked = true;
+      return false;
+    }
+    throw error;
+  }
+  try {
+    await rm(destination.backup);
+  } catch (error) {
+    destination.rollbackBlocked = true;
+    throw error;
+  }
+  destination.backupCreated = false;
+  return true;
+};
+
+export const restoreClaimedDevEnvRemoval = async (
+  destination: DevEnvDestination,
+  beforeRestore: () => void | Promise<void> = () => undefined,
+): Promise<void> => {
+  const parentProblem = await devEnvParentProblem(destination);
+  if (parentProblem !== null) {
+    destination.rollbackBlocked = true;
+    return;
+  }
+  await beforeRestore();
+  await restoreBackupNoReplace(destination);
+};
+
+const removeCommittedDestination = async (
+  destination: DevEnvDestination,
+): Promise<string | null> => {
+  const parentProblem = await requireParent(destination);
+  if (parentProblem !== null) {
+    return parentProblem;
+  }
+  const current = await devEnvStatOrNull(destination.dest);
+  if (!isWrite(destination) && current !== null) {
+    destination.rollbackBlocked = true;
+    return rollbackBlockedProblem(destination);
+  }
+  if (isWrite(destination)) {
+    await rm(destination.dest, { force: true });
+  }
+  destination.committed = false;
+  return null;
+};
+
 const rollbackOne = async (
   destination: DevEnvDestination,
 ): Promise<ReadonlyArray<string>> => {
   const problems: Array<string> = [];
+  if (destination.rollbackBlocked) {
+    return [rollbackBlockedProblem(destination)];
+  }
   if (destination.committed) {
-    const parentProblem = await requireParent(destination);
-    if (parentProblem !== null) {
-      return [parentProblem];
-    }
     try {
-      await rm(destination.dest, { force: true });
-      destination.committed = false;
+      const problem = await removeCommittedDestination(destination);
+      if (problem !== null) {
+        return [problem];
+      }
     } catch (error) {
-      problems.push(`${destination.write.rel}: ${message(error)}`);
+      problems.push(`${destination.mutation.rel}: ${message(error)}`);
     }
   }
   if (destination.backupCreated && problems.length === 0) {
@@ -33,10 +95,11 @@ const rollbackOne = async (
       return [parentProblem];
     }
     try {
-      await rename(destination.backup, destination.dest);
-      destination.backupCreated = false;
+      if (!(await restoreBackupNoReplace(destination))) {
+        return [rollbackBlockedProblem(destination)];
+      }
     } catch (error) {
-      problems.push(`${destination.write.rel}: ${message(error)}`);
+      problems.push(`${destination.mutation.rel}: ${message(error)}`);
     }
   }
   return problems;

package/src/dev-env-transaction.ts

@@ -1,13 +1,19 @@
 import { link, open, rename } from 'node:fs/promises';
 import {
   type DevEnvDestination,
+  type DevEnvMutation,
+  type DevEnvRemoval,
   type DevEnvWrite,
   devEnvParentProblem,
-  devEnvStatOrNull,
   preflightDevEnvDestinations,
 } from './dev-env-destination';
+import {
+  devEnvStatOrNull,
+  matchesDevEnvRemoval,
+} from './dev-env-reconciliation';
 import {
   cleanupDevEnvArtifacts,
+  restoreClaimedDevEnvRemoval,
   rollbackDevEnvFiles,
 } from './dev-env-transaction-recovery';
 
@@ -16,6 +22,8 @@ const OWNER_ONLY_FILE_MODE = 0o600;
 export type DevEnvTransactionHooks = {
   readonly beforeStage?: (index: number) => void | Promise<void>;
   readonly beforeCommit?: (index: number) => void | Promise<void>;
+  readonly afterDestinationCheck?: (index: number) => void | Promise<void>;
+  readonly beforeRemovalRestore?: (index: number) => void | Promise<void>;
   readonly beforeCleanup?: () => void | Promise<void>;
 };
 
@@ -30,12 +38,18 @@ const requireParent = async (destination: DevEnvDestination): Promise<void> => {
   }
 };
 
+const isWrite = (mutation: DevEnvMutation): mutation is DevEnvWrite =>
+  'content' in mutation;
+
 const stage = async (destination: DevEnvDestination): Promise<void> => {
+  if (!isWrite(destination.mutation)) {
+    return;
+  }
   await requireParent(destination);
   const file = await open(destination.temp, 'wx', OWNER_ONLY_FILE_MODE);
   try {
     await file.chmod(OWNER_ONLY_FILE_MODE);
-    await file.writeFile(destination.write.content, 'utf8');
+    await file.writeFile(destination.mutation.content, 'utf8');
     await file.sync();
   } finally {
     await file.close();
@@ -60,20 +74,52 @@ const stageAll = async (
   destinations: ReadonlyArray<DevEnvDestination>,
   hooks: DevEnvTransactionHooks,
 ): Promise<void> => {
-  await destinations.reduce<Promise<void>>(
-    async (previous, destination, index) => {
-      await previous;
-      await hooks.beforeStage?.(index);
-      await stage(destination);
-    },
-    Promise.resolve(),
+  const writes = destinations.filter((destination) =>
+    isWrite(destination.mutation),
   );
+  await writes.reduce<Promise<void>>(async (previous, destination, index) => {
+    await previous;
+    await hooks.beforeStage?.(index);
+    await stage(destination);
+  }, Promise.resolve());
 };
 
-const commitOne = async (destination: DevEnvDestination): Promise<void> => {
+const commitRemoval = async (
+  destination: DevEnvDestination,
+  removal: DevEnvRemoval,
+  index: number,
+  hooks: DevEnvTransactionHooks,
+): Promise<void> => {
+  const beforeRestore = () => hooks.beforeRemovalRestore?.(index);
+  await requireParent(destination);
+  await rename(destination.dest, destination.backup);
+  destination.backupCreated = true;
+  if (!(await matchesDevEnvRemoval(destination.backup, removal))) {
+    await restoreClaimedDevEnvRemoval(destination, beforeRestore);
+    throw new Error(`${removal.rel} changed after preflight`);
+  }
+  const parentProblem = await devEnvParentProblem(destination);
+  const replacement = await devEnvStatOrNull(destination.dest);
+  if (parentProblem !== null || replacement !== null) {
+    await restoreClaimedDevEnvRemoval(destination, beforeRestore);
+    throw new Error(`${removal.rel} changed after preflight`);
+  }
+  destination.committed = true;
+};
+
+const commitOne = async (
+  destination: DevEnvDestination,
+  index: number,
+  hooks: DevEnvTransactionHooks,
+): Promise<void> => {
   await requireParent(destination);
   if (!(await unchanged(destination))) {
-    throw new Error(`${destination.write.rel} changed after preflight`);
+    throw new Error(`${destination.mutation.rel} changed after preflight`);
+  }
+  await hooks.afterDestinationCheck?.(index);
+  if (!isWrite(destination.mutation)) {
+    await commitRemoval(destination, destination.mutation, index, hooks);
+    return;
   }
   if (destination.previous !== null) {
     await requireParent(destination);
@@ -93,7 +139,7 @@ const commitAll = async (
     async (previous, destination, index) => {
       await previous;
       await hooks.beforeCommit?.(index);
-      await commitOne(destination);
+      await commitOne(destination, index, hooks);
     },
     Promise.resolve(),
   );
@@ -121,12 +167,12 @@ const recoverFailure = async (
   };
 };
 
-export const writeDevEnvFiles = async (
+export const applyDevEnvChanges = async (
   consumer: string,
-  writes: ReadonlyArray<DevEnvWrite>,
+  mutations: ReadonlyArray<DevEnvMutation>,
   hooks: DevEnvTransactionHooks = {},
 ): Promise<DevEnvTransactionResult> => {
-  const checked = await preflightDevEnvDestinations(consumer, writes);
+  const checked = await preflightDevEnvDestinations(consumer, mutations);
   if (!checked.ok) {
     return checked;
   }