configenvy 0.1.2 → 0.1.5

package/dist/index.d.ts

@@ -1,29 +1,51 @@
 #!/usr/bin/env node
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { Command } from 'commander';
-import { buildMarkdownTable, explainVariable, scanProject, toJson, Diagnostic } from '@configenvy/core';
+import { buildMarkdownTable, explainVariable, scanProject, toJson, toSarif, ScanResult, Diagnostic } from '@configenvy/core';
 
 type DoctorOptions = {
-    format?: "text" | "json";
+    format?: "text" | "json" | "sarif";
     strict?: boolean;
     ci?: boolean;
 };
+type InitOptions = {
+    dryRun?: boolean;
+    envExample?: boolean;
+    force?: boolean;
+};
 type CliDependencies = {
     buildMarkdownTable: typeof buildMarkdownTable;
     error: (...values: unknown[]) => void;
     exit: (code: number) => never | void;
     explainVariable: typeof explainVariable;
     log: (...values: unknown[]) => void;
+    readFile: typeof readFile;
     resolvePath: typeof resolve;
     scanProject: typeof scanProject;
     toJson: typeof toJson;
+    toSarif: typeof toSarif;
     writeFile: typeof writeFile;
 };
 declare function createProgram(dependencies?: CliDependencies): Command;
+type InitFile = {
+    content: string;
+    path: 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 runTableUpdate(rootDir: string, table: string, options: {
+    dryRun?: boolean;
+    force?: boolean;
+    update: string;
+}, dependencies?: CliDependencies): Promise<void>;
+declare function updateMarkdownTableBlock(markdown: string, table: string, force: boolean): string;
 declare function resolveOutputPath(projectPath: string, outputPath: string, resolvePath?: typeof resolve): string;
 declare function printHumanReport(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
+declare function printGitHubAnnotations(diagnostics: Diagnostic[], log?: (...values: unknown[]) => void): void;
 
-export { type CliDependencies, createProgram, printHumanReport, resolveOutputPath, runCli, runDoctor };
+export { type CliDependencies, buildInitFiles, createProgram, printGitHubAnnotations, printHumanReport, resolveOutputPath, runCli, runDoctor, runInit, runTableUpdate, tableBlockEnd, tableBlockStart, updateMarkdownTableBlock };

package/dist/index.js

@@ -1,48 +1,69 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { writeFile } from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
 import { isAbsolute, resolve } from "path";
 import { pathToFileURL } from "url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson } from "@configenvy/core";
+import {
+  buildMarkdownTable,
+  explainVariable,
+  scanProject,
+  toJson,
+  toSarif
+} from "@configenvy/core";
 var defaultDependencies = {
   buildMarkdownTable,
   error: console.error,
   exit: process.exit,
   explainVariable,
   log: console.log,
+  readFile,
   resolvePath: resolve,
   scanProject,
   toJson,
+  toSarif,
   writeFile
 };
 function createProgram(dependencies = defaultDependencies) {
   const program = new Command();
-  program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version("0.1.2");
-  program.command("doctor").argument("[path]", "project directory", ".").option("--format <format>", "output format: text or json", "text").option("--strict", "treat documentation warnings as errors").action(async (projectPath, options) => {
+  program.name("configenvy").description("Find missing, unused, undocumented, and risky environment variables.").version("0.1.4");
+  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 or json", "text").action(async (projectPath, options) => {
+  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("table").argument("[path]", "project directory", ".").option("--out <file>", "write markdown table to a file").action(async (projectPath, options) => {
+  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);
     const result = await dependencies.scanProject({ rootDir });
     const table = dependencies.buildMarkdownTable(result);
-    if (options.out) {
+    if (options.update) {
+      await runTableUpdate(rootDir, table, { ...options, update: options.update }, dependencies);
+    } else if (options.out) {
       await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}
 `, "utf8");
     } else {
       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) => {
+    await runInit(projectPath, options, dependencies);
+  });
   program.command("explain").argument("<variable>", "environment variable name").argument("[path]", "project directory", ".").action(async (variable, projectPath) => {
     const result = await dependencies.scanProject({ rootDir: dependencies.resolvePath(projectPath) });
     dependencies.log(dependencies.explainVariable(result, variable));
   });
   return program;
 }
+var starterConfig = {
+  required: [],
+  optional: [],
+  ignore: ["NODE_ENV"],
+  docs: ["README.md", "docs"]
+};
+var tableBlockStart = "<!-- configenvy:start -->";
+var tableBlockEnd = "<!-- configenvy:end -->";
 async function runCli(argv, dependencies = defaultDependencies) {
   const program = createProgram(dependencies);
   await program.parseAsync(argv);
@@ -54,14 +75,152 @@ async function runDoctor(projectPath, options, dependencies = defaultDependencie
   });
   if (options.format === "json") {
     dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
     printHumanReport(result.diagnostics, dependencies.log);
+    if (options.ci) {
+      printGitHubAnnotations(result.diagnostics, dependencies.log);
+    }
   }
   const hasError = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
   const hasWarning = result.diagnostics.some((diagnostic) => diagnostic.severity === "warning");
   if (hasError || options.ci && hasWarning) dependencies.exit(2);
   if (hasWarning) dependencies.exit(1);
 }
+async function runInit(projectPath, options = {}, dependencies = defaultDependencies) {
+  const rootDir = dependencies.resolvePath(projectPath);
+  const result = await dependencies.scanProject({ rootDir });
+  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);
+  if (options.dryRun) {
+    for (const file of files) {
+      dependencies.log(`Would write ${file.path}`);
+      dependencies.log(file.content.trimEnd());
+    }
+    return;
+  }
+  if (!options.force && !await ensureInitTargetsDoNotExist(files, dependencies)) {
+    return;
+  }
+  const flag = options.force ? "w" : "wx";
+  for (const file of files) {
+    try {
+      await dependencies.writeFile(file.path, file.content, { encoding: "utf8", flag });
+    } catch (error) {
+      if (isNodeError(error) && error.code === "EEXIST") {
+        dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+        dependencies.exit(1);
+        return;
+      }
+      throw error;
+    }
+    dependencies.log(`Created ${file.path}`);
+  }
+}
+function buildInitFiles(rootDir, result, includeEnvExample, resolvePath = resolve, existingEnvExample) {
+  const required = detectedRuntimeVariables(result);
+  const config = {
+    ...starterConfig,
+    required
+  };
+  const files = [
+    {
+      path: resolvePath(rootDir, "configenvy.config.json"),
+      content: `${JSON.stringify(config, null, 2)}
+`
+    }
+  ];
+  if (includeEnvExample) {
+    files.push({
+      path: resolvePath(rootDir, ".env.example"),
+      content: buildEnvExampleDraft(result, existingEnvExample)
+    });
+  }
+  return files;
+}
+async function ensureInitTargetsDoNotExist(files, dependencies) {
+  for (const file of files) {
+    const existing = await readOptionalText(file.path, dependencies);
+    if (existing !== void 0) {
+      dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+      dependencies.exit(1);
+      return false;
+    }
+  }
+  return true;
+}
+async function readOptionalText(path, dependencies) {
+  try {
+    return String(await dependencies.readFile(path, "utf8"));
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function detectedRuntimeVariables(result) {
+  const runtimeKinds = /* @__PURE__ */ new Set(["code", "ci", "config"]);
+  return [...new Set(result.references.filter((reference) => runtimeKinds.has(reference.kind)).map((reference) => reference.name))].sort();
+}
+function buildEnvExampleDraft(result, existingContent) {
+  const runtimeVars = detectedRuntimeVariables(result);
+  if (existingContent !== void 0) {
+    const existingVars = extractEnvExampleNames(existingContent);
+    const missingVars = runtimeVars.filter((variable) => !existingVars.has(variable));
+    if (missingVars.length === 0) {
+      return existingContent.endsWith("\n") ? existingContent : `${existingContent}
+`;
+    }
+    return [
+      existingContent.trimEnd(),
+      "# Added by configenvy init",
+      ...missingVars.map((variable) => `${variable}=`)
+    ].filter(Boolean).join("\n") + "\n";
+  }
+  const lines = ["# Generated by configenvy init"];
+  for (const variable of runtimeVars) {
+    lines.push(`${variable}=`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function extractEnvExampleNames(content) {
+  const names = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match?.[1]) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+async function runTableUpdate(rootDir, table, options, dependencies = defaultDependencies) {
+  const targetPath = resolveOutputPath(rootDir, options.update, dependencies.resolvePath);
+  const current = await dependencies.readFile(targetPath, "utf8");
+  const updated = updateMarkdownTableBlock(current, table, Boolean(options.force));
+  if (options.dryRun) {
+    dependencies.log(updated);
+    return;
+  }
+  await dependencies.writeFile(targetPath, updated, "utf8");
+}
+function updateMarkdownTableBlock(markdown, table, force) {
+  const block = `${tableBlockStart}
+${table}
+${tableBlockEnd}`;
+  const blockPattern = new RegExp(`${escapeRegExp(tableBlockStart)}[\\s\\S]*?${escapeRegExp(tableBlockEnd)}`);
+  if (blockPattern.test(markdown)) {
+    return markdown.replace(blockPattern, block);
+  }
+  if (force) {
+    const separator = markdown.endsWith("\n") ? "\n" : "\n\n";
+    return `${markdown}${separator}${block}
+`;
+  }
+  throw new Error(`No configenvy table block found. Add ${tableBlockStart} and ${tableBlockEnd}, or rerun with --force.`);
+}
 function resolveOutputPath(projectPath, outputPath, resolvePath = resolve) {
   if (isAbsolute(outputPath)) return outputPath;
   return resolvePath(projectPath, outputPath);
@@ -83,6 +242,28 @@ function printHumanReport(diagnostics, log = defaultDependencies.log) {
   const warnings = diagnostics.length - errors;
   log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
 }
+function printGitHubAnnotations(diagnostics, log = defaultDependencies.log) {
+  for (const diagnostic of diagnostics) {
+    const command = diagnostic.severity === "error" ? "error" : "warning";
+    const properties = [
+      diagnostic.files[0] ? `file=${escapeAnnotationProperty(diagnostic.files[0])}` : void 0,
+      `title=${escapeAnnotationProperty(`${diagnostic.code} ${diagnostic.variable}`)}`
+    ].filter(Boolean);
+    log(`::${command} ${properties.join(",")}::${escapeAnnotationMessage(diagnostic.message)}`);
+  }
+}
+function escapeAnnotationProperty(value) {
+  return escapeAnnotationMessage(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function escapeAnnotationMessage(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
 var invokedPath = process.argv[1];
 if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
   runCli(process.argv).catch((error) => {
@@ -91,9 +272,16 @@ if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
   });
 }
 export {
+  buildInitFiles,
   createProgram,
+  printGitHubAnnotations,
   printHumanReport,
   resolveOutputPath,
   runCli,
-  runDoctor
+  runDoctor,
+  runInit,
+  runTableUpdate,
+  tableBlockEnd,
+  tableBlockStart,
+  updateMarkdownTableBlock
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configenvy",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "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.2",
+    "@configenvy/core": "0.1.5",
     "commander": "^12.1.0"
   },
   "keywords": [

package/src/index.ts

@@ -1,25 +1,41 @@
 #!/usr/bin/env node
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Command } from "commander";
-import { buildMarkdownTable, explainVariable, scanProject, toJson, type Diagnostic } from "@configenvy/core";
+import {
+  buildMarkdownTable,
+  explainVariable,
+  scanProject,
+  toJson,
+  toSarif,
+  type Diagnostic,
+  type ScanResult
+} from "@configenvy/core";
 
 type DoctorOptions = {
-  format?: "text" | "json";
+  format?: "text" | "json" | "sarif";
   strict?: boolean;
   ci?: boolean;
 };
 
+type InitOptions = {
+  dryRun?: boolean;
+  envExample?: boolean;
+  force?: boolean;
+};
+
 export type CliDependencies = {
   buildMarkdownTable: typeof buildMarkdownTable;
   error: (...values: unknown[]) => void;
   exit: (code: number) => never | void;
   explainVariable: typeof explainVariable;
   log: (...values: unknown[]) => void;
+  readFile: typeof readFile;
   resolvePath: typeof resolve;
   scanProject: typeof scanProject;
   toJson: typeof toJson;
+  toSarif: typeof toSarif;
   writeFile: typeof writeFile;
 };
 
@@ -29,9 +45,11 @@ const defaultDependencies: CliDependencies = {
   exit: process.exit,
   explainVariable,
   log: console.log,
+  readFile,
   resolvePath: resolve,
   scanProject,
   toJson,
+  toSarif,
   writeFile
 };
 
@@ -41,12 +59,12 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   program
     .name("configenvy")
     .description("Find missing, unused, undocumented, and risky environment variables.")
-    .version("0.1.2");
+    .version("0.1.4");
 
   program
     .command("doctor")
     .argument("[path]", "project directory", ".")
-    .option("--format <format>", "output format: text or json", "text")
+    .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, dependencies);
@@ -56,7 +74,7 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .command("check")
     .argument("[path]", "project directory", ".")
     .option("--ci", "fail on warnings and errors")
-    .option("--format <format>", "output format: text or json", "text")
+    .option("--format <format>", "output format: text, json, or sarif", "text")
     .action(async (projectPath: string, options: DoctorOptions) => {
       await runDoctor(projectPath, { ...options, strict: Boolean(options.ci), ci: Boolean(options.ci) }, dependencies);
     });
@@ -65,17 +83,33 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
     .command("table")
     .argument("[path]", "project directory", ".")
     .option("--out <file>", "write markdown table to a file")
-    .action(async (projectPath: string, options: { out?: string }) => {
+    .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: string, options: { dryRun?: boolean; force?: boolean; out?: string; update?: string }) => {
       const rootDir = dependencies.resolvePath(projectPath);
       const result = await dependencies.scanProject({ rootDir });
       const table = dependencies.buildMarkdownTable(result);
-      if (options.out) {
+      if (options.update) {
+        await runTableUpdate(rootDir, table, { ...options, update: options.update }, dependencies);
+      } else if (options.out) {
         await dependencies.writeFile(resolveOutputPath(rootDir, options.out, dependencies.resolvePath), `${table}\n`, "utf8");
       } else {
         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: string, options: InitOptions) => {
+      await runInit(projectPath, options, dependencies);
+    });
+
   program
     .command("explain")
     .argument("<variable>", "environment variable name")
@@ -88,6 +122,21 @@ export function createProgram(dependencies: CliDependencies = defaultDependencie
   return program;
 }
 
+const starterConfig = {
+  required: [],
+  optional: [],
+  ignore: ["NODE_ENV"],
+  docs: ["README.md", "docs"]
+};
+
+type InitFile = {
+  content: string;
+  path: string;
+};
+
+export const tableBlockStart = "<!-- configenvy:start -->";
+export const tableBlockEnd = "<!-- configenvy:end -->";
+
 export async function runCli(argv: string[], dependencies: CliDependencies = defaultDependencies): Promise<void> {
   const program = createProgram(dependencies);
   await program.parseAsync(argv);
@@ -105,8 +154,13 @@ export async function runDoctor(
 
   if (options.format === "json") {
     dependencies.log(dependencies.toJson(result));
+  } else if (options.format === "sarif") {
+    dependencies.log(dependencies.toSarif(result));
   } else {
     printHumanReport(result.diagnostics, dependencies.log);
+    if (options.ci) {
+      printGitHubAnnotations(result.diagnostics, dependencies.log);
+    }
   }
 
   const hasError = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
@@ -115,6 +169,174 @@ export async function runDoctor(
   if (hasWarning) dependencies.exit(1);
 }
 
+export async function runInit(
+  projectPath: string,
+  options: InitOptions = {},
+  dependencies: CliDependencies = defaultDependencies
+): Promise<void> {
+  const rootDir = dependencies.resolvePath(projectPath);
+  const result = await dependencies.scanProject({ rootDir });
+  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);
+
+  if (options.dryRun) {
+    for (const file of files) {
+      dependencies.log(`Would write ${file.path}`);
+      dependencies.log(file.content.trimEnd());
+    }
+    return;
+  }
+
+  if (!options.force && !(await ensureInitTargetsDoNotExist(files, dependencies))) {
+    return;
+  }
+
+  const flag = options.force ? "w" : "wx";
+  for (const file of files) {
+    try {
+      await dependencies.writeFile(file.path, file.content, { encoding: "utf8", flag });
+    } catch (error) {
+      if (isNodeError(error) && error.code === "EEXIST") {
+        dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+        dependencies.exit(1);
+        return;
+      }
+      throw error;
+    }
+
+    dependencies.log(`Created ${file.path}`);
+  }
+}
+
+export function buildInitFiles(
+  rootDir: string,
+  result: ScanResult,
+  includeEnvExample: boolean,
+  resolvePath: typeof resolve = resolve,
+  existingEnvExample?: string
+): InitFile[] {
+  const required = detectedRuntimeVariables(result);
+  const config = {
+    ...starterConfig,
+    required
+  };
+  const files: InitFile[] = [
+    {
+      path: resolvePath(rootDir, "configenvy.config.json"),
+      content: `${JSON.stringify(config, null, 2)}\n`
+    }
+  ];
+
+  if (includeEnvExample) {
+    files.push({
+      path: resolvePath(rootDir, ".env.example"),
+      content: buildEnvExampleDraft(result, existingEnvExample)
+    });
+  }
+
+  return files;
+}
+
+async function ensureInitTargetsDoNotExist(files: InitFile[], dependencies: CliDependencies): Promise<boolean> {
+  for (const file of files) {
+    const existing = await readOptionalText(file.path, dependencies);
+    if (existing !== undefined) {
+      dependencies.error(`${file.path} already exists. Re-run with --force to overwrite.`);
+      dependencies.exit(1);
+      return false;
+    }
+  }
+  return true;
+}
+
+async function readOptionalText(path: string, dependencies: CliDependencies): Promise<string | undefined> {
+  try {
+    return String(await dependencies.readFile(path, "utf8"));
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function detectedRuntimeVariables(result: ScanResult): string[] {
+  const runtimeKinds = new Set(["code", "ci", "config"]);
+  return [...new Set(result.references.filter((reference) => runtimeKinds.has(reference.kind)).map((reference) => reference.name))].sort();
+}
+
+function buildEnvExampleDraft(result: ScanResult, existingContent?: string): string {
+  const runtimeVars = detectedRuntimeVariables(result);
+  if (existingContent !== undefined) {
+    const existingVars = extractEnvExampleNames(existingContent);
+    const missingVars = runtimeVars.filter((variable) => !existingVars.has(variable));
+    if (missingVars.length === 0) {
+      return existingContent.endsWith("\n") ? existingContent : `${existingContent}\n`;
+    }
+
+    return [
+      existingContent.trimEnd(),
+      "# Added by configenvy init",
+      ...missingVars.map((variable) => `${variable}=`)
+    ].filter(Boolean).join("\n") + "\n";
+  }
+
+  const lines = ["# Generated by configenvy init"];
+
+  for (const variable of runtimeVars) {
+    lines.push(`${variable}=`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function extractEnvExampleNames(content: string): Set<string> {
+  const names = new Set<string>();
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match?.[1]) {
+      names.add(match[1]);
+    }
+  }
+  return names;
+}
+
+export async function runTableUpdate(
+  rootDir: string,
+  table: string,
+  options: { dryRun?: boolean; force?: boolean; update: string },
+  dependencies: CliDependencies = defaultDependencies
+): Promise<void> {
+  const targetPath = resolveOutputPath(rootDir, options.update, dependencies.resolvePath);
+  const current = await dependencies.readFile(targetPath, "utf8");
+  const updated = updateMarkdownTableBlock(current, table, Boolean(options.force));
+
+  if (options.dryRun) {
+    dependencies.log(updated);
+    return;
+  }
+
+  await dependencies.writeFile(targetPath, updated, "utf8");
+}
+
+export function updateMarkdownTableBlock(markdown: string, table: string, force: boolean): string {
+  const block = `${tableBlockStart}\n${table}\n${tableBlockEnd}`;
+  const blockPattern = new RegExp(`${escapeRegExp(tableBlockStart)}[\\s\\S]*?${escapeRegExp(tableBlockEnd)}`);
+
+  if (blockPattern.test(markdown)) {
+    return markdown.replace(blockPattern, block);
+  }
+
+  if (force) {
+    const separator = markdown.endsWith("\n") ? "\n" : "\n\n";
+    return `${markdown}${separator}${block}\n`;
+  }
+
+  throw new Error(`No configenvy table block found. Add ${tableBlockStart} and ${tableBlockEnd}, or rerun with --force.`);
+}
+
 export function resolveOutputPath(
   projectPath: string,
   outputPath: string,
@@ -147,6 +369,37 @@ export function printHumanReport(
   log(`Summary: ${errors} error(s), ${warnings} warning(s).`);
 }
 
+export function printGitHubAnnotations(
+  diagnostics: Diagnostic[],
+  log: (...values: unknown[]) => void = defaultDependencies.log
+): void {
+  for (const diagnostic of diagnostics) {
+    const command = diagnostic.severity === "error" ? "error" : "warning";
+    const properties = [
+      diagnostic.files[0] ? `file=${escapeAnnotationProperty(diagnostic.files[0])}` : undefined,
+      `title=${escapeAnnotationProperty(`${diagnostic.code} ${diagnostic.variable}`)}`
+    ].filter(Boolean);
+
+    log(`::${command} ${properties.join(",")}::${escapeAnnotationMessage(diagnostic.message)}`);
+  }
+}
+
+function escapeAnnotationProperty(value: string): string {
+  return escapeAnnotationMessage(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+
+function escapeAnnotationMessage(value: string): string {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
 const invokedPath = process.argv[1];
 if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
   runCli(process.argv).catch((error: unknown) => {