@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/env-file.ts

@@ -1,328 +0,0 @@
-/**
- * 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;
-}

package/src/lib/env-local.ts

@@ -1,212 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { ENV_DEFAULTS_NAME, ENV_LOCAL_NAME } from "./config-discovery.js";
-
-/**
- * Parses `.env` / `.env.local` style content into a flat key/value map.
- *
- * Supported syntax (deliberately small — this is not a shell):
- *   - `KEY=value`
- *   - `export KEY=value` (the `export ` prefix is ignored)
- *   - `# comment` lines and blank lines are skipped
- *   - single- or double-quoted values are unquoted; `\n` and `\t` inside
- *     double quotes become real newlines/tabs
- *   - an unquoted value has a trailing ` # comment` stripped and is trimmed
- *
- * Lines that do not contain `=` are ignored rather than treated as errors, so a
- * stray note in the file cannot break a build.
- *
- * @param content - Raw file contents.
- * @returns Parsed variables in file order (later duplicates win).
- */
-export function parseEnvLocal(content: string): Record<string, string> {
-  const result: Record<string, string> = {};
-
-  for (const rawLine of content.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (line === "" || line.startsWith("#")) continue;
-
-    const withoutExport = line.startsWith("export ") ? line.slice(7).trim() : line;
-
-    const eq = withoutExport.indexOf("=");
-    if (eq <= 0) continue;
-
-    const key = withoutExport.slice(0, eq).trim();
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
-
-    result[key] = parseValue(withoutExport.slice(eq + 1));
-  }
-
-  return result;
-}
-
-/**
- * Unquotes and cleans up the right-hand side of a `KEY=value` line.
- */
-function parseValue(raw: string): string {
-  const trimmed = raw.trim();
-
-  if (trimmed.startsWith('"')) {
-    const end = findClosingQuote(trimmed, '"');
-    if (end !== -1) {
-      return trimmed
-        .slice(1, end)
-        .replace(/\\n/g, "\n")
-        .replace(/\\t/g, "\t")
-        .replace(/\\"/g, '"');
-    }
-  }
-
-  if (trimmed.startsWith("'")) {
-    const end = findClosingQuote(trimmed, "'");
-    if (end !== -1) return trimmed.slice(1, end);
-  }
-
-  // Unquoted: strip an inline comment, then trim.
-  const commentAt = trimmed.search(/\s#/);
-  const body = commentAt === -1 ? trimmed : trimmed.slice(0, commentAt);
-  return body.trim();
-}
-
-/**
- * Finds the index of the closing quote for a value that starts with `quote`,
- * skipping backslash-escaped quotes. Returns -1 when unterminated.
- */
-function findClosingQuote(value: string, quote: string): number {
-  for (let i = 1; i < value.length; i++) {
-    if (value[i] === "\\") {
-      i++;
-      continue;
-    }
-    if (value[i] === quote) return i;
-  }
-  return -1;
-}
-
-/**
- * Reads one env file and returns its variables as a flat map, WITHOUT touching
- * `process.env`. Returns an empty map when the file does not exist.
- *
- * The variables layer needs each env file on its own: by the time a command
- * runs, `loadEnvFiles` has already merged both files into the process
- * environment, so reading them separately is the only way to say which layer
- * supplied an answer.
- *
- * @param filePath - Absolute path to the env file.
- * @returns The parsed variables, or an empty map when there is no such file.
- */
-export function readEnvFileMap(filePath: string): Record<string, string> {
-  if (!fs.existsSync(filePath)) return {};
-  return parseEnvLocal(fs.readFileSync(filePath, "utf8"));
-}
-
-/** The outcome of an attempted env file load. */
-export type EnvLocalLoadResult = {
-  /** Absolute path checked. */
-  filePath: string;
-  /** True when the file existed and was read. */
-  loaded: boolean;
-  /** Names of variables that were injected into process.env. */
-  applied: string[];
-  /** Names present in the file but already set in the environment (left alone). */
-  skipped: string[];
-};
-
-/** The outcome of loading both env layers. */
-export type EnvFilesLoadResult = {
-  /** Result for the gitignored `.sous/.env.local` layer (loaded first, so it wins). */
-  local: EnvLocalLoadResult;
-  /** Result for the committed `.sous/.env` defaults layer (loaded second). */
-  defaults: EnvLocalLoadResult;
-};
-
-/**
- * Loads a single env file into `env`, if it exists.
- *
- * A variable already present in `env` is never overwritten, which is what makes
- * layering work: whoever gets there first wins.
- *
- * @param filePath - Absolute path to the env file.
- * @param env - The environment object to mutate.
- * @returns What was found and what was applied.
- */
-function loadEnvFile(filePath: string, env: NodeJS.ProcessEnv): EnvLocalLoadResult {
-  if (!fs.existsSync(filePath)) {
-    return { filePath, loaded: false, applied: [], skipped: [] };
-  }
-
-  const parsed = parseEnvLocal(fs.readFileSync(filePath, "utf8"));
-  const applied: string[] = [];
-  const skipped: string[] = [];
-
-  for (const [key, value] of Object.entries(parsed)) {
-    if (env[key] !== undefined) {
-      skipped.push(key);
-      continue;
-    }
-    env[key] = value;
-    applied.push(key);
-  }
-
-  return { filePath, loaded: true, applied, skipped };
-}
-
-/**
- * Loads `<sousDir>/.env` (committed shared defaults) into `process.env`, if it
- * exists. Anything already set is left alone, so both your shell and
- * `.env.local` outrank it.
- *
- * @param sousDir - The discovered `.sous/` directory.
- * @param env - The environment object to mutate (injectable for tests).
- * @returns What was found and what was applied.
- */
-export function loadEnvDefaults(
-  sousDir: string,
-  env: NodeJS.ProcessEnv = process.env
-): EnvLocalLoadResult {
-  return loadEnvFile(path.join(sousDir, ENV_DEFAULTS_NAME), env);
-}
-
-/**
- * Loads `<sousDir>/.env.local` (machine-specific values and secrets) into
- * `process.env`, if it exists.
- *
- * Existing environment values always win: a variable already set in the real
- * environment is never overwritten, so `FOO=bar sous build` behaves as expected.
- *
- * @param sousDir - The discovered `.sous/` directory.
- * @param env - The environment object to mutate (injectable for tests).
- * @returns What was found and what was applied.
- */
-export function loadEnvLocal(
-  sousDir: string,
-  env: NodeJS.ProcessEnv = process.env
-): EnvLocalLoadResult {
-  return loadEnvFile(path.join(sousDir, ENV_LOCAL_NAME), env);
-}
-
-/**
- * Loads both env layers out of `sousDir`. Precedence, highest first:
- *
- *   real shell environment > `.sous/.env.local` > `.sous/.env`
- *
- * Because no load ever overwrites a value that is already set, the FIRST writer
- * of a key wins. So the higher-precedence file is loaded first: `.env.local`,
- * then `.env` fills in only the keys nobody else supplied. The real shell
- * environment is already populated before either runs, so it outranks both.
- *
- * Must be called before any config or variable resolution so the `_env` block
- * sees the injected values.
- *
- * @param sousDir - The discovered `.sous/` directory.
- * @param env - The environment object to mutate (injectable for tests).
- * @returns The per-file results.
- */
-export function loadEnvFiles(
-  sousDir: string,
-  env: NodeJS.ProcessEnv = process.env
-): EnvFilesLoadResult {
-  const local = loadEnvLocal(sousDir, env);
-  const defaults = loadEnvDefaults(sousDir, env);
-  return { local, defaults };
-}

package/src/lib/errors.ts

@@ -1,32 +0,0 @@
-/**
- * Shared error types for sous.
- *
- * ConfigError lives in its own module (rather than settings.ts) so that
- * config-discovery.ts can throw it without importing settings.ts — settings.ts
- * imports discovery constants, and a back-import would create a cycle.
- * settings.ts re-exports both names for backwards compatibility.
- */
-
-/**
- * A user-facing configuration error: the config file (or environment) is wrong,
- * not the CLI. Commands render these as a plain message with no stack trace,
- * since the stack points at Sous internals and tells the user nothing.
- */
-export class ConfigError extends Error {
-  readonly isConfigError = true;
-
-  constructor(message: string) {
-    super(message);
-    this.name = "ConfigError";
-  }
-}
-
-/** True when the value is a ConfigError (safe across module instances). */
-export function isConfigError(error: unknown): boolean {
-  return (
-    error instanceof ConfigError ||
-    (typeof error === "object" &&
-      error !== null &&
-      (error as { isConfigError?: boolean }).isConfigError === true)
-  );
-}

package/src/lib/glob-pattern.ts

@@ -1,24 +0,0 @@
-/**
- * Filesystem paths as glob patterns.
- *
- * glob and minimatch read `\` in a pattern as an escape character, never as a
- * path separator, and want `/` on every platform. A pattern built with
- * `path.join` or `path.resolve` on Windows is all backslashes, so it silently
- * matched nothing: a recipe's skills, memories and config layers, an include
- * glob and an `entryGlob` target all came up empty without an error.
- */
-
-import path from "node:path";
-
-/**
- * Writes a path or a path-shaped glob with `/` separators, so glob reads it the
- * same way on Windows as everywhere else. A no-op where `/` is the separator, so
- * a pattern's own escapes survive on every other platform.
- *
- * toGlobPattern("C:\\recipes\\skills\\**\\*"); // -> "C:/recipes/skills/**\/*" on Windows
- *
- * @param value - A filesystem path, or a glob pattern built from one.
- */
-export function toGlobPattern(value: string): string {
-  return path.sep === "\\" ? value.split(path.sep).join("/") : value;
-}