depfix-ai 0.2.0 → 0.2.2

package/dist/commands/env/generate.d.ts

@@ -7,6 +7,9 @@ export default class EnvGenerate extends Command {
         create: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        ai: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        model: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/env/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/env/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAG7C,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,OAAO;IAC9C,MAAM,CAAC,QAAQ,CAAC,EAAE,kBAAkB;IACpC,MAAM,CAAC,QAAQ,CAAC,WAAW,+EACmD;IAE9E,MAAM,CAAC,QAAQ,CAAC,KAAK;;;;;MAcnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAS3B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/env/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAG7C,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,OAAO;IAC9C,MAAM,CAAC,QAAQ,CAAC,EAAE,kBAAkB;IACpC,MAAM,CAAC,QAAQ,CAAC,WAAW,+EACmD;IAE9E,MAAM,CAAC,QAAQ,CAAC,KAAK;;;;;;;;MA0BnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAY3B"}

package/dist/commands/env/generate.js

@@ -17,6 +17,18 @@ export default class EnvGenerate extends Command {
         check: Flags.boolean({
             description: "Verify .env.example contains all required vars; exit 1 if not",
         }),
+        ai: Flags.boolean({
+            description: "Use OpenAI to add descriptions and where-to-get for each variable",
+            default: false,
+        }),
+        model: Flags.string({
+            description: "OpenAI model for AI mode (e.g. gpt-4o-mini)",
+            default: "gpt-4o-mini",
+        }),
+        "api-key": Flags.string({
+            description: "OpenAI API key (default: OPENAI_API_KEY env)",
+            env: "OPENAI_API_KEY",
+        }),
     };
     async run() {
         const { flags } = await this.parse(EnvGenerate);
@@ -25,6 +37,9 @@ export default class EnvGenerate extends Command {
             create: flags.create,
             force: flags.force,
             check: flags.check,
+            ai: flags.ai,
+            model: flags.model,
+            apiKey: flags["api-key"] ?? "",
         });
     }
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,OAAO,QAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,OAAO,QAAyB,CAAC"}

package/dist/index.js

@@ -1,7 +1,3 @@
-/**
- * Programmatic entry; CLI entry is bin/run.js (oclif).
- * Export version for consumers.
- */
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";

package/dist/lib/env/ai.d.ts

@@ -0,0 +1,20 @@
+export type AIEnvDoc = {
+    key: string;
+    description: string;
+    where_to_get: string;
+    example_value: string;
+    is_secret: boolean;
+};
+export type AIGenerateOptions = {
+    apiKey: string;
+    model: string;
+    projectHint?: string;
+    contexts: Record<string, {
+        file: string;
+        line: number;
+        snippet: string;
+    }[]>;
+    keys: string[];
+};
+export declare function generateEnvDocsWithOpenAI(opts: AIGenerateOptions): Promise<AIEnvDoc[]>;
+//# sourceMappingURL=ai.d.ts.map

package/dist/lib/env/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/lib/env/ai.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAoGF,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiDrB"}

package/dist/lib/env/ai.js

@@ -0,0 +1,139 @@
+const JSON_SCHEMA = {
+    name: "env_docs",
+    strict: true,
+    schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            items: {
+                type: "array",
+                items: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        key: { type: "string" },
+                        description: { type: "string" },
+                        where_to_get: { type: "string" },
+                        example_value: { type: "string" },
+                        is_secret: { type: "boolean" },
+                    },
+                    required: [
+                        "key",
+                        "description",
+                        "where_to_get",
+                        "example_value",
+                        "is_secret",
+                    ],
+                },
+            },
+        },
+        required: ["items"],
+    },
+};
+function buildInput(opts) {
+    const lines = opts.keys.map((k) => {
+        const ctx = opts.contexts[k]?.[0];
+        const seenAt = ctx ? `${ctx.file}:${ctx.line}` : "unknown";
+        const snippet = ctx ? ctx.snippet : "";
+        return `- ${k}\n  seen_at: ${seenAt}\n  snippet: ${snippet}`;
+    });
+    const system = [
+        "You generate documentation for environment variables.",
+        "Return ONLY JSON that matches the provided JSON Schema.",
+        "Do not include markdown or extra text.",
+        "Never output real secrets. Use safe placeholders.",
+        "Keep descriptions short and practical.",
+        "where_to_get must be actionable (dashboard, secret manager, CI, local service, etc.).",
+    ].join(" ");
+    const user = [
+        opts.projectHint ? `Project hint: ${opts.projectHint}` : "",
+        "Variables:",
+        ...lines,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return [
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ];
+}
+function extractTextFromResponses(data) {
+    if (typeof data?.output_text === "string") {
+        const t = data.output_text.trim();
+        if (t)
+            return t;
+    }
+    const out = data?.output;
+    if (Array.isArray(out)) {
+        for (const item of out) {
+            const content = item?.content;
+            if (!Array.isArray(content))
+                continue;
+            for (const c of content) {
+                const text = c?.text;
+                if (typeof text === "string" && text.trim())
+                    return text;
+            }
+        }
+    }
+    return "";
+}
+function tryParseJsonLoose(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        const m = raw.match(/\{[\s\S]*\}/);
+        if (!m)
+            return null;
+        try {
+            return JSON.parse(m[0]);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export async function generateEnvDocsWithOpenAI(opts) {
+    const input = buildInput(opts);
+    const res = await fetch("https://api.openai.com/v1/responses", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: opts.model,
+            input,
+            text: {
+                format: {
+                    type: "json_schema",
+                    ...JSON_SCHEMA,
+                },
+            },
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`OpenAI request failed (${res.status}): ${text}`);
+    }
+    const data = await res.json();
+    const raw = extractTextFromResponses(data).trim();
+    const parsed = tryParseJsonLoose(raw);
+    if (!parsed) {
+        throw new Error("AI output was not valid JSON. Try again, or use a different model.");
+    }
+    const items = Array.isArray(parsed?.items) ? parsed.items : [];
+    return items
+        .map((x) => {
+        const o = x;
+        return {
+            key: String(o?.key ?? ""),
+            description: String(o?.description ?? ""),
+            where_to_get: String(o?.where_to_get ?? ""),
+            example_value: String(o?.example_value ?? ""),
+            is_secret: Boolean(o?.is_secret),
+        };
+    })
+        .filter((x) => x.key.length > 0);
+}

package/dist/lib/env/render.d.ts

@@ -1,3 +1,4 @@
-import { EnvScanResult } from "./scan.js";
-export declare function renderEnv(result: EnvScanResult): string;
+import type { AIEnvDoc } from "./ai.js";
+import type { EnvScanResult } from "./scan.js";
+export declare function renderEnv(result: EnvScanResult, aiDocs?: AIEnvDoc[]): string;
 //# sourceMappingURL=render.d.ts.map

package/dist/lib/env/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/lib/env/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAgB1C,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA6BvD"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/lib/env/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAgB/C,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,QAAQ,EAAE,GAClB,MAAM,CA6CR"}

package/dist/lib/env/render.js

@@ -6,7 +6,7 @@ const GROUPS = [
     { prefix: "NEXT_PUBLIC_", heading: "Next.js public env" },
     { prefix: "VITE_", heading: "Vite env" },
 ];
-export function renderEnv(result) {
+export function renderEnv(result, aiDocs) {
     const remaining = new Set(result.keys);
     const groups = [];
     for (const { prefix, heading } of GROUPS) {
@@ -22,11 +22,27 @@ export function renderEnv(result) {
             keys: Array.from(remaining).sort(),
         });
     }
+    const byKey = aiDocs?.length
+        ? new Map(aiDocs.map((d) => [d.key, d]))
+        : null;
     const lines = [];
     for (const group of groups) {
         lines.push(`# ${group.heading}`);
         for (const key of group.keys) {
-            lines.push(`${key}=`);
+            const d = byKey?.get(key);
+            if (d) {
+                const secretNote = d.is_secret
+                    ? "Secret value. Do not commit."
+                    : "Non-secret value (verify before committing).";
+                lines.push(`# ${d.key}`);
+                lines.push(`# ${d.description}`);
+                lines.push(`# Where to get it: ${d.where_to_get}`);
+                lines.push(`# ${secretNote}`);
+                lines.push(`${d.key}=${d.example_value ?? ""}`);
+            }
+            else {
+                lines.push(`${key}=`);
+            }
         }
         lines.push("");
     }

package/dist/lib/env/scan.d.ts

@@ -1,5 +1,14 @@
 export interface EnvScanResult {
     keys: string[];
 }
+export interface KeyContext {
+    file: string;
+    line: number;
+    snippet: string;
+}
+export interface EnvScanWithContextResult extends EnvScanResult {
+    contexts: Record<string, KeyContext[]>;
+}
 export declare function scanEnv(cwd?: string): Promise<EnvScanResult>;
+export declare function scanEnvWithContext(cwd?: string, maxContextPerKey?: number): Promise<EnvScanWithContextResult>;
 //# sourceMappingURL=scan.d.ts.map

package/dist/lib/env/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/lib/env/scan.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAcD,wBAAsB,OAAO,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BzE"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/lib/env/scan.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;CACxC;AA6BD,wBAAsB,OAAO,CAAC,GAAG,SAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAGzE;AAED,wBAAsB,kBAAkB,CACtC,GAAG,SAAgB,EACnB,gBAAgB,SAAI,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAqDnC"}

package/dist/lib/env/scan.js

@@ -1,36 +1,83 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import fg from "fast-glob";
 const INCLUDE_GLOBS = [
-    "src/**/*.{js,jsx,ts,tsx}",
-    "app/**/*.{js,jsx,ts,tsx}",
-    "server/**/*.{js,jsx,ts,tsx}",
-    "pages/**/*.{js,jsx,ts,tsx}",
+    "src/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+    "app/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+    "server/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+    "pages/**/*.{js,jsx,ts,tsx,mjs,cjs}",
 ];
 const EXCLUDE_GLOBS = ["**/node_modules/**", "**/dist/**", "**/.next/**", "**/build/**", "**/coverage/**"];
+const ENV_KEY_STRICT = /^[A-Z][A-Z0-9_]*$/;
+// Patterns: [RegExp, group index for key]
+const CODE_PATTERNS = [
+    [/\bprocess(?:\?\.|\.)env(?:\?\.|\.)([A-Za-z_][A-Za-z0-9_]*)\b/g, 1],
+    [/\bprocess(?:\?\.|\.)env\[\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\]/g, 1],
+    [/\bimport\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1],
+    [/\bDeno\.env\.get\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\s*\)/g, 1],
+    [/\bBun\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1],
+];
 const PROCESS_ENV_REGEX = /process\.env\.([A-Z0-9_]+)/g;
 const IMPORT_META_ENV_REGEX = /import\.meta\.env\.([A-Z0-9_]+)/g;
+function keyOk(k) {
+    return ENV_KEY_STRICT.test(k);
+}
 export async function scanEnv(cwd = process.cwd()) {
+    const withCtx = await scanEnvWithContext(cwd, 0);
+    return { keys: withCtx.keys };
+}
+export async function scanEnvWithContext(cwd = process.cwd(), maxContextPerKey = 2) {
     const files = await fg(INCLUDE_GLOBS, {
         cwd,
         ignore: EXCLUDE_GLOBS,
         absolute: true,
     });
     const keys = new Set();
-    for (const file of files) {
+    const contexts = {};
+    function addCtx(key, relFile, line, snippet) {
+        if (!keyOk(key))
+            return;
+        keys.add(key);
+        if (maxContextPerKey <= 0)
+            return;
+        if (!contexts[key])
+            contexts[key] = [];
+        if (contexts[key].length >= maxContextPerKey)
+            return;
+        contexts[key].push({
+            file: relFile,
+            line,
+            snippet: snippet.trim().slice(0, 220),
+        });
+    }
+    for (const absPath of files) {
         let content;
         try {
-            content = await fs.readFile(file, "utf8");
+            content = await fs.readFile(absPath, "utf8");
         }
         catch {
             continue;
         }
-        let match;
-        while ((match = PROCESS_ENV_REGEX.exec(content)) !== null) {
-            keys.add(match[1]);
-        }
-        while ((match = IMPORT_META_ENV_REGEX.exec(content)) !== null) {
-            keys.add(match[1]);
+        const relFile = path.relative(cwd, absPath).replace(/\\/g, "/");
+        const lines = content.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const ln = lines[i];
+            if (ln.trim().startsWith("//") || ln.trim().startsWith("#"))
+                continue;
+            for (const [re, group] of CODE_PATTERNS) {
+                re.lastIndex = 0;
+                let match;
+                while ((match = re.exec(ln)) !== null) {
+                    const k = match[group];
+                    if (!keyOk(k))
+                        continue;
+                    addCtx(k, relFile, i + 1, ln);
+                }
+            }
         }
     }
-    return { keys: Array.from(keys).sort() };
+    return {
+        keys: Array.from(keys).sort(),
+        contexts,
+    };
 }

package/dist/lib/env/write.d.ts

@@ -3,6 +3,9 @@ export interface EnvGenerateFlags {
     create: boolean;
     force: boolean;
     check: boolean;
+    ai: boolean;
+    model: string;
+    apiKey: string;
 }
 export declare function runEnvGenerate(opts?: Partial<EnvGenerateFlags>): Promise<void>;
 //# sourceMappingURL=write.d.ts.map

package/dist/lib/env/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/lib/env/write.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAgCD,wBAAsB,cAAc,CAAC,IAAI,GAAE,OAAO,CAAC,gBAAgB,CAAM,iBA8CxE"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/lib/env/write.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAmCD,wBAAsB,cAAc,CAAC,IAAI,GAAE,OAAO,CAAC,gBAAgB,CAAM,iBA6ExE"}

package/dist/lib/env/write.js

@@ -1,13 +1,17 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { scanEnv } from "./scan.js";
+import { generateEnvDocsWithOpenAI } from "./ai.js";
 import { renderEnv } from "./render.js";
+import { scanEnv, scanEnvWithContext } from "./scan.js";
 import { logInfo, logError } from "../ui/log.js";
 const defaultEnvFlags = {
     out: ".env.example",
     create: false,
     force: false,
     check: false,
+    ai: false,
+    model: "gpt-4o-mini",
+    apiKey: "",
 };
 async function fileExists(p) {
     try {
@@ -39,7 +43,9 @@ export async function runEnvGenerate(opts = {}) {
     const cwd = process.cwd();
     const outPath = path.resolve(cwd, flags.out);
     const envPath = path.resolve(cwd, ".env");
-    const scanResult = await scanEnv(cwd);
+    const scanResult = flags.ai
+        ? await scanEnvWithContext(cwd, 2)
+        : await scanEnv(cwd);
     if (flags.check) {
         if (!(await fileExists(outPath))) {
             logError(`${flags.out} does not exist. Run 'depfix-ai env generate' to create it.`);
@@ -57,8 +63,35 @@ export async function runEnvGenerate(opts = {}) {
         logInfo(`${flags.out} contains all required environment variables.`);
         return;
     }
+    let aiDocs;
+    if (flags.ai && scanResult.keys.length > 0) {
+        const apiKey = flags.apiKey || process.env.OPENAI_API_KEY?.trim();
+        if (!apiKey) {
+            logError("AI mode requires OPENAI_API_KEY or --api-key.");
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            logInfo("Generating descriptions with AI…");
+            const contexts = "contexts" in scanResult && scanResult.contexts
+                ? scanResult.contexts
+                : Object.create(null);
+            aiDocs = await generateEnvDocsWithOpenAI({
+                apiKey,
+                model: flags.model,
+                projectHint: "Practical guidance for developers setting env vars.",
+                contexts,
+                keys: scanResult.keys,
+            });
+        }
+        catch (e) {
+            logError(e?.message ?? String(e));
+            process.exitCode = 1;
+            return;
+        }
+    }
     // Always (re)write the template example file.
-    const exampleContent = renderEnv(scanResult);
+    const exampleContent = renderEnv(scanResult, aiDocs);
     await fs.writeFile(outPath, exampleContent, "utf8");
     logInfo(`Wrote environment template to ${outPath}`);
     if (flags.create) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depfix-ai",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "license": "MIT",
   "engines": {