@penvhq/cli 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -368,19 +368,19 @@ function refsFrom(files) {
 
 // src/schema.ts
 var import_core4 = require("@penvhq/core");
-function defOf(node) {
-  if (typeof node !== "object" || node === null) {
+function defOf(node2) {
+  if (typeof node2 !== "object" || node2 === null) {
     return void 0;
   }
-  const def = node.def;
+  const def = node2.def;
   return typeof def === "object" && def !== null ? def : void 0;
 }
-function typeOf(node) {
-  const type = defOf(node)?.type;
+function typeOf(node2) {
+  const type = defOf(node2)?.type;
   return typeof type === "string" ? type : void 0;
 }
-function unwrap(node) {
-  let current = node;
+function unwrap(node2) {
+  let current = node2;
   for (let depth = 0; depth < 8; depth += 1) {
     const inner = defOf(current)?.innerType;
     if (inner === void 0) {
@@ -390,38 +390,38 @@ function unwrap(node) {
   }
   return current;
 }
-function shapeOf(node) {
-  if (typeOf(node) !== "object") {
+function shapeOf(node2) {
+  if (typeOf(node2) !== "object") {
     return void 0;
   }
-  const shape = node.shape;
+  const shape = node2.shape;
   return typeof shape === "object" && shape !== null ? shape : void 0;
 }
 function lookup(root, path) {
-  let node = unwrap(root);
+  let node2 = unwrap(root);
   for (const key of path) {
-    const shape = shapeOf(node);
+    const shape = shapeOf(node2);
     if (shape === void 0) {
       return { kind: "unknown" };
     }
     if (!Object.hasOwn(shape, key)) {
       return { kind: "absent" };
     }
-    node = unwrap(shape[key]);
+    node2 = unwrap(shape[key]);
   }
-  return { kind: "found", node };
+  return { kind: "found", node: node2 };
 }
-function minLengthOf(node) {
-  if (typeOf(node) !== "string") {
+function minLengthOf(node2) {
+  if (typeOf(node2) !== "string") {
     return void 0;
   }
-  const min = node.minLength;
+  const min = node2.minLength;
   return typeof min === "number" ? min : void 0;
 }
 var ABSENCE_PERMITTED = /* @__PURE__ */ new Set(["optional", "default", "catch", "prefault"]);
 var ABSENCE_REFUSED = /* @__PURE__ */ new Set(["nullable", "nonoptional", "readonly"]);
-function permitsAbsence(node) {
-  let current = node;
+function permitsAbsence(node2) {
+  let current = node2;
   for (let depth = 0; depth < 8; depth += 1) {
     const type = typeOf(current);
     if (type !== void 0 && ABSENCE_PERMITTED.has(type)) {
@@ -438,13 +438,13 @@ function permitsAbsence(node) {
   }
   return void 0;
 }
-function leaves(node, path, inherited, out2) {
-  const own = permitsAbsence(node);
+function leaves(node2, path, inherited, out2) {
+  const own = permitsAbsence(node2);
   const absencePermitted = inherited === true || own === true ? true : combine(inherited, own);
-  const shape = shapeOf(unwrap(node));
+  const shape = shapeOf(unwrap(node2));
   if (shape === void 0) {
     if (path.length > 0) {
-      out2.push({ path, absencePermitted, node });
+      out2.push({ path, absencePermitted, node: node2 });
     }
     return;
   }
@@ -460,8 +460,8 @@ function declaredLeaves(schema) {
   leaves(schema, [], false, out2);
   return out2;
 }
-function defaultValueOf(node) {
-  let current = node;
+function defaultValueOf(node2) {
+  let current = node2;
   for (let depth = 0; depth < 8; depth += 1) {
     const def = defOf(current);
     if (def === void 0) {
@@ -1111,18 +1111,18 @@ function place(root, path, value) {
   if (leaf === void 0) {
     return;
   }
-  let node = root;
+  let node2 = root;
   for (const key of path.slice(0, -1)) {
-    const existing = node[key];
+    const existing = node2[key];
     if (typeof existing === "object" && existing !== null) {
-      node = existing;
+      node2 = existing;
       continue;
     }
     const child = {};
-    node[key] = child;
-    node = child;
+    node2[key] = child;
+    node2 = child;
   }
-  node[leaf] = value;
+  node2[leaf] = value;
 }
 function isZodType(value) {
   return typeof value === "object" && value !== null && "safeParse" in value && typeof value.safeParse === "function";
@@ -2775,6 +2775,8 @@ var import_node_path5 = require("path");
 var import_core14 = require("@penvhq/core");
 var SIGNATURES = [
   { name: "Next.js", packages: ["next"], publicPrefixes: ["NEXT_PUBLIC_"] },
+  { name: "SvelteKit", packages: ["@sveltejs/kit"], publicPrefixes: ["PUBLIC_"] },
+  { name: "Nuxt", packages: ["nuxt"], publicPrefixes: ["NUXT_PUBLIC_"] },
   {
     name: "TanStack Start",
     packages: ["@tanstack/react-start", "@tanstack/start"],
@@ -2801,7 +2803,7 @@ function occupied(cwd, relative3) {
   return (0, import_node_fs2.existsSync)(file) && !exportsSchema(file);
 }
 function schemaFileFor(cwd) {
-  const dir = (0, import_node_fs2.existsSync)((0, import_node_path5.join)(cwd, "src")) ? "src/" : "";
+  const dir = srcPrefix(cwd);
   const preferred = `${dir}env.ts`;
   if (!occupied(cwd, preferred)) {
     return { file: preferred };
@@ -2812,6 +2814,9 @@ function schemaFileFor(cwd) {
   }
   return { file: import_core14.DEFAULT_SCHEMA_FILE, displaced: preferred };
 }
+function srcPrefix(cwd) {
+  return (0, import_node_fs2.existsSync)((0, import_node_path5.join)(cwd, "src")) ? "src/" : "";
+}
 function dependenciesOf(cwd) {
   const manifest = manifestOf(cwd);
   if (manifest === void 0) {
@@ -2848,17 +2853,23 @@ function detectFramework(cwd) {
   }
   for (const signature of SIGNATURES) {
     if (signature.packages.some((name) => dependencies.has(name))) {
-      const schema = schemaFileFor(cwd);
-      return {
-        name: signature.name,
-        schemaFile: schema.file,
-        ...schema.displaced === void 0 ? {} : { displacedFrom: schema.displaced },
-        publicPrefixes: signature.publicPrefixes
-      };
+      return detectedFrom(cwd, signature.name, signature.publicPrefixes);
     }
   }
+  if ((0, import_node_fs2.existsSync)((0, import_node_path5.join)(cwd, "bunfig.toml")) || dependencies.has("bun-types")) {
+    return detectedFrom(cwd, "Bun", []);
+  }
   return void 0;
 }
+function detectedFrom(cwd, name, publicPrefixes) {
+  const schema = schemaFileFor(cwd);
+  return {
+    name,
+    schemaFile: schema.file,
+    ...schema.displaced === void 0 ? {} : { displacedFrom: schema.displaced },
+    publicPrefixes
+  };
+}
 var DEFAULT_ALIAS = "@env";
 var IMPORTS_ALIAS = "#env";
 function detectAlias(cwd) {
@@ -2876,6 +2887,145 @@ var import_node_path6 = require("path");
 var import_promises = require("readline/promises");
 var import_core15 = require("@penvhq/core");
 var import_citty9 = require("citty");
+
+// src/seams.ts
+function nextjs({ alias, srcDir }) {
+  return {
+    kind: "scaffold",
+    file: `${srcDir}instrumentation.ts`,
+    content: `// This is instrumentation.ts, Next.js's own startup hook \u2014 Next runs it once,
+// before any of your app code, on every server boot. penv put one line here so
+// your config is in process.env before the first library reads it. The filename
+// is Next's requirement (it only finds \`instrumentation.ts\`), so keep it as-is.
+export async function register() {
+  // Next also calls register on the Edge runtime, where penv cannot read the
+  // filesystem \u2014 so inject runs on the Node runtime only.
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    await import("${alias}");
+  }
+}
+`,
+    ifPresent: `Add to your existing \`${srcDir}instrumentation.ts\`, inside \`register()\` and first:
+  if (process.env.NEXT_RUNTIME === "nodejs") { await import("${alias}"); }`,
+    notes: []
+  };
+}
+function sveltekit({ alias }) {
+  return {
+    kind: "scaffold",
+    // SvelteKit's hooks module is always under `src/`, whatever the schema path.
+    file: "src/hooks.server.ts",
+    content: `// This is hooks.server.ts, SvelteKit's server-startup module \u2014 it loads before
+// your routes handle a request. penv put this import first so your config is in
+// process.env before any library reads it. Keep it the first line; the name and
+// location are SvelteKit's, not penv's.
+import "${alias}";
+`,
+    ifPresent: `Add \`import "${alias}";\` as the FIRST line of src/hooks.server.ts, above every other import.`,
+    notes: [
+      `SvelteKit resolves app aliases through \`kit.alias\` \u2014 make sure \`${alias}\` is registered in svelte.config.js, not only tsconfig.`
+    ]
+  };
+}
+function nuxt({ alias }) {
+  return {
+    kind: "scaffold",
+    // The `0.` prefix is load-bearing: Nitro sorts plugin filenames as strings,
+    // so it must sort first to run before any other plugin reads process.env.
+    file: "server/plugins/0.penv.ts",
+    content: `// This is a Nitro server plugin (Nuxt's server layer runs it once at startup,
+// before any middleware or request handler). penv put the import here so your
+// config is in process.env before a library reads it. The \`0.\` prefix keeps this
+// plugin first \u2014 Nitro sorts plugin filenames as text \u2014 so don't rename it.
+import "${alias}";
+
+// Nitro requires every plugin file to default-export a function; the injection
+// above already ran at import, so this body is intentionally empty.
+export default defineNitroPlugin(() => {});
+`,
+    ifPresent: `Create server/plugins/0.penv.ts with \`import "${alias}";\` and \`export default defineNitroPlugin(() => {});\`.`,
+    notes: [
+      `Wire \`${alias}\` for the Nitro (server) build so it never leaks into the client bundle.`
+    ]
+  };
+}
+function bun({ alias }) {
+  return {
+    kind: "scaffold",
+    file: ".penv/preload.ts",
+    content: `// Bun evaluates this file before your entry point, because it is listed under
+// \`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: [`\`${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, 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
+code, so place the injection yourself, one of two ways (both run first):
+  \u2022 Preload at launch \u2014 add to your start script:  node --import "${runtimeSpecifier}" your-entry.js
+  \u2022 Or make it the FIRST line of your entry file:   import "${runtimeSpecifier}";
+` + (alias.startsWith("#") ? "" : `Note: \`${alias}\` is a tsconfig alias that Node does not resolve at runtime \u2014 the paths above point at the built schema module instead.
+`)
+  };
+}
+function tanstack({ alias, srcDir }) {
+  return {
+    kind: "instruct",
+    instruction: `Add \`import "${alias}";\` as the FIRST line of ${srcDir}server.ts (TanStack Start's
+server entry), above the \`@tanstack/react-start/server-entry\` import \u2014 nothing may
+import before it. If you have no server.ts yet, create it from TanStack's server-entry
+template and put that import first.`
+  };
+}
+function astro({ alias }) {
+  return {
+    kind: "instruct",
+    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) {
+  return {
+    kind: "none",
+    reason: "This is a client-only app \u2014 nothing reads process.env at runtime, so injection does not apply. Read client config through import.meta.env (only VITE_-prefixed vars, which ship to the browser and must not hold secrets). If you add a server later, place the injection there."
+  };
+}
+var SEAMS = {
+  "Next.js": nextjs,
+  SvelteKit: sveltekit,
+  Nuxt: nuxt,
+  Bun: bun,
+  "TanStack Start": tanstack,
+  Astro: astro,
+  Vite: viteSpa
+};
+function seamFor(framework, context) {
+  const build = framework === void 0 ? node : SEAMS[framework] ?? node;
+  return build(context);
+}
+
+// src/commands/init.ts
 var CONFIG_FILE = "penv.config.ts";
 var TSCONFIG_FILE = "tsconfig.json";
 var GITIGNORE_FILE = ".gitignore";
@@ -2885,6 +3035,7 @@ var IMPORTS_PREFIX = "#";
 var PACKAGE_FILE = "package.json";
 var DEFAULT_DECISIONS = {
   environments: [],
+  inject: false,
   schemaFile: import_core15.DEFAULT_SCHEMA_FILE,
   publicPrefixes: [],
   alias: DEFAULT_ALIAS
@@ -3003,6 +3154,9 @@ function planInit(root, flags = {}) {
     detected,
     decisions: {
       environments,
+      // Injection is a choice about the app's needs, not something on disk — so
+      // the plan defaults it off, and only the interactive prompt turns it on.
+      inject: false,
       schemaFile,
       publicPrefixes: declared?.publicPrefixes ?? detected?.publicPrefixes ?? [],
       alias
@@ -3053,12 +3207,30 @@ async function promptForDecisions(plan2, io) {
   if (proceed.length > 0 && proceed !== "y" && proceed !== "yes") {
     return void 0;
   }
-  return { ...plan2.decisions, environments };
+  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/" : "",
+    schemaFile: plan2.decisions.schemaFile
+  }).kind;
+}
+async function askInject(io) {
+  io.write("");
+  io.write("Also inject your validated config into process.env?");
+  io.write("  y  libraries that read process.env directly (WorkOS, Prisma\u2026) just work");
+  io.write('  n  config stays available only through  import { env } from "@env"');
+  const answer = (await io.ask(prompt("inject", "y/N"))).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 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) {
+function renderSchemaModule(fields, draft, inject = false) {
   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";
 
@@ -3068,11 +3240,7 @@ export const schema = z.object({
 ${body}
 });
 
-// The loaded, validated values for the current environment. Import this in app
-// code. Importing it loads configuration and throws (naming the parameter and
-// environment) if anything required is missing or invalid.
-export const env = load(schema);
-
+` + 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.
@@ -3364,7 +3532,7 @@ function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
     };
   }
   (0, import_node_fs3.mkdirSync)((0, import_node_path6.dirname)(file), { recursive: true });
-  (0, import_node_fs3.writeFileSync)(file, renderSchemaModule(fields, draft), "utf8");
+  (0, import_node_fs3.writeFileSync)(file, renderSchemaModule(fields, draft, decisions.inject), "utf8");
   return {
     target: "schema",
     action: "created",
@@ -3441,23 +3609,119 @@ function writeGitignore(root, decisions = DEFAULT_DECISIONS) {
     text: `${existing === void 0 ? "Created" : "Updated"} ${relative3}`
   };
 }
-function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS) {
-  return [
+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 = (0, import_node_path6.join)(root, "node_modules", "@penvhq", "penv", "package.json");
+  if (!(0, import_node_fs3.existsSync)(file)) {
+    return void 0;
+  }
+  try {
+    const version = JSON.parse((0, import_node_fs3.readFileSync)(file, "utf8")).version;
+    return typeof version === "string" ? version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+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 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 };
+  }
+  if (seam.kind === "instruct") {
+    return {
+      target: "seam",
+      action: "info",
+      text: "Place the injection seam",
+      note: withWarning(seam.instruction, outdated)
+    };
+  }
+  const alsoNote = writeAlso(root, seam.also);
+  const file = (0, import_node_path6.join)(root, ...seam.file.split("/"));
+  const baseNotes = [...seam.notes, ...alsoNote === void 0 ? [] : [alsoNote]];
+  const notes = baseNotes.length === 0 ? "" : `
+${baseNotes.map((n) => `  ${n}`).join("\n")}`;
+  if ((0, import_node_fs3.existsSync)(file)) {
+    return {
+      target: "seam",
+      action: "info",
+      text: `Add the injection seam to ${seam.file}`,
+      note: withWarning(`${seam.ifPresent}${notes}`, outdated)
+    };
+  }
+  (0, import_node_fs3.mkdirSync)((0, import_node_path6.dirname)(file), { recursive: true });
+  (0, import_node_fs3.writeFileSync)(file, seam.content, "utf8");
+  return {
+    target: "seam",
+    action: outdated === void 0 ? "created" : "info",
+    text: `Wrote ${seam.file} (runs the injection before your app)`,
+    ...notes === "" && outdated === void 0 ? {} : { note: withWarning(notes.trimStart(), outdated) }
+  };
+}
+function writeAlso(root, also) {
+  if (also === void 0) {
+    return void 0;
+  }
+  const file = (0, import_node_path6.join)(root, ...also.file.split("/"));
+  if ((0, import_node_fs3.existsSync)(file)) {
+    return also.ifPresent;
+  }
+  (0, import_node_fs3.mkdirSync)((0, import_node_path6.dirname)(file), { recursive: true });
+  (0, import_node_fs3.writeFileSync)(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),
     writeConfigFile(root, decisions),
     writeTsconfigAlias(root, decisions),
     writeGitignore(root, decisions)
   ];
+  const seam = writeSeam(root, decisions, framework);
+  return seam === void 0 ? steps : [...steps, seam];
 }
 function runInit(options) {
   const root = (0, import_node_path6.resolve)(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 : CHECK;
+    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 };
   });
   return [
@@ -3520,7 +3784,15 @@ var initCommand = (0, import_citty9.defineCommand)({
       if (!asked) {
         write([...plan2.notes, ""]);
       }
-      write(renderInit(runInit({ cwd: root, decisions })));
+      write(
+        renderInit(
+          runInit({
+            cwd: root,
+            decisions,
+            ...plan2.detected && { framework: plan2.detected.name }
+          })
+        )
+      );
     });
   }
 });
@@ -3690,6 +3962,9 @@ function environmentNamed(file, explicit) {
 function decisionsOf(config, cwd) {
   return {
     environments: config.environments,
+    // `import` re-scaffolds env.ts for an existing project; injection is an init
+    // choice, so it is not turned on here.
+    inject: false,
     schemaFile: (0, import_core16.schemaFileOf)(config),
     publicPrefixes: config.publicPrefixes ?? [],
     alias: detectAlias(cwd)