metergraph-cli 0.1.0 → 0.2.0-preview.1

package/src/setup-deployment.js

@@ -0,0 +1,178 @@
+import { runDoctor } from "./doctor.js";
+import { planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
+import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
+
+// Setup routing uses the same deployment model and Metadata credential checks
+// as the standalone routing contract. Operator prerequisites are assertions,
+// not evidence of a released bundle or provisioning. The CLI still verifies
+// the live origin/profile and (when supplied) a separate Metadata credential.
+const PREREQUISITES = Object.freeze({
+  "customer-local": Object.freeze([
+    "released_signed_bundle", "registry_invitation", "bundle_started_verified",
+    "local_admin_configured", "metadata_agent_credential",
+  ]),
+  byoc: Object.freeze([
+    "operator_provisioning", "private_network_reachability",
+    "identity_membership_configured", "metadata_agent_credential",
+  ]),
+  oss: Object.freeze([
+    "server_distribution_installed", "deployment_discovery_supported",
+    "metadata_scope_supported", "ingestion_tokens_configured",
+    "agent_read_tokens_configured", "metadata_agent_credential",
+  ]),
+});
+
+const EXPECTED_PROFILE = Object.freeze({ "customer-local": "local", byoc: "byoc-core", oss: "oss" });
+
+const handoff = (outcome, reason, nextAction = null, details = {}) => ({
+  proceed: false,
+  outcome,
+  reason,
+  data: {
+    status: "operator_handoff",
+    application_traffic_verified: false,
+    deployment_profile: details.profile ?? null,
+    origin: details.origin ?? null,
+    workspace_id: details.workspaceId ?? null,
+    prerequisites: details.prerequisites ?? "not_confirmed",
+    pending_prerequisites: details.pendingPrerequisites ?? [],
+    metadata_access: details.metadataAccess ?? "not_checked",
+    ingest_credential: "not_checked",
+    next_action: nextAction,
+  },
+});
+
+// The static agent token can be any printable string of at least 16 bytes.
+// Even a fixed status such as "operator_handoff" might equal that token. Keep
+// the verifier's non-enumerable knownCredentials on every later result and
+// drop all contextual fields if a coincidental value would echo it.
+function guardKnownCredentials(value, verified) {
+  const known = verified.knownCredentials;
+  if (!known) return value;
+  const safe = known.some((token) => holdsKnown(value, token))
+    ? { proceed: false, outcome: "unsupported", reason: "credential_echo", data: null }
+    : value;
+  Object.defineProperty(safe, "knownCredentials", { value: known, enumerable: false });
+  return safe;
+}
+
+export function containsKnownCredential(value, routed) {
+  return routed?.knownCredentials?.some((token) => holdsKnown(value, token)) ?? false;
+}
+
+function holdsKnown(value, token) {
+  if (typeof value === "string") return value.includes(token);
+  if (value === null || typeof value !== "object") return false;
+  return Object.entries(value).some(([key, entry]) => holdsKnown(key, token) || holdsKnown(entry, token));
+}
+
+export function planNonHostedSetup(options) {
+  if (!Object.hasOwn(PREREQUISITES, options.deployment)) {
+    return handoff("invalid_input", "deployment_invalid");
+  }
+  if (options.signup) return handoff("unsupported", "signup_hosted_only");
+  if (!options.originExplicit) return handoff("invalid_input", "non_hosted_origin_required");
+  if (options.workspace === null) return handoff("invalid_input", "non_hosted_workspace_required");
+
+  const prerequisites = Object.fromEntries(PREREQUISITES[options.deployment].map((name) => [
+    name, options.confirmPrerequisites ? "ready" : "unknown",
+  ]));
+  const planned = planDeploymentRoute({
+    model: options.deployment,
+    runtime: options.runtime,
+    origin: options.origin,
+    workspaceId: options.workspace,
+    prerequisites,
+  });
+  if (!planned.ok) {
+    return handoff(planned.outcome, planned.reason, planned.plan?.next_action ?? null, {
+      profile: EXPECTED_PROFILE[options.deployment], origin: planned.plan?.origin,
+      workspaceId: planned.plan?.workspace_id,
+      pendingPrerequisites: planned.plan?.prerequisites.filter((item) => item.status !== "ready").map((item) => item.name),
+    });
+  }
+  return { proceed: true, plan: planned.plan, prerequisites };
+}
+
+export async function preflightNonHostedSetup(options) {
+  const planned = planNonHostedSetup(options);
+  if (!planned.proceed) return planned;
+  const { plan, prerequisites } = planned;
+  const timeoutMs = Math.min(options.timeoutMs, AUTH_HTTP_TIMEOUT_MS);
+  if (options.deployment === "oss" && !options.agentTokenFile) {
+    return handoff("unsupported", "oss_agent_token_file_required", "oss_operator_handoff", {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+      prerequisites: "operator_confirmed",
+    });
+  }
+
+  if (options.deployment === "oss") {
+    // The OSS verifier knows the source-only `oss` discovery profile. Doctor
+    // intentionally does not accept that profile for hosted login.
+    const verified = await verifyDeploymentRoute({
+      model: options.deployment, runtime: options.runtime, origin: plan.origin,
+      workspaceId: plan.workspace_id, prerequisites,
+      credentialFile: options.agentTokenFile, timeoutMs,
+    });
+    if (!verified.ok) {
+      return guardKnownCredentials(handoff(verified.outcome, verified.reason, verified.plan?.next_action ?? null, {
+        profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+        prerequisites: "operator_confirmed",
+      }), verified);
+    }
+    // The OSS operator provisions MG_TOKENS and MG_AGENT_TOKENS separately.
+    // No released OSS server implements the purpose-bound ingest bootstrap,
+    // and a Metadata agent token cannot issue a key. Keep this a handoff.
+    return guardKnownCredentials(handoff("unsupported", "oss_ingest_operator_handoff", "oss_operator_handoff", {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+      prerequisites: "operator_confirmed", metadataAccess: "verified",
+    }), verified);
+  }
+
+  // Every non-hosted route proves the service profile before any login, local
+  // binding, credential read or ingest-key write. runDoctor rejects redirects
+  // and unsafe network responses and reports only a fixed profile token.
+  const doctor = await runDoctor({ origin: plan.origin, timeoutMs });
+  if (doctor.report.deployment_profile !== null && doctor.report.deployment_profile !== plan.deployment_profile) {
+    return handoff("unsupported", "deployment_profile_mismatch", "connection_guide", {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+      prerequisites: "operator_confirmed",
+    });
+  }
+  if (doctor.outcome !== "authentication_required") {
+    return handoff(doctor.outcome, doctor.reason, options.deployment === "oss" ? "oss_operator_handoff" : "connection_guide", {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+      prerequisites: "operator_confirmed",
+    });
+  }
+
+  // A separate agent token file is optional for local/BYOC, where setup will
+  // obtain its own Metadata OAuth grant. OSS has no scoped ingest bootstrap
+  // contract, so its separate MG_AGENT_TOKENS credential must be checked here.
+  if (options.agentTokenFile) {
+    const verified = await verifyDeploymentRoute({
+      model: options.deployment, runtime: options.runtime, origin: plan.origin,
+      workspaceId: plan.workspace_id, prerequisites,
+      credentialFile: options.agentTokenFile, timeoutMs,
+    });
+    if (!verified.ok) {
+      return guardKnownCredentials(handoff(verified.outcome, verified.reason, verified.plan?.next_action ?? null, {
+        profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+        prerequisites: "operator_confirmed",
+      }), verified);
+    }
+    return guardKnownCredentials({
+      proceed: true, profile: plan.deployment_profile, origin: plan.origin,
+      workspaceId: plan.workspace_id, prerequisites: "operator_confirmed",
+      metadataAccess: "verified",
+    }, verified);
+  }
+  return {
+    proceed: true,
+    profile: plan.deployment_profile,
+    origin: plan.origin,
+    workspaceId: plan.workspace_id,
+    prerequisites: "operator_confirmed",
+    metadataAccess: "pending_login",
+  };
+}

package/src/setup-env-acl.js

@@ -0,0 +1,99 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+import { systemRoot } from "./auth-browser.js";
+import { Stop } from "./auth-store.js";
+
+// Windows access control for a plaintext env file. File modes do not protect
+// anything on Windows, so a private file gets a protected DACL (no inherited
+// entries) that allows only the current user, SYSTEM and the local
+// Administrators group. A fixed Windows PowerShell script does the work; the
+// file path travels base64 encoded on stdin, never on the command line, and
+// nothing from the file's content is ever passed. Any failure is reported as
+// protection_failed, so a file is never called private without proof.
+
+const SCRIPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$ProgressPreference = 'SilentlyContinue'",
+  "$mode = [Console]::In.ReadLine()",
+  "$path = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadLine()))",
+  "$arg = [Console]::In.ReadLine()",
+  "$me = [Security.Principal.WindowsIdentity]::GetCurrent().User",
+  "$system = New-Object Security.Principal.SecurityIdentifier('S-1-5-18')",
+  "$admins = New-Object Security.Principal.SecurityIdentifier('S-1-5-32-544')",
+  "$allowed = @($me.Value, $system.Value, $admins.Value)",
+  "$full = [Security.AccessControl.FileSystemRights]::FullControl",
+  "function Test-Private {",
+  "  $acl = [IO.File]::GetAccessControl($path)",
+  "  if (-not $acl.AreAccessRulesProtected) { return $false }",
+  "  if ($allowed -notcontains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value) { return $false }",
+  "  $mine = $false",
+  "  foreach ($rule in $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) {",
+  "    if ($rule.AccessControlType -ne 'Allow') { continue }",
+  "    if ($allowed -notcontains $rule.IdentityReference.Value) { return $false }",
+  "    if ($rule.IdentityReference.Value -eq $me.Value -and ($rule.FileSystemRights -band $full) -eq $full) { $mine = $true }",
+  "  }",
+  "  return $mine",
+  "}",
+  "if ($mode -eq 'protect') {",
+  "  $acl = New-Object Security.AccessControl.FileSecurity",
+  "  $acl.SetAccessRuleProtection($true, $false)",
+  "  foreach ($sid in @($me, $system, $admins)) {",
+  "    $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($sid, $full, 'Allow')))",
+  "  }",
+  "  [IO.File]::SetAccessControl($path, $acl)",
+  "  if (Test-Private) { [Console]::Out.Write('private') } else { exit 3 }",
+  "} elseif ($mode -eq 'status') {",
+  "  if (Test-Private) { [Console]::Out.Write('private') } else { [Console]::Out.Write('open') }",
+  "} elseif ($mode -eq 'get') {",
+  "  $sddl = [IO.File]::GetAccessControl($path).GetSecurityDescriptorSddlForm('Access')",
+  "  [Console]::Out.Write([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($sddl)))",
+  "} elseif ($mode -eq 'set') {",
+  "  $acl = New-Object Security.AccessControl.FileSecurity",
+  "  $acl.SetSecurityDescriptorSddlForm([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($arg)), 'Access')",
+  "  [IO.File]::SetAccessControl($path, $acl)",
+  "  [Console]::Out.Write('ok')",
+  "} else { exit 2 }",
+].join("\n");
+const COMMAND = Buffer.from(SCRIPT, "utf16le").toString("base64");
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+
+function run(mode, file, arg = "") {
+  const powershell = path.win32.join(systemRoot(), "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const result = spawnSync(powershell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", COMMAND], {
+    input: `${mode}\n${Buffer.from(file, "utf8").toString("base64")}\n${arg}\n`,
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    timeout: 30000,
+    maxBuffer: 1024 * 1024,
+  });
+  const out = typeof result.stdout === "string" ? result.stdout.trim() : "";
+  if (result.error || result.status !== 0) throw new Stop("filesystem_error", "protection_failed");
+  return out;
+}
+
+// Replaces the file's DACL with the private one and verifies it.
+export function protectFile(file) {
+  if (run("protect", file) !== "private") throw new Stop("filesystem_error", "protection_failed");
+}
+
+// Returns "private" or "open".
+export function aclStatus(file) {
+  const out = run("status", file);
+  if (out !== "private" && out !== "open") throw new Stop("filesystem_error", "protection_failed");
+  return out;
+}
+
+// The file's DACL as opaque base64 SDDL, for an exact restore on rollback.
+export function saveAcl(file) {
+  const out = run("get", file);
+  if (!BASE64.test(out)) throw new Stop("filesystem_error", "protection_failed");
+  return out;
+}
+
+export function restoreAcl(file, saved) {
+  if (!BASE64.test(saved) || run("set", file, saved) !== "ok") {
+    throw new Stop("filesystem_error", "protection_failed");
+  }
+}

package/src/setup-env-git.js

@@ -0,0 +1,103 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { Stop } from "./auth-store.js";
+
+// Read-only Git checks for the env file. git runs without a shell, from the
+// project directory, with a fixed argument list holding only a validated
+// project-relative path. It never receives a value from the env file, never
+// writes the index (optional locks are off) and never changes any config.
+
+// Kept from the caller's environment. Every other GIT_* variable is dropped
+// so nothing can point git at a different repository, index or work tree.
+const KEPT = new Set([
+  "GIT_CONFIG_GLOBAL",
+  "GIT_CONFIG_SYSTEM",
+  "GIT_CONFIG_NOSYSTEM",
+  "GIT_CEILING_DIRECTORIES",
+  "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+]);
+
+function gitEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    const upper = key.toUpperCase();
+    if (!upper.startsWith("GIT_") || KEPT.has(upper)) env[key] = value;
+  }
+  env.GIT_TERMINAL_PROMPT = "0";
+  env.GIT_OPTIONAL_LOCKS = "0";
+  return env;
+}
+
+function git(root, args) {
+  const result = spawnSync("git", ["-c", "core.fsmonitor=false", ...args], {
+    cwd: root,
+    env: gitEnv(),
+    shell: false,
+    windowsHide: true,
+    timeout: 15000,
+    maxBuffer: 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return { status: result.error ? null : result.status, missing: result.error?.code === "ENOENT", stdout: result.stdout };
+}
+
+// True when root or any directory above it has a .git entry. Used when git
+// itself cannot answer, so a repository is never mistaken for none.
+function gitAbove(root) {
+  for (let dir = root; ; dir = path.dirname(dir)) {
+    try {
+      fs.lstatSync(path.join(dir, ".git"));
+      return true;
+    } catch {
+      // Keep looking.
+    }
+    if (path.dirname(dir) === dir) return false;
+  }
+}
+
+// Returns { repository: false } outside any repository, or
+// { repository: true, ignored } after checking that rel is not tracked.
+export function inspectGit(root, rel) {
+  const inside = git(root, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside.status !== 0) {
+    if (!gitAbove(root)) return { repository: false };
+    throw new Stop("conflict", inside.missing ? "git_unavailable" : "git_check_failed");
+  }
+  if (inside.stdout.toString("utf8").trim() !== "true") throw new Stop("conflict", "git_check_failed");
+  return { repository: true, ...pathState(root, rel) };
+}
+
+// A tracked env file is refused outright: untracking or resetting it is the
+// person's decision, never this CLI's. Ignore rules are checked with
+// --no-index, so a tracked file cannot hide behind a matching rule.
+export function pathState(root, rel) {
+  const tracked = git(root, ["--literal-pathspecs", "ls-files", "-z", "--cached", "--", rel]);
+  if (tracked.status !== 0) throw new Stop("conflict", "git_check_failed");
+  if (tracked.stdout.length > 0) throw new Stop("conflict", "env_tracked");
+  const ignored = git(root, ["check-ignore", "-q", "--no-index", "--", rel]);
+  if (ignored.status !== 0 && ignored.status !== 1) throw new Stop("conflict", "git_check_failed");
+  return { ignored: ignored.status === 0 };
+}
+
+// The anchored, literal .gitignore rule for rel. Characters with a meaning
+// in ignore patterns are escaped. Paths are validated before they get here,
+// so they hold no backslash, wildcard, control character or trailing space.
+export function ignoreRule(rel) {
+  return `/${rel.replace(/[[\]!#]/g, "\\$&")}`;
+}
+
+// True when content has rule as a line and no negation follows it.
+export function hasRule(content, rule) {
+  const lines = content.toString("utf8").split(/\r?\n/);
+  const at = lines.lastIndexOf(rule);
+  return at >= 0 && !lines.slice(at + 1).some((line) => line.trimStart().startsWith("!"));
+}
+
+export function appendRule(content, rule) {
+  const text = content.toString("utf8");
+  const eol = text.includes("\r\n") && !/(^|[^\r])\n/.test(text) ? "\r\n" : "\n";
+  const lead = content.length > 0 && !text.endsWith("\n") ? eol : "";
+  return Buffer.concat([content, Buffer.from(`${lead}${rule}${eol}`, "utf8")]);
+}

package/src/setup-env-parse.js

@@ -0,0 +1,169 @@
+import { Stop } from "./auth-store.js";
+import { parseOrigin } from "./origin.js";
+
+// Reads and edits dotenv files as text. Nothing is evaluated: no
+// interpolation, command substitution or escape processing, and no file is
+// ever sourced. Only the two Metergraph assignments are ever interpreted or
+// changed; every other byte is kept exactly. Anything this parser cannot read
+// without guessing stops with env_syntax_ambiguous.
+
+export const ENV_NAMES = Object.freeze({
+  token: "METERGRAPH_APP_TOKEN",
+  ingestUrl: "METERGRAPH_INGEST_URL",
+});
+const NAMES = Object.values(ENV_NAMES);
+
+// The SDK expects a service root and appends /v1/ingest itself. Accept the
+// endpoint form only while reading setup files written by the first preview.
+export const INGEST_PATHS = Object.freeze(["", "/v1/ingest"]);
+
+// Server-generated application tokens are RFC 3986 unreserved characters
+// only, so a value can never carry a quote, newline, comment or space.
+const TOKEN = /^[A-Za-z0-9._~-]{16,1024}$/;
+const URL_TEXT = /^(https?:\/\/[^/?#@\\]+)(\/[A-Za-z0-9/_.-]*)?$/i;
+const SAFE_URL = /^[A-Za-z0-9.:/[\]_-]+$/;
+
+const ASSIGNMENT = /^([ \t]*)(export[ \t]+)?([A-Za-z_][A-Za-z0-9_.-]*)([ \t]*=[ \t]*)(.*)$/;
+const DOUBLE = /^"([^"\\$`]*)"([ \t]*(?:#.*)?)$/;
+const SINGLE = /^'([^'\\$`]*)'([ \t]*(?:#.*)?)$/;
+const BARE = /^([^\s#"'`$\\]*)((?:[ \t]+#.*)?[ \t]*)$/;
+const BLANK_OR_COMMENT = /^[ \t]*(?:#.*)?$/;
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const BOM = 0xfeff;
+
+export function isAppToken(value) {
+  return typeof value === "string" && TOKEN.test(value);
+}
+
+// Returns the normalized service root or legacy ingest endpoint, or null.
+// The caller must not echo the raw input when this returns null.
+export function parseIngestUrl(raw) {
+  if (typeof raw !== "string" || raw.length > 2048) return null;
+  const match = URL_TEXT.exec(raw);
+  if (match === null || !INGEST_PATHS.includes(match[2] ?? "")) return null;
+  const origin = parseOrigin(match[1]);
+  if (origin === null) return null;
+  const url = `${origin}${match[2] ?? ""}`;
+  return SAFE_URL.test(url) ? url : null;
+}
+
+function ambiguous() {
+  return new Stop("conflict", "env_syntax_ambiguous");
+}
+
+function mentions(text) {
+  const upper = text.toUpperCase();
+  return NAMES.some((name) => upper.includes(name));
+}
+
+// Returns the text after the closing quote, or null when the quote does not
+// close on this line. Only double quotes treat a backslash as an escape.
+function afterQuote(text, quote) {
+  for (let i = 0; i < text.length; i += 1) {
+    if (quote === '"' && text[i] === "\\") i += 1;
+    else if (text[i] === quote) return text.slice(i + 1);
+  }
+  return null;
+}
+
+function metergraphValue(rest) {
+  for (const [pattern, quote] of [[DOUBLE, '"'], [SINGLE, "'"], [BARE, ""]]) {
+    const match = pattern.exec(rest);
+    if (match !== null) return { quote, value: match[1], trailer: match[2] };
+  }
+  throw ambiguous();
+}
+
+// Returns { bom, eol, lines, entries } where lines keeps each line's text and
+// its own terminator, and entries maps a Metergraph name to its one
+// assignment. content is a Buffer of the whole file.
+export function parseEnv(content) {
+  if (content.includes(0)) throw new Stop("conflict", "env_file_invalid");
+  let text;
+  try {
+    text = DECODER.decode(content);
+  } catch {
+    throw new Stop("conflict", "env_file_invalid");
+  }
+  const bom = text.charCodeAt(0) === BOM;
+  if (bom) text = text.slice(1);
+  // A lone carriage return ends a line for some parsers and not others.
+  if (/\r(?!\n)/.test(text)) throw ambiguous();
+
+  const pieces = text.split(/(\r?\n)/);
+  const lines = [];
+  for (let i = 0; i < pieces.length; i += 2) lines.push({ text: pieces[i], eol: pieces[i + 1] ?? "" });
+  if (lines.at(-1).text === "" && lines.at(-1).eol === "") lines.pop();
+
+  const entries = {};
+  let open = null;
+  for (const [index, line] of lines.entries()) {
+    if (open !== null) {
+      // Inside another variable's multiline quoted value.
+      if (mentions(line.text)) throw ambiguous();
+      const rest = afterQuote(line.text, open);
+      if (rest === null) continue;
+      if (!BLANK_OR_COMMENT.test(rest)) throw ambiguous();
+      open = null;
+      continue;
+    }
+    if (BLANK_OR_COMMENT.test(line.text)) continue;
+    const match = ASSIGNMENT.exec(line.text);
+    if (match === null) {
+      // Kept as is unless it could hide a Metergraph value or open a quote.
+      if (mentions(line.text) || /["'`]/.test(line.text)) throw ambiguous();
+      continue;
+    }
+    const [, lead, exported = "", key, separator, rest] = match;
+    if (NAMES.includes(key)) {
+      if (Object.hasOwn(entries, key)) throw new Stop("conflict", "env_duplicate_assignment");
+      entries[key] = { index, lead, exported, separator, ...metergraphValue(rest) };
+      continue;
+    }
+    if (NAMES.includes(key.toUpperCase())) throw ambiguous();
+    const quote = rest[0];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      const after = afterQuote(rest.slice(1), quote);
+      if (after === null) open = quote;
+      else if (!BLANK_OR_COMMENT.test(after)) throw ambiguous();
+    }
+  }
+  if (open !== null) throw ambiguous();
+
+  const endings = new Set(lines.map((line) => line.eol).filter((eol) => eol !== ""));
+  const eol = endings.size === 1 && endings.has("\r\n") ? "\r\n" : "\n";
+  return { bom, eol, lines, entries };
+}
+
+// Returns the file content with each name in updates set to its value. A
+// line whose value already matches is left exactly as it was. A changed line
+// keeps its indentation, export keyword, quote style and trailing comment.
+// Missing names are appended, one line each, with the file's line ending.
+export function serializeEnv(parsed, updates) {
+  const lines = parsed.lines.map((line) => ({ ...line }));
+  const appended = [];
+  for (const [name, value] of Object.entries(updates)) {
+    const entry = parsed.entries[name];
+    if (entry === undefined) {
+      appended.push(`${name}=${value}`);
+    } else if (entry.value !== value) {
+      const { lead, exported, separator, quote, trailer } = entry;
+      lines[entry.index].text = `${lead}${exported}${name}${separator}${quote}${value}${quote}${trailer}`;
+    }
+  }
+  if (appended.length > 0 && lines.length > 0 && lines.at(-1).eol === "") lines.at(-1).eol = parsed.eol;
+  for (const text of appended) lines.push({ text, eol: parsed.eol });
+  const body = lines.map((line) => line.text + line.eol).join("");
+  return Buffer.from(`${parsed.bom ? String.fromCharCode(BOM) : ""}${body}`, "utf8");
+}
+
+// Reparses generated content and checks that it holds exactly the intended
+// Metergraph values, so no value can ever add or hide an assignment.
+export function checkSerialized(content, updates, previous) {
+  const parsed = parseEnv(content);
+  for (const name of NAMES) {
+    const expected = Object.hasOwn(updates, name) ? updates[name] : previous.entries[name]?.value;
+    if (parsed.entries[name]?.value !== expected) throw new Stop("internal_error", "env_write_failed");
+  }
+  return parsed;
+}