@sous-io/sous 0.2.37 → 1.0.1

package/src/lib/sous-home.ts

@@ -1,104 +0,0 @@
-/**
- * The user-level sous directory: where machine-wide, project-independent state
- * lives. Today that is the recipe store, globally linked checkouts and the
- * machine-wide links map; the user-level config LAYER is a separate effort and
- * is deliberately NOT read from here.
- *
- * The location is `~/.sous`, overridable with the `SOUS_HOME` environment
- * variable.
- *
- * IMPORTANT: `SOUS_HOME` is file-settable. Unlike `SOUS_CONFIG`, `SOUS_DIR` and
- * `SOUS_CONFD`, which decide which project is active and therefore must come
- * from the real environment only, `SOUS_HOME` may be set in `.sous/.env.local`
- * or `.sous/.env`. Every function here reads `process.env` at CALL time for
- * exactly that reason; never capture the value at import time, because the env
- * files are loaded after this module is first imported (see `loadEnvFiles` in
- * `base-command.ts`).
- */
-
-import os from "node:os";
-import path from "node:path";
-
-/** The directory name used under the user's home directory. */
-export const SOUS_HOME_DIR_NAME = ".sous";
-
-/** The environment variable that overrides the user-level sous directory. */
-export const SOUS_HOME_ENV_VAR = "SOUS_HOME";
-
-/** Subdirectory of the user-level directory holding the recipe store. */
-export const STORE_DIR_NAME = "cache";
-
-/** Subdirectory of the user-level directory holding globally linked checkouts. */
-export const GLOBAL_REPOS_DIR_NAME = "repos";
-
-/** File name of the machine-wide links map. */
-export const GLOBAL_LINKS_FILENAME = "sous.links.json";
-
-/** A read-only view of an environment, so callers can pass a test fixture. */
-export type EnvLike = Record<string, string | undefined>;
-
-/**
- * Expands a leading `~` in a path, so `SOUS_HOME=~/sous-home` behaves the way a
- * user typing it into an env file expects. A bare `~` and `~/...` expand; a
- * `~user/...` form does not (sous has no way to resolve another account's home
- * directory portably) and is left alone.
- *
- * @param value - The raw path, as written by the user.
- */
-function expandHome(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/") || value.startsWith("~\\")) {
-    return path.join(os.homedir(), value.slice(2));
-  }
-  return value;
-}
-
-/**
- * Resolves the user-level sous directory: `$SOUS_HOME` when it is set to a
- * non-blank value, otherwise `<home>/.sous`. The result is normalized but is
- * NOT created; each consumer creates the subdirectory it needs.
- *
- * A blank or whitespace-only `SOUS_HOME` is treated as unset rather than as the
- * current directory, matching how `base-command.ts` treats the other `SOUS_*`
- * variables.
- *
- * @param env - The environment to read; defaults to the live `process.env`.
- */
-export function resolveSousHome(env: EnvLike = process.env): string {
-  const raw = env[SOUS_HOME_ENV_VAR];
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    return path.normalize(path.resolve(expandHome(raw.trim())));
-  }
-  return path.join(os.homedir(), SOUS_HOME_DIR_NAME);
-}
-
-/**
- * Resolves the root of the machine-wide recipe store, `$SOUS_HOME/cache`.
- *
- * @param env - The environment to read; defaults to the live `process.env`.
- */
-export function resolveStoreRoot(env: EnvLike = process.env): string {
-  return path.join(resolveSousHome(env), STORE_DIR_NAME);
-}
-
-/**
- * Resolves the directory holding globally linked checkouts,
- * `$SOUS_HOME/repos`. A `sous repo link --global` clones into
- * `<this dir>/<owner>/<repo>`.
- *
- * @param env - The environment to read; defaults to the live `process.env`.
- */
-export function resolveGlobalReposDir(env: EnvLike = process.env): string {
-  return path.join(resolveSousHome(env), GLOBAL_REPOS_DIR_NAME);
-}
-
-/**
- * Resolves the machine-wide links map, `$SOUS_HOME/sous.links.json`. A
- * project's own `.sous/sous.links.json` is read alongside it and wins on
- * conflict.
- *
- * @param env - The environment to read; defaults to the live `process.env`.
- */
-export function resolveGlobalLinksPath(env: EnvLike = process.env): string {
-  return path.join(resolveSousHome(env), GLOBAL_LINKS_FILENAME);
-}

package/src/lib/state.ts

@@ -1,167 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import type { VarScope } from "./settings.js";
-
-// --- Types ---------------------------------------------------------------------------------------
-
-/** A single file entry tracked by the state file. */
-export type StateFileEntry = {
-  /** Absolute destination path of the output file. */
-  dest: string;
-  /** SHA-256 hex hash of the source content at build time. */
-  srcHash: string;
-  /** SHA-256 hex hash of the destination file content at build time. */
-  destHash: string;
-  /** File size in bytes. */
-  size: number;
-  /** ISO timestamp when this file was last written. */
-  builtAt: string;
-};
-
-/** The full state tracked for a project across builds. */
-export type StateFile = {
-  /** ISO timestamp of the last successful build. */
-  lastBuild: string;
-  /** The resolved variable scope used during the last build. */
-  resolvedVars: VarScope;
-  /** Absolute paths of directories that Sous created (not pre-existing). */
-  dirs: string[];
-  /** All output files written by Sous for this project. */
-  files: StateFileEntry[];
-};
-
-// --- Protected paths -----------------------------------------------------------------------------
-
-/**
- * True when a path is one of the protected roots, or sits underneath one.
- *
- * Both sides are normalized and resolved first, so a state file written with a
- * different spelling of the same directory is still recognised.
- *
- * isProtectedPath("/home/me/.sous/cache/r/n/x/1.0.0/a.md", ["/home/me/.sous/cache"]);
- * // -> true
- *
- * @param target - The path something is about to delete.
- * @param protectedRoots - The directories that must never be reached into.
- */
-export function isProtectedPath(target: string, protectedRoots: string[]): boolean {
-  if (protectedRoots.length === 0) return false;
-  const candidate = path.resolve(target);
-  return protectedRoots.some((root) => {
-    const resolved = path.resolve(root);
-    return candidate === resolved || candidate.startsWith(resolved + path.sep);
-  });
-}
-
-// --- StateService --------------------------------------------------------------------------------
-
-/**
- * Manages reading and writing the project state file.
- * The state file tracks all files and directories Sous has written,
- * enabling sous prune and sous clear to clean up precisely.
- */
-export class StateService {
-  /**
-   * Derives the state file path for a config.
-   *
-   * Precedence:
-   *   1. A `stateFilePath` variable in the settings scope (explicit override).
-   *   2. `<sousDir>/sous.state.json`.
-   *   3. `<cwd>/sous.state.json` as a last resort.
-   *
-   * @param vars - The resolved settings-scope variables. `sousDir` is
-   *   auto-injected by buildAutoVars when a config has been discovered.
-   */
-  getFilePath(vars?: VarScope): string {
-    if (vars?.stateFilePath) {
-      return vars.stateFilePath;
-    }
-    if (vars?.sousDir) {
-      return path.join(vars.sousDir, "sous.state.json");
-    }
-    return path.join(process.cwd(), "sous.state.json");
-  }
-
-  /** Loads the state file for a project. Returns null if it does not exist. */
-  async load(filePath: string): Promise<StateFile | null> {
-    if (!fs.existsSync(filePath)) return null;
-    try {
-      const raw = fs.readFileSync(filePath, "utf8");
-      return JSON.parse(raw) as StateFile;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Deletes all tracked files and removes any now-empty tracked directories.
-   *
-   * @param files - The tracked output files to delete.
-   * @param dirs - The directories Sous created, removed when they end up empty.
-   * @param protectedRoots - Directories nothing here may reach into, whatever the
-   *   state file says. Pass `protectedRepoPaths(sousDir)` so a stale entry can
-   *   never make prune or clear delete a linked checkout or the shared recipe
-   *   store.
-   */
-  deleteTrackedFiles(
-    files: StateFileEntry[],
-    dirs: string[],
-    protectedRoots: string[] = []
-  ): void {
-    for (const entry of files) {
-      if (isProtectedPath(entry.dest, protectedRoots)) continue;
-      if (fs.existsSync(entry.dest)) fs.rmSync(entry.dest);
-    }
-    const sortedDirs = [...dirs].sort(
-      (a, b) => b.split(path.sep).length - a.split(path.sep).length
-    );
-    for (const dir of sortedDirs) {
-      if (isProtectedPath(dir, protectedRoots)) continue;
-      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
-        fs.rmdirSync(dir);
-      }
-    }
-  }
-
-  /** Saves the state file to disk, creating parent directories as needed. */
-  async save(filePath: string, state: StateFile): Promise<void> {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(filePath, JSON.stringify(state, null, 2), "utf8");
-  }
-}
-
-// --- Hash utilities ------------------------------------------------------------------------------
-
-/** Computes a SHA-256 hex hash of a file's contents. */
-export async function hashFile(filePath: string): Promise<string> {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash("sha256").update(content).digest("hex");
-}
-
-/** Computes a SHA-256 hex hash of an in-memory string. */
-export function hashContent(content: string): string {
-  return crypto.createHash("sha256").update(content, "utf8").digest("hex");
-}
-
-// --- Directory tracking --------------------------------------------------------------------------
-
-/**
- * Records that Sous created a directory.
- * Only records if the directory is not already tracked.
- */
-export function recordDirCreation(dir: string, state: StateFile): void {
-  if (!state.dirs.includes(dir)) {
-    state.dirs.push(dir);
-  }
-}
-
-/**
- * Returns true if Sous created this directory (i.e., it is tracked in the state file).
- */
-export function didSousCreateDir(dir: string, state: StateFile): boolean {
-  return state.dirs.includes(dir);
-}

package/src/lib/vars/answers.ts

@@ -1,192 +0,0 @@
-/**
- * The answers a build renders with.
- *
- * A recipe publishes variable DEFINITIONS; the project's env files and shell
- * hold the ANSWERS; the ladder (`ladder.ts`) says which answer a definition
- * gets. This module is the one place that turns all of that into the variable
- * scope a template renders from, so a `{{ variable }}` in a recipe's own skill
- * sees the answer to its own question without the project mapping the name by
- * hand through `_env`.
- *
- * Three views come out of one walk over the definitions:
- *
- *   - `merged`, what the project's own templates render: one value per
- *     variable name. Two recipes may publish the same name (the shared rung of
- *     the ladder exists for exactly that), so the first definition in lockfile
- *     order wins the merged view, and a project that wants something else says
- *     so in `_vars`, which sits above every answer.
- *   - `byRecipe`, what a recipe's own files render: the answers resolved for
- *     that recipe's definitions, which the recipe-scoped rung of the ladder can
- *     make different from the merged view.
- *   - `unanswered`, every required definition that no rung and no default
- *     answered. A build reports those and carries on, because a missing answer
- *     is something to tell the user about, not a reason to refuse to build the
- *     rest of the project.
- *
- * Alongside them comes `secrets`: every name some definition declares
- * `secret: true`. The tags that dump a whole scope (`{% showVars %}`,
- * `{% exportScalarVarsJs %}`) read it so a secret answer never lands in
- * compiled output unless a template names it explicitly.
- *
- * A definition's `default` counts as an answer of last resort: the
- * description a publisher writes promises what the default does, and a
- * template rendering an empty string instead would break that promise.
- *
- * Values are laid in exactly as the ladder found them. Nothing here resolves a
- * path or coerces a number; the answer is the string the user stored, the same
- * string an `_env` mapping would deliver.
- */
-
-import type { Settings, VarScope } from "../settings.js";
-import { BULLET } from "../../utils/formatting.js";
-import {
-  ProjectDefinitionSource,
-  definingRecipeKey,
-  type DefinedVariable,
-} from "./definition-source.js";
-import { loadLadderContext, resolveVariable, type LadderContext } from "./ladder.js";
-
-/** The answers in play for a project, in the three views a build needs. */
-export interface RecipeAnswers {
-  /** One value per variable name; the first definition in lockfile order wins a name. */
-  merged: VarScope;
-  /** The answers resolved for each recipe's own definitions, keyed `namespace/recipe`. */
-  byRecipe: Map<string, VarScope>;
-  /** Every required definition that nothing answered and that has no default. */
-  unanswered: DefinedVariable[];
-  /** Every variable name some definition declares `secret: true`, answered or not. */
-  secrets: Set<string>;
-}
-
-/** How the answers are resolved. */
-export interface RecipeAnswerOptions {
-  /** The merged project config, read for its `varMappings` block. */
-  settings: Settings;
-  /** The project's `.sous/` directory, which holds the lockfile and both env files. */
-  sousDir: string;
-  /**
-   * The definitions to answer. Defaults to every definition the project's
-   * lockfile pins; tests hand in a fixed list.
-   */
-  definitions?: DefinedVariable[];
-  /**
-   * The environment the ladder treats as the shell. A build passes nothing and
-   * gets `process.env`, which already holds every env-file value in precedence
-   * order (the files are loaded first-writer-wins, shell first), so the value
-   * that comes back is the right one; only the layer it is attributed to would
-   * differ, and a build does not report that.
-   */
-  shellEnv?: NodeJS.ProcessEnv;
-  /** The environment that decides where the store is; defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv;
-}
-
-/** The empty result, for a project that locks nothing. */
-export function noRecipeAnswers(): RecipeAnswers {
-  return { merged: {}, byRecipe: new Map(), unanswered: [], secrets: new Set() };
-}
-
-/**
- * Resolves every definition in play through the ladder and lays the answers
- * out in the three views a build renders and reports with.
- *
- * @param options - The project's config, its `.sous/` directory, and optionally
- *   the definitions and environment to use instead of the real ones.
- */
-export function resolveRecipeAnswers(options: RecipeAnswerOptions): RecipeAnswers {
-  const definitions =
-    options.definitions ??
-    new ProjectDefinitionSource(options.settings, options.sousDir, options.env).loadSync();
-  if (definitions.length === 0) return noRecipeAnswers();
-
-  const context: LadderContext = loadLadderContext({
-    sousDir: options.sousDir,
-    settings: options.settings,
-    ...(options.shellEnv === undefined ? {} : { shellEnv: options.shellEnv }),
-  });
-
-  const result = noRecipeAnswers();
-
-  for (const defined of definitions) {
-    const value = answerFor(defined, context);
-    const name = defined.definition.name;
-    if (defined.definition.secret) result.secrets.add(name);
-
-    if (value === undefined) {
-      if (defined.definition.required) result.unanswered.push(defined);
-      continue;
-    }
-
-    if (!(name in result.merged)) result.merged[name] = value;
-
-    const recipeKey = definingRecipeKey(defined.recipe);
-    const own = result.byRecipe.get(recipeKey) ?? {};
-    own[name] = value;
-    result.byRecipe.set(recipeKey, own);
-  }
-
-  return result;
-}
-
-/**
- * The answer one definition renders with: what the ladder found, else the
- * definition's own default, else nothing.
- *
- * @param defined - The definition and the recipe that published it.
- * @param context - The environment layers and mapping records.
- */
-function answerFor(defined: DefinedVariable, context: LadderContext): string | undefined {
-  const resolved = resolveVariable(defined, context);
-  if (resolved !== undefined) return resolved.value;
-  const fallback = defined.definition.default;
-  return fallback === undefined ? undefined : String(fallback);
-}
-
-/**
- * The scope a recipe's own files render with: the merged view, with that
- * recipe's own answers laid over it.
- *
- * @param answers - The resolved answers.
- * @param recipeKey - The recipe, as `namespace/recipe`.
- */
-export function answersForRecipe(answers: RecipeAnswers, recipeKey: string): VarScope {
-  return { ...answers.merged, ...(answers.byRecipe.get(recipeKey) ?? {}) };
-}
-
-/**
- * The one warning a build prints when required variables are unanswered: every
- * variable named with the recipe that asks for it, and the command that answers
- * them. Undefined when nothing is missing.
- *
- * A variable the project's config defines itself, in `_vars` or through
- * `_env`, is not missing: the template renders that value, whatever the ladder
- * found. So the check is made against the scope the templates actually render
- * with, not against the ladder alone.
- *
- * @param answers - The resolved answers.
- * @param renderScope - The scope the project's templates render with.
- */
-export function unansweredWarning(
-  answers: RecipeAnswers,
-  renderScope: VarScope = {}
-): string | undefined {
-  const missing = answers.unanswered.filter(
-    (defined) => renderScope[defined.definition.name] === undefined
-  );
-  if (missing.length === 0) return undefined;
-
-  const lines = missing.map(
-    (defined) =>
-      `  ${BULLET} ${defined.definition.name} (asked by ${definingRecipeKey(defined.recipe)})`
-  );
-  const count = missing.length;
-  const noun = count === 1 ? "variable" : "variables";
-  const pronoun = count === 1 ? "it" : "them";
-
-  return (
-    `${count} required recipe ${noun} ${count === 1 ? "has" : "have"} no answer, so the ` +
-    `templates that use ${pronoun} render an empty value:\n` +
-    `${lines.join("\n")}\n` +
-    `Run 'sous vars ask' to answer ${pronoun}.`
-  );
-}