@davidvornholt/standards 0.11.1 → 0.12.0

package/README.md

@@ -10,6 +10,7 @@ standards doctor
 standards structure
 standards dependabot --check
 standards dependabot --write
+standards dev-env
 standards github --check
 standards github --apply
 standards poller --config <path>
@@ -18,9 +19,11 @@ standards poller --print-units --config <path>
 
 `dependabot --write` regenerates the composed `.github/dependabot.yml` from the canonical `.github/dependabot.base.yml` and the optional repo-owned `.github/dependabot.local.yml`; `init` and `sync` do the same automatically. `dependabot --check` verifies the generated file still matches its sources, and `doctor`/`check` include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and `ignore` or `registries` entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy.
 
+`dev-env` decrypts the SOPS-encrypted `secrets/dev.yaml` — keyed by workspace group and a one-segment kebab-case workspace name (`apps.<name>`, `packages.<name>`), each mapping portable environment variable names to string values — and transactionally writes every declared workspace's `.env.local` with owner-only permissions and a do-not-edit header. Its Bun-specific dotenv codec exactly round-trips every value it accepts without adding helper environment variables; a value the codec cannot encode exactly is gathered as a validation problem instead of being changed silently. Validation gathers all document, containment, destination-type, workspace, and gitignore problems before writing anything. Generation then stages every output in its destination directory and rolls the whole set back if staging or commit fails, preserving prior contents, modes, and absent files; symlink destinations, duplicate resolved destinations, changed parent-directory identities, and symlinked workspace paths are rejected without following the link. Cleanup trouble after a completed commit is reported loudly as a warning rather than falsely reporting generation failure. Parent identities are checked immediately before each path operation; an unavoidable swap in the syscall-sized interval after a check remains outside the non-hostile maintainer threat model. The canonical `justfile` exposes the command as `just dev-env-generate`, and `just dev-refresh` chains a `just secrets edit dev` session into regeneration.
+
 `check` also rejects the raw token formed by `biome-` + `ignore` anywhere in lock-listed canonical files. The intentionally blunt policy keeps synced sources compatible with consumer Biome configurations without invoking Biome or maintaining language-aware comment parsing.
 
-`github --check` compares the live GitHub repository (merge settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its isolated `github-settings` job runs the live comparison with the settings-read token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
+`github --check` compares the live GitHub repository (including the canonical squash-only repository settings, rulesets, and declared labels) against the merged declaration in `.github/settings.json` + `.github/settings.local.json`; `github --apply` converges that declared state. The canonical declaration enables squash while disabling merge commits and rebases, and its default-branch ruleset independently allows only squash. Undeclared live labels remain untouched, while undeclared repository-owned rulesets are removed. `check` runs the same comparison whenever `.github/settings.json` is present, and fails closed: declared state the token cannot see fails the gate with a message naming the token fix instead of passing unverified. The canonical workflow sets `STANDARDS_SKIP_GITHUB_CHECK=true` only in its unprivileged quality step because its isolated `github-settings` job runs the live comparison with the settings-read token; this is a workflow-internal integration seam, not a general way to disable the local gate. The CLI prints an explicit diagnostic whenever that exact value skips either `check`'s live phase or `github --check`; `github --apply` is never skipped. `--apply` re-diffs the PATCH response, so a setting GitHub accepts with HTTP 200 but silently ignores (plan-unavailable features) is a reported failure, not a false success. A repository whose GitHub plan cannot enforce rulesets can declare that in the seam (see `rulesetEnforcement` below); both commands then skip rulesets and plan-gated repository settings, converge the rest, and print an unprotected-branch notice on every run.
 
 `structure` enforces the canonical monorepo structure contract: workspace scripts (`check-types`, `lint`, `lint:fix`, `test`), root gate scripts, filtered Turbo convenience aliases, internal `0.0.0`/`workspace:*` versioning, package `exports`, shared tsconfig inheritance, and browser a11y wiring. Only a workspace containing an explicit `*.a11y.ts` suite must provide a `test:a11y` script and direct `@axe-core/playwright` and `@playwright/test` dependencies. `check` includes `structure`, so these rules gate every consumer PR.
 
@@ -31,7 +34,7 @@ standards poller --print-units --config <path>
 ## Configuration
 
 - **`.github/dependabot.local.yml`** (optional) — repo-owned Dependabot extension composed with the canonical `.github/dependabot.base.yml` into the generated `.github/dependabot.yml`. May define `updates` and top-level `registries`; a block matching a canonical normalized target may only add `ignore` and/or `registries` entries. Other matching-block policy is rejected deliberately. A missing or comments-only file means no additions. CLI 0.10.1 requires the selected content ref to contain the canonical base and rejects older refs before mutation.
-- **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
+- **`sync-standards.local.json`** (optional) — consumer-owned sync policy at the repo root, validated by `doctor`/`check` and every `init`/`sync` even when an explicit ref or local source makes its `"ref"` irrelevant. All fields optional; a missing file means the defaults. `"ref"` is a non-empty single-line string that pins a tag, branch, or full commit sha to sync from instead of `main` (an explicit `--ref` overrides it; a local-path `--from` source is used as-is and ignores only the validated pin). `"autoSync": false` is read by the standards-sync workflow, not the CLI, and skips the weekly scheduled run; deliberate syncs then run locally because the secret-bearing workflow is schedule-only. Version 0.7.0 removes the legacy `STANDARDS_AUTO_SYNC` and `STANDARDS_SYNC_REF` variable behavior; consumers must upgrade the package and lockfile before adopting a policy file.
 - **`.github/settings.local.json` `"rulesetEnforcement": "unavailable-on-plan"`** (optional) — declares that the repository's GitHub plan cannot enforce rulesets (private repositories on GitHub Free, both personal accounts and organizations). `github --check` and `--apply` then skip rulesets instead of comparing them, because a comparison cannot be trusted there: personal accounts answer ruleset reads with HTTP 403, and free-plan organizations report declared rulesets as active while silently not enforcing them. Plan-gated repository settings that only function alongside branch protection (`allow_auto_merge`) are skipped for the same reason — GitHub accepts a PATCH for them with HTTP 200 and silently keeps the old value. The remaining repository merge settings are still checked and converged, and both commands print an unprotected-branch notice on every run. The only accepted value is `"unavailable-on-plan"` (enforcement is the default; omit the key on paid plans), and combining the opt-out with additional local rulesets is rejected. After upgrading the plan, remove the declaration and run `bun standards github --apply` to restore enforcement.
 - **Poller config file** (required for `poller`, passed via `--config`) — host-level JSON, deliberately not repository state. Required: `"repos"` (unique `owner/repo` strings — one poller watches any number of repositories), `"model"` and `"reasoningEffort"` (passed to `codex exec`; the model choice is deliberate and has no default). Optional: `"maxJobsPerTick"` (default 1 — the concurrency and rate-limit guard; subscription-authenticated Codex runs share the interactive rate window), `"staleClaimHours"` (default 6; must exceed `runTimeoutMinutes` so a sweep can never release the claim of a job that is still running), `"runTimeoutMinutes"` (default 240 — the timeout catches wedged agents, not honest multi-hour review runs), `"cacheDir"` (default `~/.cache/standards-poller`; holds bare mirrors and job worktrees; relative paths resolve against the config file), `"extraCodexArgs"` (extra `codex exec` arguments, e.g. enabling the collaboration feature for subagent fan-out). Unknown keys are rejected. The poller needs `git`, `codex` (authenticated — its rotating auth state must live in a writable location), and a GitHub token per the bullet below; the token needs issues, pull-requests, and contents write on the watched repos, and nothing else.
 - **`GH_TOKEN` / `GITHUB_TOKEN`** (optional) — GitHub API token for the `github` command and the GitHub portion of `check`. When neither is set, the token from the local `gh` CLI is used; with no token at all, reads still work on public repositories. `--apply` needs an admin token. GitHub's REST API reveals repo merge settings only to write-capable viewers — `check` retries REST-hidden keys over GraphQL, which serves them to read-only tokens — ruleset `bypass_actors` requires repository Administration read, and private-repository labels require Issues read (or Pull requests read); a token that still cannot see declared state fails the check rather than passing unverified. In CI, the canonical workflow decrypts `ci.github_settings_read_token` from the SOPS-encrypted `secrets/ci.yaml`: a repository-scoped fine-grained PAT with read-only "Administration" and "Issues" access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,14 @@
     "src/dependabot-compose.ts",
     "src/dependabot-inspect.ts",
     "src/dependabot-update.ts",
+    "src/dev-env-document.ts",
+    "src/dev-env-destination-duplicates.ts",
+    "src/dev-env-destination.ts",
+    "src/dev-env-dotenv-value.ts",
+    "src/dev-env-dotenv.ts",
+    "src/dev-env-transaction-recovery.ts",
+    "src/dev-env-transaction.ts",
+    "src/dev-env.ts",
     "src/github-api.ts",
     "src/github-apply.ts",
     "src/github-command-shared.ts",

package/src/cli.ts

@@ -24,6 +24,7 @@ import {
   DEPENDABOT_LOCAL_FILE,
 } from './dependabot-compose';
 import { inspectDependabot } from './dependabot-inspect';
+import { runDevEnv } from './dev-env';
 import { CANONICAL_SETTINGS_FILE, LOCAL_SETTINGS_FILE } from './github-api';
 import { runGithubApply, runGithubCheck } from './github-commands';
 import { loadGithubSettings } from './github-settings';
@@ -66,6 +67,7 @@ type Source = {
 type Command =
   | 'check'
   | 'dependabot'
+  | 'dev-env'
   | 'doctor'
   | 'github'
   | 'help'
@@ -736,6 +738,7 @@ Commands:
   doctor      Validate extension seams only
   structure   Validate monorepo structure rules only
   dependabot  Verify (--check) or regenerate (--write) the composed .github/dependabot.yml
+  dev-env     Write each workspace's generated .env.local from the SOPS-encrypted secrets/dev.yaml
   github      Compare (--check) or converge (--apply) live GitHub settings
   poller      Run one fix-poller tick over the configured repositories (host automation)
   help        Show this help
@@ -756,6 +759,7 @@ const commandFromArg = (arg: string): Command => {
   if (
     arg === 'check' ||
     arg === 'dependabot' ||
+    arg === 'dev-env' ||
     arg === 'doctor' ||
     arg === 'github' ||
     arg === 'help' ||
@@ -984,8 +988,8 @@ const runGithubCheckGate = (consumer: string): Promise<boolean> => {
 // standards-sync workflow it configures — versioned and reviewable, unlike
 // repository Actions variables. All fields are optional; a missing file means
 // the defaults (track main, weekly auto-sync on).
-//   autoSync  false skips the scheduled workflow run; manual dispatch and
-//             local CLI runs are deliberate acts and always proceed.
+//   autoSync  false skips the scheduled workflow run; local CLI runs remain
+//             the deliberate sync path.
 //   ref       tag, branch, or full commit sha to sync from instead of main.
 const POLICY_FILE = 'sync-standards.local.json';
 const LINE_BREAK = /[\r\n]/u;
@@ -1108,7 +1112,13 @@ const runSyncCommand = async (
 
 // Commands whose success is reported through the exit code.
 const runGateCommand = (
-  command: 'check' | 'dependabot' | 'doctor' | 'github' | 'structure',
+  command:
+    | 'check'
+    | 'dependabot'
+    | 'dev-env'
+    | 'doctor'
+    | 'github'
+    | 'structure',
   consumer: string,
   apply: boolean,
   profile: StructureProfile,
@@ -1119,6 +1129,9 @@ const runGateCommand = (
   if (command === 'dependabot') {
     return runDependabotCheck(consumer);
   }
+  if (command === 'dev-env') {
+    return runDevEnv(consumer);
+  }
   if (command === 'doctor') {
     return runDoctor(consumer);
   }

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

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

package/src/dev-env-destination.ts

@@ -0,0 +1,175 @@
+import { randomUUID } from 'node:crypto';
+import type { Stats } from 'node:fs';
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { duplicateDestinationProblems } from './dev-env-destination-duplicates';
+
+export type DevEnvWrite = {
+  readonly rel: string;
+  readonly content: string;
+};
+
+type DevEnvPathIdentity = {
+  readonly path: string;
+  readonly device: number;
+  readonly inode: number;
+};
+
+export type DevEnvDestination = {
+  readonly write: DevEnvWrite;
+  readonly dest: string;
+  readonly previous: Stats | null;
+  readonly temp: string;
+  readonly backup: string;
+  readonly parents: ReadonlyArray<DevEnvPathIdentity>;
+  readonly realParent: string;
+  readonly realRoot: string;
+  backupCreated: boolean;
+  committed: boolean;
+};
+
+type PreflightResult =
+  | {
+      readonly ok: true;
+      readonly destinations: ReadonlyArray<DevEnvDestination>;
+    }
+  | { readonly ok: false; readonly problems: ReadonlyArray<string> };
+
+const containedBy = (root: string, candidate: string): boolean => {
+  const rel = relative(root, candidate);
+  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,
+): Promise<string | DevEnvDestination> => {
+  const dest = resolve(root, write.rel);
+  if (!containedBy(root, dest)) {
+    return `${write.rel} escapes the consumer repository`;
+  }
+  const paths = dirname(write.rel)
+    .split(sep)
+    .map((_segment, index, segments) =>
+      join(root, ...segments.slice(0, index + 1)),
+    );
+  const parentPaths = [root, ...paths];
+  const parents = await Promise.all(parentPaths.map(devEnvStatOrNull));
+  if (
+    parents.some(
+      (entry) =>
+        entry === null || !entry.isDirectory() || entry.isSymbolicLink(),
+    )
+  ) {
+    return `${write.rel} has an unsafe destination directory`;
+  }
+  const realParent = await realpath(dirname(dest));
+  if (!containedBy(realRoot, realParent)) {
+    return `${write.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`;
+  }
+  const suffix = randomUUID();
+  return {
+    write,
+    dest,
+    previous,
+    temp: join(dirname(dest), `.env.local.standards-${suffix}.tmp`),
+    backup: join(dirname(dest), `.env.local.standards-${suffix}.bak`),
+    parents: parents.map((entry, index) => ({
+      path: parentPaths[index] ?? root,
+      device: entry?.dev ?? 0,
+      inode: entry?.ino ?? 0,
+    })),
+    realParent,
+    realRoot,
+    backupCreated: false,
+    committed: false,
+  };
+};
+
+export const preflightDevEnvDestinations = async (
+  consumer: string,
+  writes: ReadonlyArray<DevEnvWrite>,
+): Promise<PreflightResult> => {
+  const root = resolve(consumer);
+  const realRoot = await realpath(root);
+  const duplicates = duplicateDestinationProblems(root, writes);
+  const checked = await Promise.all(
+    writes.map(async (write) => {
+      try {
+        return await inspectDestination(root, realRoot, write);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return `${write.rel} could not be preflighted: ${detail}`;
+      }
+    }),
+  );
+  const destinations = checked.filter(
+    (item): item is DevEnvDestination => typeof item !== 'string',
+  );
+  const problems = [
+    ...duplicates,
+    ...checked.filter((item): item is string => typeof item === 'string'),
+  ];
+  return problems.length > 0
+    ? { ok: false, problems }
+    : {
+        ok: true,
+        destinations,
+      };
+};
+
+export const devEnvParentProblem = async (
+  destination: DevEnvDestination,
+): Promise<string | null> => {
+  try {
+    const current = await Promise.all(
+      destination.parents.map(async (parent) => ({
+        expected: parent,
+        actual: await devEnvStatOrNull(parent.path),
+      })),
+    );
+    const changed = current.some(
+      ({ expected, actual }) =>
+        actual === null ||
+        !actual.isDirectory() ||
+        actual.isSymbolicLink() ||
+        actual.dev !== expected.device ||
+        actual.ino !== expected.inode,
+    );
+    const realParent = await realpath(dirname(destination.dest));
+    if (
+      changed ||
+      realParent !== destination.realParent ||
+      !containedBy(destination.realRoot, realParent)
+    ) {
+      return `${destination.write.rel} destination directory changed after preflight`;
+    }
+    return null;
+  } catch {
+    return `${destination.write.rel} destination directory changed after preflight`;
+  }
+};
+
+export const devEnvDestinationProblems = async (
+  consumer: string,
+  writes: ReadonlyArray<DevEnvWrite>,
+): Promise<ReadonlyArray<string>> => {
+  const checked = await preflightDevEnvDestinations(consumer, writes);
+  return checked.ok ? [] : checked.problems;
+};

package/src/dev-env-document.ts

@@ -0,0 +1,117 @@
+// Workspace-group keyed dev secrets document: `apps.<name>` and
+// `packages.<name>` map env keys to string values — the shape mirrored in
+// secrets/dev.example.yaml. Parsing gathers every problem instead of failing
+// on the first one so a malformed document is repaired in one pass.
+
+import { encodeBunDotenvValue } from './dev-env-dotenv-value';
+import { isRecord } from './github-settings-parse';
+
+export type EnvValues = Readonly<Record<string, string>>;
+
+export type DevEnvTarget = {
+  readonly group: string;
+  readonly workspace: string;
+  readonly env: EnvValues;
+};
+
+export type DevEnvDocument = {
+  readonly targets: ReadonlyArray<DevEnvTarget>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const WORKSPACE_GROUPS: ReadonlyArray<string> = ['apps', 'packages'];
+const PORTABLE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const WORKSPACE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+type ParsedWorkspaces = {
+  readonly targets: ReadonlyArray<DevEnvTarget>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const parseWorkspaceEnv = (
+  label: string,
+  raw: Record<string, unknown>,
+): { readonly env: EnvValues; readonly problems: ReadonlyArray<string> } => {
+  const problems: Array<string> = [];
+  const entries: Array<readonly [string, string]> = [];
+  for (const [key, value] of Object.entries(raw)) {
+    const portableName = PORTABLE_ENV_NAME.test(key);
+    if (!portableName) {
+      problems.push(
+        `${label} env key ${JSON.stringify(key)} must be a portable environment variable name`,
+      );
+    }
+    if (typeof value !== 'string') {
+      problems.push(`${label}.${key} must be a string value`);
+    } else if (encodeBunDotenvValue(value) === null) {
+      problems.push(
+        `${label}.${key} cannot be represented losslessly in Bun dotenv syntax`,
+      );
+    } else if (portableName) {
+      entries.push([key, value]);
+    }
+  }
+  return { env: Object.fromEntries(entries), problems };
+};
+
+const parseWorkspaces = (
+  source: string,
+  group: string,
+  workspaces: Record<string, unknown>,
+): ParsedWorkspaces => {
+  const problems: Array<string> = [];
+  const targets: Array<DevEnvTarget> = [];
+  for (const [workspace, env] of Object.entries(workspaces)) {
+    const validWorkspace = WORKSPACE_NAME.test(workspace);
+    if (!validWorkspace) {
+      problems.push(
+        `${source} ${JSON.stringify(`${group}.${workspace}`)} workspace name must be one kebab-case path segment`,
+      );
+    }
+    if (isRecord(env)) {
+      const parsed = parseWorkspaceEnv(
+        `${source} "${group}.${workspace}"`,
+        env,
+      );
+      problems.push(...parsed.problems);
+      if (validWorkspace) {
+        targets.push({ group, workspace, env: parsed.env });
+      }
+    } else {
+      problems.push(
+        `${source} "${group}.${workspace}" must map env keys to string values`,
+      );
+    }
+  }
+  return { targets, problems };
+};
+
+export const parseDevEnvDocument = (
+  raw: unknown,
+  source: string,
+): DevEnvDocument => {
+  if (!isRecord(raw)) {
+    return {
+      targets: [],
+      problems: [`${source} must decrypt to a YAML object`],
+    };
+  }
+  const problems: Array<string> = [];
+  const targets: Array<DevEnvTarget> = [];
+  for (const [group, workspaces] of Object.entries(raw)) {
+    if (!WORKSPACE_GROUPS.includes(group)) {
+      problems.push(
+        `${source} top-level key "${group}" must be "apps" or "packages"`,
+      );
+    } else if (isRecord(workspaces)) {
+      const parsed = parseWorkspaces(source, group, workspaces);
+      problems.push(...parsed.problems);
+      targets.push(...parsed.targets);
+    } else {
+      problems.push(
+        `${source} "${group}" must map workspace names to env objects`,
+      );
+    }
+  }
+  return { targets, problems };
+};

package/src/dev-env-dotenv-value.ts

@@ -0,0 +1,51 @@
+const EMPTY_EXPANSION = ['$', '{:-}'].join('');
+const QUOTED_BACKSLASH_HAZARD = /\\(?:[nr]|\r|\n)/u;
+const EDGE_BACKSLASH = /\\$/u;
+const UNQUOTED_BODY_HAZARD = /[#\r\n]/u;
+const EDGE_DOLLAR = /\$$/u;
+const EDGE_WHITESPACE = /\s$/u;
+
+const escapeDollars = (value: string): string => value.replaceAll('$', '\\$');
+
+const terminalDollarExpansion = (value: string): string =>
+  EDGE_DOLLAR.test(value) ? EMPTY_EXPANSION : '';
+
+const encodeUnquoted = (value: string): string | null => {
+  if (UNQUOTED_BODY_HAZARD.test(value)) {
+    return null;
+  }
+  const terminator =
+    EDGE_WHITESPACE.test(value) || EDGE_DOLLAR.test(value)
+      ? EMPTY_EXPANSION
+      : '#';
+  return `${EMPTY_EXPANSION}${escapeDollars(value)}${terminator}`;
+};
+
+const encodeDoubleQuoted = (value: string): string | null => {
+  if (
+    value.includes('"') ||
+    EDGE_BACKSLASH.test(value) ||
+    QUOTED_BACKSLASH_HAZARD.test(value)
+  ) {
+    return null;
+  }
+  return `"${escapeDollars(value)
+    .replaceAll('\r', '\\r')
+    .replaceAll('\n', '\\n')}${terminalDollarExpansion(value)}"`;
+};
+
+const encodeLiteralQuoted = (
+  value: string,
+  delimiter: "'" | '`',
+): string | null =>
+  value.includes(delimiter) ||
+  value.includes('\r') ||
+  EDGE_BACKSLASH.test(value)
+    ? null
+    : `${delimiter}${escapeDollars(value)}${terminalDollarExpansion(value)}${delimiter}`;
+
+export const encodeBunDotenvValue = (value: string): string | null =>
+  encodeUnquoted(value) ??
+  encodeDoubleQuoted(value) ??
+  encodeLiteralQuoted(value, "'") ??
+  encodeLiteralQuoted(value, '`');

package/src/dev-env-dotenv.ts

@@ -0,0 +1,22 @@
+import type { EnvValues } from './dev-env-document';
+import { encodeBunDotenvValue } from './dev-env-dotenv-value';
+
+const renderValue = (key: string, value: string): string => {
+  const encoded = encodeBunDotenvValue(value);
+  if (encoded === null) {
+    throw new Error(`${key} was not validated for Bun dotenv rendering`);
+  }
+  return `${key}=${encoded}`;
+};
+
+export const renderDotenv = (
+  sourcePath: string,
+  secretsFile: string,
+  env: EnvValues,
+): string =>
+  [
+    '# Generated by `bun standards dev-env` (just dev-env-generate). Do not edit.',
+    `# Source: ${secretsFile} (${sourcePath})`,
+    ...Object.entries(env).map(([key, value]) => renderValue(key, value)),
+    '',
+  ].join('\n');

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

@@ -0,0 +1,80 @@
+import { rename, rm } from 'node:fs/promises';
+import {
+  type DevEnvDestination,
+  devEnvParentProblem,
+} from './dev-env-destination';
+
+const message = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const requireParent = async (
+  destination: DevEnvDestination,
+): Promise<string | null> => devEnvParentProblem(destination);
+
+const rollbackOne = async (
+  destination: DevEnvDestination,
+): Promise<ReadonlyArray<string>> => {
+  const problems: Array<string> = [];
+  if (destination.committed) {
+    const parentProblem = await requireParent(destination);
+    if (parentProblem !== null) {
+      return [parentProblem];
+    }
+    try {
+      await rm(destination.dest, { force: true });
+      destination.committed = false;
+    } catch (error) {
+      problems.push(`${destination.write.rel}: ${message(error)}`);
+    }
+  }
+  if (destination.backupCreated && problems.length === 0) {
+    const parentProblem = await requireParent(destination);
+    if (parentProblem !== null) {
+      return [parentProblem];
+    }
+    try {
+      await rename(destination.backup, destination.dest);
+      destination.backupCreated = false;
+    } catch (error) {
+      problems.push(`${destination.write.rel}: ${message(error)}`);
+    }
+  }
+  return problems;
+};
+
+export const rollbackDevEnvFiles = async (
+  destinations: ReadonlyArray<DevEnvDestination>,
+): Promise<ReadonlyArray<string>> => {
+  const outcomes = await Promise.all(destinations.map(rollbackOne));
+  return outcomes.flat();
+};
+
+const cleanupOne = async (
+  destination: DevEnvDestination,
+  preserveBackups: boolean,
+): Promise<ReadonlyArray<string>> => {
+  const parentProblem = await requireParent(destination);
+  if (parentProblem !== null) {
+    return [parentProblem];
+  }
+  const paths = [destination.temp];
+  if (!preserveBackups) {
+    paths.push(destination.backup);
+  }
+  const outcomes = await Promise.allSettled(
+    paths.map((path) => rm(path, { force: true })),
+  );
+  return outcomes.flatMap((outcome) =>
+    outcome.status === 'rejected' ? [message(outcome.reason)] : [],
+  );
+};
+
+export const cleanupDevEnvArtifacts = async (
+  destinations: ReadonlyArray<DevEnvDestination>,
+  preserveBackups: boolean,
+): Promise<ReadonlyArray<string>> => {
+  const outcomes = await Promise.all(
+    destinations.map((destination) => cleanupOne(destination, preserveBackups)),
+  );
+  return outcomes.flat();
+};

package/src/dev-env-transaction.ts

@@ -0,0 +1,152 @@
+import { link, open, rename } from 'node:fs/promises';
+import {
+  type DevEnvDestination,
+  type DevEnvWrite,
+  devEnvParentProblem,
+  devEnvStatOrNull,
+  preflightDevEnvDestinations,
+} from './dev-env-destination';
+import {
+  cleanupDevEnvArtifacts,
+  rollbackDevEnvFiles,
+} from './dev-env-transaction-recovery';
+
+const OWNER_ONLY_FILE_MODE = 0o600;
+
+export type DevEnvTransactionHooks = {
+  readonly beforeStage?: (index: number) => void | Promise<void>;
+  readonly beforeCommit?: (index: number) => void | Promise<void>;
+  readonly beforeCleanup?: () => void | Promise<void>;
+};
+
+export type DevEnvTransactionResult =
+  | { readonly ok: true; readonly warnings: ReadonlyArray<string> }
+  | { readonly ok: false; readonly problems: ReadonlyArray<string> };
+
+const requireParent = async (destination: DevEnvDestination): Promise<void> => {
+  const problem = await devEnvParentProblem(destination);
+  if (problem !== null) {
+    throw new Error(problem);
+  }
+};
+
+const stage = async (destination: DevEnvDestination): Promise<void> => {
+  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.sync();
+  } finally {
+    await file.close();
+  }
+};
+
+const unchanged = async (destination: DevEnvDestination): Promise<boolean> => {
+  const current = await devEnvStatOrNull(destination.dest);
+  if (current === null || destination.previous === null) {
+    return current === destination.previous;
+  }
+  return (
+    current.isFile() &&
+    !current.isSymbolicLink() &&
+    current.dev === destination.previous.dev &&
+    current.ino === destination.previous.ino &&
+    current.mode === destination.previous.mode
+  );
+};
+
+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 commitOne = async (destination: DevEnvDestination): Promise<void> => {
+  await requireParent(destination);
+  if (!(await unchanged(destination))) {
+    throw new Error(`${destination.write.rel} changed after preflight`);
+  }
+  if (destination.previous !== null) {
+    await requireParent(destination);
+    await link(destination.dest, destination.backup);
+    destination.backupCreated = true;
+  }
+  await requireParent(destination);
+  await rename(destination.temp, destination.dest);
+  destination.committed = true;
+};
+
+const commitAll = async (
+  destinations: ReadonlyArray<DevEnvDestination>,
+  hooks: DevEnvTransactionHooks,
+): Promise<void> => {
+  await destinations.reduce<Promise<void>>(
+    async (previous, destination, index) => {
+      await previous;
+      await hooks.beforeCommit?.(index);
+      await commitOne(destination);
+    },
+    Promise.resolve(),
+  );
+};
+
+const problemMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const recoverFailure = async (
+  destinations: ReadonlyArray<DevEnvDestination>,
+  error: unknown,
+): Promise<DevEnvTransactionResult> => {
+  const rollbackProblems = await rollbackDevEnvFiles(destinations);
+  const cleanupProblems = await cleanupDevEnvArtifacts(
+    destinations,
+    rollbackProblems.length > 0,
+  );
+  return {
+    ok: false,
+    problems: [
+      problemMessage(error),
+      ...rollbackProblems.map((problem) => `rollback failed: ${problem}`),
+      ...cleanupProblems.map((problem) => `cleanup failed: ${problem}`),
+    ],
+  };
+};
+
+export const writeDevEnvFiles = async (
+  consumer: string,
+  writes: ReadonlyArray<DevEnvWrite>,
+  hooks: DevEnvTransactionHooks = {},
+): Promise<DevEnvTransactionResult> => {
+  const checked = await preflightDevEnvDestinations(consumer, writes);
+  if (!checked.ok) {
+    return checked;
+  }
+  try {
+    await stageAll(checked.destinations, hooks);
+    await commitAll(checked.destinations, hooks);
+  } catch (error) {
+    return recoverFailure(checked.destinations, error);
+  }
+  let cleanupProblems: ReadonlyArray<string>;
+  try {
+    await hooks.beforeCleanup?.();
+    cleanupProblems = await cleanupDevEnvArtifacts(checked.destinations, false);
+  } catch (error) {
+    cleanupProblems = [problemMessage(error)];
+  }
+  return {
+    ok: true,
+    warnings: cleanupProblems.map(
+      (problem) => `generation committed but cleanup failed: ${problem}`,
+    ),
+  };
+};

package/src/dev-env.ts

@@ -0,0 +1,165 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  type DevEnvWrite,
+  devEnvDestinationProblems,
+} from './dev-env-destination';
+import { parseDevEnvDocument } from './dev-env-document';
+import { renderDotenv } from './dev-env-dotenv';
+import { writeDevEnvFiles } from './dev-env-transaction';
+
+export const DEV_SECRETS_FILE = 'secrets/dev.yaml';
+
+const SOPS_ARGS = ['--decrypt', '--output-type', 'json', DEV_SECRETS_FILE];
+
+type DecryptResult =
+  | { 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; the
+// nix fallback mirrors the canonical secrets.just tool resolution.
+const decryptDevSecrets = (consumer: string): DecryptResult => {
+  const localSops = spawnSync('sops', SOPS_ARGS, {
+    cwd: consumer,
+    encoding: 'utf8',
+  });
+  const result =
+    localSops.error === undefined && localSops.status !== null
+      ? localSops
+      : spawnSync(
+          'nix',
+          [
+            '--extra-experimental-features',
+            'nix-command flakes',
+            'run',
+            'nixpkgs#sops',
+            '--',
+            ...SOPS_ARGS,
+          ],
+          { cwd: consumer, encoding: 'utf8' },
+        );
+  if (result.status !== 0) {
+    const detail = result.error?.message ?? 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)
+      }`,
+    };
+  }
+};
+
+// Writing decrypted values into the tree is only safe when git will never
+// track them. `git check-ignore` is authoritative; anything but a clear
+// "ignored" answer fails closed, including running outside a git checkout.
+const gitIgnoreProblem = (consumer: string, rel: string): string | null => {
+  const result = spawnSync('git', ['check-ignore', '-q', '--', rel], {
+    cwd: consumer,
+  });
+  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})`;
+};
+
+export type DevEnvPlan = {
+  readonly writes: ReadonlyArray<DevEnvWrite>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const planDevEnvWrites = (
+  consumer: string,
+  raw: unknown,
+): DevEnvPlan => {
+  const document = parseDevEnvDocument(raw, DEV_SECRETS_FILE);
+  const problems: Array<string> = [...document.problems];
+  const writes: Array<DevEnvWrite> = [];
+  for (const target of document.targets) {
+    const workspaceDir = `${target.group}/${target.workspace}`;
+    const rel = `${workspaceDir}/.env.local`;
+    if (existsSync(join(consumer, workspaceDir, 'package.json'))) {
+      const ignoreProblem = gitIgnoreProblem(consumer, rel);
+      if (ignoreProblem === null) {
+        writes.push({
+          rel,
+          content: renderDotenv(
+            `${target.group}.${target.workspace}`,
+            DEV_SECRETS_FILE,
+            target.env,
+          ),
+        });
+      } else {
+        problems.push(ignoreProblem);
+      }
+    } else {
+      problems.push(
+        `${DEV_SECRETS_FILE} defines ${target.group}.${target.workspace}, but ${workspaceDir}/package.json does not exist`,
+      );
+    }
+  }
+  return { writes, problems };
+};
+
+export const runDevEnv = async (consumer: string): Promise<boolean> => {
+  if (!existsSync(join(consumer, DEV_SECRETS_FILE))) {
+    console.error(
+      `standards dev-env: ${DEV_SECRETS_FILE} not found; create it with \`just secrets edit dev\``,
+    );
+    return false;
+  }
+  const decrypted = decryptDevSecrets(consumer);
+  if (!decrypted.ok) {
+    console.error(`standards dev-env: ${decrypted.problem}`);
+    return false;
+  }
+  const plan = planDevEnvWrites(consumer, decrypted.value);
+  const problems = [
+    ...plan.problems,
+    ...(await devEnvDestinationProblems(consumer, plan.writes)),
+  ];
+  if (problems.length > 0) {
+    console.error(`standards dev-env: ${problems.length} problem(s):`);
+    console.error(problems.map((problem) => `  - ${problem}`).join('\n'));
+    return false;
+  }
+  const generated = await writeDevEnvFiles(consumer, plan.writes);
+  if (!generated.ok) {
+    console.error('standards dev-env: generation failed:');
+    console.error(
+      generated.problems.map((problem) => `  - ${problem}`).join('\n'),
+    );
+    return false;
+  }
+  if (generated.warnings.length > 0) {
+    console.error(
+      `standards dev-env: generated files with ${generated.warnings.length} cleanup warning(s):`,
+    );
+    console.error(
+      generated.warnings.map((warning) => `  - ${warning}`).join('\n'),
+    );
+  }
+  for (const write of plan.writes) {
+    console.log(`  wrote ${write.rel}`);
+  }
+  console.log(
+    `standards dev-env: generated ${plan.writes.length} env file(s) from ${DEV_SECRETS_FILE}`,
+  );
+  return true;
+};