@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/settings.ts

@@ -1,1107 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { globSync } from "glob";
-import { inferGlobBase, type CompilationConfig, type CompilationTarget, type ResolvedRuntimeContext } from "./markdown-compiler.js";
-import { buildAliasMap, resolveAliasPrefix, type AliasMap } from "./include-resolver.js";
-import { toGlobPattern } from "./glob-pattern.js";
-import {
-  CONFD_DIR_NAME,
-  ENV_DEFAULTS_NAME,
-  ENV_LOCAL_NAME,
-  SOUS_DIR_NAME,
-  type DiscoveredConfig,
-} from "./config-discovery.js";
-import { ConfigError } from "./errors.js";
-import { sharedHashNames } from "../services/ref-resolver/index.js";
-import { resolveSousHome } from "./sous-home.js";
-import { validateSettings } from "./config-schema.js";
-import { applyRepoDefaults } from "./repos/defaults.js";
-import type { RecipeConfigLayer } from "./repos/recipe-config-layers.js";
-import {
-  answersForRecipe,
-  resolveRecipeAnswers,
-  type RecipeAnswers,
-} from "./vars/answers.js";
-import { warning } from "../utils/formatting.js";
-
-// Re-exported for backwards compatibility: ConfigError moved to ./errors.ts so
-// config-discovery.ts can throw it without importing this module (cycle).
-export { ConfigError, isConfigError } from "./errors.js";
-
-// CLI_ROOT and SOUS_VERSION live in their own module so that modules this one
-// imports can read them without importing this one back. Re-exported here under
-// the names everything already uses.
-import { CLI_ROOT, SOUS_VERSION } from "./package-info.js";
-export { CLI_ROOT, SOUS_VERSION };
-
-// --- Variable scope ------------------------------------------------------------------------------
-
-/** A flat map of resolved variable names to their string values. */
-export type VarScope = Record<string, string>;
-
-// --- Raw settings types (matching settings.local.js shape) --------------------------------------
-
-type RawOutput = {
-  _if?: Record<string, { eq: string }>;
-  _vars?: Record<string, string>;
-  destinationFile?: string;
-  destinationDir?: string;
-};
-
-type RawRuntimeContext = {
-  /** ${var} path to the git repo root used for branch detection. */
-  gitRoot: string;
-  /** ${var} path where the generated session-context file is written. */
-  outputPath: string;
-  /** ${var} root directory for task files; branch name is appended to locate the active file. */
-  taskFileRoot: string;
-  /** Regex pattern string; branches matching this pattern trigger task file lookup. */
-  branchPattern?: string;
-};
-
-type RawTarget = {
-  _vars?: Record<string, string>;
-  /** Point-to-point source file path. Exactly one of entryPoint or entryGlob must be set. */
-  entryPoint?: string;
-  /** Glob pattern expanding to multiple source files. Exactly one of entryPoint or entryGlob must be set. */
-  entryGlob?: string;
-  /**
-   * Explicit base directory for computing relative output paths when using destinationDir.
-   * Only meaningful for entryGlob targets. When omitted, inferred from the glob pattern.
-   */
-  globBase?: string;
-  /**
-   * When true, the compiler generates a runtime session context file (branch name, task file)
-   * alongside the entry point before compilation. Only meaningful for AGENTS-style entry points.
-   */
-  generateRuntimeContext?: boolean;
-  outputs: RawOutput[];
-};
-
-type RawProjectCompilation = {
-  _vars?: Record<string, string>;
-  includeSourceComments?: boolean;
-  targets: RawTarget[];
-};
-
-/**
- * One trusted repository, keyed in `Settings.repos` by the short name refs use
- * in their `repo:` qualifier. Adding a repo is what trusts it.
- */
-export type RepoEntry = {
-  /** Where the repository lives. */
-  url: string;
-  /**
-   * Whether the repository takes part in anything. Defaults to true; setting it
-   * to false is how a project opts out of a repository sous provides itself,
-   * without deleting an entry it does not own.
-   */
-  enabled?: boolean;
-  /**
-   * Which provider handles it. Inferred from the URL when omitted. `local` is a
-   * repository on this machine, for local development and tests.
-   */
-  provider?: "github" | "gitlab" | "local";
-  /** Install a newer in-range version whenever one exists, rather than holding the lock. */
-  alwaysPull?: boolean;
-  /** When the repo was added. */
-  addedAt?: string;
-  /** Who required it: "user", or the ref of the recipe whose dependency pulled it in. */
-  addedBy?: string;
-};
-
-/**
- * One subscription, keyed in `Settings.subscriptions` by a ref key: a bare
- * namespace, or `namespace/recipe`.
- */
-export type SubscriptionEntry = {
-  /**
-   * Whether the subscription takes part in anything. Defaults to true; setting
-   * it to false is how a project opts out of the `core` namespace sous
-   * subscribes it to.
-   */
-  enabled?: boolean;
-  /** The semantic version range to resolve within. Defaults to "*". */
-  range?: string;
-  /** Let prerelease versions take part in range matching. */
-  prerelease?: boolean;
-  /** Per-subscription form of the repo-level always-pull flag. */
-  alwaysPull?: boolean;
-  /** When the subscription was added. */
-  addedAt?: string;
-  /** Who required it: "user", or the ref of the recipe that co-subscribed it. */
-  addedBy?: string;
-};
-
-/**
- * Knobs for the machine-wide recipe store. Defaults are applied by the store
- * itself, not here; see config-schema.ts for the values sous ships.
- */
-type StoreConfig = {
-  /** Size cap, past which least-recently-used entries are collected. */
-  maxBytes?: number;
-  /** How long a fetched index stays fresh before sous re-checks upstream. */
-  freshnessSeconds?: number;
-  /** How often watch mode polls upstream. */
-  watchPollSeconds?: number;
-};
-
-/**
- * What a project does with each content kind its subscribed recipes publish.
- *
- * `skills.outputs` lists the destination directories for recipe skills, each
- * `${var}` substituted; the default is `<project root>/.claude/skills`, the
- * project root being the parent of `.sous/`. `memories.first` and
- * `memories.exclude` are lists of globs, or `/.../` regular expressions, over
- * `namespace/recipe` keys.
- */
-type RecipesConfig = {
-  skills?: {
-    /** Where recipe skill bundles are written. */
-    outputs?: string[];
-  };
-  memories?: {
-    /** Recipes whose memories come first. */
-    first?: string[];
-    /** Recipes whose memories are left out. */
-    exclude?: string[];
-  };
-};
-
-/** Configuration for a launchable tool (e.g. claude, codex). */
-type ToolConfig = {
-  /** The executable command to run. */
-  command: string;
-  /** Arguments passed before the prompt file argument. */
-  args?: string[];
-  /**
-   * Path to a file whose contents are appended as the final argument to the command.
-   * Path is resolved through the project's var scope.
-   */
-  promptFile?: string;
-};
-
-export type Settings = {
-  /** Config schema version. Optional; when present must be 1 (validated at load). */
-  version?: number;
-  _env?: Record<string, string>;
-  /**
-   * Config variables. A few names are read by Sous itself:
-   * `stateFilePath` overrides where the build state file is written (see
-   * StateService.getFilePath), and `pidFilePath` does the same for the watcher
-   * PID file. Both resolve through the settings scope.
-   */
-  _vars?: Record<string, string>;
-  _aliases?: Record<string, string | string[]>;
-  /** Optional display name for the configured project. */
-  name?: string;
-  compilation?: RawProjectCompilation;
-  runtimeContext?: RawRuntimeContext;
-  tools?: Record<string, ToolConfig>;
-  /** Trusted repositories, keyed by the short name refs use. */
-  repos?: Record<string, RepoEntry>;
-  /** Subscriptions, keyed by ref key (`namespace` or `namespace/recipe`). */
-  subscriptions?: Record<string, SubscriptionEntry>;
-  /** Knobs for the machine-wide recipe store. */
-  store?: StoreConfig;
-  /**
-   * What the project does with each content kind its subscribed recipes publish.
-   */
-  recipes?: RecipesConfig;
-  /**
-   * Variable mapping records, keyed by environment variable name, each bound to
-   * one recipe variable written as `namespace/recipe/variableName` with an
-   * optional `repo:` qualifier. The top rung of the answer resolution ladder.
-   */
-  varMappings?: Record<string, string>;
-};
-
-// --- Loader -------------------------------------------------------------------------------------
-
-/** Options accepted by loadSettings / loadSettingsWithLayers. */
-export type LoadSettingsOptions = {
-  /**
-   * When true, the kernel returns one cumulative-config snapshot per top-level
-   * layer (the provenance seam behind `sous config get --layers`).
-   */
-  trace?: boolean;
-};
-
-/** One trace-mode snapshot: the cumulative config AFTER `path` was merged. */
-export type SettingsLayer = {
-  path: string;
-  config: unknown;
-};
-
-/** Absolute path to the config kernel subprocess entry (plain .mjs, ships in src/). */
-const CONFIG_KERNEL_PATH = path.join(CLI_ROOT, "src", "lib", "config-kernel.mjs");
-
-/**
- * Loads settings from a discovered config (primary file + conf.d layers) and
- * returns the merged result together with any trace-mode layer snapshots.
- *
- * Every layer — .js, .mjs, .json and .yaml alike — is loaded by ONE kernel
- * subprocess (src/lib/config-kernel.mjs), which parses/imports each file in
- * order, JSON-forces it, deep-merges it into a live cumulative config, runs
- * `configure(currentConfig, builder)` exports, and serialises the final JSON
- * once. Uniform kernel semantics beat the spawn cost, so there is no
- * parent-side shortcut for plain JSON.
- *
- * Two spawn attempts are made, in this order:
- *
- *   1. Plain Node, no loader. This is what a normal ESM config needs, and it is
- *      the only thing that works for a `.sous/sous.config.js` sitting in a repo
- *      whose package.json has no `"type": "module"` (under the tsx loader such a
- *      file is treated as CJS and dies with ERR_REQUIRE_CYCLE_MODULE).
- *   2. The tsx loader, so a config may use TypeScript syntax and extensionless
- *      relative imports. (The kernel itself is plain .mjs and runs under both.)
- *
- * The subprocess (rather than a direct `import()`) avoids the require(esm) cycle
- * that tsx triggers in the parent process. Because every layer is round-tripped
- * through JSON, functions, RegExp, Date and undefined values are dropped.
- *
- * @param source - The full DiscoveredConfig, or a bare config file path. A bare
- *   string means exactly that one file: no conf.d scan is performed (back-compat
- *   for tests and direct callers).
- * @param options - `{ trace }` — see LoadSettingsOptions.
- */
-/* c8 ignore next 75 */
-export async function loadSettingsWithLayers(
-  source: DiscoveredConfig | string,
-  options: LoadSettingsOptions = {}
-): Promise<{ settings: Settings; layers: SettingsLayer[] }> {
-  let configPath: string;
-  let sousDir: string;
-  let confDir: string;
-  let layerPaths: string[];
-  let recipeLayers: RecipeConfigLayer[];
-
-  if (typeof source === "string") {
-    configPath = path.resolve(source);
-    sousDir = path.dirname(configPath);
-    confDir = path.join(sousDir, CONFD_DIR_NAME);
-    layerPaths = [configPath];
-    recipeLayers = [];
-  } else {
-    ({ configPath, sousDir, confDir, layerPaths } = source);
-    recipeLayers = source.recipeLayers ?? [];
-  }
-
-  if (!fs.existsSync(configPath)) {
-    throw new Error(`Settings file not found: ${configPath}`);
-  }
-
-  // A recipe layer is handed to the kernel as content, not as a path, because
-  // it has already been read and filtered down to the keys a recipe may set
-  // (see `repos/recipe-config-layers.ts`). The kernel never opens the file, so
-  // there is no second, unfiltered reading of it.
-  const recipeLayerByPath = new Map(recipeLayers.map((layer) => [layer.path, layer]));
-  const sources = layerPaths.map((layerPath) => {
-    const recipeLayer = recipeLayerByPath.get(layerPath);
-    if (recipeLayer === undefined) return layerPath;
-    return { path: recipeLayer.path, config: recipeLayer.config };
-  });
-
-  const kernelInput = JSON.stringify({
-    sources,
-    context: {
-      sousDir,
-      confDir,
-      sousRootPath: CLI_ROOT,
-      sousVersion: SOUS_VERSION,
-      configPath,
-    },
-    trace: options.trace === true,
-  });
-
-  // Resolve tsx via module resolution so this works when npm hoists the
-  // dependency (local install, npx) as well as when it nests it (global,
-  // repo clone).
-  let tsxPath: string;
-  try {
-    tsxPath = createRequire(import.meta.url).resolve("tsx/esm");
-  } catch {
-    tsxPath = path.resolve(CLI_ROOT, "node_modules/tsx/dist/esm/index.cjs");
-  }
-
-  const attempts: { label: string; args: string[] }[] = [
-    { label: "node", args: [CONFIG_KERNEL_PATH] },
-    // `--import` takes a module specifier, so the path goes as a file:// URL:
-    // a bare Windows path reads as a URL whose scheme is the drive letter.
-    { label: "tsx", args: ["--import", pathToFileURL(tsxPath).href, CONFIG_KERNEL_PATH] },
-  ];
-
-  const failures: { label: string; message: string }[] = [];
-
-  for (const attempt of attempts) {
-    const result = spawnSync(process.execPath, attempt.args, {
-      input: kernelInput,
-      encoding: "utf8",
-    });
-
-    if (result.status === 0) {
-      let parsed: { config: unknown; layers?: SettingsLayer[] };
-      try {
-        parsed = JSON.parse(result.stdout) as { config: unknown; layers?: SettingsLayer[] };
-      } catch {
-        throw new Error(
-          `Config at ${configPath} did not produce valid JSON. Every layer must resolve ` +
-            `to a plain object (a \`config\`/default export, or a \`configure\` function).\n` +
-            `  Got: ${result.stdout.slice(0, 300)}`
-        );
-      }
-      // assertFlatConfig runs FIRST: its multi-project migration message is more
-      // actionable than a generic unknown-key error. validateSettings then checks
-      // the MERGED config against the zod schema (version, strict keys, shapes).
-      const flat = assertFlatConfig(parsed.config, configPath);
-      // The built-in repository and the implicit `core` subscription are added
-      // UNDER whatever the layers produced, and BEFORE validation, so that the
-      // shortest opt-out a project can write (`{ enabled: false }`) is a
-      // complete, valid entry once the built-in fields are underneath it. See
-      // `repos/defaults.ts`.
-      return {
-        settings: validateSettings(applyRepoDefaults(flat), configPath),
-        layers: parsed.layers ?? [],
-      };
-    }
-
-    failures.push({ label: attempt.label, message: result.stderr?.trim() || "unknown error" });
-  }
-
-  // Kernel-side errors (bad JSON/YAML, old schema, configure() throw, cycle,
-  // bad builder var, non-object layer) are raised inside the .mjs kernel, which
-  // runs identically under both the `node` and `tsx` attempts — so both stderrs
-  // are the same. Collapse identical messages so a single config error is not
-  // printed twice as if it were two distinct failures.
-  //
-  // The tsx attempt re-imports an ESM `.js` config that the `node` attempt
-  // already loaded and reported a real error for; on the tsx attempt this
-  // surfaces as a spurious "Cannot require() ES Module … in a cycle"
-  // (ERR_REQUIRE_CYCLE_MODULE) that is never a real user-config problem. Drop it
-  // whenever another attempt produced a genuine error, so the real message is
-  // not buried under an unrelated require(esm)-cycle warning.
-  const isTsxCycleArtifact = (message: string): boolean =>
-    /ERR_REQUIRE_CYCLE_MODULE/.test(message) ||
-    /Cannot require\(\) ES Module .* in a cycle/.test(message);
-  const meaningfulFailures = failures.filter((f) => !isTsxCycleArtifact(f.message));
-  const effectiveFailures = meaningfulFailures.length > 0 ? meaningfulFailures : failures;
-
-  const uniqueMessages = [...new Set(effectiveFailures.map((f) => f.message))];
-  const detail =
-    uniqueMessages.length === 1
-      ? `  ${uniqueMessages[0]}`
-      : effectiveFailures.map((f) => `  [via ${f.label}] ${f.message}`).join("\n\n");
-
-  throw new ConfigError(`Failed to load config from ${configPath}\n${detail}`);
-}
-
-/**
- * Loads the merged settings for a discovered config (or a bare config file
- * path). Thin wrapper over loadSettingsWithLayers for callers that do not need
- * the trace-mode layer snapshots.
- */
-export async function loadSettings(
-  source: DiscoveredConfig | string,
-  options: LoadSettingsOptions = {}
-): Promise<Settings> {
-  const { settings } = await loadSettingsWithLayers(source, options);
-  return settings;
-}
-
-/**
- * Rejects configs written in the removed multi-project schema. One config now
- * describes exactly one project; the fields that used to live inside a
- * `projects.<key>` entry sit at the top level instead.
- */
-function assertFlatConfig(raw: unknown, configPath: string): Settings {
-  if (
-    raw !== null &&
-    typeof raw === "object" &&
-    ("projects" in raw || "defaultProject" in raw)
-  ) {
-    throw new ConfigError(
-      `Config at ${configPath} uses the removed multi-project schema ` +
-        `('projects' / 'defaultProject').\n` +
-        `  A sous config now describes exactly one project. To migrate:\n` +
-        `    1. Move your single project's fields (name, _vars, _aliases, compilation,\n` +
-        `       runtimeContext, tools) to the top level of the config.\n` +
-        `    2. Delete the 'projects' and 'defaultProject' keys.\n` +
-        `  A config with several projects must be split into one config per project.`
-    );
-  }
-  return raw as Settings;
-}
-
-// --- Variable Resolution -------------------------------------------------------------------------
-
-/**
- * Substitutes ${varName} references in a string using the provided scope.
- * Unknown variable references are left as-is.
- */
-export function substituteVars(str: string, scope: VarScope): string {
-  return str.replace(/\$\{([^}]+)\}/g, (match, name: string) => scope[name] ?? match);
-}
-
-/** Returns the names of every `${var}` reference left unresolved in a string. */
-export function findUnresolvedVars(str: string): string[] {
-  return [...new Set([...str.matchAll(/\$\{([^}]+)\}/g)].map((m) => m[1]))];
-}
-
-/**
- * Collapses `.` and `..` segments in an already-substituted absolute path.
- *
- * Output destinations must be normalized at resolution time, not left as written.
- * A config that names a directory as `${sousDir}/..` (the natural way to reach the
- * repo root from a discovered `.sous/`) otherwise produces a `destinationDir` of
- * `/repo/.sous/../.claude/skills`, while the file paths Sous actually writes go
- * through `path.join` and come out as `/repo/.claude/skills/...`. Prune compares
- * tracked destinations against `destinationDir` by string prefix, so the two forms
- * never match and prune deletes every file compile had just written.
- *
- * Relative values are left alone: they are resolved later against a context this
- * function does not have.
- *
- * @param value - A substituted path from the config.
- * @returns The normalized path, or `value` unchanged when it is not absolute.
- */
-export function normalizeConfigPath(value: string): string {
-  return path.isAbsolute(value) ? path.normalize(value) : value;
-}
-
-/**
- * Substitutes `${varName}` references and throws when any reference cannot be
- * resolved from the scope. Used for every value Sous acts on (entry points,
- * destinations, prompt files, runtime-context paths) so a typo'd or missing
- * variable fails loudly instead of silently producing a literal `${var}` path.
- *
- * @param str - The raw value from the config.
- * @param scope - The resolved variable scope.
- * @param context - Where the value came from, e.g.
- *   `compilation.targets[0].entryPoint`. Named in the error.
- * @returns The fully substituted string.
- * @throws When one or more `${var}` references are unresolved.
- */
-export function substituteVarsStrict(str: string, scope: VarScope, context: string): string {
-  const result = substituteVars(str, scope);
-  const unresolved = findUnresolvedVars(result);
-
-  if (unresolved.length > 0) {
-    const names = unresolved.map((n) => `\${${n}}`).join(", ");
-    const plural = unresolved.length === 1 ? "variable" : "variables";
-    const available = Object.keys(scope).sort();
-    throw new ConfigError(
-      `Unresolved ${plural} ${names} in ${context}\n` +
-        `  raw value: ${str}\n` +
-        `  Define ${unresolved.length === 1 ? "it" : "them"} in a _vars block, or map ` +
-        `${unresolved.length === 1 ? "it" : "them"} from the environment via the top-level ` +
-        `_env block (values can come from .sous/.env.local or .sous/.env).\n` +
-        `  Variables in scope here: ${available.length > 0 ? available.join(", ") : "(none)"}`
-    );
-  }
-
-  return result;
-}
-
-/**
- * Resolves a _vars block into a new scope with a FIXPOINT loop:
- *
- * 1. Start from the inherited scope. Every block entry begins unresolved.
- * 2. Each round, substitute every still-unresolved entry against the current
- *    scope (inherited vars + entries already finalized this pass). An entry
- *    whose `${refs}` all resolve is finalized and added to the scope.
- * 3. Repeat until a round finalizes nothing.
- *
- * Because each round re-scans every unresolved entry, declaration order does not
- * matter: `{ file: "${root}/x", root: "/data" }` resolves as readily as the
- * reverse. When progress stops with entries still unresolved, that is a hard
- * error (see buildUnresolvedScopeError): a `${ref}` that never resolves — a typo,
- * a cycle, or a name defined nowhere — is a config mistake, not a literal to be
- * passed through silently.
- */
-export function resolveScope(block: Record<string, string>, inherited: VarScope): VarScope {
-  const blockKeys = Object.keys(block);
-
-  // Warn if user defines vars in the reserved 'sous*' namespace
-  for (const key of blockKeys) {
-    if (key.startsWith("sous")) {
-      console.warn(`Warning: variable '${key}' uses the reserved 'sous*' namespace and may conflict with auto-injected variables.`);
-    }
-  }
-
-  const scope: VarScope = { ...inherited };
-  const unresolved = new Set(blockKeys);
-
-  let progressed = true;
-  while (progressed && unresolved.size > 0) {
-    progressed = false;
-    for (const key of unresolved) {
-      const substituted = substituteVars(block[key], scope);
-      if (findUnresolvedVars(substituted).length === 0) {
-        scope[key] = substituted;
-        unresolved.delete(key);
-        progressed = true;
-      }
-    }
-  }
-
-  if (unresolved.size > 0) {
-    throw buildUnresolvedScopeError(block, scope, unresolved);
-  }
-
-  return scope;
-}
-
-/**
- * Builds the ConfigError thrown when resolveScope's fixpoint stops with entries
- * still unresolved. The message names each unresolved entry and the exact
- * `${names}` it still needs, then separates the two failure modes: reference
- * CYCLES (entries that depend on each other, no starting point) and UNDEFINED
- * references (names defined nowhere). It closes with the variables that ARE in
- * scope, so a typo is obvious at a glance.
- *
- * @param block - The raw _vars block being resolved.
- * @param scope - The working scope (inherited vars + every entry that DID
- *   resolve); its keys are the "in scope" list.
- * @param unresolved - The block keys that never resolved.
- */
-function buildUnresolvedScopeError(
-  block: Record<string, string>,
-  scope: VarScope,
-  unresolved: Set<string>
-): ConfigError {
-  // For each unresolved entry, the ${names} still missing after fixpoint. Every
-  // such name is either another unresolved block key (an intra-block edge) or a
-  // name defined nowhere (resolvable block keys and inherited vars are already
-  // in `scope`, so they never appear here).
-  const needs = new Map<string, string[]>();
-  for (const key of unresolved) {
-    needs.set(key, findUnresolvedVars(substituteVars(block[key], scope)));
-  }
-
-  // Dependency graph among unresolved entries: u -> v when u still needs the
-  // still-unresolved block key v. SCCs of this graph are the reference cycles.
-  const edges = new Map<string, string[]>();
-  for (const key of unresolved) {
-    edges.set(key, (needs.get(key) ?? []).filter((n) => unresolved.has(n)));
-  }
-  const cycles = findCycles([...unresolved], edges);
-
-  // Undefined references: needed names that are not block keys at all.
-  const undefinedRefs = new Map<string, string[]>();
-  for (const key of unresolved) {
-    for (const name of needs.get(key) ?? []) {
-      if (!unresolved.has(name)) {
-        const referrers = undefinedRefs.get(name) ?? [];
-        referrers.push(key);
-        undefinedRefs.set(name, referrers);
-      }
-    }
-  }
-
-  const lines: string[] = [
-    "Unresolved variables after fixpoint resolution of a _vars block:",
-  ];
-  for (const key of [...unresolved].sort()) {
-    const names = (needs.get(key) ?? []).map((n) => `\${${n}}`).join(", ");
-    lines.push(`  - ${key} still needs ${names || "(nothing resolvable)"}`);
-  }
-
-  if (cycles.length > 0) {
-    lines.push("");
-    lines.push("Reference cycles (these variables reference each other):");
-    for (const cycle of cycles) {
-      const sorted = [...cycle].sort();
-      lines.push(`  - ${[...sorted, sorted[0]].join(" -> ")}`);
-    }
-  }
-
-  if (undefinedRefs.size > 0) {
-    lines.push("");
-    lines.push("Undefined references (names defined nowhere — no _vars, _env, or auto-var):");
-    for (const name of [...undefinedRefs.keys()].sort()) {
-      const referrers = [...new Set(undefinedRefs.get(name) ?? [])].sort();
-      lines.push(`  - \${${name}} (needed by ${referrers.join(", ")})`);
-    }
-  }
-
-  const inScope = Object.keys(scope).sort();
-  lines.push("");
-  lines.push(`Variables in scope here: ${inScope.length > 0 ? inScope.join(", ") : "(none)"}`);
-
-  return new ConfigError(lines.join("\n"));
-}
-
-/**
- * Finds reference cycles in a directed graph via Tarjan's strongly-connected-
- * component algorithm. A cycle is an SCC with more than one member, or a single
- * node that references itself. Returns each cycle as its member list.
- */
-function findCycles(nodes: string[], edges: Map<string, string[]>): string[][] {
-  const index = new Map<string, number>();
-  const low = new Map<string, number>();
-  const onStack = new Set<string>();
-  const stack: string[] = [];
-  const sccs: string[][] = [];
-  let counter = 0;
-
-  function strongconnect(v: string): void {
-    index.set(v, counter);
-    low.set(v, counter);
-    counter++;
-    stack.push(v);
-    onStack.add(v);
-
-    for (const w of edges.get(v) ?? []) {
-      if (!index.has(w)) {
-        strongconnect(w);
-        low.set(v, Math.min(low.get(v)!, low.get(w)!));
-      } else if (onStack.has(w)) {
-        low.set(v, Math.min(low.get(v)!, index.get(w)!));
-      }
-    }
-
-    if (low.get(v) === index.get(v)) {
-      const component: string[] = [];
-      let w: string;
-      do {
-        w = stack.pop()!;
-        onStack.delete(w);
-        component.push(w);
-      } while (w !== v);
-      sccs.push(component);
-    }
-  }
-
-  for (const v of nodes) {
-    if (!index.has(v)) strongconnect(v);
-  }
-
-  return sccs.filter(
-    (component) =>
-      component.length > 1 || (edges.get(component[0]) ?? []).includes(component[0])
-  );
-}
-
-/**
- * Where the active config came from. Threaded through variable resolution so
- * configs can reference their own `.sous/` directory and so error messages can
- * point at the right `.env.local` / `.env`.
- */
-export type ConfigContext = {
-  /** Absolute path to the `.sous/` directory holding the config. */
-  sousDir: string;
-  /** Absolute path to the primary config file itself. */
-  configPath: string;
-  /** Absolute path to the `conf.d/` drop-in directory (may not exist). */
-  confDir?: string;
-  /** Ordered absolute paths of every loaded config layer (primary first). */
-  layerPaths?: string[];
-};
-
-/**
- * Builds the auto-injected variable scope. These vars are always available
- * and injected first, before _env and _vars.
- * The 'sous*' namespace is reserved — warns if user defines a var starting with 'sous'.
- *
- * `sousHome` is resolved from `process.env` on every call rather than captured
- * once, because `SOUS_HOME` is file-settable: `.sous/.env.local` and
- * `.sous/.env` are loaded into `process.env` before settings resolve.
- *
- * @param context - The discovered config location. When supplied, adds
- *   `sousDir` and `sousConfigPath` (plus `sousConfDir` when known) so configs
- *   can build paths relative to their own `.sous/` directory.
- */
-export function buildAutoVars(context?: ConfigContext): VarScope {
-  return {
-    sousRootPath: CLI_ROOT,
-    sousVersion: SOUS_VERSION,
-    sousHome: resolveSousHome(),
-    ...(context !== undefined && {
-      sousDir: context.sousDir,
-      sousConfigPath: context.configPath,
-    }),
-    ...(context?.confDir !== undefined && {
-      sousConfDir: context.confDir,
-    }),
-  };
-}
-
-/**
- * Resolves the top-level _env block into a VarScope.
- * Each entry maps a config var name (key) to an environment variable name (value).
- * Throws a clear error if any referenced env var is not set.
- * Only called on the root Settings object — _env is top-level only.
- *
- * @param settings - The root settings object.
- * @param context - The discovered config location, used to name the
- *   `.sous/.env.local` and `.sous/.env` files in the error message.
- */
-export function resolveEnvScope(settings: Settings, context?: ConfigContext): VarScope {
-  const env = settings._env ?? {};
-  const scope: VarScope = {};
-
-  for (const [varName, envVarName] of Object.entries(env)) {
-    const value = process.env[envVarName];
-    if (value === undefined) {
-      const envLocalPath = context
-        ? path.join(context.sousDir, ENV_LOCAL_NAME)
-        : `${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}`;
-      const envDefaultsPath = context
-        ? path.join(context.sousDir, ENV_DEFAULTS_NAME)
-        : `${SOUS_DIR_NAME}/${ENV_DEFAULTS_NAME}`;
-      throw new ConfigError(
-        `_env resolution failed: environment variable '${envVarName}' (mapped to config ` +
-          `var '${varName}') is not set.\n` +
-          `  Define it in ${envLocalPath} as:\n` +
-          `    ${envVarName}=<value>\n` +
-          `  ...or, if the value is shared by the whole team and is not a secret, in ` +
-          `${envDefaultsPath} (committed).\n` +
-          `  ...or export it in your shell before running sous.`
-      );
-    }
-    scope[varName] = value;
-  }
-
-  return scope;
-}
-
-/** What else a root scope may be built from; see resolveRootScope. */
-export type RootScopeOptions = {
-  /**
-   * The recipe answers already resolved for this project. When omitted and a
-   * config context is given, they are resolved here; pass them when a caller
-   * has them already, so the lockfile and the manifests are read once.
-   */
-  answers?: RecipeAnswers;
-  /**
-   * The recipe whose own files this scope renders, as `namespace/recipe`. Its
-   * own answers are laid over the merged view, so a recipe sees the answer to
-   * its own question even when another recipe asks the same name.
-   */
-  recipe?: string;
-};
-
-/**
- * Resolves the root-level _vars from a Settings object into a scope.
- * Chains: auto-vars → recipe answers → env scope → root _vars.
- *
- * The recipe answers are the values the project's env files and shell hold for
- * every variable its subscribed recipes publish, found through the ladder in
- * `vars/ladder.ts`. They sit under `_env` and `_vars`, so an explicit config
- * value always wins, and they are present only when a config context says which
- * project this is; a settings object built by hand in a test has none.
- *
- * @param settings - The root settings object.
- * @param context - The discovered config location (optional in tests).
- * @param options - Answers already resolved, or the recipe the scope is for.
- */
-export function resolveRootScope(
-  settings: Settings,
-  context?: ConfigContext,
-  options: RootScopeOptions = {}
-): VarScope {
-  const autoVars = buildAutoVars(context);
-  const answers = resolveAnswerLayer(settings, context, options);
-  const envScope = resolveEnvScope(settings, context);
-  const baseScope = { ...autoVars, ...answers, ...envScope };
-  return resolveScope(settings._vars ?? {}, baseScope);
-}
-
-/**
- * The recipe-answer layer of a root scope: the merged view, or a recipe's own
- * view of it. Empty without a config context.
- */
-function resolveAnswerLayer(
-  settings: Settings,
-  context: ConfigContext | undefined,
-  options: RootScopeOptions
-): VarScope {
-  if (context === undefined) return {};
-  const answers =
-    options.answers ?? resolveRecipeAnswers({ settings, sousDir: context.sousDir });
-  return options.recipe === undefined ? answers.merged : answersForRecipe(answers, options.recipe);
-}
-
-/**
- * Built-in `@include` aliases: every `#` name the registry holds
- * (`sharedHashNames`), each standing for its directories in this project. They
- * are reserved (user `_aliases` may not start with `#`), so a user alias can
- * never shadow one.
- *
- * - `#project` is the consuming project's root (`projectRoot`).
- *
- * Files that used to be reached through a built-in alias pointing inside the
- * sous package are published as recipes now, and a recipe's files are addressed
- * by its namespace (`@~workflow/task-files/_partials/resume-task.md`),
- * resolved against what the project has pinned. A `~` reference is NOT an
- * alias: it is resolved separately, after the alias map has been tried; see
- * `locked-namespace-resolver.ts`.
- */
-export function buildBuiltInAliases(scope: VarScope): AliasMap {
-  return sharedHashNames().aliasMap(scope as Record<string, string>);
-}
-
-/**
- * Resolve the full `@include` alias map: built-ins, then the config's
- * `_aliases` block (user entries prepend, so they are tried first and fall
- * through to built-in bases of the same name). User alias names starting
- * with `~` or `#` are a ConfigError (reserved).
- *
- * @param settings - The loaded settings (for the `_aliases` block).
- * @param scope - The resolved settings scope (for ${var} substitution + projectRoot).
- */
-export function resolveAliases(settings: Settings, scope: VarScope): AliasMap {
-  return buildAliasMap({
-    builtIns: buildBuiltInAliases(scope),
-    userAliases: [settings._aliases],
-    scope,
-    onError: (message) => {
-      throw new ConfigError(message);
-    },
-  });
-}
-
-/** A resolved tool configuration with promptFile path substituted. */
-export type ResolvedToolConfig = {
-  command: string;
-  args?: string[];
-  promptFile?: string;
-};
-
-/**
- * Resolves the config's tools block, substituting vars in promptFile paths.
- * Returns an empty object if no tools are configured.
- *
- * @param settings - The loaded settings.
- * @param scope - The resolved settings scope (from resolveRootScope).
- */
-export function resolveTools(
-  settings: Settings,
-  scope: VarScope = {}
-): Record<string, ResolvedToolConfig> {
-  if (!settings.tools) return {};
-
-  return Object.fromEntries(
-    Object.entries(settings.tools).map(([name, tool]) => [
-      name,
-      {
-        command: tool.command,
-        ...(tool.args !== undefined && { args: tool.args }),
-        ...(tool.promptFile !== undefined && {
-          promptFile: substituteVarsStrict(
-            tool.promptFile,
-            scope,
-            `tools.${name}.promptFile`
-          ),
-        }),
-      },
-    ])
-  );
-}
-
-// --- Compilation Resolution ----------------------------------------------------------------------
-
-/**
- * Resolves a RawRuntimeContext into a ResolvedRuntimeContext by substituting
- * ${var} references and converting branchPattern from string to RegExp.
- */
-function resolveRuntimeContext(
-  raw: RawRuntimeContext,
-  scope: VarScope,
-  context: string
-): ResolvedRuntimeContext {
-  return {
-    gitRoot: substituteVarsStrict(raw.gitRoot, scope, `${context}.gitRoot`),
-    outputPath: substituteVarsStrict(raw.outputPath, scope, `${context}.outputPath`),
-    taskFileRoot: substituteVarsStrict(raw.taskFileRoot, scope, `${context}.taskFileRoot`),
-    branchPattern: new RegExp(raw.branchPattern ?? "PT-"),
-  };
-}
-
-/**
- * Resolves the config's compilation block into the shape the compiler expects.
- * Walks the config tree resolving _vars at each level (settings → compilation → target → output).
- * Pass scope from resolveRootScope(settings) to thread the settings vars down.
- * Returns null if the config has no compilation block.
- */
-export function resolveCompilation(
-  settings: Settings,
-  scope: VarScope = {}
-): CompilationConfig | null {
-  if (!settings.compilation) return null;
-
-  const compilationScope = resolveScope(settings.compilation._vars ?? {}, scope);
-  const aliases = resolveAliases(settings, scope);
-
-  return {
-    includeSourceComments: settings.compilation.includeSourceComments,
-    aliases,
-    includeScope: scope,
-    targets: settings.compilation.targets.flatMap((target, targetIndex): CompilationTarget[] => {
-      const targetScope = resolveScope(target._vars ?? {}, compilationScope);
-      const where = `compilation.targets[${targetIndex}]`;
-      const hasSingle = target.entryPoint !== undefined;
-      const hasGlob = target.entryGlob !== undefined;
-
-      if (hasSingle && hasGlob) {
-        throw new Error("Target cannot have both entryPoint and entryGlob");
-      }
-      if (!hasSingle && !hasGlob) {
-        throw new Error("Target must have either entryPoint or entryGlob");
-      }
-
-      /**
-       * Resolves the outputs array for a target, filtering by _if conditions and substituting vars.
-       */
-      function resolveOutputs(scope: VarScope) {
-        return target.outputs
-          .filter(output => {
-            if (!output._if) return true;
-            const outputScope = resolveScope(output._vars ?? {}, scope);
-            return Object.entries(output._if).every(([varName, condition]) => {
-              const val = outputScope[varName] ?? scope[varName] ?? compilationScope[varName];
-              return val === condition.eq;
-            });
-          })
-          .map((output, outputIndex) => {
-            const outputScope = resolveScope(output._vars ?? {}, scope);
-            const outputWhere = `${where}.outputs[${outputIndex}]`;
-            return {
-              ...(output.destinationFile !== undefined && {
-                destinationFile: normalizeConfigPath(
-                  substituteVarsStrict(
-                    output.destinationFile,
-                    outputScope,
-                    `${outputWhere}.destinationFile`
-                  )
-                ),
-              }),
-              ...(output.destinationDir !== undefined && {
-                destinationDir: normalizeConfigPath(
-                  substituteVarsStrict(
-                    output.destinationDir,
-                    outputScope,
-                    `${outputWhere}.destinationDir`
-                  )
-                ),
-              }),
-              vars: outputScope,
-            };
-          });
-      }
-
-      if (hasSingle) {
-        const runtimeContext =
-          target.generateRuntimeContext && settings.runtimeContext
-            ? resolveRuntimeContext(settings.runtimeContext, scope, "runtimeContext")
-            : undefined;
-        return [{
-          rootInputPath: normalizeConfigPath(
-            substituteVarsStrict(target.entryPoint!, targetScope, `${where}.entryPoint`)
-          ),
-          ...(runtimeContext !== undefined && { runtimeContext }),
-          outputs: resolveOutputs(targetScope),
-        }];
-      }
-
-      /* c8 ignore start */
-      // Glob target: expand pattern into one CompilationTarget per matched file, skipping dirs.
-      // A leading alias (`#project/skills/**`) expands to one candidate pattern per alias
-      // base; the first base that matches any files wins, mirroring the first-existing-wins
-      // rule of @include resolution.
-      const rawPattern = substituteVarsStrict(target.entryGlob!, targetScope, `${where}.entryGlob`);
-      const patternCandidates = resolveAliasPrefix(rawPattern, aliases).map(toGlobPattern);
-      let pattern = patternCandidates[0];
-      let matchedFiles: string[] = [];
-      for (const candidate of patternCandidates) {
-        const matches = globSync(candidate, { absolute: true })
-          .filter(filePath => fs.statSync(filePath).isFile());
-        if (matches.length > 0) {
-          pattern = candidate;
-          matchedFiles = matches;
-          break;
-        }
-      }
-
-      if (matchedFiles.length === 0) {
-        warning(`Glob pattern matched no files:\n${patternCandidates.join("\n")}`);
-      }
-
-      const globBase = normalizeConfigPath(
-        target.globBase
-          ? substituteVarsStrict(target.globBase, targetScope, `${where}.globBase`)
-          : inferGlobBase(pattern)
-      );
-      return matchedFiles.map(filePath => ({
-        rootInputPath: filePath,
-        globBase,
-        outputs: resolveOutputs(targetScope),
-      }));
-      /* c8 ignore stop */
-    }),
-  };
-}
-
-/** Resolved watch configuration for a project. */
-export type WatchConfig = {
-  /** Exact file paths — watched directly by chokidar. Trigger partial rebuilds. */
-  files: string[];
-  /**
-   * Glob patterns — chokidar watches their base directories; incoming events are
-   * filtered against these patterns before triggering a partial rebuild.
-   */
-  globs: string[];
-  /**
-   * Additional paths (files or directories) that trigger a full rebuild when changed.
-   * Used for the settings file, templating directory, and config imports.
-   */
-  fullRebuildPaths?: string[];
-};
-
-/**
- * Returns the watch configuration for the config's compilation targets.
- *
- * - entryPoint targets → exact file path in `files`.
- * - entryGlob targets → resolved glob string in `globs`.
- *
- * Alias prefixes in entryGlob patterns are expanded (every base of the alias
- * is watched, matching compile's fall-through resolution).
- */
-export function resolveWatchConfig(settings: Settings, scope: VarScope = {}): WatchConfig {
-  if (!settings.compilation) return { files: [], globs: [] };
-
-  const compilationScope = resolveScope(settings.compilation._vars ?? {}, scope);
-  const aliases = resolveAliases(settings, scope);
-  const files: string[] = [];
-  const globs: string[] = [];
-
-  for (const [targetIndex, target] of settings.compilation.targets.entries()) {
-    const targetScope = resolveScope(target._vars ?? {}, compilationScope);
-    const where = `compilation.targets[${targetIndex}]`;
-
-    if (target.entryPoint) {
-      // Normalize to match the compilation path (rootInputPath) and, more
-      // importantly, chokidar's change events: chokidar reports the OS-normalized
-      // path, so an unnormalized `${sousDir}/../prompts/A.md` entry would never
-      // string-match the `/prompts/A.md` event and the partial rebuild would never fire.
-      files.push(
-        normalizeConfigPath(
-          substituteVarsStrict(target.entryPoint, targetScope, `${where}.entryPoint`)
-        )
-      );
-    }
-
-    if (target.entryGlob) {
-      const pattern = substituteVarsStrict(target.entryGlob, targetScope, `${where}.entryGlob`);
-      globs.push(...resolveAliasPrefix(pattern, aliases).map(normalizeConfigPath));
-    }
-  }
-
-  return {
-    files: [...new Set(files)],
-    globs: [...new Set(globs)],
-  };
-}