@wchen.ai/env-from-example 1.0.0

package/dist/src/polish.js

@@ -0,0 +1,369 @@
+import fs from "fs";
+import path from "path";
+import { input, select } from "@inquirer/prompts";
+import pc from "picocolors";
+import { getSchemaTypes, findSchemaType, parseEnumChoices, getAvailableConstraints, } from "./schema.js";
+import { parseEnvExample, serializeEnvExample, dedupeVariables, enrichVariablesForPolish, getGroup, inferDescription, stripMetaFromComment, buildCommentLine, getDefaultSchemaVersion, } from "./parse.js";
+import { detectType, matchesSchemaType } from "./validate.js";
+// ─── Summary card ────────────────────────────────────────────────────────────
+function printVariableSummary(key, index, total, fields) {
+    const progress = `[${index}/${total}]`;
+    const W = 60;
+    const keyPart = `── ${key} `;
+    const progPart = ` ${progress} ──`;
+    const fill = Math.max(0, W - keyPart.length - progPart.length);
+    const header = keyPart + "─".repeat(fill) + progPart;
+    console.log("");
+    console.log(pc.cyan(pc.bold(header)));
+    const L = 16;
+    const pad = (s) => s.padEnd(L);
+    const row = (label, value, source) => {
+        const src = source ? "  " + pc.dim(pc.yellow(source)) : "";
+        console.log(`  ${pc.gray(pad(label))}${value}${src}`);
+    };
+    row("Group", fields.group ? pc.white(fields.group) : pc.dim("(none)"), "");
+    row("Description", pc.white(fields.description), fields.descSource);
+    if (fields.type && fields.schemaType) {
+        const desc = fields.schemaType.description;
+        const short = desc.length > 50 ? desc.substring(0, 47) + "..." : desc;
+        row("Type", pc.cyan(fields.type), fields.typeSource);
+        console.log(`  ${" ".repeat(L)}${pc.dim(short)}`);
+    }
+    else if (fields.type) {
+        row("Type", pc.cyan(fields.type), fields.typeSource);
+    }
+    else {
+        row("Type", pc.dim("(none)"), "");
+    }
+    if (fields.schemaType?.examples && fields.schemaType.examples.length > 0) {
+        const exStr = fields.schemaType.examples.map((e) => String(e)).join(", ");
+        const short = exStr.length > 50 ? exStr.substring(0, 47) + "..." : exStr;
+        row("Examples", pc.dim(short), "");
+    }
+    if (fields.type === "structured/enum" && fields.constraints.pattern) {
+        const choices = parseEnumChoices(fields.constraints.pattern);
+        if (choices.length > 0) {
+            row("Choices", choices.join(pc.dim(" | ")), "");
+        }
+    }
+    const methodEntries = Object.entries(fields.constraints).filter(([k]) => {
+        if (k === "pattern" && fields.type !== "string")
+            return false;
+        if (k === "pattern" && fields.type === "structured/enum")
+            return false;
+        return true;
+    });
+    if (methodEntries.length > 0) {
+        const mStr = methodEntries.map(([k, v]) => `${k}=${v}`).join(", ");
+        row("Constraints", pc.white(mStr), "from [CONSTRAINTS]");
+    }
+    row("Required", fields.required ? pc.green("yes") : pc.dim("no"), fields.reqSource);
+    const autoGen = fields.schemaType?.auto_generate;
+    if (autoGen && !fields.defaultValue) {
+        row("Default", pc.magenta(`auto (${autoGen})`), "from schema type");
+    }
+    else if (fields.defaultValue) {
+        row("Default", pc.white(fields.defaultValue), "");
+    }
+    else {
+        row("Default", pc.dim("(empty)"), "");
+    }
+    console.log(pc.gray("─".repeat(W)));
+}
+// ─── Non-interactive polish ──────────────────────────────────────────────────
+export function polishEnvExample(rootDir) {
+    const envExamplePath = path.join(rootDir, ".env.example");
+    if (!fs.existsSync(envExamplePath)) {
+        throw new Error(`.env.example not found at ${envExamplePath}`);
+    }
+    const { version, variables } = parseEnvExample(rootDir);
+    const deduped = dedupeVariables(variables);
+    const enriched = enrichVariablesForPolish(deduped);
+    const effectiveVersion = version ?? getDefaultSchemaVersion(rootDir);
+    const content = serializeEnvExample(effectiveVersion, enriched);
+    fs.writeFileSync(envExamplePath, content, "utf-8");
+}
+// ─── Interactive polish ──────────────────────────────────────────────────────
+export async function polishEnvExampleInteractive(rootDir) {
+    const envExamplePath = path.join(rootDir, ".env.example");
+    if (!fs.existsSync(envExamplePath)) {
+        throw new Error(`.env.example not found at ${envExamplePath}`);
+    }
+    const { version, variables } = parseEnvExample(rootDir);
+    const deduped = dedupeVariables(variables);
+    const effectiveVersion = version ?? getDefaultSchemaVersion(rootDir);
+    const polished = [];
+    const total = deduped.length;
+    const knownGroups = new Set();
+    for (const v of deduped) {
+        const g = getGroup(v);
+        if (g)
+            knownGroups.add(g);
+    }
+    if (knownGroups.size > 0 && deduped.some((v) => !getGroup(v))) {
+        knownGroups.add("Other");
+    }
+    console.log(pc.cyan(pc.bold("  Interactive polish")) +
+        pc.dim(` — ${total} variables to review\n`));
+    for (let i = 0; i < deduped.length; i++) {
+        const v = deduped[i];
+        let group = getGroup(v) || (knownGroups.size > 0 ? "Other" : "");
+        let description = inferDescription(v);
+        let descSource = stripMetaFromComment(v.comment)
+            ? "from comment"
+            : "inferred from key";
+        let type = v.type || detectType(v.defaultValue, v.key);
+        let typeSource;
+        if (v.type)
+            typeSource = "from [TYPE] tag";
+        else if (type)
+            typeSource = "detected";
+        else
+            typeSource = "";
+        let schemaType = type ? findSchemaType(type) : undefined;
+        let required = v.required;
+        let reqSource = v.required ? "from [REQUIRED] tag" : "";
+        let constraints = v.constraints
+            ? { ...v.constraints }
+            : {};
+        let defaultValue = v.defaultValue;
+        let accepted = false;
+        while (!accepted) {
+            printVariableSummary(v.key, i + 1, total, {
+                description,
+                descSource,
+                type,
+                typeSource,
+                schemaType,
+                constraints,
+                required,
+                reqSource,
+                defaultValue,
+                group,
+            });
+            const availableConstraints = type ? getAvailableConstraints(type) : {};
+            const methodEntries = Object.entries(availableConstraints).filter(([mKey]) => !(type === "structured/enum" && mKey === "pattern"));
+            const actionChoices = [
+                { name: pc.green("Accept"), value: "accept" },
+                { name: "Edit description", value: "edit_desc" },
+                { name: "Edit type", value: "edit_type" },
+                { name: "Edit default", value: "edit_default" },
+                {
+                    name: required ? "Mark as optional" : "Mark as required",
+                    value: "edit_required",
+                },
+                { name: "Edit group", value: "edit_group" },
+            ];
+            for (const [mKey] of methodEntries) {
+                const current = constraints[mKey];
+                const label = current
+                    ? `Set ${mKey} ${pc.dim(`(${current})`)}`
+                    : `Set ${mKey}`;
+                actionChoices.push({ name: label, value: `set_method:${mKey}` });
+            }
+            const action = await select({
+                message: "Action",
+                choices: actionChoices,
+                default: "accept",
+            });
+            if (action === "accept") {
+                accepted = true;
+            }
+            else if (action === "edit_desc") {
+                description = await input({
+                    message: "Description",
+                    default: description,
+                });
+                descSource = "";
+            }
+            else if (action === "edit_type") {
+                const allTypes = getSchemaTypes();
+                const trimmedValue = defaultValue.trim();
+                const matchingTypes = trimmedValue
+                    ? allTypes.filter((t) => matchesSchemaType(t, trimmedValue, v.key))
+                    : [];
+                const matchingNames = new Set(matchingTypes.map((t) => t.name));
+                const otherTypes = allTypes.filter((t) => !matchingNames.has(t.name));
+                const formatType = (t) => ({
+                    name: `${t.name}${pc.dim(" — " + t.description.substring(0, 50))}`,
+                    value: t.name,
+                });
+                let newType;
+                if (matchingTypes.length > 0) {
+                    const picked = await select({
+                        message: "Type",
+                        choices: [
+                            { name: pc.dim("(none)"), value: "" },
+                            ...matchingTypes.map(formatType),
+                            { name: pc.cyan("Other..."), value: "__other__" },
+                        ],
+                        default: type ?? "",
+                    });
+                    if (picked === "__other__") {
+                        newType = await select({
+                            message: "Type",
+                            choices: [
+                                { name: pc.dim("(none)"), value: "" },
+                                ...otherTypes.map(formatType),
+                            ],
+                            default: "",
+                        });
+                    }
+                    else {
+                        newType = picked;
+                    }
+                }
+                else {
+                    newType = await select({
+                        message: "Type",
+                        choices: [
+                            { name: pc.dim("(none)"), value: "" },
+                            ...allTypes.map(formatType),
+                        ],
+                        default: type ?? "",
+                    });
+                }
+                if (newType === "structured/enum") {
+                    const currentChoices = constraints.pattern
+                        ? parseEnumChoices(constraints.pattern)
+                        : [];
+                    const choicesStr = await input({
+                        message: "Enum values (pipe-separated, e.g. debug|info|warn|error)",
+                        default: currentChoices.join("|"),
+                        validate: (val) => val.trim().length > 0 || "At least one value is required",
+                    });
+                    const values = choicesStr
+                        .split(/[|,]/)
+                        .map((s) => s.trim())
+                        .filter(Boolean);
+                    constraints = { pattern: `^(${values.join("|")})$` };
+                }
+                else if (newType) {
+                    const newAvailable = getAvailableConstraints(newType);
+                    const cleaned = {};
+                    for (const [k, val] of Object.entries(constraints)) {
+                        if (k in newAvailable)
+                            cleaned[k] = val;
+                    }
+                    constraints = cleaned;
+                }
+                else {
+                    constraints = {};
+                }
+                type = newType || undefined;
+                schemaType = type ? findSchemaType(type) : undefined;
+                typeSource = "";
+            }
+            else if (action === "edit_default") {
+                const autoGen = schemaType?.auto_generate;
+                if (autoGen) {
+                    const defaultChoices = [
+                        { name: "Enter a static value", value: "static" },
+                        {
+                            name: pc.magenta(`auto:${autoGen}`) +
+                                pc.dim(" — auto-generate when empty"),
+                            value: "auto",
+                        },
+                    ];
+                    const choice = await select({
+                        message: "Default value",
+                        choices: defaultChoices,
+                        default: defaultValue ? "static" : "auto",
+                    });
+                    if (choice === "auto") {
+                        defaultValue = "";
+                    }
+                    else {
+                        defaultValue = await input({
+                            message: "Value",
+                            default: defaultValue,
+                        });
+                    }
+                }
+                else {
+                    defaultValue = await input({
+                        message: "Value",
+                        default: defaultValue,
+                    });
+                }
+            }
+            else if (action === "edit_required") {
+                required = !required;
+                reqSource = "";
+            }
+            else if (action === "edit_group") {
+                const groupChoices = [];
+                if (!knownGroups.has("Other")) {
+                    groupChoices.push({ name: pc.dim("(none)"), value: "" });
+                }
+                groupChoices.push(...[...knownGroups].map((g) => ({ name: g, value: g })));
+                groupChoices.push({
+                    name: pc.cyan("+ New group..."),
+                    value: "__new__",
+                });
+                const picked = await select({
+                    message: "Group",
+                    choices: groupChoices,
+                    default: group || (knownGroups.has("Other") ? "Other" : ""),
+                });
+                if (picked === "__new__") {
+                    const newGroup = await input({
+                        message: "Group name (e.g. Database, Auth, App)",
+                        validate: (val) => val.trim().length > 0 || "Group name is required",
+                    });
+                    group = newGroup.trim();
+                    knownGroups.add(group);
+                }
+                else {
+                    group = picked;
+                }
+            }
+            else if (action.startsWith("set_method:")) {
+                const mKey = action.slice("set_method:".length);
+                if (mKey === "pattern") {
+                    const patternStr = await input({
+                        message: "Pattern (regex, e.g. ^[a-z0-9-]+$) [empty to clear]",
+                        default: constraints.pattern || "",
+                    });
+                    if (patternStr.trim()) {
+                        constraints.pattern = patternStr.trim();
+                    }
+                    else {
+                        delete constraints.pattern;
+                    }
+                }
+                else {
+                    const current = constraints[mKey] || "";
+                    const val = await input({
+                        message: `${mKey} [empty to clear]`,
+                        default: current,
+                    });
+                    if (val.trim()) {
+                        constraints[mKey] = val.trim();
+                    }
+                    else {
+                        delete constraints[mKey];
+                    }
+                }
+            }
+        }
+        const commentLine = buildCommentLine({
+            description,
+            required,
+            type,
+            constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+            defaultValue,
+        });
+        polished.push({
+            ...v,
+            comment: commentLine,
+            defaultValue,
+            required,
+            type,
+            constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+            group: group || undefined,
+        });
+    }
+    const content = serializeEnvExample(effectiveVersion, polished);
+    fs.writeFileSync(envExamplePath, content, "utf-8");
+}

package/dist/src/schema.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+let _schema = null;
+export function loadSchema(customPath) {
+    if (_schema && !customPath)
+        return _schema;
+    if (customPath) {
+        return JSON.parse(fs.readFileSync(customPath, "utf-8"));
+    }
+    const selfPath = fileURLToPath(import.meta.url);
+    const dir = path.dirname(selfPath);
+    for (const candidate of [
+        path.join(dir, "..", "schema.json"),
+        path.join(dir, "..", "..", "schema.json"),
+        path.join(dir, "schema.json"),
+    ]) {
+        if (fs.existsSync(candidate)) {
+            _schema = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+            return _schema;
+        }
+    }
+    throw new Error("schema.json not found");
+}
+export function resetSchemaCache() {
+    _schema = null;
+}
+export function getSchemaTypes() {
+    return loadSchema().types;
+}
+export function findSchemaType(name) {
+    return getSchemaTypes().find((t) => t.name === name);
+}
+/** Parse ^(a|b|c)$ pattern into choice strings. */
+export function parseEnumChoices(pattern) {
+    const m = pattern.match(/^\^?\(([^)]+)\)\$?$/);
+    if (m)
+        return m[1]
+            .split("|")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return [];
+}
+/**
+ * Return the available constraint descriptors for a type.
+ * If the type itself defines constraints, use those.
+ * Otherwise, fall back to the constraints of the corresponding primitive type.
+ */
+export function getAvailableConstraints(typeName) {
+    const st = findSchemaType(typeName);
+    if (!st)
+        return {};
+    if (st.constraints)
+        return st.constraints;
+    const baseName = {
+        number: "float",
+        integer: "integer",
+        boolean: "boolean",
+        string: "string",
+    };
+    const base = baseName[st.type];
+    if (base) {
+        const bt = findSchemaType(base);
+        return bt?.constraints || {};
+    }
+    return {};
+}

package/dist/src/validate.js

@@ -0,0 +1,255 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { getSchemaTypes, findSchemaType, parseEnumChoices, } from "./schema.js";
+import { parseEnvExample, getExistingEnvVersion, getExistingEnvVariables, } from "./parse.js";
+// ─── Type detection ──────────────────────────────────────────────────────────
+export function detectType(value, key) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const types = getSchemaTypes();
+    const integerType = types.find((t) => t.name === "integer");
+    const floatType = types.find((t) => t.name === "float");
+    const booleanType = types.find((t) => t.name === "boolean");
+    const stringType = types.find((t) => t.name === "string");
+    const enumType = types.find((t) => t.name === "structured/enum");
+    const ordered = [
+        integerType,
+        floatType,
+        booleanType,
+        ...types.filter((t) => t.name !== "integer" &&
+            t.name !== "float" &&
+            t.name !== "boolean" &&
+            t.name !== "string" &&
+            t.name !== "structured/enum"),
+        stringType,
+        enumType,
+    ].filter(Boolean);
+    for (const t of ordered) {
+        if (matchesSchemaType(t, trimmed, key))
+            return t.name;
+    }
+    return undefined;
+}
+export function matchesSchemaType(t, value, key) {
+    if (t.pattern) {
+        if (t.name === "file/path" && !/[/\\]|^[.~]/.test(value))
+            return false;
+        if (t.name === "locale/langtag" &&
+            /^(true|false|yes|no|on|off|ok)$/i.test(value))
+            return false;
+        try {
+            if (!new RegExp(t.pattern).test(value))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        if (t.name === "structured/json") {
+            try {
+                JSON.parse(value);
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (t.name === "credentials/secret" && t.minLength !== undefined) {
+        return (/SECRET|KEY|TOKEN|PASSWORD|SALT|BEARER|CREDENTIAL|AUTH/i.test(key) &&
+            value.length >= t.minLength);
+    }
+    if (t.name === "float" && t.type === "number") {
+        return /^-?\d*\.\d+$/.test(value) && !isNaN(parseFloat(value));
+    }
+    if (t.name === "integer" && t.type === "integer") {
+        return /^-?\d+$/.test(value) && !isNaN(parseInt(value, 10));
+    }
+    if (t.name === "boolean" && t.type === "boolean") {
+        return /^(true|false|1|0|yes|no)$/i.test(value);
+    }
+    if (t.name === "string" && t.type === "string" && !t.pattern) {
+        return true;
+    }
+    return false;
+}
+// ─── Value validation ────────────────────────────────────────────────────────
+export function validateValue(value, v) {
+    const trimmed = value.trim();
+    if (v.required && !trimmed)
+        return `${v.key} is required.`;
+    if (!trimmed && !v.required)
+        return null;
+    if (!v.type)
+        return null;
+    const st = findSchemaType(v.type);
+    if (!st)
+        return null;
+    if (v.type === "structured/enum" && v.constraints?.pattern) {
+        try {
+            if (!new RegExp(v.constraints.pattern).test(trimmed)) {
+                const choices = parseEnumChoices(v.constraints.pattern);
+                if (choices.length > 0) {
+                    return `${v.key} must be one of: ${choices.join(", ")}`;
+                }
+                return `${v.key} must match pattern ${v.constraints.pattern}`;
+            }
+        }
+        catch {
+            return `${v.key} has an invalid enum pattern: ${v.constraints.pattern}`;
+        }
+        return null;
+    }
+    if (st.pattern) {
+        try {
+            if (!new RegExp(st.pattern).test(trimmed)) {
+                return `${v.key} must be a valid ${st.name} (${st.description}).`;
+            }
+        }
+        catch {
+            /* invalid pattern in schema, skip */
+        }
+    }
+    if (v.type === "structured/json") {
+        try {
+            JSON.parse(trimmed);
+        }
+        catch {
+            return `${v.key} must be valid JSON.`;
+        }
+    }
+    if (st.type === "number" || st.name === "float") {
+        const n = Number(trimmed);
+        if (isNaN(n))
+            return `${v.key} must be a number.`;
+        const m = v.constraints || {};
+        if (m.min !== undefined && n < Number(m.min))
+            return `${v.key} must be >= ${m.min}.`;
+        if (m.max !== undefined && n > Number(m.max))
+            return `${v.key} must be <= ${m.max}.`;
+        if (m.precision !== undefined) {
+            const prec = Number(m.precision);
+            const decPart = trimmed.split(".")[1];
+            if (decPart && decPart.length > prec) {
+                return `${v.key} must have at most ${prec} decimal places.`;
+            }
+        }
+    }
+    if (st.type === "integer" || st.name === "integer") {
+        const n = Number(trimmed);
+        if (isNaN(n) || Math.floor(n) !== n)
+            return `${v.key} must be an integer.`;
+        const m = v.constraints || {};
+        if (m.min !== undefined && n < Number(m.min))
+            return `${v.key} must be >= ${m.min}.`;
+        if (m.max !== undefined && n > Number(m.max))
+            return `${v.key} must be <= ${m.max}.`;
+    }
+    if (st.type === "boolean" || st.name === "boolean") {
+        if (!/^(true|false|1|0|yes|no)$/i.test(trimmed)) {
+            return `${v.key} must be a boolean (true/false/1/0/yes/no).`;
+        }
+    }
+    if (st.minLength !== undefined && trimmed.length < st.minLength) {
+        return `${v.key} must be at least ${st.minLength} characters.`;
+    }
+    if (st.type === "string") {
+        const m = v.constraints || {};
+        if (m.minLength !== undefined && trimmed.length < Number(m.minLength))
+            return `${v.key} must be at least ${m.minLength} characters.`;
+        if (m.maxLength !== undefined && trimmed.length > Number(m.maxLength))
+            return `${v.key} must be at most ${m.maxLength} characters.`;
+        if (m.pattern) {
+            try {
+                if (!new RegExp(m.pattern).test(trimmed))
+                    return `${v.key} must match pattern ${m.pattern}`;
+            }
+            catch {
+                return `${v.key} has an invalid pattern: ${m.pattern}`;
+            }
+        }
+    }
+    return null;
+}
+export function validateEnv(rootDir, options = {}) {
+    const { version, variables } = parseEnvExample(rootDir);
+    const envFileName = options.envFile || ".env";
+    const envPath = path.join(rootDir, envFileName);
+    const existing = getExistingEnvVariables(envPath);
+    const errors = [];
+    const warnings = [];
+    if (fs.existsSync(envPath) && version) {
+        const schemaVersionInEnv = getExistingEnvVersion(fs.readFileSync(envPath, "utf-8"));
+        if (schemaVersionInEnv !== null && schemaVersionInEnv !== version) {
+            warnings.push(`ENV_SCHEMA_VERSION mismatch: ${envFileName} has "${schemaVersionInEnv}", .env.example has "${version}".`);
+        }
+    }
+    for (const v of variables) {
+        if (v.isCommentedOut)
+            continue;
+        const value = existing[v.key];
+        const valuePresent = value !== undefined && value !== null;
+        if (v.required && !valuePresent) {
+            errors.push(`Missing required variable: ${v.key}`);
+            continue;
+        }
+        if (!valuePresent)
+            continue;
+        const err = validateValue(value, v);
+        if (err)
+            errors.push(err);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+// ─── Coercion ────────────────────────────────────────────────────────────────
+export function coerceToType(value, typeName) {
+    if (!typeName)
+        return value;
+    const st = findSchemaType(typeName);
+    if (!st)
+        return value;
+    const trimmed = value.trim();
+    if (st.type === "number" || st.name === "float") {
+        const n = Number(trimmed);
+        if (isNaN(n))
+            return value;
+        return String(n);
+    }
+    if (st.type === "integer" || st.name === "integer") {
+        const n = Number(trimmed);
+        if (isNaN(n))
+            return value;
+        return String(Math.floor(n));
+    }
+    if (st.type === "boolean" || st.name === "boolean") {
+        const lower = trimmed.toLowerCase();
+        if (["true", "1", "yes"].includes(lower))
+            return "true";
+        if (["false", "0", "no", ""].includes(lower))
+            return "false";
+        return value;
+    }
+    if (st.type === "string")
+        return trimmed;
+    return value;
+}
+// ─── Auto-generation ─────────────────────────────────────────────────────────
+const AUTO_GENERATORS = {
+    rsa_private_key: () => {
+        const { privateKey } = crypto.generateKeyPairSync("rsa", {
+            modulusLength: 2048,
+            publicKeyEncoding: { type: "spki", format: "pem" },
+            privateKeyEncoding: { type: "pkcs8", format: "pem" },
+        });
+        return privateKey;
+    },
+    uuidv4: () => crypto.randomUUID(),
+    random_secret_32: () => crypto.randomBytes(32).toString("base64"),
+};
+export function generateAutoValue(kind) {
+    const gen = AUTO_GENERATORS[kind];
+    if (!gen)
+        return "";
+    return gen();
+}