@penvhq/cli 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,13 +1,15 @@
 // src/index.ts
 import { setKeychain } from "@penvhq/core";
-import { runMain as cittyRunMain, defineCommand as defineCommand18 } from "citty";
+import { runMain as cittyRunMain, defineCommand as defineCommand19 } from "citty";
 
 // src/commands/doctor.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
 import {
   accessPath as accessPath3,
   assertNever,
   effectiveMeta,
-  formatValueFile as formatValueFile2,
+  formatValueFile as formatValueFile3,
   holdsProjection as holdsProjection3,
   holdsRecords,
   isPublicVariable,
@@ -81,7 +83,8 @@ function environmentFromShorthand(config, candidates, explicit) {
 }
 
 // src/project.ts
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { existsSync, readFileSync } from "fs";
+import { dirname as dirname2, join, resolve as resolve2 } from "path";
 import {
   candidatesFor,
   formatValueFile,
@@ -94,7 +97,9 @@ import {
   ReservedTokenError,
   refFromAccessPath,
   resolveEnvironment,
-  resolveKeySource
+  resolveKeySource,
+  SCHEMA_SHAPE_FILE,
+  schemaFileOf
 } from "@penvhq/core";
 import { FilesystemProvider } from "@penvhq/provider-filesystem";
 
@@ -248,6 +253,18 @@ function localTree(project) {
   }
   return project.provider;
 }
+function selfContainedSchemaModule(root, schemaFile) {
+  const file = join(root, ...schemaFile.split("/"));
+  if (!existsSync(file)) {
+    return void 0;
+  }
+  const source = readFileSync(file, "utf8");
+  return source.includes("PenvSchemaShape") || source.includes("z.object") ? schemaFile : void 0;
+}
+function schemaShapeFileOf(project) {
+  const schemaFile = schemaFileOf(project.config);
+  return selfContainedSchemaModule(project.root, schemaFile) ?? SCHEMA_SHAPE_FILE;
+}
 async function sourceProviderFor(project, environment) {
   const providerConfig = project.config.providers[environment];
   if (providerConfig === void 0) {
@@ -479,7 +496,7 @@ function hasValue(resolution) {
   return resolution.winner !== void 0;
 }
 function computeDrift(input) {
-  const { schema, resolutions, config, environment } = input;
+  const { schema, resolutions, config, environment, schemaShapeFile } = input;
   const valued = new Set(resolutions.filter(hasValue).map((resolution) => resolution.parameter));
   const declared = [];
   const optional = [];
@@ -489,7 +506,7 @@ function computeDrift(input) {
     }
     const path = leaf.path.join(".");
     const ref = refFromAccessPath2(leaf.path);
-    const renameRemedy = `Rename the \`${path}\` key in .penv/env.ts \u2014 a parameter name is lower-case, hyphenated, and never a reserved token, so no value file reaches this key.`;
+    const renameRemedy = `Rename the \`${path}\` key in ${schemaShapeFile} \u2014 a parameter name is lower-case, hyphenated, and never a reserved token, so no value file reaches this key.`;
     if (ref === void 0 || isReservedToken2(ref.name, config)) {
       if (leaf.absencePermitted) {
         optional.push({ subject: path, remedy: renameRemedy });
@@ -519,7 +536,7 @@ function computeDrift(input) {
       subject: parameterId2(ref),
       ref,
       remedy: `penv set ${[...ref.namespace, ref.name].join("/")} --env ${environment}`,
-      detail: `declared in .penv/env.ts, no value for ${environment}`
+      detail: `declared in ${schemaShapeFile}, no value for ${environment}`
     });
   }
   const undeclared = [];
@@ -535,6 +552,133 @@ function computeDrift(input) {
   return { declared, undeclared, optional };
 }
 
+// src/snapshot.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join2 } from "path";
+import { formatValueFile as formatValueFile2, schemaFileOf as schemaFileOf2 } from "@penvhq/core";
+import { createFilesystemProvider as createFilesystemProvider2 } from "@penvhq/provider-filesystem";
+var SNAPSHOT_FILE = "penv.snapshot.ts";
+function sealedValues(tree) {
+  const collected = {};
+  for (const file of tree.listSync()) {
+    if (!file.encrypted) {
+      continue;
+    }
+    if (file.scope.kind === "local" || file.scope.kind === "environment-local") {
+      continue;
+    }
+    const stored = tree.readSync(file);
+    if (stored === void 0) {
+      continue;
+    }
+    collected[formatValueFile2(file)] = stored;
+  }
+  const values = {};
+  for (const key of Object.keys(collected).sort()) {
+    values[key] = collected[key];
+  }
+  return values;
+}
+function buildSnapshotFrom(root, config) {
+  const tree = createFilesystemProvider2({ root: join2(root, PENV_DIR), config });
+  return { v: 1, config, values: sealedValues(tree) };
+}
+function buildSnapshot(project) {
+  return { v: 1, config: project.config, values: sealedValues(localTree(project)) };
+}
+function renderSnapshotModule(snapshot) {
+  const body = JSON.stringify(snapshot, null, 2);
+  return `// penv.snapshot.ts \u2014 GENERATED by penv. Do not edit; run \`penv snapshot\` to refresh.
+// It embeds the evaluated config and every committed sealed (.enc) value, so \`load()\`
+// resolves in a bundled or serverless runtime where no penv.config.ts is on disk.
+import type { PenvSnapshot } from "@penvhq/penv";
+
+export const snapshot = ${body} satisfies PenvSnapshot;
+`;
+}
+function equalsIgnoringEol(a, b) {
+  return a.replace(/\r\n/g, "\n") === b.replace(/\r\n/g, "\n");
+}
+function writeSnapshotFile(project) {
+  const path = join2(project.root, SNAPSHOT_FILE);
+  const wanted = renderSnapshotModule(buildSnapshot(project));
+  const existing = existsSync2(path) ? readFileSync2(path, "utf8") : void 0;
+  if (existing !== void 0 && equalsIgnoringEol(existing, wanted)) {
+    return { file: SNAPSHOT_FILE, action: "unchanged" };
+  }
+  writeFileSync(path, wanted, "utf8");
+  return { file: SNAPSHOT_FILE, action: existing === void 0 ? "created" : "updated" };
+}
+function snapshotExists(root) {
+  return existsSync2(join2(root, SNAPSHOT_FILE));
+}
+function refreshSnapshot(project) {
+  if (snapshotExists(project.root)) {
+    writeSnapshotFile(project);
+  }
+}
+function snapshotSpecifier(schemaFile) {
+  const depth = schemaFile.split("/").length - 1;
+  const climb = depth === 0 ? "./" : "../".repeat(depth);
+  return `${climb}penv.snapshot.js`;
+}
+function insertSnapshotImport(source, importLine) {
+  const afterSchema = /^import\s*\{\s*schema\s*\}\s*from\s*["'][^"']*penv\.schema\.js["'];?[ \t]*\r?\n/m;
+  const schemaMatch = afterSchema.exec(source);
+  if (schemaMatch !== null) {
+    const index = schemaMatch.index + schemaMatch[0].length;
+    return `${source.slice(0, index)}${importLine}
+${source.slice(index)}`;
+  }
+  const afterLoad = /^import\s*\{[^}]*\}\s*from\s*["']@penvhq\/penv["'];?[ \t]*\r?\n/m;
+  const loadMatch = afterLoad.exec(source);
+  if (loadMatch !== null) {
+    const index = loadMatch.index + loadMatch[0].length;
+    return `${source.slice(0, index)}${importLine}
+${source.slice(index)}`;
+  }
+  return `${importLine}
+${source}`;
+}
+function wireEnvModule(project) {
+  const schemaFile = schemaFileOf2(project.config);
+  const specifier = snapshotSpecifier(schemaFile);
+  const importLine = `import { snapshot } from "${specifier}";`;
+  const loadHint = "pass it to load: `load(schema, { snapshot })`";
+  const manual = { file: schemaFile, action: "manual", importLine, loadHint };
+  const path = join2(project.root, ...schemaFile.split("/"));
+  if (!existsSync2(path)) {
+    return manual;
+  }
+  const source = readFileSync2(path, "utf8");
+  const loadCall = /load\(\s*schema\s*(\)|,\s*\{([\s\S]*?)\}\s*\))/;
+  const match = loadCall.exec(source);
+  if (match === null) {
+    return manual;
+  }
+  const options = match[2];
+  const snapshotProperty = /(?:^|[,{\s])snapshot\s*(?=[,:}]|$)/;
+  const snapshotInOptions = options !== void 0 && snapshotProperty.test(options);
+  const importPresent = source.includes(importLine);
+  if (snapshotInOptions && importPresent) {
+    return { file: schemaFile, action: "kept", importLine, loadHint };
+  }
+  let updated = source;
+  if (!snapshotInOptions) {
+    const trimmed = (options ?? "").trim();
+    const replacement = match[1] === ")" || trimmed.length === 0 ? "load(schema, { snapshot })" : `load(schema, { ${trimmed}, snapshot })`;
+    updated = updated.replace(loadCall, replacement);
+  }
+  if (!importPresent) {
+    updated = insertSnapshotImport(updated, importLine);
+  }
+  if (updated === source) {
+    return { file: schemaFile, action: "kept", importLine, loadHint };
+  }
+  writeFileSync(path, updated, "utf8");
+  return { file: schemaFile, action: "wired", importLine, loadHint };
+}
+
 // src/style.ts
 function supportsColor(stream) {
   const env = process.env;
@@ -1077,7 +1221,7 @@ import {
   ReservedTokenError as ReservedTokenError2,
   resolveAll,
   SCHEMA_HARVEST_ENV,
-  schemaFileOf,
+  schemaFileOf as schemaFileOf3,
   validateConfig
 } from "@penvhq/core";
 import { defineCommand as defineCommand2 } from "citty";
@@ -1126,7 +1270,7 @@ function place(root, path, value) {
 function isZodType(value) {
   return typeof value === "object" && value !== null && "safeParse" in value && typeof value.safeParse === "function";
 }
-function validationIssuesOf(cause, schemaPath) {
+function validationIssuesOf(cause, schemaPath, schemaShapeFile) {
   if (typeof cause !== "object" || cause === null) {
     return void 0;
   }
@@ -1140,7 +1284,10 @@ function validationIssuesOf(cause, schemaPath) {
       kind: "schema",
       subject: typeof parameter === "string" && parameter !== "" ? parameter : schemaPath,
       message: typeof message === "string" ? message : String(issue),
-      remedy: `Fix the value, or adjust the schema in ${schemaPath} if the shape is wrong.`
+      // `schemaPath` is the loader penv evaluated; the shape to adjust lives in
+      // `schemaShapeFile`, which is that same file for an old-layout project and
+      // `penv.schema.ts` for one on the split.
+      remedy: `Fix the value, or adjust the schema in ${schemaShapeFile} if the shape is wrong.`
     };
   });
 }
@@ -1154,11 +1301,12 @@ function exclusively(work) {
   return result2;
 }
 function loadSchema(project, environment) {
-  const schemaPath = schemaFileOf(project.config);
+  const schemaPath = schemaFileOf3(project.config);
+  const schemaShapeFile = schemaShapeFileOf(project);
   const file = pathToFileURL2(resolvePath(project.root, schemaPath)).href;
-  return exclusively(() => loadSchemaExclusively(file, schemaPath, environment));
+  return exclusively(() => loadSchemaExclusively(file, schemaPath, schemaShapeFile, environment));
 }
-async function loadSchemaExclusively(file, schemaPath, environment) {
+async function loadSchemaExclusively(file, schemaPath, schemaShapeFile, environment) {
   const jiti = jitiFor(file);
   const previous = process.env.PENV_ENV;
   const previousHarvest = process.env[SCHEMA_HARVEST_ENV];
@@ -1168,7 +1316,7 @@ async function loadSchemaExclusively(file, schemaPath, environment) {
   try {
     loaded = await jiti.import(file);
   } catch (cause) {
-    const issues = validationIssuesOf(cause, schemaPath);
+    const issues = validationIssuesOf(cause, schemaPath, schemaShapeFile);
     if (issues !== void 0) {
       return { issues };
     }
@@ -1213,7 +1361,8 @@ async function loadSchemaExclusively(file, schemaPath, environment) {
 async function runValidate(options) {
   const project = openProject(options.cwd);
   const environment = targetEnvironment(project, options.environment, options.envFlags);
-  const schemaPath = schemaFileOf(project.config);
+  const schemaPath = schemaFileOf3(project.config);
+  const schemaShapeFile = schemaShapeFileOf(project);
   const issues = [];
   let files;
   try {
@@ -1263,7 +1412,13 @@ async function runValidate(options) {
         place(object, accessPath2(resolution.ref), resolution.value);
       }
     }
-    drift = computeDrift({ schema, resolutions, config: project.config, environment });
+    drift = computeDrift({
+      schema,
+      resolutions,
+      config: project.config,
+      environment,
+      schemaShapeFile
+    });
     const result2 = schema.safeParse(object);
     if (!result2.success) {
       for (const problem of result2.error.issues) {
@@ -1275,7 +1430,7 @@ async function runValidate(options) {
           kind: "schema",
           subject: path || schemaPath,
           message: problem.message,
-          remedy: `Fix the value, or adjust the schema in ${schemaPath} if the shape is wrong.`
+          remedy: `Fix the value, or adjust the schema in ${schemaShapeFile} if the shape is wrong.`
         });
       }
     }
@@ -1398,13 +1553,15 @@ async function runDoctor(options) {
       skipped("unused", "Value coverage")
     );
   } else {
+    const schemaShapeFile = schemaShapeFileOf(project);
     const drift = computeDrift({
       schema,
       resolutions: subjects.map(({ resolution }) => resolution),
       config: project.config,
-      environment
+      environment,
+      schemaShapeFile
     });
-    findings.push(...declaredFindings(drift, missing, environment));
+    findings.push(...declaredFindings(drift, missing, environment, schemaShapeFile));
     findings.push(...weakFindings(subjects, schema));
     findings.push(...unusedFindings(drift));
   }
@@ -1420,6 +1577,8 @@ async function runDoctor(options) {
     findings.push(...stuckFindings(rotation.subjects, environment, now, stuckThresholdMs));
   }
   findings.push(...await providerDriftFindings(project, environment, options.source));
+  findings.push(...snapshotStaleFindings(project));
+  findings.push(...bundleInvisibleFindings(project, subjects, environment));
   findings.push(...await projectionFindings(project, environment, options.projection));
   findings.push({
     check: "provider",
@@ -1455,7 +1614,7 @@ function missingFindings(subjects, environment) {
     }
   ];
 }
-function declaredFindings(drift, missing, environment) {
+function declaredFindings(drift, missing, environment, schemaShapeFile) {
   const reported = new Set(missing.filter((f) => f.severity !== "pass").map((f) => f.subject));
   const findings = drift.declared.filter((item) => !reported.has(item.subject)).map((item) => ({
     check: "declared",
@@ -1473,7 +1632,7 @@ function declaredFindings(drift, missing, environment) {
       check: "declared",
       severity: "pass",
       label: "Schema coverage",
-      subject: `every parameter .penv/env.ts requires has a value for ${environment}`
+      subject: `every parameter ${schemaShapeFile} requires has a value for ${environment}`
     }
   ];
 }
@@ -2045,7 +2204,7 @@ async function providerDriftFindings(project, environment, override) {
           check: "provider-value-drift",
           severity: "unknown",
           label: "Provider value unreadable",
-          subject: formatValueFile2(here.file),
+          subject: formatValueFile3(here.file),
           detail: `the local value is sealed and did not open, so it cannot be compared against the ${providerConfig.type} source of truth`
         });
         continue;
@@ -2055,7 +2214,7 @@ async function providerDriftFindings(project, environment, override) {
           check: "provider-value-drift",
           severity: "failure",
           label: "Provider value drift",
-          subject: formatValueFile2(here.file),
+          subject: formatValueFile3(here.file),
           detail: `the local tree and the ${providerConfig.type} source of truth hold different values`
         });
       }
@@ -2069,7 +2228,7 @@ async function providerDriftFindings(project, environment, override) {
       check: "provider-value-drift",
       severity: "warning",
       label: here !== void 0 ? "Only in the local tree" : "Only in the source",
-      subject: formatValueFile2(present.file),
+      subject: formatValueFile3(present.file),
       detail: here !== void 0 ? `present locally, absent from the ${providerConfig.type} source of truth` : `present in the ${providerConfig.type} source of truth, absent from the local tree`
     });
   }
@@ -2085,6 +2244,68 @@ async function providerDriftFindings(project, environment, override) {
     }
   ];
 }
+function snapshotStaleFindings(project) {
+  if (!snapshotExists(project.root)) {
+    return [];
+  }
+  const wanted = renderSnapshotModule(buildSnapshot(project));
+  const committed = readFileSync3(join3(project.root, SNAPSHOT_FILE), "utf8");
+  if (equalsIgnoringEol(committed, wanted)) {
+    return [
+      {
+        check: "snapshot-stale",
+        severity: "pass",
+        label: "Snapshot",
+        subject: `${SNAPSHOT_FILE} matches the committed sealed values and config`
+      }
+    ];
+  }
+  return [
+    {
+      check: "snapshot-stale",
+      severity: "failure",
+      label: "Snapshot stale",
+      subject: SNAPSHOT_FILE,
+      detail: "does not match the current sealed values or config, so a bundle resolves stale data",
+      remedy: "penv snapshot"
+    }
+  ];
+}
+function bundleInvisibleFindings(project, subjects, environment) {
+  if (!snapshotExists(project.root)) {
+    return [];
+  }
+  const findings = [];
+  for (const { resolution } of subjects) {
+    const winner = resolution.winner;
+    if (winner === void 0 || winner.file.encrypted) {
+      continue;
+    }
+    const scope = winner.file.scope;
+    if (scope.kind === "local" || scope.kind === "environment-local") {
+      continue;
+    }
+    findings.push({
+      check: "bundle-invisible-plaintext",
+      severity: "warning",
+      label: "Invisible to bundles",
+      subject: winner.location,
+      detail: "plaintext is gitignored and not embedded in the snapshot, so a bundle cannot see it",
+      remedy: `penv encrypt ${refPathOf(resolution.ref)} --env ${environment}`
+    });
+  }
+  if (findings.length > 0) {
+    return findings;
+  }
+  return [
+    {
+      check: "bundle-invisible-plaintext",
+      severity: "pass",
+      label: "Bundle coverage",
+      subject: `every value resolving for ${environment} is embeddable in ${SNAPSHOT_FILE}`
+    }
+  ];
+}
 var GLYPHS = {
   pass: CHECK,
   warning: WARN,
@@ -2157,7 +2378,7 @@ var doctorCommand = defineCommand3({
 
 // src/commands/encrypt.ts
 import {
-  formatValueFile as formatValueFile4,
+  formatValueFile as formatValueFile5,
   isSecret as isSecret3,
   openValue as openValue3,
   PenvError as PenvError8,
@@ -2167,7 +2388,7 @@ import {
 import { defineCommand as defineCommand5 } from "citty";
 
 // src/commands/set.ts
-import { formatValueFile as formatValueFile3, isSecret as isSecret2, PenvError as PenvError7, parameterId as parameterId3, sealValue } from "@penvhq/core";
+import { formatValueFile as formatValueFile4, isSecret as isSecret2, PenvError as PenvError7, parameterId as parameterId3, sealValue } from "@penvhq/core";
 import { defineCommand as defineCommand4 } from "citty";
 function scopeFrom(options) {
   if (options.local === true) {
@@ -2202,7 +2423,7 @@ function sealFor(project, file, value, parameter, environment) {
   if (environment === void 0) {
     throw new PenvError7(
       "SECRET_SCOPE_AMBIGUOUS",
-      `Parameter ${parameter} is a secret, and ${PENV_DIR}/${formatValueFile3(file)} names no environment`,
+      `Parameter ${parameter} is a secret, and ${PENV_DIR}/${formatValueFile4(file)} names no environment`,
       "Keys are declared per environment in the `keys` block of penv.config.ts, so penv cannot tell which key should seal a file that every environment reads. Write it at an environment scope \u2014 add `--env <environment>` \u2014 or drop `secret` from the parameter's meta."
     );
   }
@@ -2220,7 +2441,7 @@ async function sealAwareWrite(options) {
   const stored = secret ? sealFor(project, file, value, parameterId3(ref), environment) : value;
   await provider.write(file, stored);
   await provider.remove({ ...file, encrypted: !secret });
-  return { encrypted: secret, location: formatValueFile3(file) };
+  return { encrypted: secret, location: formatValueFile4(file) };
 }
 async function runSet(options) {
   const project = openProject(options.cwd);
@@ -2236,6 +2457,7 @@ async function runSet(options) {
     value: options.value,
     environment
   });
+  refreshSnapshot(project);
   return { parameter: options.key, location, encrypted };
 }
 function renderSet(result2) {
@@ -2323,17 +2545,18 @@ async function runEncrypt(options) {
     const already = await readOne(project, sealed);
     throw new PenvError8(
       "PARAMETER_ABSENT",
-      already === void 0 ? `Parameter ${parameter} has no value file at ${PENV_DIR}/${formatValueFile4(plain)}` : `Parameter ${parameter} is already encrypted at ${PENV_DIR}/${formatValueFile4(sealed)}`,
+      already === void 0 ? `Parameter ${parameter} has no value file at ${PENV_DIR}/${formatValueFile5(plain)}` : `Parameter ${parameter} is already encrypted at ${PENV_DIR}/${formatValueFile5(sealed)}`,
       already === void 0 ? `Write it first with \`penv set ${options.key} --env ${environment}\`, which seals it automatically when the parameter's meta declares it a secret.` : "Nothing to do."
     );
   }
   const text = sealValue2(sealed, value, keySourceFor(project, environment), parameter, environment);
   await project.provider.write(sealed, text);
   await project.provider.remove(plain);
+  refreshSnapshot(project);
   return {
     parameter,
-    location: formatValueFile4(sealed),
-    removed: formatValueFile4(plain)
+    location: formatValueFile5(sealed),
+    removed: formatValueFile5(plain)
   };
 }
 async function runDecrypt(options) {
@@ -2352,7 +2575,7 @@ async function runDecrypt(options) {
   if (stored === void 0) {
     throw new PenvError8(
       "PARAMETER_ABSENT",
-      `Parameter ${parameter} has no encrypted value file at ${PENV_DIR}/${formatValueFile4(sealed)}`,
+      `Parameter ${parameter} has no encrypted value file at ${PENV_DIR}/${formatValueFile5(sealed)}`,
       `Nothing to decrypt. \`penv get ${options.key} --env ${environment} --explain\` shows every file penv looked at.`
     );
   }
@@ -2361,16 +2584,17 @@ async function runDecrypt(options) {
     throw new UndecryptableAt(
       parameter,
       environment,
-      formatValueFile4(sealed),
+      formatValueFile5(sealed),
       opened.failure.detail
     );
   }
   await project.provider.write(plain, opened.value);
   await project.provider.remove(sealed);
+  refreshSnapshot(project);
   return {
     parameter,
-    location: formatValueFile4(plain),
-    removed: formatValueFile4(sealed)
+    location: formatValueFile5(plain),
+    removed: formatValueFile5(sealed)
   };
 }
 var UndecryptableAt = class extends PenvError8 {
@@ -2578,7 +2802,7 @@ var fillCommand = defineCommand6({
 });
 
 // src/commands/generate.ts
-import { writeFileSync } from "fs";
+import { writeFileSync as writeFileSync2 } from "fs";
 import { isAbsolute, relative, resolve as resolve3 } from "path";
 import {
   checkNameCollisions as checkNameCollisions3,
@@ -2639,7 +2863,7 @@ function runGenerate(options) {
   const environment = targetEnvironment(project, options.environment, options.envFlags);
   const { entries, decrypted } = entriesFor(project, environment, options.allowDecrypt === true);
   const file = options.out === void 0 ? resolve3(project.root, DEFAULT_OUTPUT) : isAbsolute(options.out) ? options.out : resolve3(options.cwd, options.out);
-  writeFileSync(file, serializeDotenv(entries), "utf8");
+  writeFileSync2(file, serializeDotenv(entries), "utf8");
   return { file, environment, entries: entries.length, decrypted };
 }
 function displayPath(cwd, file) {
@@ -2777,7 +3001,7 @@ var getCommand = defineCommand8({
 });
 
 // src/commands/import.ts
-import { copyFileSync, existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { copyFileSync, existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
 import { basename, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve5 } from "path";
 import {
   accessPath as accessPath4,
@@ -2793,15 +3017,15 @@ import {
   ReservedTokenError as ReservedTokenError3,
   refFromVariable,
   roundTripsCleanly,
-  schemaFileOf as schemaFileOf3,
+  schemaFileOf as schemaFileOf5,
   UnknownEnvironmentError,
   variableName as variableName5
 } from "@penvhq/core";
 import { defineCommand as defineCommand10 } from "citty";
 
 // src/detect.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 import { DEFAULT_SCHEMA_FILE } from "@penvhq/core";
 var SIGNATURES = [
   { name: "Next.js", packages: ["next"], publicPrefixes: ["NEXT_PUBLIC_"] },
@@ -2818,7 +3042,7 @@ var SIGNATURES = [
 function exportsSchema(file) {
   let source;
   try {
-    source = readFileSync(file, "utf8");
+    source = readFileSync4(file, "utf8");
   } catch {
     return false;
   }
@@ -2829,11 +3053,11 @@ function exportsSchema(file) {
   );
 }
 function occupied(cwd, relative3) {
-  const file = join(cwd, ...relative3.split("/"));
-  return existsSync(file) && !exportsSchema(file);
+  const file = join4(cwd, ...relative3.split("/"));
+  return existsSync3(file) && !exportsSchema(file);
 }
 function schemaFileFor(cwd) {
-  const dir = existsSync(join(cwd, "src")) ? "src/" : "";
+  const dir = srcPrefix(cwd);
   const preferred = `${dir}env.ts`;
   if (!occupied(cwd, preferred)) {
     return { file: preferred };
@@ -2844,6 +3068,9 @@ function schemaFileFor(cwd) {
   }
   return { file: DEFAULT_SCHEMA_FILE, displaced: preferred };
 }
+function srcPrefix(cwd) {
+  return existsSync3(join4(cwd, "src")) ? "src/" : "";
+}
 function dependenciesOf(cwd) {
   const manifest = manifestOf(cwd);
   if (manifest === void 0) {
@@ -2861,13 +3088,13 @@ function dependenciesOf(cwd) {
   return names;
 }
 function manifestOf(cwd) {
-  const file = join(cwd, "package.json");
-  if (!existsSync(file)) {
+  const file = join4(cwd, "package.json");
+  if (!existsSync3(file)) {
     return void 0;
   }
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync(file, "utf8"));
+    manifest = JSON.parse(readFileSync4(file, "utf8"));
   } catch {
     return void 0;
   }
@@ -2883,7 +3110,7 @@ function detectFramework(cwd) {
       return detectedFrom(cwd, signature.name, signature.publicPrefixes);
     }
   }
-  if (existsSync(join(cwd, "bunfig.toml")) || dependencies.has("bun-types")) {
+  if (existsSync3(join4(cwd, "bunfig.toml")) || dependencies.has("bun-types")) {
     return detectedFrom(cwd, "Bun", []);
   }
   return void 0;
@@ -2909,8 +3136,8 @@ function hasImportsBlock(cwd) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join2, resolve as resolve4 } from "path";
+import { existsSync as existsSync4, mkdirSync, readdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join5, resolve as resolve4 } from "path";
 import { createInterface as createInterface2 } from "readline/promises";
 import {
   DEFAULT_SCHEMA_FILE as DEFAULT_SCHEMA_FILE2,
@@ -2918,7 +3145,8 @@ import {
   loadConfigFrom,
   PenvError as PenvError12,
   RESERVED_TOKENS,
-  schemaFileOf as schemaFileOf2,
+  SCHEMA_SHAPE_FILE as SCHEMA_SHAPE_FILE2,
+  schemaFileOf as schemaFileOf4,
   schemaInsideTree,
   validateSchemaFile
 } from "@penvhq/core";
@@ -2990,19 +3218,25 @@ function bun({ alias }) {
     kind: "scaffold",
     file: ".penv/preload.ts",
     content: `// Bun evaluates this file before your entry point, because it is listed under
-// \`preload\` in bunfig.toml (see the note penv printed). Running it injects your
-// config into process.env before any library reads it.
+// \`preload\` in bunfig.toml. Running it injects your config into process.env
+// before any library reads it.
 import "${alias}";
 `,
     ifPresent: `Keep .penv/preload.ts as \`import "${alias}";\`.`,
-    notes: [
-      'Register it in bunfig.toml so Bun runs it: `preload = ["./.penv/preload.ts"]` (and the same under `[test]`).',
-      `\`${alias}\` must be a tsconfig \`paths\` alias for Bun to resolve it.`
-    ]
+    notes: [`\`${alias}\` must be a tsconfig \`paths\` alias for Bun to resolve it.`],
+    // The preload file is inert until bunfig.toml points at it — so penv writes
+    // that too, both for the runtime and for `bun test`. Only when there is no
+    // bunfig to overwrite; an existing one is the user's, and penv prints instead.
+    also: {
+      file: "bunfig.toml",
+      content: 'preload = ["./.penv/preload.ts"]\n\n[test]\npreload = ["./.penv/preload.ts"]\n',
+      ifPresent: 'Add "./.penv/preload.ts" to the `preload` array in bunfig.toml \u2014 and mirror it under `[test]` so `bun test` injects too.'
+    }
   };
 }
-function node({ alias, srcDir }) {
-  const runtimeSpecifier = alias.startsWith("#") ? alias : `./${srcDir}.penv/env.js`;
+function node({ alias, schemaFile }) {
+  const builtSchema = `./${schemaFile.replace(/\.ts$/, ".js")}`;
+  const runtimeSpecifier = alias.startsWith("#") ? alias : builtSchema;
   return {
     kind: "instruct",
     instruction: `Plain Node / Express / Fastify have no framework hook that runs before your
@@ -3022,10 +3256,17 @@ import before it. If you have no server.ts yet, create it from TanStack's server
 template and put that import first.`
   };
 }
-function astro(_context) {
+function astro({ alias }) {
   return {
     kind: "instruct",
-    instruction: 'Astro has no single pre-app hook. Add a small integration to astro.config that\ninjects the import into every SSR page, then cover the routes it cannot reach:\n  \u2022 In astro.config integrations, add:\n      { name: "penv", hooks: { "astro:config:setup": ({ injectScript }) =>\n          injectScript("page-ssr", \'import "@env";\') } }\n  \u2022 Also add `import "@env";` as the first line of src/middleware.ts and of any\n    endpoint route (src/pages/*.ts) that imports a library reading process.env.\nInjection only applies under a server (on-demand) adapter, not a static build.'
+    instruction: `Astro has no single pre-app hook. Add a small integration to astro.config that
+injects the import into every SSR page, then cover the routes it cannot reach:
+  \u2022 In astro.config integrations, add:
+      { name: "penv", hooks: { "astro:config:setup": ({ injectScript }) =>
+          injectScript("page-ssr", 'import "${alias}";') } }
+  \u2022 Also add \`import "${alias}";\` as the first line of src/middleware.ts and of any
+    endpoint route (src/pages/*.ts) that imports a library reading process.env.
+Injection only applies under a server (on-demand) adapter, not a static build.`
   };
 }
 function viteSpa(_context) {
@@ -3049,6 +3290,7 @@ function seamFor(framework, context) {
 }
 
 // src/commands/init.ts
+var SCHEMA_SHAPE_BASENAME = "penv.schema";
 var CONFIG_FILE = "penv.config.ts";
 var TSCONFIG_FILE = "tsconfig.json";
 var GITIGNORE_FILE = ".gitignore";
@@ -3111,8 +3353,8 @@ function configOf(decisions) {
   return { environments: decisions.environments, providers: {}, schemaFile: decisions.schemaFile };
 }
 function declaredIn(root) {
-  const file = join2(root, CONFIG_FILE);
-  if (!existsSync2(file)) {
+  const file = join5(root, CONFIG_FILE);
+  if (!existsSync4(file)) {
     return void 0;
   }
   return loadConfigFrom(file);
@@ -3135,7 +3377,7 @@ function planInit(root, flags = {}) {
       );
     }
   }
-  const schemaFile = flags.schema === void 0 ? declared !== void 0 ? schemaFileOf2(declared) : detected?.schemaFile ?? DEFAULT_SCHEMA_FILE2 : flags.schema.trim();
+  const schemaFile = flags.schema === void 0 ? declared !== void 0 ? schemaFileOf4(declared) : detected?.schemaFile ?? DEFAULT_SCHEMA_FILE2 : flags.schema.trim();
   if (flags.schema !== void 0) {
     if (schemaFile.length === 0) {
       throw emptyFlag("schema");
@@ -3226,17 +3468,18 @@ async function promptForDecisions(plan2, io) {
     );
     io.write("");
   }
-  const inject = seamKindFor(plan2) === "none" ? false : await askInject(io);
   const proceed = (await io.ask(prompt("Proceed?", "Y/n"))).trim().toLowerCase();
   if (proceed.length > 0 && proceed !== "y" && proceed !== "yes") {
     return void 0;
   }
+  const inject = seamKindFor(plan2) === "none" ? false : await askInject(io);
   return { ...plan2.decisions, environments, inject };
 }
 function seamKindFor(plan2) {
   return seamFor(plan2.detected?.name, {
     alias: plan2.decisions.alias,
-    srcDir: plan2.decisions.schemaFile.startsWith("src/") ? "src/" : ""
+    srcDir: plan2.decisions.schemaFile.startsWith("src/") ? "src/" : "",
+    schemaFile: plan2.decisions.schemaFile
   }).kind;
 }
 async function askInject(io) {
@@ -3249,20 +3492,17 @@ async function askInject(io) {
 }
 var EMPTY_SCHEMA_BODY = "  // One key per parameter, e.g. `databaseUrl: z.url(),`. Nesting a key nests\n  // the parameter: `redis: z.object({ password: z.string() })` is redis/password.";
 var DRAFT_HEADER = "// DRAFT \u2014 generated by `penv import` from one sample of each value, and yours\n// to correct. Single-sample inference cannot know that a boolean seen as `true`\n// must also accept `1`/`0`, or that a string is really a URL. penv scaffolds\n// this file once and never regenerates it, so edits here are safe.\n";
-function renderSchemaModule(fields, draft, inject = false) {
+function renderSchemaShapeModule(fields, draft) {
   const body = fields.length === 0 ? EMPTY_SCHEMA_BODY : fields.map((field) => `  ${field.key}: ${field.type},`).join("\n");
-  const loadComment = inject ? "// The loaded, validated values for the current environment. Import this in app\n// code. `inject: true` also copies the values into process.env, for libraries\n// that read process.env directly (WorkOS, Prisma) instead of importing @env.\n" : "// The loaded, validated values for the current environment. Import this in app\n// code. Importing it loads configuration and throws (naming the parameter and\n// environment) if anything required is missing or invalid.\n";
-  const loadCall = inject ? "export const env = load(schema, { inject: true });\n" : "export const env = load(schema);\n";
   return `${draft ? DRAFT_HEADER : ""}import { z } from "zod";
-import { load } from "@penvhq/penv";
 
-// The shape. Import this (or z.infer<typeof schema>) when you only need the
-// type \u2014 tests, tooling \u2014 so you don't trigger config loading.
+// The shape \u2014 the one definition every consumer derives from. Import this (or
+// z.infer<typeof schema>) when you only need the type \u2014 tests, tooling \u2014 so you
+// don't trigger config loading. .penv/env.ts wraps it with load().
 export const schema = z.object({
 ${body}
 });
 
-` + loadComment + loadCall + `
 // Registers the schema's shape with penv's types (erased at runtime, so
 // nothing cycles). This is what makes \`override\` keys in penv.config.ts
 // autocomplete from this schema \u2014 a typo'd parameter id is a compile error.
@@ -3273,6 +3513,24 @@ declare module "@penvhq/core" {
 }
 `;
 }
+function shapeSpecifier(schemaFile) {
+  const depth = schemaFile.split("/").length - 1;
+  const climb = depth === 0 ? "./" : "../".repeat(depth);
+  return `${climb}${SCHEMA_SHAPE_BASENAME}.js`;
+}
+function renderEnvModule(schemaFile, inject = false) {
+  const loadComment = inject ? "// The loaded, validated values for the current environment. Import this in app\n// code. `inject: true` also copies the values into process.env, for libraries\n// that read process.env directly. `snapshot` lets load() resolve in a bundled or\n// serverless runtime where no penv.config.ts is on disk.\n" : "// The loaded, validated values for the current environment. Import this in app\n// code. Importing it loads configuration and throws (naming the parameter and\n// environment) if anything required is missing or invalid. `snapshot` lets load()\n// resolve in a bundled or serverless runtime where no penv.config.ts is on disk.\n";
+  const loadCall = inject ? "export const env = load(schema, { inject: true, snapshot });\n" : "export const env = load(schema, { snapshot });\n";
+  return `import { load } from "@penvhq/penv";
+import { schema } from "${shapeSpecifier(schemaFile)}";
+import { snapshot } from "${snapshotSpecifier(schemaFile)}";
+
+// Re-exported so type-only consumers can import the shape through @env without
+// triggering config loading \u2014 the shape itself lives in ${SCHEMA_SHAPE_FILE2}.
+export { schema };
+
+` + loadComment + loadCall;
+}
 function renderEnvironments(decisions) {
   const shared = "  // Environments are a whitelist. A filename segment is an environment only if\n  // it is declared here \u2014 penv never infers one from a folder or a filename.\n";
   if (decisions.environments.length === 0) {
@@ -3280,7 +3538,7 @@ function renderEnvironments(decisions) {
   // can read off your codebase, and an environment you do not have is worse
   // than one you have not declared yet. Name yours, and give each a provider:
   //   environments: ["development", "production"],
-  //   providers: { development: { type: "@penvhq/provider-filesystem" }, production: { type: "@penvhq/provider-filesystem" } },
+  //   providers: { development: { type: "@penvhq/provider-filesystem" }, production: { type: "@penvhq/provider-vault" } },
   environments: [],
 
   providers: {},
@@ -3537,45 +3795,101 @@ function renderTsconfig(target, alias) {
 }
 function ensurePenvDir(root) {
   const dir = resolve4(root, PENV_DIR2);
-  if (existsSync2(dir)) {
+  if (existsSync4(dir)) {
     return { target: "penv-dir", action: "kept", text: `Found ${PENV_DIR2}/` };
   }
   mkdirSync(dir, { recursive: true });
   return { target: "penv-dir", action: "created", text: `Created ${PENV_DIR2}/` };
 }
-function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
-  const file = join2(root, ...decisions.schemaFile.split("/"));
-  if (existsSync2(file)) {
+function writeSchemaShapeFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
+  const file = join5(root, SCHEMA_SHAPE_FILE2);
+  if (existsSync4(file)) {
+    return {
+      target: "schema",
+      action: "kept",
+      text: `Kept ${SCHEMA_SHAPE_FILE2}`,
+      note: "(yours \u2014 penv never regenerates it)"
+    };
+  }
+  const oldLayout = selfContainedSchemaModule(root, decisions.schemaFile);
+  if (oldLayout !== void 0) {
     return {
       target: "schema",
+      action: "conflicted",
+      text: `Kept your schema in ${oldLayout}`,
+      note: `(the shape lives there, from before the ${SCHEMA_SHAPE_FILE2} split \u2014 penv did not add a second one. To adopt the split: move the \`z.object\` (and any \`declare module\` block) into ${SCHEMA_SHAPE_FILE2}, leaving ${oldLayout} importing \`schema\` from it and calling \`load\`.)`
+    };
+  }
+  writeFileSync3(file, renderSchemaShapeModule(fields, draft), "utf8");
+  return {
+    target: "schema",
+    action: "created",
+    text: `Generated ${SCHEMA_SHAPE_FILE2}`,
+    note: draft ? "(draft schema \u2014 review it, it's yours)" : "(the shape \u2014 yours to edit)"
+  };
+}
+function writeEnvFile(root, decisions = DEFAULT_DECISIONS) {
+  const file = join5(root, ...decisions.schemaFile.split("/"));
+  if (existsSync4(file)) {
+    return {
+      target: "env",
       action: "kept",
       text: `Kept ${decisions.schemaFile}`,
       note: "(yours \u2014 penv never regenerates it)"
     };
   }
   mkdirSync(dirname3(file), { recursive: true });
-  writeFileSync2(file, renderSchemaModule(fields, draft, decisions.inject), "utf8");
+  writeFileSync3(file, renderEnvModule(decisions.schemaFile, decisions.inject), "utf8");
   return {
-    target: "schema",
+    target: "env",
     action: "created",
     text: `Generated ${decisions.schemaFile}`,
-    note: draft ? "(draft schema \u2014 review it, it's yours)" : "(schema + loader \u2014 yours to edit)"
+    note: "(loads the shape \u2014 yours to edit)"
   };
 }
 function writeConfigFile(root, decisions = DEFAULT_DECISIONS) {
-  const file = join2(root, CONFIG_FILE);
-  if (existsSync2(file)) {
+  const file = join5(root, CONFIG_FILE);
+  if (existsSync4(file)) {
     return { target: "config", action: "kept", text: `Kept ${CONFIG_FILE}` };
   }
-  writeFileSync2(file, renderConfigModule(decisions), "utf8");
+  writeFileSync3(file, renderConfigModule(decisions), "utf8");
   return { target: "config", action: "created", text: `Generated ${CONFIG_FILE}` };
 }
+function snapshotConfig(decisions) {
+  const providers = {};
+  for (const environment of decisions.environments) {
+    providers[environment] = { type: "@penvhq/provider-filesystem" };
+  }
+  return {
+    environments: decisions.environments,
+    providers,
+    ...decisions.schemaFile === DEFAULT_SCHEMA_FILE2 ? {} : { schemaFile: decisions.schemaFile },
+    ...decisions.publicPrefixes.length === 0 ? {} : { publicPrefixes: decisions.publicPrefixes }
+  };
+}
+function writeSnapshotModule(root, decisions = DEFAULT_DECISIONS) {
+  const file = join5(root, SNAPSHOT_FILE);
+  if (existsSync4(file)) {
+    return { target: "snapshot", action: "kept", text: `Kept ${SNAPSHOT_FILE}` };
+  }
+  writeFileSync3(
+    file,
+    renderSnapshotModule(buildSnapshotFrom(root, snapshotConfig(decisions))),
+    "utf8"
+  );
+  return {
+    target: "snapshot",
+    action: "created",
+    text: `Generated ${SNAPSHOT_FILE}`,
+    note: "(committed \u2014 the bundle resolves load() from it)"
+  };
+}
 function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
   const alias = decisions.alias;
   const imports = alias.startsWith(IMPORTS_PREFIX);
-  const file = join2(root, imports ? PACKAGE_FILE : TSCONFIG_FILE);
+  const file = join5(root, imports ? PACKAGE_FILE : TSCONFIG_FILE);
   const where = imports ? PACKAGE_FILE : TSCONFIG_FILE;
-  if (!existsSync2(file)) {
+  if (!existsSync4(file)) {
     if (imports) {
       return {
         target: "tsconfig",
@@ -3584,14 +3898,14 @@ function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
         note: `(run \`npm init\` first, or use \`--alias @env\` to alias through ${TSCONFIG_FILE})`
       };
     }
-    writeFileSync2(file, renderTsconfig(decisions.schemaFile, alias), "utf8");
+    writeFileSync3(file, renderTsconfig(decisions.schemaFile, alias), "utf8");
     return {
       target: "tsconfig",
       action: "created",
       text: `Created ${TSCONFIG_FILE} with the ${alias} path alias`
     };
   }
-  const source = readFileSync2(file, "utf8");
+  const source = readFileSync5(file, "utf8");
   const edit = imports ? insertImportsAlias(source, decisions.schemaFile, alias) : insertEnvAlias(source, decisions.schemaFile, alias);
   if (edit.conflict !== void 0) {
     return {
@@ -3608,7 +3922,7 @@ function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
       text: `Kept the ${alias} alias in ${where}`
     };
   }
-  writeFileSync2(file, edit.source, "utf8");
+  writeFileSync3(file, edit.source, "utf8");
   return {
     target: "tsconfig",
     action: "updated",
@@ -3616,30 +3930,63 @@ function writeTsconfigAlias(root, decisions = DEFAULT_DECISIONS) {
   };
 }
 function writeGitignore(root, decisions = DEFAULT_DECISIONS) {
-  const file = join2(root, PENV_DIR2, GITIGNORE_FILE);
+  const file = join5(root, PENV_DIR2, GITIGNORE_FILE);
   const relative3 = `${PENV_DIR2}/${GITIGNORE_FILE}`;
   const wanted = renderGitignore(decisions);
-  const existing = existsSync2(file) ? readFileSync2(file, "utf8") : void 0;
+  const existing = existsSync4(file) ? readFileSync5(file, "utf8") : void 0;
   if (existing === wanted) {
     return { target: "gitignore", action: "kept", text: `Kept ${relative3}` };
   }
-  mkdirSync(join2(root, PENV_DIR2), { recursive: true });
-  writeFileSync2(file, wanted, "utf8");
+  mkdirSync(join5(root, PENV_DIR2), { recursive: true });
+  writeFileSync3(file, wanted, "utf8");
   return {
     target: "gitignore",
     action: existing === void 0 ? "created" : "updated",
     text: `${existing === void 0 ? "Created" : "Updated"} ${relative3}`
   };
 }
-function srcDirOf(root) {
-  return existsSync2(join2(root, "src")) ? "src/" : "";
+var INJECT_MIN_VERSION = "0.6.0";
+function outdatedRuntimeWarning(root) {
+  const version = installedPenvVersion(root);
+  if (version === void 0 || !isBelow(version, INJECT_MIN_VERSION)) {
+    return void 0;
+  }
+  return `Injection needs @penvhq/penv ${INJECT_MIN_VERSION}+ \u2014 this project has ${version}, whose \`load\` ignores \`{ inject: true }\`. Upgrade, or process.env stays empty.`;
+}
+function installedPenvVersion(root) {
+  const file = join5(root, "node_modules", "@penvhq", "penv", "package.json");
+  if (!existsSync4(file)) {
+    return void 0;
+  }
+  try {
+    const version = JSON.parse(readFileSync5(file, "utf8")).version;
+    return typeof version === "string" ? version : void 0;
+  } catch {
+    return void 0;
+  }
 }
-function writeSeam(root, decisions = DEFAULT_DECISIONS) {
+function releaseTriple(version) {
+  const parts = (version.split("-")[0] ?? "").split(".");
+  const at = (i) => Number.parseInt(parts[i] ?? "0", 10) || 0;
+  return [at(0), at(1), at(2)];
+}
+function isBelow(a, b) {
+  const [am, an, ap] = releaseTriple(a);
+  const [bm, bn, bp] = releaseTriple(b);
+  if (am !== bm) return am < bm;
+  if (an !== bn) return an < bn;
+  return ap < bp;
+}
+function writeSeam(root, decisions = DEFAULT_DECISIONS, framework = detectFramework(root)?.name) {
   if (!decisions.inject) {
     return void 0;
   }
-  const framework = detectFramework(root)?.name;
-  const seam = seamFor(framework, { alias: decisions.alias, srcDir: srcDirOf(root) });
+  const seam = seamFor(framework, {
+    alias: decisions.alias,
+    srcDir: srcPrefix(root),
+    schemaFile: decisions.schemaFile
+  });
+  const outdated = outdatedRuntimeWarning(root);
   if (seam.kind === "none") {
     return { target: "seam", action: "info", text: "No injection seam needed", note: seam.reason };
   }
@@ -3648,54 +3995,84 @@ function writeSeam(root, decisions = DEFAULT_DECISIONS) {
       target: "seam",
       action: "info",
       text: "Place the injection seam",
-      note: seam.instruction
+      note: withWarning(seam.instruction, outdated)
     };
   }
-  const file = join2(root, ...seam.file.split("/"));
-  const notes = seam.notes.length === 0 ? "" : `
-${seam.notes.map((n) => `  ${n}`).join("\n")}`;
-  if (existsSync2(file)) {
+  const alsoNote = writeAlso(root, seam.also);
+  const file = join5(root, ...seam.file.split("/"));
+  const baseNotes = [...seam.notes, ...alsoNote === void 0 ? [] : [alsoNote]];
+  const notes = baseNotes.length === 0 ? "" : `
+${baseNotes.map((n) => `  ${n}`).join("\n")}`;
+  if (existsSync4(file)) {
     return {
       target: "seam",
       action: "info",
       text: `Add the injection seam to ${seam.file}`,
-      note: `${seam.ifPresent}${notes}`
+      note: withWarning(`${seam.ifPresent}${notes}`, outdated)
     };
   }
   mkdirSync(dirname3(file), { recursive: true });
-  writeFileSync2(file, seam.content, "utf8");
+  writeFileSync3(file, seam.content, "utf8");
   return {
     target: "seam",
-    action: "created",
+    action: outdated === void 0 ? "created" : "info",
     text: `Wrote ${seam.file} (runs the injection before your app)`,
-    ...notes === "" ? {} : { note: notes.trimStart() }
+    ...notes === "" && outdated === void 0 ? {} : { note: withWarning(notes.trimStart(), outdated) }
   };
 }
-function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS) {
+function writeAlso(root, also) {
+  if (also === void 0) {
+    return void 0;
+  }
+  const file = join5(root, ...also.file.split("/"));
+  if (existsSync4(file)) {
+    return also.ifPresent;
+  }
+  mkdirSync(dirname3(file), { recursive: true });
+  writeFileSync3(file, also.content, "utf8");
+  return `Wrote ${also.file} to register it.`;
+}
+function withWarning(note, warning) {
+  if (warning === void 0) {
+    return note;
+  }
+  return note === "" ? warning : `${note}
+  \u26A0 ${warning}`;
+}
+function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS, framework = detectFramework(root)?.name) {
   const steps = [
     ensurePenvDir(root),
-    writeSchemaFile(root, fields, draft, decisions),
+    // The shape at the root, then the wrapper that loads it — both write-once.
+    // The shape step needs the decisions too: an old-layout `schemaFile` already
+    // holds the shape, and a second `penv.schema.ts` beside it would not compile.
+    writeSchemaShapeFile(root, fields, draft, decisions),
+    writeEnvFile(root, decisions),
     writeConfigFile(root, decisions),
+    // After the config, whose evaluated shape the snapshot embeds; the wrapper
+    // env.ts written above already imports it.
+    writeSnapshotModule(root, decisions),
     writeTsconfigAlias(root, decisions),
     writeGitignore(root, decisions)
   ];
-  const seam = writeSeam(root, decisions);
+  const seam = writeSeam(root, decisions, framework);
   return seam === void 0 ? steps : [...steps, seam];
 }
 function runInit(options) {
   const root = resolve4(options.cwd);
   const decisions = options.decisions ?? planInit(root).decisions;
-  return { root, decisions, steps: scaffold(root, [], false, decisions) };
+  return { root, decisions, steps: scaffold(root, [], false, decisions, options.framework) };
 }
 function renderInit(result2) {
   const steps = result2.steps.map((step) => {
     const glyph = step.action === "conflicted" ? WARN : step.action === "info" ? "\u2192" : CHECK;
     return step.note === void 0 ? { glyph, text: step.text } : { glyph, text: step.text, note: step.note };
   });
+  const schemaStep = result2.steps.find((step) => step.target === "schema");
+  const shapeFile = schemaStep?.action === "conflicted" ? result2.decisions.schemaFile : SCHEMA_SHAPE_FILE2;
   return [
     ...formatSteps(steps),
     "",
-    `${out.green(CHECK)} ${out.bold("Done.")} Declare your parameters in ${result2.decisions.schemaFile}, then:`,
+    `${out.green(CHECK)} ${out.bold("Done.")} Declare your parameters in ${shapeFile}, then:`,
     tip(out.cyan("penv set <key>")),
     ...result2.decisions.environments.length === 0 ? [
       `Then declare your environments in ${CONFIG_FILE}: penv leaves the whitelist empty rather than inventing one, and every command needs it.`
@@ -3752,7 +4129,15 @@ var initCommand = defineCommand9({
       if (!asked) {
         write([...plan2.notes, ""]);
       }
-      write(renderInit(runInit({ cwd: root, decisions })));
+      write(
+        renderInit(
+          runInit({
+            cwd: root,
+            decisions,
+            ...plan2.detected && { framework: plan2.detected.name }
+          })
+        )
+      );
     });
   }
 });
@@ -3925,7 +4310,7 @@ function decisionsOf(config, cwd) {
     // `import` re-scaffolds env.ts for an existing project; injection is an init
     // choice, so it is not turned on here.
     inject: false,
-    schemaFile: schemaFileOf3(config),
+    schemaFile: schemaFileOf5(config),
     publicPrefixes: config.publicPrefixes ?? [],
     alias: detectAlias(cwd)
   };
@@ -3947,14 +4332,14 @@ function configInEffect(cwd, environment) {
 function importDotenv(options) {
   const cwd = resolve5(options.cwd);
   const file = isAbsolute2(options.file) ? options.file : resolve5(cwd, options.file);
-  if (!existsSync3(file)) {
+  if (!existsSync5(file)) {
     throw new PenvError13(
       "IMPORT_FILE_MISSING",
       `There is no file at ${file} to import`,
       "Point `penv import` at an existing dotenv file, e.g. `penv import .env`."
     );
   }
-  const parsed = parseDotenv(readFileSync3(file, "utf8"));
+  const parsed = parseDotenv(readFileSync6(file, "utf8"));
   const { config, decisions } = configInEffect(cwd, environmentNamed(file, options.environment));
   const source = displayPath2(cwd, file);
   const named = scopeFromFilename(file, config);
@@ -3992,6 +4377,7 @@ function importDotenv(options) {
   }
   const backup = `${file}${BACKUP_SUFFIX}`;
   copyFileSync(file, backup);
+  refreshSnapshot(project);
   return {
     root: project.root,
     file,
@@ -4304,7 +4690,7 @@ var listCommand = defineCommand12({
 import {
   accessPath as accessPath5,
   formatMetaFile,
-  formatValueFile as formatValueFile5,
+  formatValueFile as formatValueFile6,
   openValue as openValue4,
   PenvError as PenvError15,
   parameterId as parameterId5,
@@ -4327,7 +4713,7 @@ async function planFile(project, source, target, parameter) {
   if (environment === void 0) {
     throw new PenvError15(
       "SECRET_SCOPE_AMBIGUOUS",
-      `${PENV_DIR}/${formatValueFile5(source)} is encrypted at a scope that names no environment, so penv cannot tell which key would re-seal it`,
+      `${PENV_DIR}/${formatValueFile6(source)} is encrypted at a scope that names no environment, so penv cannot tell which key would re-seal it`,
       "Keys are declared per environment in the `keys` block of penv.config.ts. Decrypt it with `penv decrypt`, move the parameter, then encrypt it again at its new address."
     );
   }
@@ -4336,7 +4722,7 @@ async function planFile(project, source, target, parameter) {
   if (opened.kind === "failed") {
     throw new PenvError15(
       "VALUE_UNDECRYPTABLE",
-      `${PENV_DIR}/${formatValueFile5(source)} could not be decrypted, so penv cannot re-seal it at its new address: ${opened.failure.detail}`,
+      `${PENV_DIR}/${formatValueFile6(source)} could not be decrypted, so penv cannot re-seal it at its new address: ${opened.failure.detail}`,
       "A sealed value is bound to the file it lives in, so moving it means opening it and sealing it again. Make the key available and run this again. Nothing has been moved."
     );
   }
@@ -4401,19 +4787,21 @@ async function runMove(options) {
   if (meta !== void 0) {
     await project.provider.removeMeta(from);
   }
+  refreshSnapshot(project);
   return {
     from: parameterId5(from),
     to: parameterId5(to),
     files: planned.map((file) => ({
-      from: formatValueFile5(file.source),
-      to: formatValueFile5(file.target),
+      from: formatValueFile6(file.source),
+      to: formatValueFile6(file.target),
       resealed: file.resealed
     })),
     // The meta's path, not the parameter's dotted id: `redis.password` is what
     // the schema calls it and `redis/password.json` is the file, and a report
     // that printed the first while moving the second names no file on disk.
     meta: meta === void 0 ? void 0 : formatMetaFile({ ...to, format: "json" }),
-    schema: { was: accessPath5(from).join("."), now: accessPath5(to).join(".") }
+    schema: { was: accessPath5(from).join("."), now: accessPath5(to).join(".") },
+    schemaFile: schemaShapeFileOf(project)
   };
 }
 function renderMove(result2) {
@@ -4430,7 +4818,7 @@ function renderMove(result2) {
   lines.push(
     "",
     tip(
-      `.penv/env.ts still declares \`${result2.schema.was}\` \u2014 rename it to \`${result2.schema.now}\`, or \`penv validate\` will report the value as unused and the declaration as unset.`
+      `${result2.schemaFile} still declares \`${result2.schema.was}\` \u2014 rename it to \`${result2.schema.now}\`, or \`penv validate\` will report the value as unused and the declaration as unset.`
     )
   );
   return lines;
@@ -4517,6 +4905,7 @@ async function runPull(options) {
     tree.writeMetaSync(ref, block);
     meta += 1;
   }
+  refreshSnapshot(project);
   return { environment, source: source.type, localSource: false, values, meta, refs: refs.length };
 }
 function renderPull(result2) {
@@ -4585,7 +4974,7 @@ var pullCommand = defineCommand14({
 });
 
 // src/commands/remove.ts
-import { formatValueFile as formatValueFile6 } from "@penvhq/core";
+import { formatValueFile as formatValueFile7 } from "@penvhq/core";
 import { defineCommand as defineCommand15 } from "citty";
 async function runRemove(options) {
   const project = openProject(options.cwd);
@@ -4603,12 +4992,13 @@ async function runRemove(options) {
       continue;
     }
     await project.provider.remove(file);
-    removed.push(formatValueFile6(file));
+    removed.push(formatValueFile7(file));
   }
+  refreshSnapshot(project);
   return {
     parameter: options.key,
     removed,
-    considered: files.map((file) => formatValueFile6(file))
+    considered: files.map((file) => formatValueFile7(file))
   };
 }
 function renderRemove(result2) {
@@ -4684,6 +5074,7 @@ async function writeRotatedValue(project, provider, ref, environment, value) {
       value,
       environment
     });
+    refreshSnapshot(project);
     return;
   }
   await provider.write(rotatingFile(ref, environment), value);
@@ -4851,11 +5242,53 @@ var rotateCommand = defineCommand16({
   }
 });
 
+// src/commands/snapshot.ts
+import { defineCommand as defineCommand17 } from "citty";
+function runSnapshot(options) {
+  const project = openProject(options.cwd);
+  return { write: writeSnapshotFile(project), wire: wireEnvModule(project) };
+}
+function renderSnapshot(result2) {
+  const label = result2.write.action === "created" ? "Generated" : result2.write.action === "updated" ? "Updated" : "Up to date";
+  const rows = [{ glyph: CHECK, label, subject: SNAPSHOT_FILE }];
+  if (result2.wire.action === "wired") {
+    rows.push({
+      glyph: CHECK,
+      label: "Wired",
+      subject: result2.wire.file,
+      detail: "load reads the snapshot"
+    });
+  } else if (result2.wire.action === "kept") {
+    rows.push({ glyph: CHECK, label: "Wired", subject: result2.wire.file });
+  }
+  const lines = formatRows(rows);
+  if (result2.wire.action === "manual") {
+    lines.push(
+      "",
+      `${WARN} penv could not wire ${result2.wire.file} automatically \u2014 add these two lines yourself:`,
+      tip(result2.wire.importLine),
+      tip(result2.wire.loadHint)
+    );
+  }
+  return lines;
+}
+var snapshotCommand = defineCommand17({
+  meta: {
+    name: "snapshot",
+    description: "Generate penv.snapshot.ts so load() resolves in a bundled/serverless runtime"
+  },
+  run() {
+    return guard(async () => {
+      write(renderSnapshot(runSnapshot({ cwd: process.cwd() })));
+    });
+  }
+});
+
 // src/commands/watch.ts
-import { existsSync as existsSync4, watch } from "fs";
+import { existsSync as existsSync6, watch } from "fs";
 import { basename as basename2, dirname as dirname4, resolve as resolve6 } from "path";
-import { schemaFileOf as schemaFileOf4, schemaInsideTree as schemaInsideTree2 } from "@penvhq/core";
-import { defineCommand as defineCommand17 } from "citty";
+import { SCHEMA_SHAPE_FILE as SCHEMA_SHAPE_FILE3, schemaFileOf as schemaFileOf6, schemaInsideTree as schemaInsideTree2 } from "@penvhq/core";
+import { defineCommand as defineCommand18 } from "citty";
 var DEBOUNCE_MS = 100;
 function runWatch(options) {
   const project = openProject(options.cwd);
@@ -4920,14 +5353,14 @@ function runWatch(options) {
         if (closed || recovery === void 0) {
           return;
         }
-        if (!existsSync4(parent)) {
+        if (!existsSync6(parent)) {
           stop(recovery);
           return;
         }
         if (filename !== null && basename2(filename) !== name) {
           return;
         }
-        if (!existsSync4(target)) {
+        if (!existsSync6(target)) {
           return;
         }
         stop(recovery);
@@ -4951,7 +5384,7 @@ function runWatch(options) {
       if (closed) {
         return;
       }
-      if (!existsSync4(target)) {
+      if (!existsSync6(target)) {
         if (watcher !== void 0) {
           stop(watcher);
         }
@@ -4987,8 +5420,9 @@ function runWatch(options) {
   }
   addWatcher(project.penvDir, true);
   addWatcher(dirname4(project.configFile), false, configFile);
+  addWatcher(project.root, false, SCHEMA_SHAPE_FILE3);
   if (schemaInsideTree2(project.config) === void 0) {
-    const schemaFile = resolve6(project.root, schemaFileOf4(project.config));
+    const schemaFile = resolve6(project.root, schemaFileOf6(project.config));
     addWatcher(dirname4(schemaFile), false, basename2(schemaFile));
   }
   void validate();
@@ -5032,7 +5466,7 @@ function renderDrift(drift, environment) {
   }
   return lines;
 }
-var watchCommand = defineCommand17({
+var watchCommand = defineCommand18({
   meta: {
     name: "watch",
     description: "Re-validate whenever .penv/ or penv.config.ts changes"
@@ -5071,7 +5505,7 @@ var watchCommand = defineCommand17({
 });
 
 // src/index.ts
-var main = defineCommand18({
+var main = defineCommand19({
   meta: {
     name: "penv",
     description: "Configuration that shares a data model with your production secret manager"
@@ -5092,6 +5526,7 @@ var main = defineCommand18({
     encrypt: encryptCommand,
     decrypt: decryptCommand,
     key: keyCommand,
+    snapshot: snapshotCommand,
     validate: validateCommand,
     doctor: doctorCommand,
     watch: watchCommand
@@ -5113,6 +5548,7 @@ export {
   renderPull,
   renderPush,
   renderRotate,
+  renderSnapshot,
   renderWatch,
   runDecrypt,
   runDoctor,
@@ -5130,6 +5566,7 @@ export {
   runRemove,
   runRotate,
   runSet,
+  runSnapshot,
   runValidate,
   runWatch
 };