configenvy 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -13,6 +13,7 @@ type InitOptions = {
     dryRun?: boolean;
     envExample?: boolean;
     force?: boolean;
+    preset?: string;
 };
 type CliDependencies = {
     buildMarkdownTable: typeof buildMarkdownTable;
@@ -28,16 +29,23 @@ type CliDependencies = {
     writeFile: typeof writeFile;
 };
 declare function createProgram(dependencies?: CliDependencies): Command;
+type StarterConfig = {
+    docs: string[];
+    ignore: string[];
+    optional: string[];
+    required: string[];
+};
 type InitFile = {
     content: string;
     path: string;
 };
+declare const cliVersion: string;
 declare const tableBlockStart = "<!-- configenvy:start -->";
 declare const tableBlockEnd = "<!-- configenvy:end -->";
 declare function runCli(argv: string[], dependencies?: CliDependencies): Promise<void>;
 declare function runDoctor(projectPath: string, options: DoctorOptions, dependencies?: CliDependencies): Promise<void>;
 declare function runInit(projectPath: string, options?: InitOptions, dependencies?: CliDependencies): Promise<void>;
-declare function buildInitFiles(rootDir: string, result: ScanResult, includeEnvExample: boolean, resolvePath?: typeof resolve, existingEnvExample?: string): InitFile[];
+declare function buildInitFiles(rootDir: string, result: ScanResult, includeEnvExample: boolean, resolvePath?: typeof resolve, existingEnvExample?: string, preset?: Partial<StarterConfig>): InitFile[];
 declare function runTableUpdate(rootDir: string, table: string, options: {
     dryRun?: boolean;
     force?: boolean;
@@ -48,4 +56,4 @@ declare function resolveOutputPath(projectPath: string, outputPath: string, reso
 declare function printHumanReport(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
 declare function printGitHubAnnotations(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
 
-export { type CliDependencies, buildInitFiles, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit, runTableUpdate, tableBlockEnd, tableBlockStart, updateMarkdownTableBlock };
+export { type CliDependencies, buildInitFiles, cliVersion, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit, runTableUpdate, tableBlockEnd, tableBlockStart, updateMarkdownTableBlock };

package/dist/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { readFile, writeFile } from "fs/promises";
+import { createRequire } from "module";
 import { isAbsolute, resolve } from "path";
 import { pathToFileURL } from "url";
 import { Command } from "commander";
@@ -27,12 +28,12 @@ var defaultDependencies = {
 };
 function createProgram(dependencies = defaultDependencies) {
   const program = new Command();
-  program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version("0.1.4");
+  program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version(cliVersion);
   program.command("doctor").argument("[path]", "project directory", ".").option("--format <format>", "output format: text, json, or sarif", "text").option("--strict", "treat documentation warnings as errors").action(async (projectPath, options) => {
     await runDoctor(projectPath, options, dependencies);
   });
-  program.command("check").argument("[path]", "project directory", ".").option("--ci", "fail on warnings and errors").option("--format <format>", "output format: text, json, or sarif", "text").action(async (projectPath, options) => {
-    await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) }, dependencies);
+  program.command("check").argument("[path]", "project directory", ".").option("--ci", "fail on warnings and errors").option("--format <format>", "output format: text, json, or sarif", "text").option("--strict", "treat documentation warnings as errors").action(async (projectPath, options) => {
+    await runDoctor(projectPath, { ...options, strict: Boolean(options.strict || options.ci), ci: Boolean(options.ci) }, dependencies);
   });
   program.command("table").argument("[path]", "project directory", ".").option("--out <file>", "write markdown table to a file").option("--update <file>", "replace a marked configenvy table block in a markdown file").option("--force", "append a configenvy table block when --update target has no marked block").option("--dry-run", "print the updated markdown instead of writing it").action(async (projectPath, options) => {
     const rootDir = dependencies.resolvePath(projectPath);
@@ -47,7 +48,7 @@ function createProgram(dependencies = defaultDependencies) {
       dependencies.log(table);
     }
   });
-  program.command("init").argument("[path]", "project directory", ".").description("create starter configenvy files").option("--dry-run", "print planned files instead of writing them").option("--env-example", "also create a .env.example draft from detected variables").option("--force", "overwrite generated files if they already exist").action(async (projectPath, options) => {
+  program.command("init").argument("[path]", "project directory", ".").description("create starter configenvy files").option("--dry-run", "print planned files instead of writing them").option("--env-example", "also create a .env.example draft from detected variables").option("--force", "overwrite generated files if they already exist").option("--preset <name>", `apply a preset: ${availablePresetList}`).action(async (projectPath, options) => {
     await runInit(projectPath, options, dependencies);
   });
   program.command("explain").argument("<variable>", "environment variable name").argument("[path]", "project directory", ".").action(async (variable, projectPath) => {
@@ -62,6 +63,38 @@ var starterConfig = {
   ignore: ["NODE_ENV"],
   docs: ["README.md", "docs"]
 };
+var presetConfigs = {
+  astro: {
+    optional: ["PUBLIC_SITE_URL"],
+    ignore: ["BASE_URL", "DEV", "MODE", "PROD", "SSR"]
+  },
+  docker: {
+    optional: ["COMPOSE_PROJECT_NAME"],
+    ignore: ["HOSTNAME"]
+  },
+  nextjs: {
+    optional: ["NEXT_PUBLIC_APP_URL"],
+    ignore: ["NEXT_RUNTIME"]
+  },
+  nuxt: {
+    optional: ["NUXT_PUBLIC_API_BASE"]
+  },
+  sveltekit: {
+    optional: ["PUBLIC_BASE_URL"]
+  },
+  vercel: {
+    ignore: ["VERCEL", "VERCEL_ENV", "VERCEL_URL", "VERCEL_BRANCH_URL", "VERCEL_PROJECT_PRODUCTION_URL", "VERCEL_REGION"]
+  },
+  vite: {
+    optional: ["VITE_PUBLIC_URL"],
+    ignore: ["BASE_URL", "DEV", "MODE", "PROD", "SSR"]
+  }
+};
+var availablePresetNames = Object.keys(presetConfigs).sort();
+var availablePresetList = availablePresetNames.join(", ");
+var require2 = createRequire(import.meta.url);
+var cliPackage = require2("../package.json");
+var cliVersion = cliPackage.version;
 var tableBlockStart = "<!-- configenvy:start -->";
 var tableBlockEnd = "<!-- configenvy:end -->";
 async function runCli(argv, dependencies = defaultDependencies) {
@@ -91,8 +124,10 @@ async function runDoctor(projectPath, options, dependencies = defaultDependencie
 async function runInit(projectPath, options = {}, dependencies = defaultDependencies) {
   const rootDir = dependencies.resolvePath(projectPath);
   const result = await dependencies.scanProject({ rootDir });
+  const preset = resolvePreset(options.preset, dependencies);
+  if (options.preset && !preset) return;
   const existingEnvExample = options.envExample && options.force ? await readOptionalText(dependencies.resolvePath(rootDir, ".env.example"), dependencies) : void 0;
-  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample);
+  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample, preset);
   if (options.dryRun) {
     for (const file of files) {
       dependencies.log(`Would write ${file.path}`);
@@ -118,10 +153,13 @@ async function runInit(projectPath, options = {}, dependencies = defaultDependen
     dependencies.log(`Created ${file.path}`);
   }
 }
-function buildInitFiles(rootDir, result, includeEnvExample, resolvePath = resolve, existingEnvExample) {
+function buildInitFiles(rootDir, result, includeEnvExample, resolvePath = resolve, existingEnvExample, preset) {
   const required = detectedRuntimeVariables(result);
   const config = {
     ...starterConfig,
+    docs: mergeUnique(starterConfig.docs, preset?.docs ?? []),
+    ignore: mergeUnique(starterConfig.ignore, preset?.ignore ?? []),
+    optional: mergeUnique(starterConfig.optional, preset?.optional ?? []),
     required
   };
   const files = [
@@ -139,6 +177,18 @@ function buildInitFiles(rootDir, result, includeEnvExample, resolvePath = resolv
   }
   return files;
 }
+function resolvePreset(name, dependencies) {
+  if (!name) return void 0;
+  if (name in presetConfigs) {
+    return presetConfigs[name];
+  }
+  dependencies.error(`Unknown preset "${name}". Available presets: ${availablePresetList}.`);
+  dependencies.exit(1);
+  return void 0;
+}
+function mergeUnique(base, extra) {
+  return [.../* @__PURE__ */ new Set([...base, ...extra])].sort();
+}
 async function ensureInitTargetsDoNotExist(files, dependencies) {
   for (const file of files) {
     const existing = await readOptionalText(file.path, dependencies);
@@ -273,6 +323,7 @@ if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
 }
 export {
   buildInitFiles,
+  cliVersion,
   createProgram,
   printGitHubAnnotations,
   printHumanReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configenvy",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Find missing, unused, undocumented, and risky environment variables before setup breaks.",
   "type": "module",
   "engines": {
@@ -35,7 +35,7 @@
     "build": "tsup src/index.ts --format esm --dts --clean"
   },
   "dependencies": {
-    "@configenvy/core": "0.1.5",
+    "@configenvy/core": "0.1.7",
     "commander": "^12.1.0"
   },
   "keywords": [

package/src/index.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command } from "commander";
@@ -23,6 +24,7 @@ type InitOptions = {
   dryRun?: boolean;
   envExample?: boolean;
   force?: boolean;
+  preset?: string;
 };
 
 export type CliDependencies = {
@@ -59,7 +61,7 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   program
     .name("configenvy")
     .description("Find missing, unused, undocumented, and risky environment variables.")
-    .version("0.1.4");
+    .version(cliVersion);
 
   program
     .command("doctor")
@@ -75,8 +77,9 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .argument("[path]", "project directory", ".")
     .option("--ci", "fail on warnings and errors")
     .option("--format <format>", "output format: text, json, or sarif", "text")
+    .option("--strict", "treat documentation warnings as errors")
     .action(async (projectPath: string, options: DoctorOptions) => {
-      await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) }, dependencies);
+      await runDoctor(projectPath, { ...options, strict: Boolean(options.strict || options.ci), ci: Boolean(options.ci) }, dependencies);
     });
 
   program
@@ -106,6 +109,7 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .option("--dry-run", "print planned files instead of writing them")
     .option("--env-example", "also create a .env.example draft from detected variables")
     .option("--force", "overwrite generated files if they already exist")
+    .option("--preset <name>", `apply a preset: ${availablePresetList}`)
     .action(async (projectPath: string, options: InitOptions) => {
       await runInit(projectPath, options, dependencies);
     });
@@ -122,18 +126,62 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   return program;
 }
 
-const starterConfig = {
+type StarterConfig = {
+  docs: string[];
+  ignore: string[];
+  optional: string[];
+  required: string[];
+};
+
+const starterConfig: StarterConfig = {
   required: [],
   optional: [],
   ignore: ["NODE_ENV"],
   docs: ["README.md", "docs"]
 };
 
+type PresetName = keyof typeof presetConfigs;
+
+const presetConfigs = {
+  astro: {
+    optional: ["PUBLIC_SITE_URL"],
+    ignore: ["BASE_URL", "DEV", "MODE", "PROD", "SSR"]
+  },
+  docker: {
+    optional: ["COMPOSE_PROJECT_NAME"],
+    ignore: ["HOSTNAME"]
+  },
+  nextjs: {
+    optional: ["NEXT_PUBLIC_APP_URL"],
+    ignore: ["NEXT_RUNTIME"]
+  },
+  nuxt: {
+    optional: ["NUXT_PUBLIC_API_BASE"]
+  },
+  sveltekit: {
+    optional: ["PUBLIC_BASE_URL"]
+  },
+  vercel: {
+    ignore: ["VERCEL", "VERCEL_ENV", "VERCEL_URL", "VERCEL_BRANCH_URL", "VERCEL_PROJECT_PRODUCTION_URL", "VERCEL_REGION"]
+  },
+  vite: {
+    optional: ["VITE_PUBLIC_URL"],
+    ignore: ["BASE_URL", "DEV", "MODE", "PROD", "SSR"]
+  }
+} satisfies Record<string, Partial<StarterConfig>>;
+
+const availablePresetNames = Object.keys(presetConfigs).sort();
+const availablePresetList = availablePresetNames.join(", ");
+
 type InitFile = {
   content: string;
   path: string;
 };
 
+const require = createRequire(import.meta.url);
+const cliPackage = require("../package.json") as { version: string };
+export const cliVersion = cliPackage.version;
+
 export const tableBlockStart = "<!-- configenvy:start -->";
 export const tableBlockEnd = "<!-- configenvy:end -->";
 
@@ -176,10 +224,12 @@ export async function runInit(
 ): Promise<void> {
   const rootDir = dependencies.resolvePath(projectPath);
   const result = await dependencies.scanProject({ rootDir });
+  const preset = resolvePreset(options.preset, dependencies);
+  if (options.preset && !preset) return;
   const existingEnvExample = options.envExample && options.force
     ? await readOptionalText(dependencies.resolvePath(rootDir, ".env.example"), dependencies)
     : undefined;
-  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample);
+  const files = buildInitFiles(rootDir, result, Boolean(options.envExample), dependencies.resolvePath, existingEnvExample, preset);
 
   if (options.dryRun) {
     for (const file of files) {
@@ -215,11 +265,15 @@ export function buildInitFiles(
   result: ScanResult,
   includeEnvExample: boolean,
   resolvePath: typeof resolve = resolve,
-  existingEnvExample?: string
+  existingEnvExample?: string,
+  preset?: Partial<StarterConfig>
 ): InitFile[] {
   const required = detectedRuntimeVariables(result);
   const config = {
     ...starterConfig,
+    docs: mergeUnique(starterConfig.docs, preset?.docs ?? []),
+    ignore: mergeUnique(starterConfig.ignore, preset?.ignore ?? []),
+    optional: mergeUnique(starterConfig.optional, preset?.optional ?? []),
     required
   };
   const files: InitFile[] = [
@@ -239,6 +293,20 @@ export function buildInitFiles(
   return files;
 }
 
+function resolvePreset(name: string | undefined, dependencies: CliDependencies): Partial<StarterConfig> | undefined {
+  if (!name) return undefined;
+  if (name in presetConfigs) {
+    return presetConfigs[name as PresetName];
+  }
+  dependencies.error(`Unknown preset "${name}". Available presets: ${availablePresetList}.`);
+  dependencies.exit(1);
+  return undefined;
+}
+
+function mergeUnique(base: string[], extra: readonly string[]): string[] {
+  return [...new Set([...base, ...extra])].sort();
+}
+
 async function ensureInitTargetsDoNotExist(files: InitFile[], dependencies: CliDependencies): Promise<boolean> {
   for (const file of files) {
     const existing = await readOptionalText(file.path, dependencies);