@penvhq/cli 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -250,14 +250,18 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore";
+type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
 /**
  * `conflicted` is the one that is not a success. penv wanted to write something,
  * found the user's file already saying something else about the same thing, and
  * left it alone — so the step is reported with a warning rather than a ✓, and the
  * text says what will not work until the user decides.
+ *
+ * `info` is a step penv did not perform automatically — a manual instruction (the
+ * injection seam for a framework penv cannot scaffold), reported so the user
+ * knows the one thing left to do.
  */
-type InitAction = "created" | "kept" | "updated" | "conflicted";
+type InitAction = "created" | "kept" | "updated" | "conflicted" | "info";
 interface InitStep {
     readonly target: InitTarget;
     readonly action: InitAction;
@@ -289,6 +293,13 @@ interface InitDecisions {
      * offers that.
      */
     readonly alias: string;
+    /**
+     * Whether to inject the validated config into `process.env` for libraries that
+     * read it directly, so `env.ts` loads with `{ inject: true }` and penv places
+     * the framework's pre-app seam. Off by default and only ever turned on by an
+     * explicit yes — a project that reads config only through `@env` gets none.
+     */
+    readonly inject: boolean;
 }
 interface InitResult {
     readonly root: string;

package/dist/index.d.ts

@@ -250,14 +250,18 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore";
+type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
 /**
  * `conflicted` is the one that is not a success. penv wanted to write something,
  * found the user's file already saying something else about the same thing, and
  * left it alone — so the step is reported with a warning rather than a ✓, and the
  * text says what will not work until the user decides.
+ *
+ * `info` is a step penv did not perform automatically — a manual instruction (the
+ * injection seam for a framework penv cannot scaffold), reported so the user
+ * knows the one thing left to do.
  */
-type InitAction = "created" | "kept" | "updated" | "conflicted";
+type InitAction = "created" | "kept" | "updated" | "conflicted" | "info";
 interface InitStep {
     readonly target: InitTarget;
     readonly action: InitAction;
@@ -289,6 +293,13 @@ interface InitDecisions {
      * offers that.
      */
     readonly alias: string;
+    /**
+     * Whether to inject the validated config into `process.env` for libraries that
+     * read it directly, so `env.ts` loads with `{ inject: true }` and penv places
+     * the framework's pre-app seam. Off by default and only ever turned on by an
+     * explicit yes — a project that reads config only through `@env` gets none.
+     */
+    readonly inject: boolean;
 }
 interface InitResult {
     readonly root: string;

package/dist/index.js

@@ -350,19 +350,19 @@ import {
   refFromAccessPath as refFromAccessPath2,
   variableName
 } from "@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) {
@@ -372,38 +372,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)) {
@@ -420,13 +420,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;
   }
@@ -442,8 +442,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) {
@@ -1110,18 +1110,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";
@@ -2805,6 +2805,8 @@ import { join } from "path";
 import { DEFAULT_SCHEMA_FILE } from "@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"],
@@ -2878,17 +2880,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 (existsSync(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) {
@@ -2915,6 +2923,132 @@ import {
   validateSchemaFile
 } from "@penvhq/core";
 import { defineCommand as defineCommand9 } from "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 (see the note penv printed). 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.`
+    ]
+  };
+}
+function node({ alias, srcDir }) {
+  const runtimeSpecifier = alias.startsWith("#") ? alias : `./${srcDir}.penv/env.js`;
+  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(_context) {
+  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.'
+  };
+}
+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";
@@ -2924,6 +3058,7 @@ var IMPORTS_PREFIX = "#";
 var PACKAGE_FILE = "package.json";
 var DEFAULT_DECISIONS = {
   environments: [],
+  inject: false,
   schemaFile: DEFAULT_SCHEMA_FILE2,
   publicPrefixes: [],
   alias: DEFAULT_ALIAS
@@ -3042,6 +3177,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
@@ -3088,16 +3226,33 @@ 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;
   }
-  return { ...plan2.decisions, environments };
+  return { ...plan2.decisions, environments, inject };
+}
+function seamKindFor(plan2) {
+  return seamFor(plan2.detected?.name, {
+    alias: plan2.decisions.alias,
+    srcDir: plan2.decisions.schemaFile.startsWith("src/") ? "src/" : ""
+  }).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";
 
@@ -3107,11 +3262,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.
@@ -3403,7 +3554,7 @@ function writeSchemaFile(root, fields, draft, decisions = DEFAULT_DECISIONS) {
     };
   }
   mkdirSync(dirname3(file), { recursive: true });
-  writeFileSync2(file, renderSchemaModule(fields, draft), "utf8");
+  writeFileSync2(file, renderSchemaModule(fields, draft, decisions.inject), "utf8");
   return {
     target: "schema",
     action: "created",
@@ -3480,14 +3631,56 @@ function writeGitignore(root, decisions = DEFAULT_DECISIONS) {
     text: `${existing === void 0 ? "Created" : "Updated"} ${relative3}`
   };
 }
+function srcDirOf(root) {
+  return existsSync2(join2(root, "src")) ? "src/" : "";
+}
+function writeSeam(root, decisions = DEFAULT_DECISIONS) {
+  if (!decisions.inject) {
+    return void 0;
+  }
+  const framework = detectFramework(root)?.name;
+  const seam = seamFor(framework, { alias: decisions.alias, srcDir: srcDirOf(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: seam.instruction
+    };
+  }
+  const file = join2(root, ...seam.file.split("/"));
+  const notes = seam.notes.length === 0 ? "" : `
+${seam.notes.map((n) => `  ${n}`).join("\n")}`;
+  if (existsSync2(file)) {
+    return {
+      target: "seam",
+      action: "info",
+      text: `Add the injection seam to ${seam.file}`,
+      note: `${seam.ifPresent}${notes}`
+    };
+  }
+  mkdirSync(dirname3(file), { recursive: true });
+  writeFileSync2(file, seam.content, "utf8");
+  return {
+    target: "seam",
+    action: "created",
+    text: `Wrote ${seam.file} (runs the injection before your app)`,
+    ...notes === "" ? {} : { note: notes.trimStart() }
+  };
+}
 function scaffold(root, fields, draft, decisions = DEFAULT_DECISIONS) {
-  return [
+  const steps = [
     ensurePenvDir(root),
     writeSchemaFile(root, fields, draft, decisions),
     writeConfigFile(root, decisions),
     writeTsconfigAlias(root, decisions),
     writeGitignore(root, decisions)
   ];
+  const seam = writeSeam(root, decisions);
+  return seam === void 0 ? steps : [...steps, seam];
 }
 function runInit(options) {
   const root = resolve4(options.cwd);
@@ -3496,7 +3689,7 @@ function runInit(options) {
 }
 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 [
@@ -3729,6 +3922,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: schemaFileOf3(config),
     publicPrefixes: config.publicPrefixes ?? [],
     alias: detectAlias(cwd)