@davidvornholt/standards 0.20.0 → 0.21.0

package/src/creds-revoke.ts

@@ -0,0 +1,162 @@
+// One-shot retirement of a Cloudflare token the broker does not manage, named
+// explicitly by ID. Replacing a hand-made credential means minting a brokered
+// one and deleting the original; without this the second half could only be
+// done in the dashboard. The power granted is deliberately momentary: nothing
+// is recorded, nothing becomes automatic, and a human names the target every
+// time. Tokens reconciliation owns are refused — those are retired by deleting
+// their SOPS key and running `standards creds apply`, which keeps the secret
+// and the provider in step.
+
+import { deleteAccountToken } from './creds-cloudflare';
+import { isCloudflareId } from './creds-cloudflare-id';
+import { selectAccount } from './creds-dest';
+import { identifyCloudflareBootstrapAuthority } from './creds-login-cloudflare';
+import {
+  BROKER_IDENTITY_NAME,
+  type BrokeredTokenRef,
+  parseAnyTokenName,
+} from './creds-naming';
+import { readBrokerStore, resolveBrokerPath } from './creds-store';
+import { resolveGithubRepo } from './github-api';
+
+const fail = (message: string): false => {
+  console.error(`standards creds: ${message}`);
+  return false;
+};
+
+// GitHub owner and repository names are case-insensitive, so a checkout cloned
+// as `DavidVornholt/Example` owns the token minted as `davidvornholt/example`.
+// An exact comparison would call that token foreign and let --force delete a
+// live credential this very checkout reconciles. Owner and name are compared
+// together: `otherowner/example` shares this repository's name and nothing
+// else.
+const sameRepo = (left: string, right: string): boolean =>
+  left.toLowerCase() === right.toLowerCase();
+
+// A brokered name carries the repository that owns it, and the reconciled
+// remedy — delete the SOPS key, run `apply` — only works in that repository.
+// Naming a bare `<target>:<key>` to an operator standing somewhere else would
+// have them destroy their own live credential of the same name, so the owning
+// repository is always named and the remedy is placed where it runs.
+const brokeredRefusal = ({
+  tokenId,
+  name,
+  brokered,
+  currentRepo,
+  force,
+}: {
+  readonly tokenId: string;
+  readonly name: string;
+  readonly brokered: BrokeredTokenRef;
+  readonly currentRepo: string | null;
+  readonly force: boolean;
+}): string | null => {
+  // Without a repository here, the one thing --force claims to override — that
+  // this checkout is not the owner — is the thing that could not be checked,
+  // so the override is refused rather than granted on an unevaluated guard.
+  if (currentRepo === null) {
+    return `token ${tokenId} is brokered as ${name}, which belongs to ${brokered.repo}, and this checkout cannot resolve the GitHub repository from its origin remote, so whether this checkout owns the token could not be determined; --force widens only that ownership check, so here it has nothing to widen. Re-run from a checkout whose origin remote names a GitHub repository, or point --dir at one. If ${brokered.repo} still exists, the remedy runs there: delete ${brokered.target}:${brokered.key} from its SOPS target and run \`standards creds apply\` in that checkout`;
+  }
+  if (brokered.repo === currentRepo) {
+    return `token ${tokenId} is brokered as ${name} for this repository (${brokered.repo}); delete ${brokered.target}:${brokered.key} from this repository's SOPS target and run \`standards creds apply\`, which revokes it and keeps the secret in step`;
+  }
+  // Revoke compares repository names case-insensitively, but reconciliation
+  // matches the token name exactly, so a checkout whose origin differs only in
+  // capitalisation renews nothing and revokes nothing. Sending the operator to
+  // the reconciled remedy would prescribe a no-op.
+  if (sameRepo(brokered.repo, currentRepo)) {
+    return `token ${tokenId} is brokered as ${name}, and this checkout's origin names ${currentRepo}, which differs from ${brokered.repo} only in capitalisation; reconciliation matches the token name exactly, so from here it will neither renew nor revoke this token. Re-point the origin remote at ${brokered.repo} to bring the token back under reconciliation, or retire it in the Cloudflare dashboard`;
+  }
+  if (force) {
+    return null;
+  }
+  return `token ${tokenId} is brokered as ${name}, which belongs to ${brokered.repo}, and this checkout is ${currentRepo}; the remedy runs there: delete ${brokered.target}:${brokered.key} from ${brokered.repo}'s SOPS target and run \`standards creds apply\` in that checkout. Pass --force only if ${brokered.repo} was renamed, transferred, or deleted, so no checkout resolves to that name and no apply will ever revoke this token`;
+};
+
+export const runCredsRevoke = async (options: {
+  readonly account: string | undefined;
+  readonly tokenId: string | undefined;
+  readonly dir: string;
+  readonly force: boolean;
+}): Promise<boolean> => {
+  const { tokenId } = options;
+  if (tokenId === undefined) {
+    return fail(
+      'revoke requires --token-id <id>; `standards creds plan` prints the ID inside every revoke command it offers, and the Cloudflare dashboard has the ID of anything that listing leaves out',
+    );
+  }
+  if (!isCloudflareId(tokenId)) {
+    return fail(
+      `not a token ID: ${tokenId}; --token-id takes the 32-character hexadecimal token ID`,
+    );
+  }
+  const store = await readBrokerStore(resolveBrokerPath());
+  const account = selectAccount(store, options.account);
+  if (account === null) {
+    return false;
+  }
+  const identified = await identifyCloudflareBootstrapAuthority(
+    account.accountId,
+    account.token,
+  );
+  if (!identified.ok) {
+    return fail(`account ${account.accountId}: ${identified.problem}`);
+  }
+  // The bootstrap token is matched by its verified ID rather than its name,
+  // because deleting it would strip the broker of every power it has and no
+  // rename should be able to disguise it.
+  if (identified.value.id === tokenId) {
+    return fail(
+      `token ${tokenId} is this account's broker bootstrap credential; revoking it would leave the broker unable to mint or reconcile anything`,
+    );
+  }
+  const target = identified.value.tokens.find((entry) => entry.id === tokenId);
+  if (target === undefined) {
+    return fail(
+      `no token ${tokenId} in account ${account.accountId}; revoke names a token in the account the bootstrap credential belongs to`,
+    );
+  }
+  // The broker store is machine-global and `creds login` is a per-machine
+  // bootstrap, so one account can hold several tokens under the reserved name
+  // — one per machine. Only this machine's is identified by ID above; the rest
+  // are refused by name, because deleting one locks another machine out of the
+  // account and the broker cannot re-mint its own root credential.
+  if (target.name === BROKER_IDENTITY_NAME) {
+    return fail(
+      `token ${tokenId} is named ${BROKER_IDENTITY_NAME}, the reserved name for a machine's broker bootstrap credential; this machine's own bootstrap is a different token, so this one belongs to another machine or is a superseded one — retire it in the Cloudflare dashboard, where you can confirm which machine it belongs to`,
+    );
+  }
+  const brokered = parseAnyTokenName(target.name);
+  if (brokered !== null) {
+    const refusal = brokeredRefusal({
+      tokenId,
+      name: target.name,
+      brokered,
+      currentRepo: resolveGithubRepo(options.dir),
+      force: options.force,
+    });
+    if (refusal !== null) {
+      return fail(refusal);
+    }
+  }
+  const deleted = await deleteAccountToken(
+    account.accountId,
+    account.token,
+    tokenId,
+  );
+  if (!deleted.ok) {
+    return fail(`${target.name}: ${deleted.problem}`);
+  }
+  console.log(
+    `standards creds: revoked ${target.name} (${account.accountId}/${tokenId})`,
+  );
+  if (brokered !== null) {
+    console.log(
+      `  it was brokered to ${brokered.repo}; --force took it because this checkout is not that repository`,
+    );
+  }
+  console.log(
+    '  any stored copy of its value is now dead; replace it with `standards creds add cloudflare` if something still needs it',
+  );
+  return true;
+};

package/src/creds-store-lock-holder.ts

@@ -10,6 +10,13 @@ const OWNER_ONLY_FILE_MODE = 0o600;
 const HOLDER_PREFIX = 'holder-';
 const HOLDER_SUFFIX = '.json';
 const LEASE_DIVISOR = 3;
+// Both codes mean the lock is no longer this owner's to clean up. ENOENT: it is
+// already gone. ENOTEMPTY: a contender published its own generation into the
+// directory during the moment the unlink left it empty — renaming onto an empty
+// directory succeeds, which is exactly how a waiter takes the lock. Releasing
+// runs from a finally, so throwing here would replace the result of an
+// operation that already succeeded.
+const RELEASABLE_RMDIR_CODES = ['ENOENT', 'ENOTEMPTY'] as const;
 
 export type HeldBrokerLock = {
   readonly holderPath: string;
@@ -91,7 +98,7 @@ export const releaseBrokerLock = async ({
   try {
     await rmdir(lockPath);
   } catch (error) {
-    if (!isErrorCode(error, 'ENOENT')) {
+    if (!RELEASABLE_RMDIR_CODES.some((code) => isErrorCode(error, code))) {
       throw error;
     }
   }

package/src/creds-store-lock.ts

@@ -2,7 +2,8 @@
 // place before its operation starts. A worker-thread lease remains live while
 // synchronous SOPS/Nix blocks the main event loop. Cleanup unlinks the exact
 // generation token before removing the directory, so an old owner cannot
-// remove a replacement.
+// remove a replacement — and finding one there instead of an empty directory
+// is a no-op, never a failure of the operation being unwound.
 
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';

package/src/dev-env-compose.ts

@@ -0,0 +1,120 @@
+// Composes the dev env layers — tracked config/dev.yaml, decrypted
+// secrets/dev.yaml, and the gitignored per-machine config/dev.local.yaml —
+// into one workspace-keyed target set. Later layers override earlier ones
+// per env key. A key declared by both tracked shared layers is a placement
+// error: a value is either configuration or a secret, never both.
+
+import type { DevEnvDocument, EnvValues } from './dev-env-document';
+
+export type DevEnvLayer = {
+  readonly source: string;
+  readonly document: DevEnvDocument;
+};
+
+export type ComposedDevEnvTarget = {
+  readonly group: string;
+  readonly workspace: string;
+  readonly env: EnvValues;
+  readonly sources: ReadonlyArray<string>;
+};
+
+export type ComposedDevEnv = {
+  readonly targets: ReadonlyArray<ComposedDevEnvTarget>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+type MutableTarget = {
+  readonly group: string;
+  readonly workspace: string;
+  readonly env: Record<string, string>;
+  readonly sources: Array<string>;
+};
+
+const copyEnv = (source: EnvValues): Record<string, string> => {
+  const copy = Object.create(null) as Record<string, string>;
+  for (const [key, value] of Object.entries(source)) {
+    copy[key] = value;
+  }
+  return copy;
+};
+
+const applyLayer = (
+  merged: Map<string, MutableTarget>,
+  layer: DevEnvLayer,
+): void => {
+  for (const target of layer.document.targets) {
+    const key = `${target.group}.${target.workspace}`;
+    const existing = merged.get(key);
+    if (existing === undefined) {
+      merged.set(key, {
+        group: target.group,
+        workspace: target.workspace,
+        env: copyEnv(target.env),
+        sources: [layer.source],
+      });
+    } else {
+      for (const [envKey, value] of Object.entries(target.env)) {
+        existing.env[envKey] = value;
+      }
+      existing.sources.push(layer.source);
+    }
+  }
+};
+
+const sharedOverlapProblems = (
+  config: DevEnvLayer,
+  secrets: DevEnvLayer,
+): ReadonlyArray<string> => {
+  const secretTargets = new Map(
+    secrets.document.targets.map((target) => [
+      `${target.group}.${target.workspace}`,
+      target,
+    ]),
+  );
+  return config.document.targets.flatMap((target) => {
+    const counterpart = secretTargets.get(
+      `${target.group}.${target.workspace}`,
+    );
+    if (counterpart === undefined) {
+      return [];
+    }
+    return [...target.declaredKeys]
+      .filter((key) => counterpart.declaredKeys.has(key))
+      .map(
+        (key) =>
+          `${target.group}.${target.workspace}.${key} is declared in both ${config.source} and ${secrets.source}; a value is either configuration or a secret, so keep it in exactly one`,
+      );
+  });
+};
+
+export const composeDevEnv = (
+  config: DevEnvLayer | null,
+  secrets: DevEnvLayer,
+  local: DevEnvLayer | null,
+): ComposedDevEnv => {
+  const problems: ReadonlyArray<string> = [
+    ...(config === null ? [] : config.document.problems),
+    ...secrets.document.problems,
+    ...(local === null ? [] : local.document.problems),
+    ...(config === null ? [] : sharedOverlapProblems(config, secrets)),
+  ];
+  const merged = new Map<string, MutableTarget>();
+  for (const layer of [config, secrets, local]) {
+    if (layer !== null) {
+      applyLayer(merged, layer);
+    }
+  }
+  const targets = [...merged.values()]
+    .sort((a, b) =>
+      a.group === b.group
+        ? a.workspace.localeCompare(b.workspace)
+        : a.group.localeCompare(b.group),
+    )
+    .map((target) => ({
+      group: target.group,
+      workspace: target.workspace,
+      env: target.env,
+      sources: target.sources,
+    }));
+  return { targets, problems };
+};

package/src/dev-env-destination-duplicates.ts

@@ -1,19 +1,19 @@
 import { resolve } from 'node:path';
-import type { DevEnvWrite } from './dev-env-destination';
+import type { DevEnvMutation } from './dev-env-destination';
 
 export const duplicateDestinationProblems = (
   root: string,
-  writes: ReadonlyArray<DevEnvWrite>,
+  mutations: ReadonlyArray<DevEnvMutation>,
 ): ReadonlyArray<string> => {
-  const rawDuplicates = writes.flatMap((write, index) => {
-    const firstIndex = writes.findIndex(({ rel }) => rel === write.rel);
+  const rawDuplicates = mutations.flatMap((mutation, index) => {
+    const firstIndex = mutations.findIndex(({ rel }) => rel === mutation.rel);
     return firstIndex < index
-      ? [`${write.rel} is declared more than once`]
+      ? [`${mutation.rel} is declared more than once`]
       : [];
   });
-  const resolved = writes.map((write) => ({
-    write,
-    dest: resolve(root, write.rel),
+  const resolved = mutations.map((mutation) => ({
+    mutation,
+    dest: resolve(root, mutation.rel),
   }));
   const normalizedDuplicates = resolved.flatMap((destination, index) => {
     const firstIndex = resolved.findIndex(
@@ -22,9 +22,9 @@ export const duplicateDestinationProblems = (
     const first = resolved[firstIndex];
     return firstIndex < index &&
       first !== undefined &&
-      first.write.rel !== destination.write.rel
+      first.mutation.rel !== destination.mutation.rel
       ? [
-          `${destination.write.rel} resolves to the same destination as ${first.write.rel}`,
+          `${destination.mutation.rel} resolves to the same destination as ${first.mutation.rel}`,
         ]
       : [];
   });

package/src/dev-env-destination-gitignore.ts

@@ -0,0 +1,22 @@
+import { spawnSync } from 'node:child_process';
+
+// Decrypted values are safe only when git proves it will ignore them.
+export const devEnvGitIgnoreProblem = (
+  consumer: string,
+  rel: string,
+): string | null => {
+  const result = spawnSync('git', ['check-ignore', '-q', '--', rel], {
+    cwd: consumer,
+    encoding: 'utf8',
+  });
+  if (result.error !== undefined || result.status === null) {
+    return `cannot run git to verify ${rel} is gitignored`;
+  }
+  if (result.status === 0) {
+    return null;
+  }
+  if (result.status === 1) {
+    return `${rel} is not gitignored; ignore it before generating dev env files`;
+  }
+  return `cannot verify ${rel} is gitignored (git check-ignore exited ${result.status})`;
+};

package/src/dev-env-destination.ts

@@ -1,14 +1,29 @@
 import { randomUUID } from 'node:crypto';
 import type { Stats } from 'node:fs';
-import { lstat, realpath } from 'node:fs/promises';
+import { realpath } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { duplicateDestinationProblems } from './dev-env-destination-duplicates';
+import { devEnvGitIgnoreProblem } from './dev-env-destination-gitignore';
+import {
+  devEnvStatOrNull,
+  matchesDevEnvRemoval,
+} from './dev-env-reconciliation';
 
 export type DevEnvWrite = {
   readonly rel: string;
   readonly content: string;
 };
 
+export type DevEnvRemoval = {
+  readonly rel: string;
+  readonly identity: {
+    readonly device: number;
+    readonly inode: number;
+  };
+};
+
+export type DevEnvMutation = DevEnvWrite | DevEnvRemoval;
+
 type DevEnvPathIdentity = {
   readonly path: string;
   readonly device: number;
@@ -16,7 +31,7 @@ type DevEnvPathIdentity = {
 };
 
 export type DevEnvDestination = {
-  readonly write: DevEnvWrite;
+  readonly mutation: DevEnvMutation;
   readonly dest: string;
   readonly previous: Stats | null;
   readonly temp: string;
@@ -26,6 +41,7 @@ export type DevEnvDestination = {
   readonly realRoot: string;
   backupCreated: boolean;
   committed: boolean;
+  rollbackBlocked: boolean;
 };
 
 type PreflightResult =
@@ -40,27 +56,16 @@ const containedBy = (root: string, candidate: string): boolean => {
   return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 };
 
-export const devEnvStatOrNull = async (path: string): Promise<Stats | null> => {
-  try {
-    return await lstat(path);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null;
-    }
-    throw error;
-  }
-};
-
 const inspectDestination = async (
   root: string,
   realRoot: string,
-  write: DevEnvWrite,
+  mutation: DevEnvMutation,
 ): Promise<string | DevEnvDestination> => {
-  const dest = resolve(root, write.rel);
+  const dest = resolve(root, mutation.rel);
   if (!containedBy(root, dest)) {
-    return `${write.rel} escapes the consumer repository`;
+    return `${mutation.rel} escapes the consumer repository`;
   }
-  const paths = dirname(write.rel)
+  const paths = dirname(mutation.rel)
     .split(sep)
     .map((_segment, index, segments) =>
       join(root, ...segments.slice(0, index + 1)),
@@ -73,19 +78,24 @@ const inspectDestination = async (
         entry === null || !entry.isDirectory() || entry.isSymbolicLink(),
     )
   ) {
-    return `${write.rel} has an unsafe destination directory`;
+    return `${mutation.rel} has an unsafe destination directory`;
   }
   const realParent = await realpath(dirname(dest));
   if (!containedBy(realRoot, realParent)) {
-    return `${write.rel} resolves outside the consumer repository`;
+    return `${mutation.rel} resolves outside the consumer repository`;
   }
   const previous = await devEnvStatOrNull(dest);
   if (previous !== null && (!previous.isFile() || previous.isSymbolicLink())) {
-    return `${write.rel} must be absent or a regular file, not a symlink or other file type`;
+    return `${mutation.rel} must be absent or a regular file, not a symlink or other file type`;
+  }
+  if (
+    !('content' in mutation || (await matchesDevEnvRemoval(dest, mutation)))
+  ) {
+    return `${mutation.rel} changed after planning`;
   }
   const suffix = randomUUID();
   return {
-    write,
+    mutation,
     dest,
     previous,
     temp: join(dirname(dest), `.env.local.standards-${suffix}.tmp`),
@@ -99,32 +109,44 @@ const inspectDestination = async (
     realRoot,
     backupCreated: false,
     committed: false,
+    rollbackBlocked: false,
   };
 };
 
 export const preflightDevEnvDestinations = async (
   consumer: string,
-  writes: ReadonlyArray<DevEnvWrite>,
+  mutations: ReadonlyArray<DevEnvMutation>,
 ): Promise<PreflightResult> => {
   const root = resolve(consumer);
   const realRoot = await realpath(root);
-  const duplicates = duplicateDestinationProblems(root, writes);
+  const duplicates = duplicateDestinationProblems(root, mutations);
   const checked = await Promise.all(
-    writes.map(async (write) => {
+    mutations.map(async (mutation) => {
       try {
-        return await inspectDestination(root, realRoot, write);
+        return await inspectDestination(root, realRoot, mutation);
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
-        return `${write.rel} could not be preflighted: ${detail}`;
+        return `${mutation.rel} could not be preflighted: ${detail}`;
       }
     }),
   );
   const destinations = checked.filter(
     (item): item is DevEnvDestination => typeof item !== 'string',
   );
+  const gitignoreProblems = destinations.flatMap((destination) =>
+    [
+      destination.mutation.rel,
+      relative(root, destination.temp),
+      relative(root, destination.backup),
+    ].flatMap((rel) => {
+      const problem = devEnvGitIgnoreProblem(consumer, rel);
+      return problem === null ? [] : [problem];
+    }),
+  );
   const problems = [
     ...duplicates,
     ...checked.filter((item): item is string => typeof item === 'string'),
+    ...gitignoreProblems,
   ];
   return problems.length > 0
     ? { ok: false, problems }
@@ -158,18 +180,18 @@ export const devEnvParentProblem = async (
       realParent !== destination.realParent ||
       !containedBy(destination.realRoot, realParent)
     ) {
-      return `${destination.write.rel} destination directory changed after preflight`;
+      return `${destination.mutation.rel} destination directory changed after preflight`;
     }
     return null;
   } catch {
-    return `${destination.write.rel} destination directory changed after preflight`;
+    return `${destination.mutation.rel} destination directory changed after preflight`;
   }
 };
 
 export const devEnvDestinationProblems = async (
   consumer: string,
-  writes: ReadonlyArray<DevEnvWrite>,
+  mutations: ReadonlyArray<DevEnvMutation>,
 ): Promise<ReadonlyArray<string>> => {
-  const checked = await preflightDevEnvDestinations(consumer, writes);
+  const checked = await preflightDevEnvDestinations(consumer, mutations);
   return checked.ok ? [] : checked.problems;
 };

package/src/dev-env-document.ts

@@ -12,6 +12,7 @@ export type DevEnvTarget = {
   readonly group: string;
   readonly workspace: string;
   readonly env: EnvValues;
+  readonly declaredKeys: ReadonlySet<string>;
 };
 
 export type DevEnvDocument = {
@@ -31,12 +32,19 @@ type ParsedWorkspaces = {
 const parseWorkspaceEnv = (
   label: string,
   raw: Record<string, unknown>,
-): { readonly env: EnvValues; readonly problems: ReadonlyArray<string> } => {
+): {
+  readonly env: EnvValues;
+  readonly declaredKeys: ReadonlySet<string>;
+  readonly problems: ReadonlyArray<string>;
+} => {
   const problems: Array<string> = [];
-  const entries: Array<readonly [string, string]> = [];
+  const env = Object.create(null) as Record<string, string>;
+  const declaredKeys = new Set<string>();
   for (const [key, value] of Object.entries(raw)) {
     const portableName = PORTABLE_ENV_NAME.test(key);
-    if (!portableName) {
+    if (portableName) {
+      declaredKeys.add(key);
+    } else {
       problems.push(
         `${label} env key ${JSON.stringify(key)} must be a portable environment variable name`,
       );
@@ -48,10 +56,10 @@ const parseWorkspaceEnv = (
         `${label}.${key} cannot be represented losslessly in Bun dotenv syntax`,
       );
     } else if (portableName) {
-      entries.push([key, value]);
+      env[key] = value;
     }
   }
-  return { env: Object.fromEntries(entries), problems };
+  return { env, declaredKeys, problems };
 };
 
 const parseWorkspaces = (
@@ -75,7 +83,12 @@ const parseWorkspaces = (
       );
       problems.push(...parsed.problems);
       if (validWorkspace) {
-        targets.push({ group, workspace, env: parsed.env });
+        targets.push({
+          group,
+          workspace,
+          env: parsed.env,
+          declaredKeys: parsed.declaredKeys,
+        });
       }
     } else {
       problems.push(

package/src/dev-env-dotenv.ts

@@ -1,6 +1,15 @@
 import type { EnvValues } from './dev-env-document';
 import { encodeBunDotenvValue } from './dev-env-dotenv-value';
 
+export const DEV_ENV_GENERATED_HEADER =
+  '# Generated by `bun standards dev-env` (just dev-env-generate). Do not edit.';
+
+export const hasDevEnvGeneratedHeader = (content: string): boolean => {
+  const newline = content.indexOf('\n');
+  const firstLine = newline === -1 ? content : content.slice(0, newline);
+  return firstLine === DEV_ENV_GENERATED_HEADER;
+};
+
 const renderValue = (key: string, value: string): string => {
   const encoded = encodeBunDotenvValue(value);
   if (encoded === null) {
@@ -11,12 +20,12 @@ const renderValue = (key: string, value: string): string => {
 
 export const renderDotenv = (
   sourcePath: string,
-  secretsFile: string,
+  sources: ReadonlyArray<string>,
   env: EnvValues,
 ): string =>
   [
-    '# Generated by `bun standards dev-env` (just dev-env-generate). Do not edit.',
-    `# Source: ${secretsFile} (${sourcePath})`,
+    DEV_ENV_GENERATED_HEADER,
+    `# Sources: ${sources.join(' + ')} (${sourcePath})`,
     ...Object.entries(env).map(([key, value]) => renderValue(key, value)),
     '',
   ].join('\n');