feat(env): add env overlays and doctor migration checks

Author: hack-cli-tests

CHANGELOG.md

@@ -7,6 +7,12 @@
 * Merge pull request #29 from hack-dance/codex/define-env-key-rotation-and-recovery-flows-16o779 ([408f664](https://github.com/hack-dance/hack/commit/408f664)), closes [#29](https://github.com/hack-dance/hack/issues/29)
 * docs: clarify portable env recovery flows ([5bb98db](https://github.com/hack-dance/hack/commit/5bb98db))
 
+## Next
+
+* feat(env): add `--env=<name>` overlays on top of the base `.hack/hack.env.json` contract and `.hack/.env` compatibility file
+* feat(env): allow project defaults via `defaultEnvConfig` / `default_env_config`
+* feat(doctor): warn when repos are still on legacy local-only plaintext env mode instead of the bundled portable backend flow
+
 ## <small>1.21.2 (2026-03-24)</small>
 
 * Merge branch 'main' into codex/linear-mention-hack-462-preserve-.env-compatibility-whil-6icfe6 ([7e821e4](https://github.com/hack-dance/hack/commit/7e821e4))

docs/env.md

@@ -35,6 +35,8 @@ Opt-in portable bundle mode:
 - Set `controlPlane.secrets.storePlaintextInBackend=true` in project config when you want `plain_env` values mirrored into the configured backend alongside secret values.
 - In that mode, the backend copy becomes the portable source of truth and `.hack/.env` becomes a compatibility materialization target.
 - This works best with the repo-relative `encrypted_file` backend, because the encrypted file plus key can move with the repo onboarding flow.
+- Optional env overlays can then be selected with `--env=<name>`, which layers `.hack/.env.<name>` and backend-scoped values on top of the base `.hack/.env` values.
+- Projects can set `defaultEnvConfig` (or `default_env_config`) in `.hack/hack.config.json` so `hack up`, `hack env`, and related commands automatically use that overlay unless `--env=base` is passed.
 
 Current status:
 
@@ -66,6 +68,36 @@ See `docs/plans/2026-03-13-env-portability-and-secret-management-design.md` for
 - `process.env` (ambient fallback): supplies `plain_env` values when `.hack/.env` is missing a key.
 - Configured secret backend (`controlPlane.secrets.backend`): stores secret values for `source: "keychain"` contract vars.
 
+## Env overlay model
+
+Hack now supports a Pulumi-like overlay convention without changing the base contract file:
+
+- Base contract: `.hack/hack.env.json`
+- Base plaintext compatibility file: `.hack/.env`
+- Optional overlay plaintext compatibility file: `.hack/.env.<env>`
+- Optional overlay selection: `hack ... --env=qa`
+- Optional project default: `"defaultEnvConfig": "qa"` in `.hack/hack.config.json`
+
+Resolution order:
+
+1. selected overlay value (`--env=qa` or `defaultEnvConfig`)
+2. base value
+3. `process.env` fallback for `plain_env`
+
+Secret-backed overlay values are stored in the configured backend under env-scoped keys, so one encrypted backend can carry base plus multiple overlays together.
+
+Use `--env=base` to bypass the configured default overlay and operate on the base env only.
+
+## Migrating older repos
+
+For older repos that only used `.hack/.env`:
+
+1. Keep `.hack/hack.env.json` as the base contract.
+2. Enable `controlPlane.secrets.storePlaintextInBackend=true`.
+3. Re-save existing values with `hack env set KEY=VALUE` so plaintext values are mirrored into the portable backend bundle.
+4. Add overlay-specific values with `hack env set --env=qa KEY=VALUE` or `hack env set --env=prod KEY=VALUE`.
+5. Run `hack doctor` to confirm whether the repo is still on legacy local-only plaintext mode or is using bundled base/overlay envs.
+
 ## Contract format (`.hack/hack.env.json`)
 
 ```json

src/cli/options.ts

@@ -19,6 +19,15 @@ export const optProject = defineOption({
     "Target a registered project by name (from ~/.hack/projects.json)",
 } as const);
 
+export const optEnv = defineOption({
+  name: "env",
+  type: "string",
+  long: "--env",
+  valueHint: "<name|base>",
+  description:
+    "Apply an optional env overlay by name (use 'base' to bypass overlays)",
+} as const);
+
 export const optBranch = defineOption({
   name: "branch",
   type: "string",

src/commands/doctor.ts

@@ -21,6 +21,7 @@ import {
   GLOBAL_LOGGING_COMPOSE_FILENAME,
   GLOBAL_LOGGING_DIR_NAME,
   HACK_PROJECT_DIR_PRIMARY,
+  PROJECT_ENV_CONTRACT_FILENAME,
 } from "../constants.ts";
 import { resolveGatewayConfig } from "../control-plane/extensions/gateway/config.ts";
 import { listGatewayTokens } from "../control-plane/extensions/gateway/tokens.ts";
@@ -42,6 +43,7 @@ import {
   writeTextFileIfChanged,
 } from "../lib/fs.ts";
 import { resolveHackInvocation } from "../lib/hack-cli.ts";
+import { resolveEnvFilePath } from "../lib/hack-env.ts";
 import {
   ensureBundledMutagenInstalled,
   getManagedMutagenAgentBundlePath,
@@ -351,6 +353,9 @@ const handleDoctor: CommandHandlerFor<typeof doctorSpec> = async ({
     results.push(
       await runCheck(s, "DEV_HOST", () => checkDevHost({ startDir }))
     );
+    results.push(
+      await runCheck(s, "env mode", () => checkProjectEnvMode({ startDir }))
+    );
     results.push(
       await runCheck(
         s,
@@ -373,6 +378,12 @@ const handleDoctor: CommandHandlerFor<typeof doctorSpec> = async ({
       message: `Skipped (no ${HACK_PROJECT_DIR_PRIMARY}/ found)`,
       durationMs: 0,
     });
+    results.push({
+      name: "env mode",
+      status: "warn",
+      message: `Skipped (no ${HACK_PROJECT_DIR_PRIMARY}/ found)`,
+      durationMs: 0,
+    });
     results.push({
       name: "tickets git",
       status: "warn",
@@ -1442,6 +1453,84 @@ async function checkProjectTicketsGitHealth({
   };
 }
 
+async function checkProjectEnvMode({
+  startDir,
+}: {
+  readonly startDir: string;
+}): Promise<CheckResult> {
+  const ctx = await findProjectContext(startDir);
+  if (!ctx) {
+    return {
+      name: "env mode",
+      status: "warn",
+      message: `Missing ${HACK_PROJECT_DIR_PRIMARY}/ (run 'hack init' in a repo)`,
+    };
+  }
+
+  const cfg = await readProjectConfig(ctx);
+  const configPath = cfg.configPath ?? ctx.configFile;
+  if (cfg.parseError) {
+    return {
+      name: "env mode",
+      status: "warn",
+      message: `Invalid ${configPath}: ${cfg.parseError}`,
+    };
+  }
+
+  const contractPath = resolve(ctx.projectDir, PROJECT_ENV_CONTRACT_FILENAME);
+  const contractExists = await pathExists(contractPath);
+  if (!contractExists) {
+    return {
+      name: "env mode",
+      status: "warn",
+      message: `Missing ${contractPath}`,
+    };
+  }
+
+  const controlPlane = await readControlPlaneConfig({
+    projectDir: ctx.projectDir,
+  });
+  if (controlPlane.parseError) {
+    return {
+      name: "env mode",
+      status: "warn",
+      message: controlPlane.parseError,
+    };
+  }
+
+  const storePlaintextInBackend =
+    controlPlane.config.secrets.storePlaintextInBackend;
+  if (!storePlaintextInBackend) {
+    return {
+      name: "env mode",
+      status: "warn",
+      message:
+        "Portable plaintext bundling is disabled. Legacy .hack/.env values stay machine-local until controlPlane.secrets.storePlaintextInBackend=true and values are re-saved with hack env set.",
+    };
+  }
+
+  if (!cfg.defaultEnvConfig) {
+    return {
+      name: "env mode",
+      status: "ok",
+      message: "Base env only (.hack/.env + bundled backend)",
+    };
+  }
+
+  const overlayPath = resolveEnvFilePath({
+    projectDir: ctx.projectDir,
+    envName: cfg.defaultEnvConfig,
+  });
+  const overlayExists = await pathExists(overlayPath);
+  return {
+    name: "env mode",
+    status: overlayExists ? "ok" : "warn",
+    message: overlayExists
+      ? `defaultEnvConfig=${cfg.defaultEnvConfig} overlays ${overlayPath} on top of .hack/.env`
+      : `defaultEnvConfig=${cfg.defaultEnvConfig} is set, but ${overlayPath} does not exist yet; base env will still apply`,
+  };
+}
+
 async function checkCaddyHostMapping({
   startDir,
 }: {

src/commands/env.ts

@@ -8,8 +8,7 @@ import {
   defineOption,
   withHandler,
 } from "../cli/command.ts";
-import { optJson, optPath, optProject } from "../cli/options.ts";
-import { PROJECT_ENV_FILENAME } from "../constants.ts";
+import { optEnv, optJson, optPath, optProject } from "../cli/options.ts";
 import { readControlPlaneConfig } from "../control-plane/sdk/config.ts";
 import { updateGlobalConfig } from "../lib/config.ts";
 import type {
@@ -19,13 +18,16 @@ import type {
 import {
   readHackEnvRuntimeConfig,
   removeDotEnvKey,
+  resolveEnvFilePath,
+  resolveEnvSecretKey,
   resolveHackEnv,
   upsertDotEnvValue,
 } from "../lib/hack-env.ts";
 import type { ProjectContext } from "../lib/project.ts";
 import {
   defaultProjectSlugFromPath,
   findProjectContext,
+  parseEnvConfigSelection,
   readProjectConfig,
   sanitizeProjectSlug,
 } from "../lib/project.ts";
@@ -56,7 +58,7 @@ const listSpec = defineCommand({
   name: "list",
   summary: "List env contract vars and resolution state",
   group: "Project",
-  options: [optPath, optProject, optJson, optShowSecrets],
+  options: [optPath, optProject, optEnv, optJson, optShowSecrets],
   positionals: [],
   subcommands: [],
 } as const);
@@ -65,7 +67,7 @@ const setSpec = defineCommand({
   name: "set",
   summary: "Set an env value (.hack/.env or keychain)",
   group: "Project",
-  options: [optPath, optProject, optSecret],
+  options: [optPath, optProject, optEnv, optSecret],
   positionals: [{ name: "spec", required: false }],
   subcommands: [],
 } as const);
@@ -74,7 +76,7 @@ const unsetSpec = defineCommand({
   name: "unset",
   summary: "Unset an env value (.hack/.env and keychain)",
   group: "Project",
-  options: [optPath, optProject],
+  options: [optPath, optProject, optEnv],
   positionals: [{ name: "key", required: false }],
   subcommands: [],
 } as const);
@@ -403,6 +405,16 @@ async function resolveProjectName(project: ProjectContext): Promise<string> {
   return sanitizeProjectSlug(raw.length > 0 ? raw : derived);
 }
 
+function resolveRequestedEnvName(input: {
+  readonly envOption: string | undefined;
+}): string | null | undefined {
+  const envName = parseEnvConfigSelection(input.envOption);
+  if (input.envOption !== undefined && envName === undefined) {
+    throw new CliUsageError("Invalid --env value.");
+  }
+  return envName;
+}
+
 async function resolveConfiguredSecretStore(input: {
   readonly project: ProjectContext;
   readonly projectName: string;
@@ -433,17 +445,28 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
   const projectName = await resolveProjectName(project);
   const showSecrets = args.options.showSecrets === true;
   const json = args.options.json === true;
+  const envName = resolveRequestedEnvName({
+    envOption: args.options.env,
+  });
 
   const resolved = await resolveHackEnv({
     projectDir: project.projectDir,
     projectName,
+    envName,
   });
 
   if (json) {
     process.stdout.write(
       `${JSON.stringify(
         {
           project: projectName,
+          env_selection: {
+            requested: resolved.envSelection.requestedEnv,
+            default: resolved.envSelection.defaultEnv,
+            effective: resolved.envSelection.effectiveEnv,
+            overlay_path: resolved.envSelection.overlayPath,
+            overlay_exists: resolved.envSelection.overlayExists,
+          },
           storage: serializeEnvStorageForJson({ storage: resolved.storage }),
           vars: resolved.values.map((v) => ({
             key: v.key,
@@ -472,6 +495,12 @@ const handleEnvList: CommandHandlerFor<typeof listSpec> = async ({
   await display.kv({
     title: "Env storage",
     entries: [
+      [
+        "env_selection",
+        resolved.envSelection.effectiveEnv
+          ? `${resolved.envSelection.effectiveEnv} (base .hack/.env overlaid by ${resolved.envSelection.overlayPath})`
+          : "base (.hack/.env only)",
+      ],
       [
         "contract",
         `${resolved.storage.contract.path} (committed metadata only; no values are stored here)`,
@@ -597,6 +626,9 @@ const handleEnvSet: CommandHandlerFor<typeof setSpec> = async ({
   const runtimeConfig = await readHackEnvRuntimeConfig({
     projectDir: project.projectDir,
   });
+  const envName = resolveRequestedEnvName({
+    envOption: args.options.env,
+  });
 
   const spec = (args.positionals.spec ?? "").trim();
   const [keyFromSpec, valueFromSpec] = parseKeyValueSpec(spec);
@@ -610,20 +642,29 @@ const handleEnvSet: CommandHandlerFor<typeof setSpec> = async ({
 
   if (storeSecret) {
     const store = await resolveConfiguredSecretStore({ project, projectName });
-    await store.set({ key, value });
+    await store.set({
+      key: resolveEnvSecretKey({ key, envName }),
+      value,
+    });
     logger.success({
-      message: `Stored secret "${key}" in ${formatSecretStoreDescriptor({ descriptor: store.descriptor })}`,
+      message: `Stored secret "${key}" in ${formatSecretStoreDescriptor({ descriptor: store.descriptor })}${envName ? ` (env ${envName})` : ""}`,
     });
     return 0;
   }
 
-  const envFile = resolve(project.projectDir, PROJECT_ENV_FILENAME);
+  const envFile = resolveEnvFilePath({
+    projectDir: project.projectDir,
+    envName,
+  });
   const [result, mirroredToBackend] = await Promise.all([
     upsertDotEnvValue({ envFile, key, value }),
     runtimeConfig.storePlaintextInBackend
       ? resolveConfiguredSecretStore({ project, projectName }).then(
           async (store) => {
-            await store.set({ key, value });
+            await store.set({
+              key: resolveEnvSecretKey({ key, envName }),
+              value,
+            });
             return formatSecretStoreDescriptor({
               descriptor: store.descriptor,
             });
@@ -655,11 +696,14 @@ const handleEnvUnset: CommandHandlerFor<typeof unsetSpec> = async ({
   });
   const projectName = await resolveProjectName(project);
   const store = await resolveConfiguredSecretStore({ project, projectName });
+  const envName = resolveRequestedEnvName({
+    envOption: args.options.env,
+  });
 
   const key = await resolveEnvKey({ key: (args.positionals.key ?? "").trim() });
 
   const ok = await confirm({
-    message: `Unset "${key}" from ${project.projectDir}/.env and ${formatSecretStoreDescriptor({ descriptor: store.descriptor })}?`,
+    message: `Unset "${key}" from ${resolveEnvFilePath({ projectDir: project.projectDir, envName })} and ${formatSecretStoreDescriptor({ descriptor: store.descriptor })}${envName ? ` (env ${envName})` : ""}?`,
     initialValue: true,
   });
   if (isCancel(ok)) {
@@ -669,10 +713,15 @@ const handleEnvUnset: CommandHandlerFor<typeof unsetSpec> = async ({
     return 0;
   }
 
-  const envFile = resolve(project.projectDir, PROJECT_ENV_FILENAME);
+  const envFile = resolveEnvFilePath({
+    projectDir: project.projectDir,
+    envName,
+  });
   const [dotenvResult, secretDeleted] = await Promise.all([
     removeDotEnvKey({ envFile, key }),
-    store.delete({ key }),
+    store.delete({
+      key: resolveEnvSecretKey({ key, envName }),
+    }),
   ]);
 
   logger.success({