@wchen.ai/env-from-example 1.0.0

package/dist/test/unit/setup-env.test.js

@@ -0,0 +1,236 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs';
+import { getRootDirFromArgv, parseEnvExample, getExistingEnvVersion, getExistingEnvVariables, serializeEnvExample, polishEnvExample, bumpSemver, updateEnvSchemaVersion, } from '../../setup-env.js';
+const FIXTURES_DIR = path.resolve(__dirname, '../fixtures');
+describe('getRootDirFromArgv', () => {
+    const originalArgv = process.argv;
+    afterEach(() => {
+        process.argv = originalArgv;
+    });
+    it('returns process.cwd() when --cwd is not present', () => {
+        process.argv = ['node', 'setup-env.js'];
+        expect(getRootDirFromArgv()).toBe(process.cwd());
+    });
+    it('returns resolved path when --cwd is present with value', () => {
+        process.argv = ['node', 'setup-env.js', '--cwd', '/some/project'];
+        expect(getRootDirFromArgv()).toBe(path.resolve('/some/project'));
+    });
+    it('returns process.cwd() when --cwd is last (no value)', () => {
+        process.argv = ['node', 'setup-env.js', '--yes', '--cwd'];
+        expect(getRootDirFromArgv()).toBe(process.cwd());
+    });
+    it('returns resolved path for relative --cwd', () => {
+        process.argv = ['node', 'setup-env.js', '--cwd', './fixtures/full'];
+        const result = getRootDirFromArgv();
+        expect(path.isAbsolute(result)).toBe(true);
+        expect(result).toMatch(/fixtures[\\/]full$/);
+    });
+});
+describe('parseEnvExample', () => {
+    it('throws when .env.example does not exist', () => {
+        expect(() => parseEnvExample('/nonexistent/dir')).toThrow(/.env.example not found at/);
+    });
+    it('parses full fixture: version, sections, required, commented-out', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'full');
+        const { version, variables } = parseEnvExample(rootDir);
+        expect(version).toBe('1.0');
+        const keys = variables.map((v) => v.key);
+        expect(keys).toContain('DATABASE_URL');
+        expect(keys).toContain('DATABASE_POOL_SIZE');
+        expect(keys).toContain('API_KEY');
+        expect(keys).toContain('API_SECRET');
+        expect(keys).toContain('API_BASE_URL');
+        expect(keys).toContain('NODE_ENV');
+        expect(keys).toContain('SESSION_SECRET');
+        expect(keys).toContain('FEATURE_BETA');
+        expect(keys).toContain('PORT');
+        const databaseUrl = variables.find((v) => v.key === 'DATABASE_URL');
+        expect(databaseUrl.defaultValue).toBe('postgres://localhost:5432/myapp');
+        expect(databaseUrl.required).toBe(true);
+        expect(databaseUrl.isCommentedOut).toBe(false);
+        expect(databaseUrl.comment).toMatch(/Postgres|REQUIRED/);
+        const apiBaseUrl = variables.find((v) => v.key === 'API_BASE_URL');
+        expect(apiBaseUrl.defaultValue).toBe('https://api.example.com/v1');
+        const featureBeta = variables.find((v) => v.key === 'FEATURE_BETA');
+        expect(featureBeta.isCommentedOut).toBe(true);
+        expect(featureBeta.defaultValue).toBe('false');
+        const port = variables.find((v) => v.key === 'PORT');
+        expect(port.isCommentedOut).toBe(true);
+        expect(port.defaultValue).toBe('3000');
+    });
+    it('parses minimal fixture with version', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'minimal');
+        const { version, variables } = parseEnvExample(rootDir);
+        expect(version).toBe('2.0');
+        expect(variables).toHaveLength(2);
+        const nodeEnv = variables.find((v) => v.key === 'NODE_ENV');
+        expect(nodeEnv.defaultValue).toBe('development');
+        expect(nodeEnv.required).toBe(false);
+        const someKey = variables.find((v) => v.key === 'SOME_KEY');
+        expect(someKey.defaultValue).toBe('default_value');
+    });
+    it('parses required-only fixture', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'required-only');
+        const { version, variables } = parseEnvExample(rootDir);
+        expect(version).toBe('1.0');
+        expect(variables).toHaveLength(1);
+        expect(variables[0].key).toBe('REQUIRED_VAR');
+        expect(variables[0].required).toBe(true);
+        expect(variables[0].defaultValue).toBe('');
+    });
+    it('parses no-version fixture: version is null', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'no-version');
+        const { version, variables } = parseEnvExample(rootDir);
+        expect(version).toBeNull();
+        expect(variables).toHaveLength(2);
+        expect(variables.find((v) => v.key === 'FOO')?.defaultValue).toBe('bar');
+        expect(variables.find((v) => v.key === 'BAZ')?.defaultValue).toBe('qux');
+    });
+    it('strips inline comments from values', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'full');
+        const { variables } = parseEnvExample(rootDir);
+        // API_BASE_URL has no inline comment in fixture; DATABASE_URL might have comment in some examples
+        // Check that quoted values are unquoted
+        const apiBase = variables.find((v) => v.key === 'API_BASE_URL');
+        expect(apiBase.defaultValue).toBe('https://api.example.com/v1');
+    });
+    it('preserves section headers in comment', () => {
+        const rootDir = path.join(FIXTURES_DIR, 'full');
+        const { variables } = parseEnvExample(rootDir);
+        const dbUrl = variables.find((v) => v.key === 'DATABASE_URL');
+        expect(dbUrl.comment).toMatch(/------/);
+    });
+});
+describe('getExistingEnvVersion', () => {
+    it('returns null for content without version', () => {
+        expect(getExistingEnvVersion('FOO=bar')).toBeNull();
+        expect(getExistingEnvVersion('')).toBeNull();
+    });
+    it('returns version from quoted ENV_SCHEMA_VERSION', () => {
+        const content = '# ENV_SCHEMA_VERSION="1.0"\nFOO=bar';
+        expect(getExistingEnvVersion(content)).toBe('1.0');
+    });
+    it('returns version from unquoted ENV_SCHEMA_VERSION', () => {
+        const content = '# ENV_SCHEMA_VERSION=2.0\n';
+        expect(getExistingEnvVersion(content)).toBe('2.0');
+    });
+    it('returns first match when multiple version-like lines exist', () => {
+        const content = '# ENV_SCHEMA_VERSION="1.0"\n# ENV_SCHEMA_VERSION="2.0"';
+        expect(getExistingEnvVersion(content)).toBe('1.0');
+    });
+});
+describe('getExistingEnvVariables', () => {
+    it('returns empty object when file does not exist', () => {
+        const result = getExistingEnvVariables(path.join(FIXTURES_DIR, 'nonexistent.env'));
+        expect(result).toEqual({});
+    });
+    it('parses existing .env file', () => {
+        const envPath = path.join(FIXTURES_DIR, 'full', '.env.example');
+        const result = getExistingEnvVariables(envPath);
+        expect(result).toBeDefined();
+        expect(typeof result).toBe('object');
+        expect(result.DATABASE_URL).toBe('postgres://localhost:5432/myapp');
+        expect(result.NODE_ENV).toBe('development');
+    });
+    it('returns empty object for empty or comment-only file', () => {
+        const tmpDir = path.join(FIXTURES_DIR, 'full');
+        const commentOnlyPath = path.join(tmpDir, '.env.comment-only');
+        fs.writeFileSync(commentOnlyPath, '# only comments\n\n', 'utf-8');
+        try {
+            const result = getExistingEnvVariables(commentOnlyPath);
+            expect(result).toEqual({});
+        }
+        finally {
+            try {
+                fs.unlinkSync(commentOnlyPath);
+            }
+            catch {
+                // ignore
+            }
+        }
+    });
+});
+describe('serializeEnvExample', () => {
+    it('outputs version line and variables with sections', () => {
+        const variables = [
+            {
+                key: 'FOO',
+                defaultValue: 'bar',
+                comment: '# ------ Section ------\nDescription',
+                required: false,
+                isCommentedOut: false,
+            },
+            {
+                key: 'BAZ',
+                defaultValue: 'qux',
+                comment: '',
+                required: false,
+                isCommentedOut: true,
+            },
+        ];
+        const out = serializeEnvExample('1.0', variables);
+        expect(out).toMatch(/# ENV_SCHEMA_VERSION="1.0"/);
+        expect(out).toMatch(/# ------ Section ------/);
+        expect(out).toMatch(/FOO=bar/);
+        expect(out).toMatch(/# BAZ=qux/);
+    });
+    it('outputs no version line when version is null', () => {
+        const variables = [
+            { key: 'X', defaultValue: 'y', comment: '', required: false, isCommentedOut: false },
+        ];
+        const out = serializeEnvExample(null, variables);
+        expect(out).not.toMatch(/ENV_SCHEMA_VERSION/);
+        expect(out).toMatch(/^X=y/);
+    });
+});
+describe('bumpSemver', () => {
+    it('bumps patch', () => {
+        expect(bumpSemver('1.0.0', 'patch')).toBe('1.0.1');
+        expect(bumpSemver('1.0', 'patch')).toBe('1.0.1');
+    });
+    it('bumps minor', () => {
+        expect(bumpSemver('1.0.0', 'minor')).toBe('1.1.0');
+        expect(bumpSemver('2.1', 'minor')).toBe('2.2.0');
+    });
+    it('bumps major', () => {
+        expect(bumpSemver('1.0.0', 'major')).toBe('2.0.0');
+        expect(bumpSemver('3.2.1', 'major')).toBe('4.0.0');
+    });
+});
+describe('polishEnvExample', () => {
+    it('overwrites .env.example with normalized content and dedupes keys', () => {
+        const fixtureDir = path.join(FIXTURES_DIR, 'full');
+        const envPath = path.join(fixtureDir, '.env.example');
+        const before = fs.readFileSync(envPath, 'utf-8');
+        polishEnvExample(fixtureDir);
+        const after = fs.readFileSync(envPath, 'utf-8');
+        expect(after).toMatch(/# ENV_SCHEMA_VERSION="1.0"/);
+        expect(after).toMatch(/DATABASE_URL=postgres:\/\/localhost:5432\/myapp/);
+        expect(after).toMatch(/# ------ Database ------/);
+        // Restore original so other tests and fixtures are unchanged
+        fs.writeFileSync(envPath, before, 'utf-8');
+    });
+    it('throws when .env.example does not exist', () => {
+        expect(() => polishEnvExample('/nonexistent/dir')).toThrow(/.env.example not found/);
+    });
+});
+describe('updateEnvSchemaVersion', () => {
+    it('updates ENV_SCHEMA_VERSION in .env.example', () => {
+        const fixtureDir = path.join(FIXTURES_DIR, 'minimal');
+        const envPath = path.join(fixtureDir, '.env.example');
+        const before = fs.readFileSync(envPath, 'utf-8');
+        try {
+            updateEnvSchemaVersion(fixtureDir, '3.0.0');
+            const after = fs.readFileSync(envPath, 'utf-8');
+            expect(after).toMatch(/# ENV_SCHEMA_VERSION="3.0.0"/);
+            expect(after).toMatch(/NODE_ENV=development/);
+        }
+        finally {
+            fs.writeFileSync(envPath, before, 'utf-8');
+        }
+    });
+    it('throws when .env.example does not exist', () => {
+        expect(() => updateEnvSchemaVersion('/nonexistent', '1.0.0')).toThrow(/.env.example not found/);
+    });
+});

package/dist/vitest.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+import { resolve } from "path";
+export default defineConfig({
+    test: {
+        include: ["test/**/*.test.ts"],
+        environment: "node",
+        globals: true,
+        fileParallelism: false,
+    },
+    resolve: {
+        alias: {
+            "env-from-example": resolve(__dirname, "env-from-example.ts"),
+        },
+    },
+});

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@wchen.ai/env-from-example",
+  "version": "1.0.0",
+  "description": "Interactive and non-interactive CLI to set up .env from .env.example",
+  "keywords": [
+    "env",
+    "dotenv",
+    "cli",
+    "environment",
+    "setup"
+  ],
+  "homepage": "https://github.com/wchen02/env-from-example#readme",
+  "bugs": {
+    "url": "https://github.com/wchen02/env-from-example/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wchen02/env-from-example.git"
+  },
+  "license": "ISC",
+  "author": "Wensheng Chen",
+  "type": "module",
+  "main": "dist/env-from-example.js",
+  "bin": {
+    "env-from-example": "dist/env-from-example.js"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "dist",
+    "schema.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm run build",
+    "start": "node dist/env-from-example.js",
+    "dev": "tsx env-from-example.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "code-quality": "pnpm run lint && pnpm run format:check && pnpm run typecheck"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^5.4.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.15.0",
+    "vitest": "^2.1.0"
+  },
+  "packageManager": "pnpm@10.30.0"
+}

package/schema.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.example.com/env-types-priority-array-pruned.schema.json",
+  "title": "Environment Variable Runtime Types (Priority Ordered, pruned)",
+  "description": "Pruned ordered env value type definitions for deterministic value→type detection. Ambiguous types removed so detection falls back to primitives when ambiguous.",
+  "type": "object",
+  "types": [
+    {
+      "name": "credentials/private_key_pem",
+      "type": "string",
+      "pattern": "^-----BEGIN [A-Z ]+KEY-----[\\s\\S]*-----END [A-Z ]+KEY-----$",
+      "description": "PEM private key (-----BEGIN ... KEY-----).",
+      "examples": [
+        "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----"
+      ],
+      "auto_generate": "rsa_private_key"
+    },
+
+    {
+      "name": "network/https_url",
+      "type": "string",
+      "pattern": "^https:\\/\\/[^\\s]+$",
+      "description": "HTTPS URL.",
+      "examples": [
+        "https://api.example.com",
+        "https://hooks.example.com/ingest"
+      ],
+      "default": "https://localhost:443"
+    },
+
+    {
+      "name": "network/url",
+      "type": "string",
+      "pattern": "^https?:\\/\\/[^\\s]+$",
+      "description": "HTTP or HTTPS URL.",
+      "examples": ["http://localhost:3000", "https://api.example.com/v1"],
+      "default": "http://localhost:80"
+    },
+
+    {
+      "name": "network/uri",
+      "type": "string",
+      "pattern": "^(?!https?:\\/\\/)[a-zA-Z][a-zA-Z0-9+.\\-]*:\\/\\/.+$",
+      "description": "Non-HTTP service URI (e.g. postgres://).",
+      "examples": [
+        "postgres://user:pass@db:5432/mydb?sslmode=require",
+        "redis://:password@redis:6379/0",
+        "s3://my-bucket/path"
+      ]
+    },
+
+    {
+      "name": "network/domain",
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9\\-]+(\\.[a-zA-Z0-9\\-]+)*\\.[a-zA-Z]{2,}$",
+      "description": "Domain or hostname with TLD (e.g. example.com).",
+      "examples": ["example.com", "api.bestpos.io"]
+    },
+
+    {
+      "name": "network/ip",
+      "type": "string",
+      "pattern": "^(25[0-5]|2[0-4]\\d|1?\\d{1,2})(\\.(25[0-5]|2[0-4]\\d|1?\\d{1,2})){3}$",
+      "description": "IPv4 dotted-decimal address (e.g. 127.0.0.1).",
+      "examples": ["127.0.0.1", "10.0.0.5"],
+      "default": "127.0.0.1"
+    },
+
+    {
+      "name": "network/ipv6",
+      "type": "string",
+      "pattern": "^(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$|^(?:[0-9a-fA-F]{1,4}:){1,7}:$|^:(:[0-9a-fA-F]{1,4}){1,7}$|^(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}$",
+      "description": "IPv6 address (compressed or full notation).",
+      "examples": ["::1", "fe80::1", "2001:db8::1"],
+      "default": "::1"
+    },
+
+    {
+      "name": "version/semver",
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+      "description": "Semver: MAJOR.MINOR.PATCH + optional suffix.",
+      "examples": ["1.2.3", "0.10.0-alpha.1"],
+      "default": "0.0.0"
+    },
+
+    {
+      "name": "id/uuid",
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
+      "description": "UUID in canonical form (v1–v5).",
+      "examples": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
+      "auto_generate": "uuidv4"
+    },
+
+    {
+      "name": "structured/json",
+      "type": "string",
+      "pattern": "^\\{[\\s\\S]*\\}$",
+      "description": "JSON object as string; validate with parse.",
+      "examples": ["{\"ai\":true}", "{\"features\":[\"a\",\"b\"]}"],
+      "default": "{}"
+    },
+
+    {
+      "name": "structured/key_value_pairs",
+      "type": "string",
+      "pattern": "^[^=,]+=.+(,[^=,]+=.+)*$",
+      "description": "Comma-separated key=value pairs.",
+      "examples": ["env=prod,region=us-east-1", "tier=premium,plan=annual"]
+    },
+
+    {
+      "name": "locale/langtag",
+      "type": "string",
+      "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z]{2,4})?(?:-[A-Za-z0-9-]+)*$",
+      "description": "BCP-47 language tag (e.g. en, en-US).",
+      "examples": ["en", "en-US", "zh-Hant-TW"],
+      "default": "en-US"
+    },
+
+    {
+      "name": "structured/email_list",
+      "type": "string",
+      "pattern": "^[^\\s,@]+@[^\\s,@]+\\.[^\\s,@]+(?:,[^\\s,@]+@[^\\s,@]+\\.[^\\s,@]+)+$",
+      "description": "Comma-separated email list; validate each.",
+      "examples": ["a@example.com,b@x.org"]
+    },
+
+    {
+      "name": "structured/csv",
+      "type": "string",
+      "pattern": "^[^,]+(,[^,]+)+$",
+      "description": "Comma-separated list (2+ values).",
+      "examples": ["a,b,c", "one,two"]
+    },
+
+    {
+      "name": "file/windows_path",
+      "type": "string",
+      "pattern": "^[a-zA-Z]:\\\\(?:[^<>:\\\"/\\\\|?*\\r\\n]+\\\\)*[^<>:\\\"/\\\\|?*\\r\\n]*$",
+      "description": "Windows absolute path (e.g. C:\\dir\\file).",
+      "examples": ["C:\\Program Files\\App\\config.yml", "C:\\temp\\file.txt"]
+    },
+
+    {
+      "name": "file/path",
+      "type": "string",
+      "pattern": "^(?!\\s*$)(\\.?\\.?\\/)?([^\\/\\0]+\\/)*[^\\/\\0]+$",
+      "description": "POSIX path (relative or absolute).",
+      "examples": [
+        "./config.yml",
+        "/var/app/secrets.json",
+        "secrets/gcp/key.json"
+      ]
+    },
+
+    {
+      "name": "temporal/cron",
+      "type": "string",
+      "pattern": "^([\\d\\*/,-]+\\s){4}[\\d\\*/,-]+$",
+      "description": "Five-field cron (min hour day month dow).",
+      "examples": ["0 3 1 * *", "*/15 * * * *"],
+      "default": "0 0 * * *"
+    },
+
+    {
+      "name": "temporal/time_hhmm",
+      "type": "string",
+      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
+      "description": "Time in 24-hour format (HH:MM).",
+      "examples": ["03:00", "23:59"],
+      "default": "00:00"
+    },
+
+    {
+      "name": "temporal/duration",
+      "type": "string",
+      "pattern": "^\\d+(ms|s|m|h|d)$",
+      "description": "Duration with unit (e.g. 30s, 5m, 1h, 7d).",
+      "examples": ["30s", "7d", "1h"],
+      "default": "1h"
+    },
+
+    {
+      "name": "credentials/secret",
+      "type": "string",
+      "minLength": 16,
+      "description": "API key, token, or secret (min length).",
+      "examples": ["sk_live_4f3b2a1c...", "superlongrandomsecretvalue"],
+      "auto_generate": "random_secret_32",
+      "constraints": {
+        "minLength": "value.length >= minLength",
+        "maxLength": "value.length <= maxLength"
+      }
+    },
+
+    {
+      "name": "visual/hex_color",
+      "type": "string",
+      "pattern": "^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$",
+      "description": "Hex color (#RGB, #RRGGBB, #RRGGBBAA).",
+      "examples": ["#fff", "#aabbcc", "#AABBCCFF"],
+      "default": "#ffffff"
+    },
+
+    {
+      "name": "structured/enum",
+      "type": "string",
+      "pattern": "^([a-zA-Z\\-_]*)$",
+      "description": "Value from a predefined set of options.",
+      "examples": ["debug", "info", "production"],
+      "constraints": {
+        "pattern": "new RegExp(pattern).test(value) // pattern should be ^(opt1|opt2|...)$ with valid options"
+      }
+    },
+
+    {
+      "name": "float",
+      "type": "number",
+      "description": "Floating-point number.",
+      "examples": [0.0, 3.1415],
+      "constraints": {
+        "min": "value >= min",
+        "max": "value <= max",
+        "precision": "limit decimal places (e.g. toFixed or check rounded equality)"
+      },
+      "default": 0.0
+    },
+
+    {
+      "name": "integer",
+      "type": "integer",
+      "description": "Integer.",
+      "examples": [0, 1, 42],
+      "constraints": {
+        "min": "value >= min",
+        "max": "value <= max"
+      },
+      "default": 0
+    },
+
+    {
+      "name": "boolean",
+      "type": "boolean",
+      "description": "Boolean (true/false, 1/0, yes/no).",
+      "examples": [true, false],
+      "default": false
+    },
+
+    {
+      "name": "string",
+      "type": "string",
+      "description": "Arbitrary string.",
+      "examples": ["Copyright 2026", "my-app", "free text"],
+      "constraints": {
+        "minLength": "value.length >= minLength",
+        "maxLength": "value.length <= maxLength",
+        "pattern": "new RegExp(pattern).test(value)  // pattern should be a valid JS/PCRE regex string"
+      }
+    }
+  ]
+}