@env-lane/core 0.1.0

package/dist/index.js

@@ -0,0 +1,884 @@
+// src/check.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import path4 from "path";
+import { parse as parse2 } from "dotenv";
+import fg2 from "fast-glob";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { loadConfig as c12LoadConfig } from "c12";
+import { findUp } from "find-up";
+import YAML from "yaml";
+import { z } from "zod";
+var sortTargetSchema = z.object({
+  baseDir: z.string().min(1).optional(),
+  file: z.string().min(1).optional(),
+  template: z.string().min(1).optional(),
+  files: z.record(z.string(), z.string().min(1)).optional()
+});
+var schema = z.object({
+  selector: z.object({
+    envKey: z.string().min(1).optional(),
+    defaultBuild: z.string().min(1).optional(),
+    builds: z.array(z.string().min(1)).optional(),
+    forbidInDotenv: z.boolean().optional()
+  }).optional(),
+  workspace: z.object({
+    packageGlobs: z.array(z.string().min(1)).optional(),
+    aliases: z.record(z.string(), z.string().min(1)).optional(),
+    defaultTarget: z.string().min(1).optional(),
+    includeRoot: z.boolean().optional()
+  }).optional(),
+  dotenv: z.object({
+    order: z.array(z.string().min(1)).optional(),
+    localBuildName: z.string().min(1).optional(),
+    localOverrideFile: z.string().min(1).optional(),
+    requireOverride: z.boolean().optional(),
+    includeProcessEnv: z.boolean().optional()
+  }).optional(),
+  vault: z.object({
+    enabled: z.boolean().optional(),
+    disableUnsafeWarning: z.boolean().optional(),
+    configFile: z.string().min(1).optional()
+  }).optional(),
+  output: z.object({
+    format: z.enum(["text", "json", "dotenv"]).optional()
+  }).optional(),
+  sort: z.record(z.string(), sortTargetSchema).optional()
+}).passthrough();
+function defineConfig(config) {
+  return config;
+}
+async function findWorkspaceRoot(cwd = process.cwd()) {
+  const marker = await findUp(["pnpm-workspace.yaml", "package.json", ".git"], {
+    cwd,
+    type: "file"
+  });
+  if (!marker) return path.resolve(cwd);
+  if (path.basename(marker) === ".git") return path.dirname(marker);
+  if (path.basename(marker) === "package.json") {
+    const pnpm = await findUp("pnpm-workspace.yaml", { cwd: path.dirname(marker), type: "file" });
+    return pnpm ? path.dirname(pnpm) : path.dirname(marker);
+  }
+  return path.dirname(marker);
+}
+function readPnpmWorkspaceGlobs(rootDir) {
+  const workspaceFile = path.join(rootDir, "pnpm-workspace.yaml");
+  if (!existsSync(workspaceFile)) return [];
+  const doc = YAML.parse(readFileSync(workspaceFile, "utf8"));
+  return Array.isArray(doc?.packages) ? doc.packages.filter((item) => typeof item === "string") : [];
+}
+async function loadEnvLaneConfig(options = {}) {
+  const rootDir = await findWorkspaceRoot(options.cwd);
+  const configFileName = options.configFile ? path.relative(rootDir, path.resolve(rootDir, options.configFile)) : void 0;
+  const loaded = await c12LoadConfig({
+    name: "env-lane",
+    cwd: rootDir,
+    configFile: configFileName,
+    packageJson: false,
+    dotenv: false,
+    rcFile: false,
+    globalRc: false
+  });
+  const parsed = schema.parse(loaded.config ?? {});
+  const workspaceGlobs = parsed.workspace?.packageGlobs ?? readPnpmWorkspaceGlobs(rootDir) ?? [];
+  return {
+    rootDir,
+    selector: {
+      envKey: parsed.selector?.envKey ?? "ENV_BUILD",
+      defaultBuild: parsed.selector?.defaultBuild ?? "local",
+      builds: parsed.selector?.builds ?? [],
+      forbidInDotenv: parsed.selector?.forbidInDotenv ?? true
+    },
+    workspace: {
+      packageGlobs: workspaceGlobs.length ? workspaceGlobs : ["packages/*", "apps/*"],
+      aliases: parsed.workspace?.aliases ?? {},
+      defaultTarget: parsed.workspace?.defaultTarget ?? "",
+      includeRoot: parsed.workspace?.includeRoot ?? true
+    },
+    dotenv: {
+      order: parsed.dotenv?.order ?? [".env", ".env.{build}"],
+      localBuildName: parsed.dotenv?.localBuildName ?? "local",
+      localOverrideFile: parsed.dotenv?.localOverrideFile ?? ".env.local",
+      requireOverride: parsed.dotenv?.requireOverride ?? false,
+      includeProcessEnv: parsed.dotenv?.includeProcessEnv ?? true
+    },
+    vault: {
+      enabled: parsed.vault?.enabled ?? false,
+      disableUnsafeWarning: parsed.vault?.disableUnsafeWarning ?? false,
+      configFile: parsed.vault?.configFile ?? "env-lane.vault.json"
+    },
+    output: {
+      format: parsed.output?.format ?? "text"
+    },
+    sort: parsed.sort
+  };
+}
+
+// src/dotenv.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import path3 from "path";
+import { parse } from "dotenv";
+
+// src/workspace.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import path2 from "path";
+import fg from "fast-glob";
+function readPackageName(dir) {
+  const file = path2.join(dir, "package.json");
+  if (!existsSync2(file)) return void 0;
+  try {
+    const json = JSON.parse(readFileSync2(file, "utf8"));
+    return typeof json.name === "string" ? json.name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+async function listWorkspacePackages(options = {}) {
+  const config = options.config ?? await loadEnvLaneConfig(options);
+  return listWorkspacePackagesForConfig(config);
+}
+async function listWorkspacePackagesForConfig(config) {
+  const entries = await fg(config.workspace.packageGlobs, {
+    cwd: config.rootDir,
+    onlyDirectories: true,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**"]
+  });
+  const packages = [];
+  if (config.workspace.includeRoot) {
+    const rootName = readPackageName(config.rootDir);
+    packages.push({
+      name: rootName,
+      dir: config.rootDir,
+      relativeDir: ".",
+      aliases: unique(["root", ".", rootName].filter(Boolean)),
+      isRoot: true
+    });
+  }
+  for (const dir of entries.sort()) {
+    const packageJson = path2.join(dir, "package.json");
+    if (!existsSync2(packageJson)) continue;
+    const name = readPackageName(dir);
+    const relativeDir = path2.relative(config.rootDir, dir).replaceAll(path2.sep, "/");
+    packages.push({
+      name,
+      dir,
+      relativeDir,
+      aliases: unique([name, path2.basename(dir), relativeDir].filter(Boolean)),
+      isRoot: false
+    });
+  }
+  for (const [alias, target] of Object.entries(config.workspace.aliases)) {
+    const matched = packages.find(
+      (pkg) => pkg.name === target || pkg.relativeDir === target || path2.basename(pkg.dir) === target
+    );
+    if (matched && !matched.aliases.includes(alias)) matched.aliases.push(alias);
+  }
+  const byDir = /* @__PURE__ */ new Map();
+  for (const pkg of packages) byDir.set(pkg.dir, pkg);
+  return [...byDir.values()];
+}
+function targetMatchesPackage(pkg, value) {
+  return pkg.aliases.includes(value) || pkg.name === value || pkg.relativeDir === value;
+}
+function formatAvailableTargets(packages) {
+  return unique(packages.flatMap((pkg) => pkg.aliases)).join(", ");
+}
+function resolveTargetPackageFromList(target, config, packages) {
+  const value = (target || config.workspace.defaultTarget || "").trim();
+  if (!value) {
+    const nonRoot = packages.filter((pkg) => !pkg.isRoot);
+    if (nonRoot.length === 0) return packages.find((pkg) => pkg.isRoot) ?? packages[0];
+    throw new Error(`Missing target. Available targets: ${formatAvailableTargets(packages)}`);
+  }
+  const matches = packages.filter((pkg) => targetMatchesPackage(pkg, value));
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous target '${value}'. Matches: ${matches.map((pkg) => pkg.name ?? pkg.relativeDir).join(", ")}. Use a package name, relative directory, or configure a unique alias.`
+    );
+  }
+  const matched = matches[0];
+  if (!matched) {
+    throw new Error(
+      `Unknown target '${value}'. Available targets: ${formatAvailableTargets(packages)}`
+    );
+  }
+  return matched;
+}
+async function resolveTargetPackage(target, options = {}) {
+  const config = options.config ?? await loadEnvLaneConfig(options);
+  const packages = options.packages ?? await listWorkspacePackagesForConfig(config);
+  return resolveTargetPackageFromList(target, config, packages);
+}
+
+// src/dotenv.ts
+function resolveBuildName(options, envKey, defaultBuild) {
+  const raw = String(options.build ?? process.env[envKey] ?? defaultBuild).trim();
+  if (!raw) throw new Error("Build name is empty.");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(raw)) throw new Error(`Invalid build name '${raw}'.`);
+  return raw;
+}
+function patternToFile(pattern, build, localBuildName, localOverrideFile) {
+  if (pattern === ".env.{build}" && build === localBuildName) return localOverrideFile;
+  return pattern.replaceAll("{build}", build);
+}
+async function listEnvFiles(options = {}) {
+  const config = await loadEnvLaneConfig(options);
+  const target = await resolveTargetPackage(options.target, { ...options, config });
+  return listEnvFilesForTarget(config, target, options);
+}
+function listEnvFilesForTarget(config, target, options = {}) {
+  const build = resolveBuildName(options, config.selector.envKey, config.selector.defaultBuild);
+  return config.dotenv.order.map((pattern, index) => {
+    const fileName = patternToFile(
+      pattern,
+      build,
+      config.dotenv.localBuildName,
+      config.dotenv.localOverrideFile
+    );
+    const filePath = path3.resolve(target.dir, fileName);
+    return {
+      kind: index === 0 ? "base" : index === 1 ? "override" : "custom",
+      path: filePath,
+      relativePath: path3.relative(config.rootDir, filePath).replaceAll(path3.sep, "/"),
+      exists: existsSync3(filePath),
+      required: index > 0 && Boolean(options.requireOverride ?? config.dotenv.requireOverride),
+      order: index
+    };
+  });
+}
+function lineForKey(content, key) {
+  const lines = content.split(/\r?\n/);
+  const re = new RegExp(`^\\s*(?:export\\s+)?${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=`);
+  const idx = lines.findIndex((line) => re.test(line));
+  return idx >= 0 ? idx + 1 : void 0;
+}
+async function resolveInjectedEnv(options = {}) {
+  const config = await loadEnvLaneConfig(options);
+  const target = await resolveTargetPackage(options.target, { ...options, config });
+  const build = resolveBuildName(options, config.selector.envKey, config.selector.defaultBuild);
+  const files = listEnvFilesForTarget(config, target, options);
+  const values = {};
+  const sources = {};
+  const missingRequired = files.filter((file) => file.required && !file.exists);
+  if (missingRequired.length)
+    throw new Error(
+      `Missing required env file(s): ${missingRequired.map((file) => file.relativePath).join(", ")}`
+    );
+  for (const file of files) {
+    if (!file.exists) continue;
+    const content = readFileSync3(file.path, "utf8");
+    const parsed = parse(content);
+    if (config.selector.forbidInDotenv && Object.prototype.hasOwnProperty.call(parsed, config.selector.envKey)) {
+      throw new Error(
+        `${config.selector.envKey} is a selector and must not be stored in dotenv files (${file.relativePath}).`
+      );
+    }
+    for (const [key, value] of Object.entries(parsed)) {
+      values[key] = value;
+      sources[key] = {
+        source: "dotenv",
+        file: file.path,
+        relativeFile: file.relativePath,
+        line: lineForKey(content, key)
+      };
+    }
+  }
+  if (options.includeProcessEnv ?? config.dotenv.includeProcessEnv) {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value === void 0) continue;
+      if (Object.prototype.hasOwnProperty.call(values, key)) {
+        sources[key] = { source: "process", shellOverride: true };
+      } else {
+        sources[key] = { source: "process" };
+      }
+      values[key] = value;
+    }
+  }
+  values[config.selector.envKey] = build;
+  sources[config.selector.envKey] = {
+    source: "selector",
+    shellOverride: Object.prototype.hasOwnProperty.call(process.env, config.selector.envKey)
+  };
+  return {
+    rootDir: config.rootDir,
+    target,
+    build,
+    selectorKey: config.selector.envKey,
+    files,
+    values,
+    sources
+  };
+}
+
+// src/check.ts
+function lineForKey2(content, key) {
+  const lines = content.split(/\r?\n/);
+  const re = new RegExp(`^\\s*(?:export\\s+)?${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=`);
+  const idx = lines.findIndex((line) => re.test(line));
+  return idx >= 0 ? idx + 1 : void 0;
+}
+async function checkDotenvSelector(options = {}) {
+  const config = await loadEnvLaneConfig(options);
+  const target = options.target && options.target !== "all" ? await resolveTargetPackage(options.target, { ...options, config }) : void 0;
+  const scanDir = target?.dir ?? config.rootDir;
+  const files = await fg2(["**/.env", "**/.env.*", "**/*.env", "**/*.env.*"], {
+    cwd: scanDir,
+    absolute: true,
+    onlyFiles: true,
+    ignore: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/coverage/**",
+      "**/tmp/**",
+      "**/.git/**",
+      "**/.turbo/**"
+    ]
+  });
+  const violations = [];
+  for (const file of files) {
+    if (!existsSync4(file)) continue;
+    const content = readFileSync4(file, "utf8");
+    const parsed = parse2(content);
+    if (Object.prototype.hasOwnProperty.call(parsed, config.selector.envKey)) {
+      violations.push({
+        file,
+        relativeFile: path4.relative(config.rootDir, file).replaceAll(path4.sep, "/"),
+        line: lineForKey2(content, config.selector.envKey)
+      });
+    }
+  }
+  const missingRequired = [];
+  if (options.requireOverride ?? config.dotenv.requireOverride) {
+    const targets = options.target && options.target !== "all" ? [target ?? await resolveTargetPackage(options.target, { ...options, config })] : await listWorkspacePackagesForConfig(config);
+    for (const pkg of targets) {
+      const envFiles = listEnvFilesForTarget(config, pkg, {
+        target: pkg.relativeDir,
+        build: options.build,
+        requireOverride: true
+      });
+      for (const file of envFiles.filter((item) => item.required && !item.exists)) {
+        missingRequired.push({
+          file: file.path,
+          relativeFile: file.relativePath,
+          target: pkg.name ?? pkg.relativeDir
+        });
+      }
+    }
+  }
+  return {
+    ok: violations.length === 0 && missingRequired.length === 0,
+    selectorKey: config.selector.envKey,
+    violations,
+    missingRequired
+  };
+}
+
+// src/logger.ts
+var currentLogger = {
+  log: (...args) => console.log(...args),
+  info: (...args) => console.info(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args),
+  success: (...args) => console.log(...args),
+  debug: (...args) => console.debug(...args),
+  write: (msg) => process.stdout.write(msg)
+};
+function setLogger(logger) {
+  currentLogger = logger;
+}
+function getLogger() {
+  return currentLogger;
+}
+
+// src/redaction.ts
+var SECRET_KEY_RE = /(SECRET|PRIVATE|PASSWORD|PASS|TOKEN|API_KEY|ACCESS_KEY|CREDENTIAL|DATABASE_URL|DB_URL|REDIS_URL|REDIS_URI|RPC_URL|(^|_)KEY($|_))/i;
+function isSecretLikeKey(key) {
+  return SECRET_KEY_RE.test(key);
+}
+function redactValue(key, value, showSecrets = false) {
+  if (showSecrets) return value;
+  return isSecretLikeKey(key) ? value ? "<redacted>" : "" : value;
+}
+function redactRecord(values, showSecrets = false) {
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [key, redactValue(key, value, showSecrets)])
+  );
+}
+
+// src/run.ts
+import { execa } from "execa";
+async function runWithInjectedEnv(options) {
+  if (!options.command.length) throw new Error("Missing command.");
+  const resolved = await resolveInjectedEnv(options);
+  const cwd = options.runCwd === "root" ? resolved.rootDir : !options.runCwd || options.runCwd === "target" ? resolved.target.dir : options.runCwd;
+  if (!options.quiet) {
+    const loaded = resolved.files.filter((file) => file.exists).map((file) => file.relativePath).join(", ") || "<none>";
+    const missing = resolved.files.filter((file) => !file.exists).map((file) => file.relativePath).join(", ");
+    const logger = getLogger();
+    logger.info(
+      `[env-lane] target=${resolved.target.name ?? resolved.target.relativeDir} build=${resolved.build}`
+    );
+    logger.info(`[env-lane] loaded=${loaded}`);
+    if (missing) logger.info(`[env-lane] missing=${missing}`);
+  }
+  const subprocess = execa(options.command[0], options.command.slice(1), {
+    cwd,
+    env: resolved.values,
+    stdio: "inherit",
+    reject: false,
+    shell: process.platform === "win32"
+  });
+  const result = await subprocess;
+  return result.exitCode ?? 1;
+}
+
+// src/sort.ts
+import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync5, writeFileSync } from "fs";
+import path5 from "path";
+var ENV_ENTRY_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+var COMMENTED_ENV_ENTRY_RE = /^\s*#\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+function portable(file) {
+  return file.replace(/\\/g, "/").replaceAll(path5.sep, "/");
+}
+async function loadSortConfig(configPath) {
+  const abs = path5.resolve(configPath);
+  if (!existsSync5(abs)) throw new Error(`Sort config does not exist: ${abs}`);
+  const config = await loadEnvLaneConfig({ cwd: path5.dirname(abs), configFile: abs });
+  const packages = await listWorkspacePackagesForConfig(config);
+  const sort = { ...config.sort };
+  const handledAliases = /* @__PURE__ */ new Set();
+  for (const pkg of packages) {
+    for (const alias of pkg.aliases) {
+      handledAliases.add(alias);
+      const target = sort[alias] ?? {};
+      sort[alias] = {
+        ...target,
+        baseDir: target.baseDir ?? pkg.dir,
+        file: target.file ?? ".env",
+        template: target.template ?? ".env.example"
+      };
+    }
+  }
+  for (const [key, target] of Object.entries(sort)) {
+    if (handledAliases.has(key)) continue;
+    sort[key] = {
+      ...target,
+      baseDir: target.baseDir ?? config.rootDir,
+      file: target.file ?? ".env",
+      template: target.template ?? ".env.example"
+    };
+  }
+  return {
+    baseDir: config.rootDir,
+    envFiles: [],
+    sort,
+    dotenv: config.dotenv,
+    selector: config.selector,
+    packages
+  };
+}
+function emitCommandChange(command, payload) {
+  getLogger().info(`[env-store-change] ${JSON.stringify({ command, ...payload })}`);
+}
+function createEmptyDocument() {
+  return { hasBom: false, eol: "\n", hasFinalNewline: true, lines: [] };
+}
+function createTextDocument(content) {
+  const hasBom = content.startsWith("\uFEFF");
+  const raw = hasBom ? content.slice(1) : content;
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const hasFinalNewline = raw.length > 0 && /\r?\n$/.test(raw);
+  let lines = raw.length > 0 ? raw.split(/\r\n|\n/) : [];
+  if (hasFinalNewline && lines.at(-1) === "") lines = lines.slice(0, -1);
+  return { hasBom, eol, hasFinalNewline, lines };
+}
+function renderTextDocument(document, lines) {
+  const body = lines.join(document.eol);
+  const withNewline = lines.length > 0 && document.hasFinalNewline ? `${body}${document.eol}` : body;
+  return document.hasBom ? `\uFEFF${withNewline}` : withNewline;
+}
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return { kind: "empty", rawLine: line };
+  if (trimmed.startsWith("#")) {
+    const commentedEntryMatch = line.match(COMMENTED_ENV_ENTRY_RE);
+    if (commentedEntryMatch) {
+      const eqIdx2 = line.indexOf("=");
+      return {
+        kind: "commented-entry",
+        rawLine: line,
+        key: commentedEntryMatch[1],
+        prefix: line.slice(0, eqIdx2 + 1),
+        rawValue: line.slice(eqIdx2 + 1)
+      };
+    }
+    return { kind: "comment", rawLine: line };
+  }
+  const eqIdx = line.indexOf("=");
+  if (eqIdx < 0) return { kind: "invalid", rawLine: line, reason: "missing equals sign" };
+  const match = line.match(ENV_ENTRY_RE);
+  if (!match) return { kind: "invalid", rawLine: line, reason: "invalid env key" };
+  return {
+    kind: "entry",
+    rawLine: line,
+    key: match[1],
+    prefix: line.slice(0, eqIdx + 1),
+    rawValue: line.slice(eqIdx + 1)
+  };
+}
+function loadEnvDocument(filePath) {
+  const fileExists = existsSync5(filePath);
+  const document = fileExists ? createTextDocument(readFileSync5(filePath, "utf8")) : createEmptyDocument();
+  const parsedLines = document.lines.map((line, index) => ({
+    lineNumber: index + 1,
+    ...parseEnvLine(line)
+  }));
+  return { exists: fileExists, document, parsedLines };
+}
+function isEnvEntryLikeLine(line) {
+  return line.kind === "entry" || line.kind === "commented-entry";
+}
+function buildEnvSortLayout(envDoc) {
+  const blocks = [];
+  let preambleLines = [];
+  let pendingLines = [];
+  let sawEntry = false;
+  for (const line of envDoc.parsedLines) {
+    if (isEnvEntryLikeLine(line)) {
+      if (!sawEntry) {
+        preambleLines = pendingLines;
+        pendingLines = [];
+        sawEntry = true;
+      }
+      blocks.push({
+        key: line.key,
+        kind: line.kind,
+        rawLine: line.rawLine,
+        rawValue: line.rawValue,
+        leadingLines: pendingLines,
+        lineNumber: line.lineNumber,
+        order: blocks.length
+      });
+      pendingLines = [];
+      continue;
+    }
+    pendingLines.push(line.rawLine);
+  }
+  if (!sawEntry) {
+    preambleLines = pendingLines;
+    pendingLines = [];
+  }
+  return { preambleLines, blocks, suffixLines: pendingLines };
+}
+function hasCommentedEnvValue(block) {
+  const trimmed = block.rawValue.trim();
+  return trimmed !== "" && !trimmed.startsWith("#");
+}
+function shouldIgnoreEmptyCommentedEnvBlock(block, groupBlocks) {
+  if (block.kind !== "commented-entry" || hasCommentedEnvValue(block)) return false;
+  return groupBlocks.some(
+    (candidate) => candidate !== block && (candidate.kind === "entry" || hasCommentedEnvValue(candidate))
+  );
+}
+function isBlankLine(line) {
+  return line.trim() === "";
+}
+function normalizeBlankLineRuns(lines) {
+  const normalizedLines = [];
+  for (const line of lines) {
+    if (isBlankLine(line) && normalizedLines.length > 0 && isBlankLine(normalizedLines.at(-1) ?? ""))
+      continue;
+    normalizedLines.push(line);
+  }
+  return normalizedLines;
+}
+function buildEnvSortGroups(blocks) {
+  const groupedBlocks = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    const groupBlocks = groupedBlocks.get(block.key) ?? [];
+    groupBlocks.push(block);
+    groupedBlocks.set(block.key, groupBlocks);
+  }
+  const groups = [];
+  for (const [key, groupBlocks] of groupedBlocks) {
+    const keptBlocks = groupBlocks.filter(
+      (block) => !shouldIgnoreEmptyCommentedEnvBlock(block, groupBlocks)
+    );
+    if (keptBlocks.length === 0) continue;
+    groups.push({
+      key,
+      order: Math.min(...keptBlocks.map((block) => block.order)),
+      blocks: keptBlocks,
+      leadingLines: normalizeBlankLineRuns(groupBlocks.flatMap((block) => block.leadingLines)),
+      rawLines: keptBlocks.map((block) => block.rawLine)
+    });
+  }
+  groups.sort((left, right) => left.order - right.order);
+  return groups;
+}
+function buildCommentLineSet(lines) {
+  const normalizedComments = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    const parsed = parseEnvLine(line);
+    if (parsed.kind === "comment") normalizedComments.add(line.trim());
+  }
+  return normalizedComments;
+}
+function partitionPreambleLines(templateLines, envLines) {
+  const normalizedTemplateLines = normalizeBlankLineRuns(templateLines);
+  const normalizedEnvLines = normalizeBlankLineRuns(envLines);
+  if (normalizedEnvLines.length === 0) return { matchedTemplateLines: [], extraLines: [] };
+  if (normalizedTemplateLines.length === 0) {
+    return {
+      matchedTemplateLines: [],
+      extraLines: normalizedEnvLines.filter((line) => !isBlankLine(line))
+    };
+  }
+  const templateComments = buildCommentLineSet(normalizedTemplateLines);
+  const matchedTemplateLines = [];
+  const extraLines = [];
+  for (const line of normalizedEnvLines) {
+    const parsed = parseEnvLine(line);
+    if (parsed.kind === "comment" && templateComments.has(line.trim())) {
+      matchedTemplateLines.push(line);
+      continue;
+    }
+    if (parsed.kind === "empty") continue;
+    extraLines.push(line);
+  }
+  return {
+    matchedTemplateLines: normalizeBlankLineRuns(matchedTemplateLines),
+    extraLines: normalizeBlankLineRuns(extraLines)
+  };
+}
+function mergeLeadingLines(templateLines, envLines) {
+  const normalizedTemplateLines = normalizeBlankLineRuns(templateLines);
+  if (normalizedTemplateLines.length === 0) return normalizeBlankLineRuns(envLines);
+  const templateComments = buildCommentLineSet(normalizedTemplateLines);
+  const unmatchedEnvLines = normalizeBlankLineRuns(
+    envLines.filter((line) => {
+      const parsed = parseEnvLine(line);
+      if (parsed.kind === "empty") return false;
+      return parsed.kind !== "comment" || !templateComments.has(line.trim());
+    })
+  );
+  if (unmatchedEnvLines.length === 0) return normalizedTemplateLines;
+  const mergedLines = [...normalizedTemplateLines];
+  if (!isBlankLine(mergedLines.at(-1) ?? "") && !isBlankLine(unmatchedEnvLines[0]))
+    mergedLines.push("");
+  mergedLines.push(...unmatchedEnvLines);
+  return normalizeBlankLineRuns(mergedLines);
+}
+function commentOutEnvEntryLine(line) {
+  const parsed = parseEnvLine(line);
+  if (parsed.kind === "commented-entry") return parsed.rawLine;
+  if (parsed.kind !== "entry") return `# ${line.trimStart()}`;
+  const indent = line.match(/^\s*/)?.[0] ?? "";
+  return `${indent}# ${line.slice(indent.length)}`;
+}
+function buildEnvSortPlan(envFilePath, templateFilePath) {
+  const resolvedEnvFilePath = path5.resolve(envFilePath);
+  const resolvedTemplateFilePath = path5.resolve(templateFilePath);
+  if (!existsSync5(resolvedTemplateFilePath)) {
+    throw new Error(`Template env file does not exist: ${resolvedTemplateFilePath}`);
+  }
+  const envDoc = loadEnvDocument(resolvedEnvFilePath);
+  const templateDoc = loadEnvDocument(resolvedTemplateFilePath);
+  const envLayout = buildEnvSortLayout(envDoc);
+  const templateLayout = buildEnvSortLayout(templateDoc);
+  if (envLayout.blocks.length > 0) {
+    const { matchedTemplateLines, extraLines } = partitionPreambleLines(
+      templateLayout.preambleLines,
+      envLayout.preambleLines
+    );
+    envLayout.preambleLines = matchedTemplateLines;
+    if (extraLines.length > 0) {
+      envLayout.blocks[0] = {
+        ...envLayout.blocks[0],
+        leadingLines: normalizeBlankLineRuns([...extraLines, ...envLayout.blocks[0].leadingLines])
+      };
+    }
+  }
+  const envGroups = new Map(buildEnvSortGroups(envLayout.blocks).map((group) => [group.key, group]));
+  const templateKeys = new Set(templateLayout.blocks.map((block) => block.key));
+  const templateBlocksByKey = [];
+  const seenTemplateKeys = /* @__PURE__ */ new Set();
+  for (const block of templateLayout.blocks) {
+    if (seenTemplateKeys.has(block.key)) continue;
+    seenTemplateKeys.add(block.key);
+    templateBlocksByKey.push(block);
+  }
+  const renderedLines = mergeLeadingLines(templateLayout.preambleLines, envLayout.preambleLines);
+  const consumedKeys = /* @__PURE__ */ new Set();
+  const operations = [];
+  let renderedOrder = 0;
+  for (const templateBlock of templateBlocksByKey) {
+    const envGroup = envGroups.get(templateBlock.key);
+    if (envGroup) {
+      consumedKeys.add(envGroup.key);
+      renderedLines.push(
+        ...mergeLeadingLines(templateBlock.leadingLines, envGroup.leadingLines),
+        ...envGroup.rawLines
+      );
+      if (envGroup.order !== renderedOrder) operations.push({ action: "move", key: envGroup.key });
+      if (envGroup.blocks.length > 1)
+        operations.push({ action: "group-duplicate", key: envGroup.key });
+      renderedOrder++;
+      continue;
+    }
+    renderedLines.push(...templateBlock.leadingLines, commentOutEnvEntryLine(templateBlock.rawLine));
+    operations.push({ action: "insert-commented", key: templateBlock.key });
+    renderedOrder++;
+  }
+  const leftoverGroups = [...envGroups.values()].filter((group) => !consumedKeys.has(group.key));
+  for (const group of leftoverGroups) {
+    renderedLines.push(...group.leadingLines, ...group.rawLines);
+    operations.push({
+      action: templateKeys.has(group.key) ? "append-duplicate" : "append-extra",
+      key: group.key
+    });
+    renderedOrder++;
+  }
+  renderedLines.push(...mergeLeadingLines(templateLayout.suffixLines, envLayout.suffixLines));
+  const renderDocument = envDoc.exists ? envDoc.document : templateDoc.document;
+  const currentContent = envDoc.exists ? renderTextDocument(envDoc.document, envDoc.document.lines) : "";
+  const nextContent = renderTextDocument(renderDocument, renderedLines);
+  const summary = operations.reduce(
+    (acc, operation) => {
+      if (operation.action === "move") acc.movedCount++;
+      else if (operation.action === "insert-commented") acc.insertedCommentedCount++;
+      else if (operation.action === "append-extra") acc.appendedExtraCount++;
+      else if (operation.action === "append-duplicate") acc.appendedDuplicateCount++;
+      else if (operation.action === "group-duplicate") acc.groupedDuplicateCount++;
+      return acc;
+    },
+    {
+      movedCount: 0,
+      insertedCommentedCount: 0,
+      appendedExtraCount: 0,
+      appendedDuplicateCount: 0,
+      groupedDuplicateCount: 0
+    }
+  );
+  return {
+    filePath: resolvedEnvFilePath,
+    templateFilePath: resolvedTemplateFilePath,
+    changed: currentContent !== nextContent,
+    currentContent,
+    nextContent,
+    operations,
+    summary
+  };
+}
+async function sortEnvFile(envFilePath, templateFilePath) {
+  const plan = buildEnvSortPlan(envFilePath, templateFilePath);
+  if (!plan.changed) {
+    return {
+      applied: false,
+      filePath: plan.filePath,
+      templateFilePath: plan.templateFilePath,
+      ...plan.summary
+    };
+  }
+  mkdirSync(path5.dirname(plan.filePath), { recursive: true });
+  writeFileSync(plan.filePath, plan.nextContent, "utf8");
+  for (const operation of plan.operations) {
+    emitCommandChange("sort", {
+      action: operation.action,
+      filePath: portable(plan.filePath),
+      templateFilePath: portable(plan.templateFilePath),
+      key: operation.key
+    });
+  }
+  emitCommandChange("sort", {
+    action: "write-file",
+    filePath: portable(plan.filePath),
+    templateFilePath: portable(plan.templateFilePath)
+  });
+  return {
+    applied: true,
+    filePath: plan.filePath,
+    templateFilePath: plan.templateFilePath,
+    ...plan.summary
+  };
+}
+function normalizeSortSelector(value, fallback, fieldName) {
+  const normalized = value === void 0 || value === null || value === "" ? fallback : String(value).trim();
+  if (!normalized) return fallback;
+  if (fieldName === "env-suffix" && normalized === "default") return "";
+  return normalized;
+}
+function interpolateSortFilePattern(pattern, envSuffix) {
+  return pattern.replaceAll("{env}", envSuffix).replaceAll("{suffix}", envSuffix);
+}
+async function sortEnvFilesFromConfig(configPath, keyArg = "all", envSuffixArg = "all") {
+  const config = await loadSortConfig(configPath);
+  const keySelector = normalizeSortSelector(keyArg, "all", "key");
+  const envSuffixSelector = normalizeSortSelector(envSuffixArg, "all", "env-suffix");
+  const selectedTargets = Object.entries(config.sort).filter(
+    ([key]) => keySelector === "all" || key === keySelector
+  );
+  if (selectedTargets.length === 0) throw new Error(`Unknown sort key: ${keySelector}`);
+  const results = [];
+  for (const [key, target] of selectedTargets) {
+    const baseDir = target.baseDir ?? config.baseDir;
+    const file = target.file ?? ".env";
+    const template = target.template ?? ".env.example";
+    const defaultFilePath = path5.resolve(baseDir, file);
+    const templateFilePath = path5.resolve(baseDir, template);
+    const targetDir = path5.dirname(defaultFilePath);
+    const files = /* @__PURE__ */ new Map([["", defaultFilePath]]);
+    for (const pattern of config.dotenv.order) {
+      if (pattern.includes("{build}")) {
+        for (const build of config.selector.builds) {
+          files.set(build, path5.resolve(targetDir, pattern.replace("{build}", build)));
+        }
+      }
+    }
+    if (target.files) {
+      for (const [suffix, file2] of Object.entries(target.files)) {
+        if (suffix === "default")
+          throw new Error(`config.sort.${key}.files must not use reserved suffix "default".`);
+        files.set(suffix, path5.resolve(baseDir, interpolateSortFilePattern(file2, suffix)));
+      }
+    }
+    const jobs = envSuffixSelector === "all" ? [...files.entries()] : [
+      [
+        envSuffixSelector,
+        files.get(envSuffixSelector) ?? path5.resolve(targetDir, `${path5.basename(defaultFilePath)}.${envSuffixSelector}`)
+      ]
+    ];
+    for (const [, file2] of jobs) results.push(await sortEnvFile(file2, templateFilePath));
+  }
+  return { applied: results.some((result) => result.applied), count: results.length, results };
+}
+export {
+  buildEnvSortPlan,
+  checkDotenvSelector,
+  defineConfig,
+  findWorkspaceRoot,
+  getLogger,
+  isSecretLikeKey,
+  listEnvFiles,
+  listEnvFilesForTarget,
+  listWorkspacePackages,
+  listWorkspacePackagesForConfig,
+  loadEnvLaneConfig,
+  readPnpmWorkspaceGlobs,
+  redactRecord,
+  redactValue,
+  resolveBuildName,
+  resolveInjectedEnv,
+  resolveTargetPackage,
+  resolveTargetPackageFromList,
+  runWithInjectedEnv,
+  setLogger,
+  sortEnvFile,
+  sortEnvFilesFromConfig
+};