@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/config-schema.ts

@@ -0,0 +1,361 @@
+/**
+ * Zod schema for a merged sous config.
+ *
+ * This mirrors the hand-written `Settings` / `RawProjectCompilation` /
+ * `RawTarget` / `RawOutput` / `RawRuntimeContext` / `ToolConfig` types in
+ * settings.ts — those remain the exported TypeScript types; this schema is the
+ * RUNTIME validator. Keep the two in sync: when a config field changes in
+ * settings.ts, change it here too.
+ *
+ * Every object level is STRICT (unknown keys are rejected), so a typo like
+ * `compilaton` is caught the moment the merged config is loaded rather than
+ * silently ignored. Validation runs on the MERGED config only (in
+ * loadSettingsWithLayers, after the kernel merges every conf.d layer and after
+ * assertFlatConfig); a single conf.d fragment need not be a complete config.
+ *
+ * The schema also drives `npm run schema:build`, which emits the committed
+ * `sous.config.schema.json` artifact via `z.toJSONSchema`.
+ */
+
+import { z } from "zod";
+import { ConfigError } from "./errors.js";
+import { repoUrlSchema, semverRangeSchema } from "./repos/formats/common.js";
+import { REF_KEY_PATTERN, REPO_NAME_PATTERN } from "./repos/formats/patterns.js";
+import type { Settings } from "./settings.js";
+
+/** The only config version this sous understands. */
+export const SUPPORTED_CONFIG_VERSION = 1;
+
+/** A record of string → string (used for _env and every _vars block). */
+const stringRecord = z.record(z.string(), z.string());
+
+const outputSchema = z
+  .object({
+    _if: z.record(z.string(), z.object({ eq: z.string() }).strict()).optional(),
+    _vars: stringRecord.optional(),
+    destinationFile: z.string().optional(),
+    destinationDir: z.string().optional(),
+  })
+  .strict();
+
+const runtimeContextSchema = z
+  .object({
+    gitRoot: z.string(),
+    outputPath: z.string(),
+    taskFileRoot: z.string(),
+    branchPattern: z.string().optional(),
+  })
+  .strict();
+
+const targetSchema = z
+  .object({
+    _vars: stringRecord.optional(),
+    entryPoint: z.string().optional(),
+    entryGlob: z.string().optional(),
+    globBase: z.string().optional(),
+    generateRuntimeContext: z.boolean().optional(),
+    outputs: z.array(outputSchema),
+  })
+  .strict()
+  .refine((t) => (t.entryPoint !== undefined) !== (t.entryGlob !== undefined), {
+    message: "a target must have exactly one of 'entryPoint' or 'entryGlob'",
+  });
+
+const compilationSchema = z
+  .object({
+    _vars: stringRecord.optional(),
+    includeSourceComments: z.boolean().optional(),
+    targets: z.array(targetSchema),
+  })
+  .strict();
+
+const toolSchema = z
+  .object({
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    promptFile: z.string().optional(),
+  })
+  .strict();
+
+// --- Repositories -------------------------------------------------------------------------------
+
+/**
+ * One trusted repository, keyed by the short name refs use in the `repo:`
+ * qualifier. Adding a repo IS trusting it: `sous repo add` writes the entry
+ * into the machine-written `conf.d/500-repos.jsonc` layer, and removing the
+ * entry withdraws the trust. A user may also hand-write `repos:` in the primary
+ * config; the two layers merge like anything else.
+ */
+const repoEntrySchema = z
+  .object({
+    /**
+     * Where the repository lives. A hosted repository is named by its URL; a
+     * repository on this machine, which the `local` provider reads, is named by
+     * an absolute path or the same path in `file:///...` form.
+     */
+    url: repoUrlSchema,
+    /**
+     * Whether the repository takes part in anything at all. Defaults to true.
+     * Setting it to false is how a project opts out of a repository sous
+     * provides itself (the official `sous-recipes`), without having to delete an
+     * entry it never wrote.
+     */
+    enabled: z.boolean().optional(),
+    /**
+     * Which provider handles it. Inferred from the URL when omitted; set it
+     * explicitly for a self-hosted instance the URL does not give away.
+     * `local` is a repository on this machine, for local development and tests;
+     * its trust semantics are identical to a hosted one.
+     */
+    provider: z.enum(["github", "gitlab", "local"]).optional(),
+    /**
+     * When true, sous installs a newer in-range version whenever one exists
+     * rather than holding the locked one. The flag never widens the range a
+     * subscription or a dependency declared.
+     */
+    alwaysPull: z.boolean().optional(),
+    /** When the repo was added, for provenance. */
+    addedAt: z.string().optional(),
+    /**
+     * Who required the repo: the literal "user" for a deliberate add, or the ref
+     * of the recipe whose dependency pulled it in. Removal hygiene reads this.
+     */
+    addedBy: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * One subscription, keyed by a ref key: a bare namespace (every recipe in it,
+ * including ones published later) or `namespace/recipe`. Written by
+ * `sous subscribe` into the machine-written `conf.d/510-subscriptions.jsonc`
+ * layer, and hand-writable in the primary config.
+ */
+const subscriptionEntrySchema = z
+  .object({
+    /**
+     * Whether the subscription takes part in anything at all. Defaults to true.
+     * Setting it to false is how a project opts out of the `core` namespace sous
+     * subscribes every project to.
+     */
+    enabled: z.boolean().optional(),
+    /** The semantic version range to resolve within. Defaults to "*". */
+    range: semverRangeSchema.optional(),
+    /** When true, prerelease versions take part in range matching. */
+    prerelease: z.boolean().optional(),
+    /** Per-subscription form of the repo-level always-pull flag. */
+    alwaysPull: z.boolean().optional(),
+    /** When the subscription was added, for provenance. */
+    addedAt: z.string().optional(),
+    /** Who required it: "user", or the ref of the recipe that co-subscribed it. */
+    addedBy: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * Knobs for the machine-wide recipe store under the user-level sous directory.
+ * Every value here is a number the user can change; the numbers sous ships are
+ * defaults, not assumptions. Phase 2 applies them, so all three are optional
+ * here and the defaults live with the store itself: one gigabyte for maxBytes,
+ * 300 seconds for freshnessSeconds, and 300 seconds for watchPollSeconds.
+ */
+const storeSchema = z
+  .object({
+    /** Size cap for the store, past which least-recently-used entries are collected. */
+    maxBytes: z.number().int().positive().optional(),
+    /**
+     * How long a fetched index stays fresh. A non-watch build checks upstream
+     * only once this window has lapsed, and a failed check never breaks a
+     * build; the last good answer stands.
+     */
+    freshnessSeconds: z.number().int().nonnegative().optional(),
+    /** How often watch mode polls upstream for a newer in-range version. */
+    watchPollSeconds: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+/**
+ * Where the files a subscribed recipe contributes are written, one list of
+ * destination directories per content kind. Each destination is `${var}`
+ * substituted like any other config path, and a kind may name several so the
+ * same recipe feeds more than one agent directory (`.claude/skills` and
+ * `.codex/skills`, say).
+ *
+ * Only `skills` has a default: `<project root>/.claude/skills`, the project root
+ * being the parent of the discovered `.sous/` directory. A kind with no
+ * destination is skipped, with one warning naming this key, because sous cannot
+ * guess where a project wants its memories or its prompts. A recipe's `config`
+ * contents are not listed here; they are loaded as config layers rather than
+ * written anywhere.
+ */
+const recipeOutputsSchema = z
+  .object({
+    /** Where recipe skill bundles are written. */
+    skills: z.array(z.string()).optional(),
+    /** Where recipe memory files are written. */
+    memories: z.array(z.string()).optional(),
+    /** Where recipe prompt files are written. */
+    prompts: z.array(z.string()).optional(),
+  })
+  .strict();
+
+// --- Variable mappings --------------------------------------------------------------------------
+
+/**
+ * A mapping record's target: one variable, named in full, as
+ * `namespace/recipe/variableName` with an optional `repo:` qualifier. Mapping
+ * records are the top rung of the answer resolution ladder and the universal
+ * resolver when two recipes want the same environment variable name.
+ */
+const mappingTargetSchema = z
+  .string()
+  .regex(
+    /^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*\/[a-z][a-zA-Z0-9]*$/,
+    "a variable mapping target must be written as 'namespace/recipe/variableName', " +
+      "optionally qualified with a repository as 'repo:namespace/recipe/variableName'"
+  );
+
+/**
+ * The full merged-config schema. `version`, when present, must be exactly
+ * `SUPPORTED_CONFIG_VERSION` — but validateSettings pre-checks it with a clearer
+ * message before this schema runs, so a bad version never reaches the generic
+ * literal error here.
+ */
+export const settingsSchema = z
+  .object({
+    // Allowed so a JSON config can bind itself to the shipped
+    // `sous.config.schema.json` via the standard `"$schema": "..."` property
+    // for editor autocompletion / external validation. Editors treat `$schema`
+    // as reserved and never flag it, so rejecting it here would break the
+    // documented workflow. sous itself ignores the value.
+    $schema: z.string().optional(),
+    version: z.literal(SUPPORTED_CONFIG_VERSION).optional(),
+    _env: stringRecord.optional(),
+    _vars: stringRecord.optional(),
+    _aliases: z
+      .record(z.string(), z.union([z.string(), z.array(z.string())]))
+      .optional(),
+    name: z.string().optional(),
+    compilation: compilationSchema.optional(),
+    runtimeContext: runtimeContextSchema.optional(),
+    tools: z.record(z.string(), toolSchema).optional(),
+    /** Trusted repositories, keyed by the short name refs use. */
+    repos: z
+      .record(
+        z
+          .string()
+          .regex(
+            REPO_NAME_PATTERN,
+            "a repo name must be lowercase kebab-case: a letter, then letters, " +
+              "digits or hyphens"
+          ),
+        repoEntrySchema
+      )
+      .optional(),
+    /** Subscriptions, keyed by ref key (`namespace` or `namespace/recipe`). */
+    subscriptions: z
+      .record(
+        z
+          .string()
+          .regex(
+            REF_KEY_PATTERN,
+            "a subscription key must be a namespace such as 'workflow', or a " +
+              "namespace and recipe such as 'workflow/task-files', with no repo " +
+              "qualifier and no version range"
+          ),
+        subscriptionEntrySchema
+      )
+      .optional(),
+    /** Knobs for the machine-wide recipe store. */
+    store: storeSchema.optional(),
+    /** Where the files subscribed recipes contribute are written, per content kind. */
+    recipeOutputs: recipeOutputsSchema.optional(),
+    /**
+     * Variable mapping records, keyed by environment variable name. Each entry
+     * binds that name to one recipe variable, which is how an answer is stored
+     * under a name of your choosing when the generated names are taken. Written
+     * by `sous vars ask` into `conf.d/520-var-mappings.jsonc`, and hand-writable
+     * in the primary config.
+     */
+    varMappings: z
+      .record(
+        z
+          .string()
+          .regex(
+            /^[A-Z][A-Z0-9_]*$/,
+            "an environment variable name must be upper snake case: a capital " +
+              "letter, then capitals, digits or underscores"
+          ),
+        mappingTargetSchema
+      )
+      .optional(),
+  })
+  .strict();
+
+/** Renders a zod issue path (e.g. `["compilation","targets",0,"entryPoint"]`) as `compilation.targets[0].entryPoint`. */
+function formatIssuePath(parts: ReadonlyArray<PropertyKey>): string {
+  let out = "";
+  for (const part of parts) {
+    if (typeof part === "number") out += `[${part}]`;
+    else out += out.length > 0 ? `.${String(part)}` : String(part);
+  }
+  return out;
+}
+
+/**
+ * Turns a ZodError into a readable, per-issue ConfigError message. Never leaks
+ * the raw zod JSON dump. Unknown-key issues are surfaced as likely typos and
+ * name the config file.
+ */
+function formatZodError(error: z.ZodError, configPath: string): ConfigError {
+  const lines: string[] = [`Invalid sous config at ${configPath}:`];
+
+  for (const issue of error.issues) {
+    const where = formatIssuePath(issue.path);
+    if (issue.code === "unrecognized_keys") {
+      const keys = issue.keys.map((k) => `'${k}'`).join(", ");
+      const loc = where.length > 0 ? `under '${where}'` : "at the top level";
+      lines.push(
+        `  - unknown key(s) ${keys} ${loc} — likely a typo. Check ${configPath}.`
+      );
+    } else if (issue.code === "invalid_key") {
+      // zod reports a bad record KEY as a bare "Invalid key in record" and hides
+      // the reason in a nested issue list. Surface the reason, since that is the
+      // part telling the user how to fix the key.
+      const reasons = issue.issues.map((inner) => inner.message).join("; ");
+      lines.push(`  - ${where}: invalid key; ${reasons}`);
+    } else {
+      lines.push(`  - ${where.length > 0 ? where : "(root)"}: ${issue.message}`);
+    }
+  }
+
+  return new ConfigError(lines.join("\n"));
+}
+
+/**
+ * Validates a merged config object against the schema, returning it typed as
+ * `Settings`. Throws a ConfigError (never a raw ZodError) on any problem.
+ *
+ * @param raw - The merged config produced by the kernel (post assertFlatConfig).
+ * @param configPath - The primary config file path, named in error messages.
+ */
+export function validateSettings(raw: unknown, configPath: string): Settings {
+  // Version gets a dedicated, friendlier message than the generic literal error.
+  if (raw !== null && typeof raw === "object" && "version" in raw) {
+    const version = (raw as { version: unknown }).version;
+    if (version !== SUPPORTED_CONFIG_VERSION) {
+      throw new ConfigError(
+        `Config at ${configPath} declares version ${JSON.stringify(version)}, which is not ` +
+          `supported by this version of sous.\n` +
+          `  This sous understands config version ${SUPPORTED_CONFIG_VERSION}. Omit the ` +
+          `'version' field or set it to ${SUPPORTED_CONFIG_VERSION}.`
+      );
+    }
+  }
+
+  const result = settingsSchema.safeParse(raw);
+  if (!result.success) {
+    throw formatZodError(result.error, configPath);
+  }
+
+  return result.data as Settings;
+}

package/src/lib/env-file.ts

@@ -0,0 +1,328 @@
+/**
+ * A line-preserving editor for `.sous/.env` and `.sous/.env.local`.
+ *
+ * These files belong to the user: they are hand-written, commented, ordered
+ * deliberately, and (for `.env`) committed. So sous edits them the way a
+ * careful person would. The file is parsed into a line model, exactly one line
+ * is rewritten or appended, and every other byte comes back out unchanged:
+ * comments, blank lines, ordering, quoting style and the `export ` prefix all
+ * survive.
+ *
+ * Comments are OUTPUT ONLY. sous writes a short generated header above each
+ * entry it appends, explaining where the value came from, and never reads a
+ * comment back or tries to keep one up to date. The header says as much, so
+ * nobody wonders whether editing it will confuse the tool.
+ *
+ * The parser here recognizes the same syntax `env-local.ts` reads, since these
+ * two modules are the write and read halves of one small format.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** The key syntax accepted on an assignment line, matching the env file parser. */
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** One line of an env file, classified. */
+export type EnvFileLine =
+  /** An empty or whitespace-only line. */
+  | { kind: "blank"; text: string }
+  /** A whole-line comment. */
+  | { kind: "comment"; text: string }
+  /** A `KEY=value` assignment, with everything needed to rewrite just the value. */
+  | {
+      kind: "assignment";
+      text: string;
+      /** Leading whitespace, preserved on rewrite. */
+      indent: string;
+      /** True when the line carried an `export ` prefix. */
+      exported: boolean;
+      /** The variable's name. */
+      key: string;
+      /** The value as written, before unquoting. */
+      rawValue: string;
+      /** A trailing ` # comment`, when the line had one, including its spacing. */
+      inlineComment: string;
+    }
+  /** Anything else: kept verbatim, never interpreted. */
+  | { kind: "other"; text: string };
+
+/** A parsed env file: its lines, and how to put them back together. */
+export interface EnvFileModel {
+  /** Every line, in order. */
+  lines: EnvFileLine[];
+  /** The line ending the file uses. */
+  eol: "\n" | "\r\n";
+  /** True when the file ended with a newline (or is empty and will). */
+  trailingNewline: boolean;
+}
+
+/**
+ * Splits an assignment line's right-hand side into the value and any trailing
+ * comment. Quoted values are scanned to their closing quote first, so a `#`
+ * inside quotes is part of the value.
+ */
+function splitValueAndComment(raw: string): { rawValue: string; inlineComment: string } {
+  const leadingSpaces = raw.length - raw.trimStart().length;
+  const body = raw.trimStart();
+
+  const quote = body.startsWith('"') ? '"' : body.startsWith("'") ? "'" : undefined;
+  if (quote !== undefined) {
+    for (let i = 1; i < body.length; i++) {
+      if (body[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (body[i] === quote) {
+        return {
+          rawValue: raw.slice(0, leadingSpaces + i + 1),
+          inlineComment: raw.slice(leadingSpaces + i + 1),
+        };
+      }
+    }
+    return { rawValue: raw, inlineComment: "" };
+  }
+
+  const commentAt = body.search(/\s#/);
+  if (commentAt === -1) return { rawValue: raw, inlineComment: "" };
+
+  // Walk back over every space before the comment, so the gap belongs to the
+  // comment and survives a rewrite of the value.
+  let start = leadingSpaces + commentAt;
+  while (start > 0 && /\s/.test(raw[start - 1]!)) start--;
+  return { rawValue: raw.slice(0, start), inlineComment: raw.slice(start) };
+}
+
+/**
+ * Parses env file text into a line model. Nothing is dropped: a line the
+ * parser does not recognize is kept verbatim as an `other` line.
+ *
+ * @param content - The file's contents.
+ */
+export function parseEnvFile(content: string): EnvFileModel {
+  const eol: "\n" | "\r\n" = content.includes("\r\n") ? "\r\n" : "\n";
+  const trailingNewline = content.length === 0 || content.endsWith("\n");
+  const body = content.endsWith("\r\n")
+    ? content.slice(0, -2)
+    : content.endsWith("\n")
+      ? content.slice(0, -1)
+      : content;
+  const rawLines = content.length === 0 ? [] : body.split(/\r?\n/);
+
+  const lines: EnvFileLine[] = rawLines.map((text) => {
+    if (text.trim() === "") return { kind: "blank", text };
+    if (text.trimStart().startsWith("#")) return { kind: "comment", text };
+
+    const indent = text.slice(0, text.length - text.trimStart().length);
+    const withoutIndent = text.slice(indent.length);
+    const exported = withoutIndent.startsWith("export ");
+    const assignment = exported ? withoutIndent.slice(7).trimStart() : withoutIndent;
+
+    const equals = assignment.indexOf("=");
+    if (equals <= 0) return { kind: "other", text };
+
+    const key = assignment.slice(0, equals).trim();
+    if (!KEY_PATTERN.test(key)) return { kind: "other", text };
+
+    const { rawValue, inlineComment } = splitValueAndComment(assignment.slice(equals + 1));
+    return { kind: "assignment", text, indent, exported, key, rawValue, inlineComment };
+  });
+
+  return { lines, eol, trailingNewline };
+}
+
+/**
+ * Renders a line model back to text.
+ *
+ * @param model - The model to render.
+ */
+export function renderEnvFile(model: EnvFileModel): string {
+  if (model.lines.length === 0) return "";
+  const body = model.lines.map((line) => line.text).join(model.eol);
+  return model.trailingNewline ? body + model.eol : body;
+}
+
+/**
+ * Quotes a value if it needs quoting so the env file parser reads back exactly
+ * what was written. An ordinary word is left bare, which keeps the file
+ * readable.
+ *
+ * @param value - The value to write.
+ */
+export function quoteEnvValue(value: string): string {
+  const needsQuotes =
+    value.length === 0 ||
+    /[\s#"'\\]/.test(value) ||
+    value.startsWith("'") ||
+    value.startsWith('"');
+
+  if (!needsQuotes) return value;
+
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\t/g, "\\t");
+  return `"${escaped}"`;
+}
+
+/** Options for `setEntry`. */
+export interface SetEntryOptions {
+  /**
+   * Comment lines written above the entry when it is APPENDED. An existing
+   * entry keeps whatever comment is already above it, because sous only ever
+   * rewrites the value line. Lines may be passed with or without their leading
+   * `#`.
+   */
+  header?: string | string[];
+}
+
+/** Turns header text into `#`-prefixed comment lines. */
+function headerLines(header: string | string[]): string[] {
+  const source = Array.isArray(header) ? header : header.split("\n");
+  return source.map((line) => {
+    const trimmed = line.trimEnd();
+    if (trimmed.length === 0) return "#";
+    return trimmed.startsWith("#") ? trimmed : `# ${trimmed}`;
+  });
+}
+
+/**
+ * Sets one variable in a line model, in place.
+ *
+ * An existing assignment is rewritten where it stands, keeping its indentation,
+ * its `export ` prefix and any trailing comment. When the key appears more than
+ * once, the LAST one is rewritten, because that is the one the parser honors.
+ * A key that is not there yet is appended at the end of the file, under its
+ * generated header comment.
+ *
+ * @param model - The model to edit.
+ * @param key - The variable's name.
+ * @param value - The value to store, quoted as needed.
+ * @param options - Header comment for a newly appended entry.
+ * @returns Whether the entry was updated in place or appended.
+ */
+export function setEntry(
+  model: EnvFileModel,
+  key: string,
+  value: string,
+  options: SetEntryOptions = {}
+): "updated" | "appended" {
+  const quoted = quoteEnvValue(value);
+
+  for (let i = model.lines.length - 1; i >= 0; i--) {
+    const line = model.lines[i]!;
+    if (line.kind !== "assignment" || line.key !== key) continue;
+
+    const prefix = line.exported ? "export " : "";
+    const text = `${line.indent}${prefix}${key}=${quoted}${line.inlineComment}`;
+    model.lines[i] = { ...line, text, rawValue: quoted };
+    return "updated";
+  }
+
+  // Appending: separate the new entry from whatever came before with one blank
+  // line, unless the file is empty or already ends with one.
+  const last = model.lines[model.lines.length - 1];
+  if (last !== undefined && last.kind !== "blank") {
+    model.lines.push({ kind: "blank", text: "" });
+  }
+
+  if (options.header !== undefined) {
+    for (const text of headerLines(options.header)) {
+      model.lines.push({ kind: "comment", text });
+    }
+  }
+
+  model.lines.push({
+    kind: "assignment",
+    text: `${key}=${quoted}`,
+    indent: "",
+    exported: false,
+    key,
+    rawValue: quoted,
+    inlineComment: "",
+  });
+  model.trailingNewline = true;
+  return "appended";
+}
+
+/**
+ * Removes every assignment of one variable from a line model, leaving comments
+ * and blank lines alone (sous does not read comments, so it does not presume to
+ * know which ones belonged to the entry).
+ *
+ * @param model - The model to edit.
+ * @param key - The variable's name.
+ * @returns How many assignment lines were removed.
+ */
+export function removeEntry(model: EnvFileModel, key: string): number {
+  const before = model.lines.length;
+  model.lines = model.lines.filter(
+    (line) => !(line.kind === "assignment" && line.key === key)
+  );
+  return before - model.lines.length;
+}
+
+/**
+ * Reads an env file into a line model, returning an empty model when the file
+ * does not exist yet.
+ *
+ * @param filePath - Absolute path to the env file.
+ */
+export function readEnvFile(filePath: string): EnvFileModel {
+  if (!fs.existsSync(filePath)) return { lines: [], eol: "\n", trailingNewline: true };
+  return parseEnvFile(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * Writes a line model back to disk atomically: the new contents go to a
+ * temporary file in the same directory and are renamed over the original, so an
+ * interrupted write can never leave a half-written env file behind.
+ *
+ * A file that does not exist yet is created readable and writable by its owner
+ * only, since `.env.local` holds secrets; an existing file keeps its mode.
+ *
+ * @param filePath - Absolute path to the env file.
+ * @param model - The model to write.
+ */
+export function writeEnvFile(filePath: string, model: EnvFileModel): void {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true });
+
+  const temporary = path.join(
+    directory,
+    `.${path.basename(filePath)}.sous-${process.pid}-${Date.now()}.tmp`
+  );
+
+  let mode = 0o600;
+  try {
+    mode = fs.statSync(filePath).mode & 0o777;
+  } catch {
+    // No existing file, so the restrictive default stands.
+  }
+
+  fs.writeFileSync(temporary, renderEnvFile(model), { encoding: "utf8", mode });
+  fs.renameSync(temporary, filePath);
+}
+
+/**
+ * Reads, edits and rewrites one env file in a single call: the usual way to
+ * store an answer.
+ *
+ * @param filePath - Absolute path to the env file.
+ * @param key - The variable's name.
+ * @param value - The value to store.
+ * @param options - Header comment for a newly appended entry.
+ * @returns Whether the entry was updated in place or appended.
+ */
+export function updateEnvFile(
+  filePath: string,
+  key: string,
+  value: string,
+  options: SetEntryOptions = {}
+): "updated" | "appended" {
+  const model = readEnvFile(filePath);
+  const outcome = setEntry(model, key, value, options);
+  writeEnvFile(filePath, model);
+  return outcome;
+}