celery-env 0.1.2 → 0.1.3

package/README.md

@@ -44,7 +44,16 @@ bun add -d celery-env
 
 ## 60-Second Setup
 
-Create a schema:
+Infer a schema from existing env files and source references:
+
+```sh
+npx celery-env infer --schema env.schema.mjs
+```
+
+This writes a starter schema and refuses overwrite unless you pass `--force`.
+Review it before generating; inference cannot know every production-only rule.
+
+Or create a schema manually:
 
 ```js
 // env.schema.mjs
@@ -85,8 +94,8 @@ export const env = loadEnv(process.env);
 Celery validates the env object you pass. Load `.env` with your platform,
 shell, or `dotenv` before calling `loadEnv`.
 
-That is the main path: write `env.schema.mjs`, generate `src/env.mjs`, and use
-the typed result everywhere else.
+That is the main path: infer or write `env.schema.mjs`, generate `src/env.mjs`,
+and use the typed result everywhere else.
 
 ## When To Use Celery
 
@@ -157,25 +166,25 @@ The benchmark corpus includes realistic API, web, worker, list-heavy, and
 JSON-heavy env schemas. Results are workload-specific; real `process.env` access
 narrows some gaps compared with frozen plain env objects.
 
-Current npm package metadata:
+Package metadata snapshot. Celery is this branch's `npm pack --dry-run`;
+competitors were checked with `npm view` on 2026-06-25.
 
 | Package | Version checked | Runtime deps | Unpacked npm size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
 | `envsafe` | 2.0.3 | 0 | 91.4 kB | 27 |
 | `env-var` | 7.5.0 | 0 | 42.9 kB | 30 |
 
-Metadata checked with `npm view` on 2026-06-25.
-
 ## Documentation
 
 - [Getting Started](docs/GETTING_STARTED.md)
 - [Schema API](docs/SCHEMA.md)
 - [CLI](docs/CLI.md)
 - [TypeScript](docs/TYPESCRIPT.md)
+- [Examples](docs/EXAMPLES.md)
 - [Runtime Mode](docs/RUNTIME.md)
 - [Comparison](docs/COMPARISON.md)
 - [Troubleshooting](docs/TROUBLESHOOTING.md)

package/docs/BENCHMARKS.md

@@ -68,12 +68,12 @@ Snapshot dependency versions:
 
 ## Package Metadata
 
-Package footprint is separate from runtime speed. Current npm metadata checked
-on 2026-06-25:
+Package footprint is separate from runtime speed. Celery is this branch's
+`npm pack --dry-run`; competitors were checked with `npm view` on 2026-06-25.
 
 | Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
@@ -89,6 +89,10 @@ The published package intentionally does not ship the local benchmark lab or
 competitor dependencies. Public docs keep the benchmark summary and claim rules
 so the npm package stays small and dependency-free.
 
+The local benchmark lab lives outside the published package. A refresh should
+rerun the benchmark corpus, then update only the summarized public tables and
+metadata in this document and the README.
+
 When refreshing claims, record:
 
 - `celery-env` version or commit;

package/docs/CLI.md

@@ -19,6 +19,32 @@ Targets:
 | `next` | Next.js projects. |
 | `vite` | Vite projects and edge-style environments. |
 
+## Infer A Schema
+
+```sh
+npx celery-env infer --schema env.schema.mjs
+```
+
+Use `infer` when a project already has `.env` files or source code that reads
+env vars. It discovers `.env.example`, `.env`, `.env.local`, and common source
+directories by default. It writes a starter schema and refuses overwrite unless
+you pass `--force`.
+
+You can pass sources explicitly:
+
+```sh
+npx celery-env infer \
+  --schema env.schema.mjs \
+  --env .env.example \
+  --scan src
+```
+
+Inference is conservative. Ambiguous values become `str({ min: 1 })`. Only
+example, sample, or template env files can emit `example` metadata; local env
+values and secret-looking values are not copied into the generated schema.
+Review the result for project-specific constraints such as `requiredWhen`,
+`min`, `max`, or stricter URL protocols.
+
 ## Generate
 
 ```sh
@@ -31,7 +57,17 @@ npx celery-env generate \
 
 Use `generate` after editing `env.schema.mjs`.
 
-## Flags
+## Infer Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--schema <file>` | Schema file to write. |
+| `--env <file>` | Env file to read for `infer`. Repeatable. |
+| `--scan <path>` | File or directory to scan for `infer`. Repeatable. |
+| `--force` | Overwrite an existing schema file. |
+| `--version`, `-v` | Print the installed CLI version. |
+
+## Generate Flags
 
 | Flag | Meaning |
 | --- | --- |

package/docs/COMPARISON.md

@@ -16,10 +16,12 @@ tool for environment configuration.
 ## Celery vs Zod
 
 Zod is excellent for general TypeScript validation: forms, API payloads,
-domain objects, JSON data, and reusable schemas across an app.
+domain objects, JSON data, and reusable schemas across an app. If your team
+already uses Zod, keep it for those jobs.
 
 Celery is narrower. It validates `process.env`, then can generate a standalone
-validator and declaration file for production startup.
+validator and declaration file for production startup. It is designed to sit
+beside Zod, not replace it.
 
 | Question | Celery | Zod |
 | --- | --- | --- |
@@ -32,8 +34,24 @@ validator and declaration file for production startup.
 | Secret-safe env errors | Built in. | Build yourself. |
 | Ecosystem size | Small and focused. | Large and mature. |
 
-Use Zod when you need general validation. Use Celery when the thing being
-validated is application configuration.
+Use both when that is the cleanest architecture: Zod for request bodies,
+forms, and domain objects; Celery for process configuration that should be
+validated once at startup.
+
+## Using Celery Alongside Zod
+
+Keep the boundary simple:
+
+```js
+// src/env.mjs is generated by celery-env.
+import { loadEnv } from "./env.mjs";
+
+export const env = loadEnv(process.env);
+```
+
+Then pass `env` into the rest of the app. Zod schemas should not read
+`process.env` directly; they should receive already-validated config when they
+need it.
 
 ## Celery vs Envalid / Envsafe / env-var
 
@@ -71,19 +89,18 @@ Celery's main difference is generated mode:
 
 ## Package Footprint
 
-This table is npm package metadata, not benchmark speed:
+This table is package metadata, not benchmark speed. Celery is this branch's
+`npm pack --dry-run`; competitors were checked with `npm view` on 2026-06-25.
 
 | Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
 | `envsafe` | 2.0.3 | 0 | 91.4 kB | 27 |
 | `env-var` | 7.5.0 | 0 | 42.9 kB | 30 |
 
-Checked with `npm view` on 2026-06-25.
-
 ## What Celery Does Not Do
 
 - It does not load `.env` files. Use your platform, shell, or a dotenv loader.

package/docs/EXAMPLES.md

@@ -0,0 +1,50 @@
+# Examples
+
+The examples directory contains small schema fixtures that mirror common app
+setups. They are intentionally plain JavaScript so they work in TypeScript and
+JavaScript projects.
+
+## Plain Node Service
+
+Use [`examples/node-service/env.schema.mjs`](../examples/node-service/env.schema.mjs)
+for API services, workers, and CLIs.
+
+```sh
+npx celery-env generate \
+  --schema examples/node-service/env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts \
+  --example .env.example \
+  --minify
+```
+
+Validate once at startup:
+
+```js
+import { loadEnv } from "./env.mjs";
+
+export const env = loadEnv(process.env);
+```
+
+## Next.js-Style Schema
+
+Use [`examples/next/env.schema.mjs`](../examples/next/env.schema.mjs) when a
+project has server-only variables and `NEXT_PUBLIC_` browser variables.
+
+Generate the validator during development and import the generated output only
+from server startup or server-only modules. Celery does not load `.env` files;
+let Next.js, your platform, or a dotenv loader populate `process.env` first.
+
+## Runtime-Only Fallback
+
+Use runtime mode when generation is not practical yet:
+
+```js
+import schema from "./env.schema.mjs";
+import { parseEnv } from "celery-env";
+
+export const env = parseEnv(schema, process.env);
+```
+
+Generated mode remains the recommended production path because it avoids loading
+the schema library at startup.

package/docs/GETTING_STARTED.md

@@ -17,9 +17,26 @@ bun add -d celery-env
 Generated validators do not need `celery-env` at runtime, so most apps install
 it as a dev dependency.
 
+Check the CLI version when debugging local installs:
+
+```sh
+npx celery-env --version
+```
+
 ## 2. Create A Schema
 
-Create `env.schema.mjs`:
+If your project already has `.env` files or `process.env` references, infer a
+starter schema:
+
+```sh
+npx celery-env infer --schema env.schema.mjs
+```
+
+This reads `.env.example`, `.env`, `.env.local`, and common source directories.
+It writes a starter schema and refuses overwrite unless you pass `--force`.
+Review it for project-specific rules such as production-only secrets, ranges,
+or stricter URL protocols.
+You can also create `env.schema.mjs` manually:
 
 ```js
 import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
@@ -75,7 +92,8 @@ Add a script so generation is repeatable:
 ```json
 {
   "scripts": {
-    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify --force"
+    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify --force",
+    "env:check": "npm run env:generate && git diff --exit-code src/env.mjs src/env.d.ts .env.example"
   }
 }
 ```
@@ -138,8 +156,7 @@ npm run env:generate
 In CI, verify generated files are current:
 
 ```sh
-npm run env:generate
-git diff --exit-code src/env.mjs src/env.d.ts .env.example
+npm run env:check
 ```
 
 ## Next Steps

package/docs/MIGRATION.md

@@ -2,7 +2,16 @@
 
 Use this guide when adding Celery to an existing app.
 
-## Step 1. Find Env Reads
+## Step 1. Infer A Starter Schema
+
+```sh
+npx celery-env infer --schema env.schema.mjs
+```
+
+This reads existing env files and static source references. Review the generated
+schema before using it in production.
+
+## Step 2. Find Env Reads
 
 Search for direct env access:
 
@@ -12,7 +21,7 @@ rg "process\\.env|env\\.[A-Z_]+"
 
 The goal is one central module that reads env and exports validated config.
 
-## Step 2. Write A Flat Schema
+## Step 3. Tighten The Flat Schema
 
 Keep schema keys close to actual env var names:
 
@@ -26,13 +35,13 @@ export default defineEnv({
 });
 ```
 
-## Step 3. Generate
+## Step 4. Generate
 
 ```sh
 npx celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify
 ```
 
-## Step 4. Keep Your Existing Shape
+## Step 5. Keep Your Existing Shape
 
 If your app already expects nested config, adapt once:
 
@@ -49,6 +58,6 @@ export function loadConfig(source = process.env) {
 }
 ```
 
-## Step 5. Remove Direct Env Reads
+## Step 6. Remove Direct Env Reads
 
 Use the validated config everywhere else.

package/docs/README.md

@@ -4,12 +4,14 @@ Start here if you are new to Celery or new to typed env validation.
 
 ## Learning Path
 
-1. [Getting Started](GETTING_STARTED.md): install, write a schema, generate a validator.
+1. [Getting Started](GETTING_STARTED.md): install, infer or write a schema, generate a validator.
 2. [Schema API](SCHEMA.md): every validator and option.
-3. [CLI](CLI.md): `init`, `generate`, and generation flags.
+3. [CLI](CLI.md): `init`, `infer`, `generate`, and command flags.
 4. [TypeScript](TYPESCRIPT.md): generated types and `InferEnv`.
 5. [Runtime Mode](RUNTIME.md): use Celery without generation.
-6. [Comparison](COMPARISON.md): when to choose Celery, Zod, Envalid, Envsafe, or runtime-only env validators.
-7. [Troubleshooting](TROUBLESHOOTING.md): common setup and generation issues.
-8. [Migration Guide](MIGRATION.md): add Celery to an existing project.
-9. [Benchmarks](BENCHMARKS.md): what is measured and what claims are safe.
+6. [Examples](EXAMPLES.md): Node service and Next.js-style schemas.
+7. [Comparison](COMPARISON.md): when to choose Celery, Zod, Envalid, Envsafe, or runtime-only env validators.
+8. [Troubleshooting](TROUBLESHOOTING.md): common setup and generation issues.
+9. [Migration Guide](MIGRATION.md): add Celery to an existing project.
+10. [Benchmarks](BENCHMARKS.md): what is measured and what claims are safe.
+11. [Release Checklist](RELEASE.md): maintainer publishing steps.

package/docs/RELEASE.md

@@ -0,0 +1,60 @@
+# Release Checklist
+
+Use this when publishing a new npm version.
+
+## Before Publishing
+
+1. Update `package.json`.
+2. Add a matching `CHANGELOG.md` section.
+3. Refresh package metadata tables if packed size or file count changed.
+4. Run:
+
+```sh
+npm run release:check
+npm run ci
+```
+
+`release:check` verifies the changelog entry, checks that the version is not
+already on npm, and dry-runs the package contents.
+
+## Publish
+
+```sh
+npm publish --access public
+```
+
+If npm asks for browser or one-time-password authentication, finish that prompt
+in the browser and rerun the same command if needed.
+
+If npm reports a cache ownership or permission error, do not change package
+files to work around it. Use a temporary cache for the publish command:
+
+```sh
+npm --cache /tmp/celery-npm-cache publish --access public
+```
+
+## After Publishing
+
+1. Verify npm:
+
+```sh
+npm view celery-env version dist.unpackedSize dist.fileCount
+```
+
+2. Smoke-test a fresh install:
+
+```sh
+npm install celery-env@latest --prefix /tmp/celery-smoke
+```
+
+3. Tag the release:
+
+```sh
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+4. Create a GitHub Release from the tag with the changelog bullets.
+
+Keep publishing manual until npm provenance and release permissions are designed
+explicitly.

package/examples/env.schema.mjs

@@ -0,0 +1,9 @@
+import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: url({ protocols: ["postgres", "postgresql"] }),
+  PORT: int({ default: 3000, min: 1, max: 65535 }),
+  DEBUG: bool({ default: false }),
+  API_KEY: str({ min: 8 })
+});

package/examples/next/env.schema.mjs

@@ -0,0 +1,20 @@
+import { bool, defineEnv, oneOf, str, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: url({
+    protocols: ["postgres", "postgresql"],
+    desc: "Server-only database connection string."
+  }),
+  NEXT_PUBLIC_APP_URL: url({
+    protocols: ["https"],
+    desc: "Browser-visible application origin.",
+    example: "https://app.example.com"
+  }),
+  NEXT_PUBLIC_ANALYTICS: bool({ default: false }),
+  SESSION_SECRET: str({
+    optional: true,
+    min: 32,
+    requiredWhen: (env) => env.NODE_ENV === "production"
+  })
+});

package/examples/node-service/env.schema.mjs

@@ -0,0 +1,19 @@
+import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: url({
+    protocols: ["postgres", "postgresql"],
+    desc: "Primary database connection string.",
+    example: "postgres://user:pass@localhost:5432/app"
+  }),
+  PORT: int({ default: 3000, min: 1, max: 65535 }),
+  LOG_LEVEL: oneOf(["debug", "info", "warn", "error"], { default: "info" }),
+  QUEUE_ENABLED: bool({ default: false }),
+  SESSION_SECRET: str({
+    optional: true,
+    min: 32,
+    requiredWhen: (env) => env.NODE_ENV === "production",
+    desc: "Required for production sessions."
+  })
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "celery-env",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Type-safe process.env validation that generates zero-dependency standalone validators.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -31,6 +31,7 @@
   "files": [
     "src/index.js",
     "src/compiler.js",
+    "src/infer.js",
     "src/index.d.ts",
     "src/compiler.d.ts",
     "src/cli.js",
@@ -38,13 +39,18 @@
     "docs/BENCHMARKS.md",
     "docs/CLI.md",
     "docs/COMPARISON.md",
+    "docs/EXAMPLES.md",
     "docs/GETTING_STARTED.md",
     "docs/MIGRATION.md",
     "docs/README.md",
+    "docs/RELEASE.md",
     "docs/RUNTIME.md",
     "docs/SCHEMA.md",
     "docs/TROUBLESHOOTING.md",
     "docs/TYPESCRIPT.md",
+    "examples/env.schema.mjs",
+    "examples/node-service/env.schema.mjs",
+    "examples/next/env.schema.mjs",
     "SECURITY.md",
     "README.md",
     "LICENSE"
@@ -56,6 +62,7 @@
     "security:scan": "node scripts/security-scan.mjs && npm run prepublishOnly",
     "validate:publish": "node scripts/validate-publish.mjs",
     "smoke:pack": "node scripts/smoke-pack.mjs",
+    "release:check": "node scripts/release-check.mjs",
     "prepublishOnly": "npm test && npm run size && npm run validate:publish && npm run smoke:pack",
     "demo:generate": "node src/cli.js --schema examples/env.schema.mjs --out .tmp/generated/env.mjs --types .tmp/generated/env.d.ts"
   },

package/src/cli.js

@@ -16,6 +16,8 @@ if (args.version) {
 
 if (args.command === "init") {
   await init(args);
+} else if (args.command === "infer") {
+  await infer(args);
 } else {
   await generate(args);
 }
@@ -59,14 +61,24 @@ async function init(args) {
   await writeFile(schemaPath, source, { encoding: "utf8", flag: "wx" });
 }
 
+async function infer(args) {
+  if (!args.schema) usage(1);
+  const schemaPath = resolve(args.schema);
+  const { inferSchemaSource } = await import("./infer.js");
+  await mkdir(dirname(schemaPath), { recursive: true });
+  await writeOutput(schemaPath, await inferSchemaSource({ envFiles: args.envFiles, scanPaths: args.scanPaths }), args.force);
+}
+
 function parseArgs(argv) {
   const out = { command: "generate", functionName: "loadEnv" };
-  if (argv[0] === "generate" || argv[0] === "init") out.command = argv.shift();
+  if (argv[0] === "generate" || argv[0] === "init" || argv[0] === "infer") out.command = argv.shift();
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") out.help = true;
     else if (arg === "--version" || arg === "-v") out.version = true;
     else if (arg === "--schema") out.schema = argv[++i];
+    else if (arg === "--env") (out.envFiles ||= []).push(argv[++i]);
+    else if (arg === "--scan") (out.scanPaths ||= []).push(argv[++i]);
     else if (arg === "--target") out.target = argv[++i];
     else if (arg === "--out") out.out = argv[++i];
     else if (arg === "--types") out.types = argv[++i];
@@ -138,6 +150,7 @@ function usage(code) {
   console.log(`Usage:
   celery-env --schema env.schema.mjs --out src/env.mjs [--types src/env.d.ts]
   celery-env generate --schema env.schema.mjs --out src/env.mjs [--types src/env.d.ts] [--example .env.example] [--force] [--optimize speed]
+  celery-env infer --schema env.schema.mjs [--env .env.example] [--scan src] [--force]
   celery-env init --target node|next|vite --schema env.schema.mjs
   celery-env --version`);
   process.exit(code);

package/src/infer.js

@@ -0,0 +1,400 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const JS_IDENT = /^[$A-Z_a-z][$\w]*$/;
+const SOURCE_EXTENSIONS = new Set([".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".svelte", ".ts", ".tsx", ".vue"]);
+const SKIP_DIRS = new Set([".git", ".next", ".nuxt", ".output", ".tmp", "build", "coverage", "dist", "node_modules"]);
+const DEFAULT_ENV_FILES = [".env.example", ".env", ".env.local"];
+const DEFAULT_SCAN_PATHS = ["src", "app", "pages", "lib", "server"];
+const BOOL_VALUES = new Set(["true", "yes", "on", "false", "no", "off"]);
+const SECRET_KEY = /(?:SECRET|TOKEN|PASSWORD|PASS|PRIVATE|CREDENTIAL|AUTH|API_KEY|ACCESS_KEY)/i;
+const SECRET_VALUE = /(?:^sk_|^pk_|^gh[pousr]_|^xox[baprs]-|^eyJ|-----BEGIN |:\/\/[^/\s:@]+:[^/\s:@]+@|[A-Za-z0-9+/=_-]{32,})/;
+const MAX_ENV_FILE_BYTES = 256 * 1024;
+const MAX_SOURCE_FILE_BYTES = 1024 * 1024;
+const MAX_SOURCE_FILES = 2000;
+const MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+const MAX_SCAN_DEPTH = 32;
+
+export async function inferSchemaSource(options = {}) {
+  const cwd = resolve(options.cwd || process.cwd());
+  const explicitEnvFiles = options.envFiles?.length;
+  const explicitScanPaths = options.scanPaths?.length;
+  const envFiles = explicitEnvFiles ? resolveAll(cwd, options.envFiles) : await discoverExisting(cwd, DEFAULT_ENV_FILES);
+  const scanPaths = explicitScanPaths ? resolveAll(cwd, options.scanPaths) : await discoverExisting(cwd, DEFAULT_SCAN_PATHS);
+  const entries = new Map();
+
+  for (const file of envFiles) {
+    const source = await readEnvFile(file);
+    const safeExamples = isExampleEnvFile(file);
+    for (const item of parseEnvSource(source)) {
+      record(entries, item.key, { value: item.value, safeExamples });
+    }
+  }
+
+  for (const file of await sourceFiles(scanPaths, { rejectRootSymlinks: Boolean(explicitScanPaths) })) {
+    const source = await readFile(file, "utf8");
+    for (const key of scanEnvKeys(source)) {
+      record(entries, key, { codeOnly: true });
+    }
+  }
+
+  if (!entries.size) {
+    throw new Error("No environment variables found; pass --env or --scan");
+  }
+
+  return generateSchemaModule(entries);
+}
+
+export function parseEnvSource(source) {
+  const out = [];
+  for (const raw of source.replace(/^\uFEFF/, "").split(/\r?\n/)) {
+    const parsed = parseEnvLine(raw);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+export function scanEnvKeys(source) {
+  const keys = new Set();
+  collectMatches(keys, source, /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1);
+  collectMatches(keys, source, /\bimport\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1);
+  collectMatches(keys, source, /\bprocess\.env\[\s*(["'`])([A-Za-z_][A-Za-z0-9_]*)\1\s*\]/g, 2);
+  collectMatches(keys, source, /\bimport\.meta\.env\[\s*(["'`])([A-Za-z_][A-Za-z0-9_]*)\1\s*\]/g, 2);
+
+  for (const match of source.matchAll(/\{([^}]+)\}\s*=\s*process\.env\b/g)) {
+    for (const key of destructuredKeys(match[1])) keys.add(key);
+  }
+  for (const match of source.matchAll(/\{([^}]+)\}\s*=\s*import\.meta\.env\b/g)) {
+    for (const key of destructuredKeys(match[1])) keys.add(key);
+  }
+
+  return [...keys].sort();
+}
+
+function parseEnvLine(line) {
+  let text = line.trim();
+  if (!text || text.startsWith("#")) return;
+  if (text.startsWith("export ")) text = text.slice(7).trimStart();
+
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(text);
+  if (!match) return;
+
+  const key = match[1];
+  let value = match[2] ?? "";
+  if (!ENV_NAME.test(key)) return;
+  value = parseEnvValue(value);
+  return { key, value };
+}
+
+function parseEnvValue(raw) {
+  const value = raw.trim();
+  if (!value) return "";
+  const quote = value[0];
+  if (quote === "'" || quote === "\"" || quote === "`") {
+    let end = 1;
+    let escaped = false;
+    for (; end < value.length; end++) {
+      const char = value[end];
+      if (escaped) {
+        escaped = false;
+      } else if (quote !== "'" && char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        break;
+      }
+    }
+    const inner = value.slice(1, end);
+    return quote === "'" ? inner : unescapeQuoted(inner);
+  }
+  return stripInlineComment(value).trim();
+}
+
+function unescapeQuoted(value) {
+  return value.replace(/\\([nrt"\\`])/g, (_, char) => {
+    if (char === "n") return "\n";
+    if (char === "r") return "\r";
+    if (char === "t") return "\t";
+    return char;
+  });
+}
+
+function stripInlineComment(value) {
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] === "#" && (i === 0 || /\s/.test(value[i - 1]))) return value.slice(0, i);
+  }
+  return value;
+}
+
+function collectMatches(keys, source, pattern, group) {
+  for (const match of source.matchAll(pattern)) keys.add(match[group]);
+}
+
+function destructuredKeys(source) {
+  const keys = [];
+  for (const raw of source.split(",")) {
+    const item = raw.trim();
+    if (!item || item.startsWith("...")) continue;
+    const key = item.split(/[:=]/, 1)[0].trim();
+    if (ENV_NAME.test(key)) keys.push(key);
+  }
+  return keys;
+}
+
+async function discoverExisting(cwd, names) {
+  const out = [];
+  for (const name of names) {
+    const path = resolve(cwd, name);
+    if (await exists(path)) out.push(path);
+  }
+  return out;
+}
+
+function resolveAll(cwd, paths) {
+  return paths.map((path) => resolve(cwd, path));
+}
+
+async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function readEnvFile(path) {
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") throw new Error(`${path} does not exist`);
+    throw error;
+  }
+  if (info.isSymbolicLink()) throw new Error(`${path} is a symlink; refusing to read`);
+  if (!info.isFile()) throw new Error(`${path} is not a file`);
+  if (info.size > MAX_ENV_FILE_BYTES) throw new Error(`${path} is too large for env inference: ${info.size} > ${MAX_ENV_FILE_BYTES} bytes`);
+  return readFile(path, "utf8");
+}
+
+async function sourceFiles(paths, options = {}) {
+  const out = [];
+  const state = { files: 0, bytes: 0 };
+  for (const path of paths) {
+    await collectSourceFiles(out, path, state, 0, options.rejectRootSymlinks);
+  }
+  return out.sort();
+}
+
+async function collectSourceFiles(out, path, state, depth, rejectSymlink) {
+  if (depth > MAX_SCAN_DEPTH) throw new Error(`${path} exceeds scan depth limit: ${depth} > ${MAX_SCAN_DEPTH}`);
+
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+
+  if (info.isSymbolicLink()) {
+    if (rejectSymlink) throw new Error(`${path} is a symlink; refusing to scan`);
+    return;
+  }
+
+  if (info.isDirectory()) {
+    if (SKIP_DIRS.has(basename(path))) return;
+    for (const entry of await readdir(path)) {
+      await collectSourceFiles(out, join(path, entry), state, depth + 1, false);
+    }
+    return;
+  }
+
+  if (!info.isFile() || !SOURCE_EXTENSIONS.has(extname(path))) return;
+  if (info.size > MAX_SOURCE_FILE_BYTES) throw new Error(`${path} is too large for source inference: ${info.size} > ${MAX_SOURCE_FILE_BYTES} bytes`);
+  state.files += 1;
+  state.bytes += info.size;
+  if (state.files > MAX_SOURCE_FILES) throw new Error(`source scan found too many files: ${state.files} > ${MAX_SOURCE_FILES}`);
+  if (state.bytes > MAX_SOURCE_BYTES) throw new Error(`source scan is too large: ${state.bytes} > ${MAX_SOURCE_BYTES} bytes`);
+  out.push(path);
+}
+
+function record(entries, key, source) {
+  let entry = entries.get(key);
+  if (!entry) {
+    entry = { key, values: [], code: false };
+    entries.set(key, entry);
+  }
+  if (source.codeOnly) entry.code = true;
+  else entry.values.push({ value: source.value, safeExamples: source.safeExamples });
+}
+
+function generateSchemaModule(entries) {
+  const keys = [...entries.keys()].sort();
+  const rules = keys.map((key) => [key, inferRule(entries.get(key))]);
+  const imports = new Set(["defineEnv"]);
+  for (const [, rule] of rules) collectRuleImports(imports, rule);
+
+  const lines = [
+    `import { ${[...imports].sort(importSort).join(", ")} } from "celery-env";`,
+    "",
+    "export default defineEnv({"
+  ];
+
+  for (let i = 0; i < rules.length; i++) {
+    const [key, rule] = rules[i];
+    lines.push(`  ${schemaKey(key)}: ${ruleSource(rule)}${i === rules.length - 1 ? "" : ","}`);
+  }
+
+  lines.push("});", "");
+  return lines.join("\n");
+}
+
+function inferRule(entry) {
+  if (entry.key === "NODE_ENV") {
+    return { kind: "oneOf", values: ["development", "test", "production"], options: { default: "development" } };
+  }
+
+  const samples = entry.values.map((item) => item.value).filter((value) => value !== "");
+  if (!samples.length) return { kind: "str", options: { min: 1 } };
+
+  const kinds = samples.map(inferValue);
+  if (kinds.some((kind) => kind.kind === "str")) return stringRule(entry);
+
+  const first = kinds[0].kind;
+  if (!kinds.every((kind) => kind.kind === first)) return stringRule(entry);
+
+  const rule = mergeRules(first, kinds);
+  const example = safeExample(entry, rule);
+  if (example !== undefined) rule.options = { ...rule.options, example };
+  return rule;
+}
+
+function inferValue(value) {
+  if (BOOL_VALUES.has(value)) return { kind: "bool" };
+  if (strictInt(value)) return { kind: "int", options: { strict: true } };
+  if (strictNumber(value)) return { kind: "num", options: { strict: true } };
+  const jsonRule = inferJson(value);
+  if (jsonRule) return jsonRule;
+  const listRule = inferList(value);
+  if (listRule) return listRule;
+  const urlRule = inferUrl(value);
+  if (urlRule) return urlRule;
+  return { kind: "str", options: { min: 1 } };
+}
+
+function inferJson(value) {
+  if (!/^\s*[\[{]/.test(value)) return;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object") return { kind: "json" };
+  } catch {}
+}
+
+function inferList(value) {
+  if (!value.includes(",") || /^\s*[\[{]/.test(value)) return;
+  const parts = value.split(",").map((part) => part.trim());
+  if (parts.length < 2 || parts.some((part) => part === "")) return;
+  const items = parts.map((part) => {
+    if (BOOL_VALUES.has(part)) return { kind: "bool" };
+    if (strictInt(part)) return { kind: "int", options: { strict: true } };
+    if (strictNumber(part)) return { kind: "num", options: { strict: true } };
+    const urlRule = inferUrl(part);
+    return urlRule || { kind: "str" };
+  });
+  const first = items[0].kind;
+  if (first === "str" || !items.every((item) => item.kind === first)) return;
+  return { kind: "list", item: mergeRules(first, items) };
+}
+
+function inferUrl(value) {
+  try {
+    const url = new URL(value);
+    if (!url.protocol) return;
+    return { kind: "url", options: { protocols: [url.protocol.slice(0, -1)] } };
+  } catch {}
+}
+
+function strictInt(value) {
+  return /^[+-]?\d+$/.test(value) && Number.isSafeInteger(Number(value));
+}
+
+function strictNumber(value) {
+  if (!/^[+-]?(?:\d+\.\d*|\.\d+|\d+)$/.test(value)) return false;
+  return Number.isFinite(Number(value));
+}
+
+function mergeRules(kind, rules) {
+  if (kind === "url") {
+    return {
+      kind: "url",
+      options: { protocols: [...new Set(rules.flatMap((rule) => rule.options?.protocols || []))].sort() }
+    };
+  }
+  if (kind === "list") {
+    const itemKind = rules[0].item.kind;
+    return { kind: "list", item: mergeRules(itemKind, rules.map((rule) => rule.item)) };
+  }
+  if (kind === "int" || kind === "num") return { kind, options: { strict: true } };
+  return { kind };
+}
+
+function stringRule(entry) {
+  const rule = { kind: "str", options: { min: 1 } };
+  const example = safeExample(entry, rule);
+  if (example !== undefined) rule.options.example = example;
+  return rule;
+}
+
+function safeExample(entry, rule) {
+  const sample = entry.values.find((item) => item.safeExamples && item.value !== "");
+  if (!sample || SECRET_KEY.test(entry.key) || SECRET_VALUE.test(sample.value)) return;
+  return exampleValue(sample.value, rule);
+}
+
+function exampleValue(value, rule) {
+  if (rule.kind === "bool") return value === "true" || value === "1" || value === "yes" || value === "on";
+  if (rule.kind === "int" || rule.kind === "num") return Number(value);
+  if (rule.kind === "json") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return;
+    }
+  }
+  if (rule.kind === "list") return value.split(",").map((part) => exampleValue(part.trim(), rule.item));
+  return value;
+}
+
+function collectRuleImports(imports, rule) {
+  imports.add(rule.kind);
+  if (rule.kind === "list") collectRuleImports(imports, rule.item);
+}
+
+function ruleSource(rule) {
+  if (rule.kind === "oneOf") return `oneOf(${literal(rule.values)}, ${literal(rule.options)})`;
+  if (rule.kind === "list") {
+    const item = ruleSource(rule.item);
+    return rule.options && Object.keys(rule.options).length ? `list(${item}, ${literal(rule.options)})` : `list(${item})`;
+  }
+  if (rule.options && Object.keys(rule.options).length) return `${rule.kind}(${literal(rule.options)})`;
+  return `${rule.kind}()`;
+}
+
+function schemaKey(key) {
+  return JS_IDENT.test(key) && key !== "__proto__" ? key : JSON.stringify(key);
+}
+
+function literal(value) {
+  return JSON.stringify(value);
+}
+
+function importSort(a, b) {
+  return a.localeCompare(b);
+}
+
+function isExampleEnvFile(path) {
+  const name = basename(path).toLowerCase();
+  return name.includes("example") || name.includes("sample") || name.includes("template");
+}