@sous-io/sous 0.2.2 → 0.2.3

package/docs/markdown/_sidebar.md

@@ -19,3 +19,4 @@
   - [Troubleshooting](repositories-troubleshooting.md)
 - **ADRs**
   - [0001: Repositories](adrs/0001-repositories.md)
+  - [0002: Recipe answers in the template scope](adrs/0002-recipe-answers-in-templates.md)

package/docs/markdown/repositories-consuming.md

@@ -264,7 +264,9 @@ $ sous build
 ```
 
 A variable with no answer in the committed `.sous/.env` and none in the environment renders empty
-rather than stopping the build; run `sous vars ask` from a terminal to fill it in.
+rather than stopping the build, and the build prints a warning naming it before it compiles; run
+`sous vars ask` from a terminal to fill it in. How an answer reaches a template is described in
+[How a template reads an answer](repositories-variables.md#how-a-template-reads-an-answer).
 
 ## Control freshness and the store
 

package/docs/markdown/repositories-variables.md

@@ -297,20 +297,39 @@ nothing about it sensitive, committing it to `.sous/.env` is simpler: a fresh cl
 
 ## How a template reads an answer
 
-Answers are environment variables, and a template renders config variables. The bridge is one `_env` entry
-in your config, naming the variable the answer is stored under (`sous vars show` prints it as `stored-as`):
-
-```json
-{ "_env": { "taskFileRoot": "SOUS_VAR_TASK_FILE_ROOT" } }
-```
-
-With that line `{{ taskFileRoot }}` renders in any template this project compiles, and `${taskFileRoot}`
-works in `_vars` and every other config value.
-
-!> Answers are not injected into the template scope on their own, and `_env` names one exact environment
-variable rather than walking the ladder. A recipe's own templates read the project's `_vars` and the
-auto-injected `sous*` variables; they do not see the answers to their own questions unless your config maps
-them in.
+A build lays the answers into the template scope itself. For every variable a subscribed recipe publishes,
+the build walks the ladder above, takes the first value it finds, and adds it to the scope under the
+variable's own name. So once `taskFileRoot` is answered, `{{ taskFileRoot }}` renders in the recipe's own
+skills and in any template this project compiles, and `${taskFileRoot}` works in `_vars` and every other
+config value. Nothing has to be mapped by hand.
+
+The answers sit under your config, not over it. The scope a template renders with is assembled in this
+order, each layer overriding the one before:
+
+1. The auto-injected `sous*` variables.
+2. The recipe answers, found through the ladder.
+3. Your `_env` block.
+4. Your `_vars` block.
+
+So a project that already carries an answer in `_vars`, or maps one through `_env`, keeps rendering exactly
+what it did; the answer in the env files is simply shadowed, and `sous vars list` still reports it.
+
+When no rung answers, the definition's own `default` is what renders, because the description a publisher
+writes promises what the default does. A required variable with no answer and no default renders as an
+empty string, and the build says so before it compiles, naming each such variable, the recipe that asks for
+it, and `sous vars ask` as the way to answer. The build still succeeds; an unanswered question is
+something to tell you about, not a reason to refuse the rest of the project.
+
+?> Two recipes may ask the same question. Their shared answer renders in both, and in your own templates.
+When the recipe-scoped name gives one of them a different answer, that recipe's own files render its own
+answer while everything else, your templates included, renders the first definition's; `sous vars show`
+tells you which names are in play.
+
+An answer is laid in exactly as it is stored: a path stays the string you typed, relative or absolute, and a
+number stays text. A template that needs an absolute path from a relative answer composes one under another
+name in `_vars`, for instance `taskFileDir: "${sousDir}/../${taskFileRoot}"`.
+
+The `_env` block is still the way to reach any environment variable no recipe asks about.
 
 ## Where to go next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.2
+version: 0.2.3
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/commands/compile.ts

@@ -3,6 +3,7 @@ import { BaseCommand } from "../base-command.js";
 import { CompilationService } from "../lib/markdown-compiler.js";
 import { resolveCompilation, resolveRootScope } from "../lib/settings.js";
 import {
+  resolveProjectAnswers,
   resolveRecipeTargets,
   resolveStateFilePath,
   withRecipeTargets,
@@ -57,8 +58,9 @@ export default class Compile extends BaseCommand {
     // The recipes this project subscribes to contribute compile targets
     // alongside its own; both go through the same compiler.
     const withRecipes = () => {
-      const scope = resolveRootScope(this.settings, this.configContext);
-      const recipes = resolveRecipeTargets(this.settings, scope, this.configContext);
+      const answers = resolveProjectAnswers(this.settings, this.configContext);
+      const scope = resolveRootScope(this.settings, this.configContext, { answers });
+      const recipes = resolveRecipeTargets(this.settings, scope, this.configContext, answers);
       for (const notice of recipes.warnings) warning(notice);
       return withRecipeTargets(
         resolveCompilation(this.settings, scope),

package/src/lib/build-service.ts

@@ -11,6 +11,12 @@ import type { CompilationConfig, CompilationTarget } from "./markdown-compiler.j
 import { StateService } from "./state.js";
 import { isProtectedPath } from "./state.js";
 import { protectedRepoPaths } from "./repos/links.js";
+import {
+  noRecipeAnswers,
+  resolveRecipeAnswers,
+  unansweredWarning,
+  type RecipeAnswers,
+} from "./vars/answers.js";
 import { log, warning } from "../utils/formatting.js";
 
 export type BuildOptions = {
@@ -50,26 +56,65 @@ const NO_RECIPE_TARGETS: RecipeTargets = {
   warnings: [],
 };
 
+/**
+ * The answers to every recipe variable in play for the project the context
+ * describes, resolved once so a build can render with them, hand them to every
+ * scope it builds, and report what is still unanswered. Empty when the caller
+ * gave no config context.
+ *
+ * @param settings - The merged project config.
+ * @param configContext - Where the active config was discovered.
+ */
+export function resolveProjectAnswers(
+  settings: Settings,
+  configContext?: ConfigContext
+): RecipeAnswers {
+  if (configContext === undefined) return noRecipeAnswers();
+  return resolveRecipeAnswers({ settings, sousDir: configContext.sousDir });
+}
+
 /**
  * The compile targets a project's subscribed recipes contribute, for the project
  * the options describe. Empty when the caller gave no config context, which is
  * the case only in tests that build a settings object by hand.
  *
+ * Each recipe's files render with that recipe's own view of the answers, and a
+ * required variable nothing answered is reported through `warnings`, so every
+ * caller that prints those tells the user what the build could not fill in.
+ *
  * @param settings - The merged project config.
  * @param rootScope - The resolved settings scope, for `${var}` in destinations.
  * @param configContext - Where the active config was discovered.
+ * @param answers - The project's recipe answers, when the caller resolved them
+ *   already; resolved here otherwise.
  */
 export function resolveRecipeTargets(
   settings: Settings,
   rootScope: Record<string, string>,
-  configContext?: ConfigContext
+  configContext?: ConfigContext,
+  answers?: RecipeAnswers
 ): RecipeTargets {
   if (configContext === undefined) return NO_RECIPE_TARGETS;
-  return buildRecipeTargets({
+  const resolved = answers ?? resolveProjectAnswers(settings, configContext);
+  const scopes = new Map<string, Record<string, string>>();
+
+  const recipes = buildRecipeTargets({
     sousDir: configContext.sousDir,
     settings,
     scope: rootScope,
+    scopeFor: (recipe) => {
+      let scope = scopes.get(recipe.key);
+      if (scope === undefined) {
+        scope = resolveRootScope(settings, configContext, { answers: resolved, recipe: recipe.key });
+        scopes.set(recipe.key, scope);
+      }
+      return scope;
+    },
   });
+
+  const missing = unansweredWarning(resolved, rootScope);
+  if (missing !== undefined) recipes.warnings.push(missing);
+  return recipes;
 }
 
 /**
@@ -232,7 +277,10 @@ export class BuildService {
    * Returns true if all steps succeeded.
    */
   async build(settings: Settings, options: BuildOptions = {}): Promise<boolean> {
-    const rootScope = resolveRootScope(settings, options.configContext);
+    // The recipe answers are resolved once here and handed to every scope the
+    // build assembles, so the lockfile and the manifests are read one time.
+    const answers = resolveProjectAnswers(settings, options.configContext);
+    const rootScope = resolveRootScope(settings, options.configContext, { answers });
     const namespaceResolver = resolveNamespaceResolver(settings, options);
     const protectedPaths = protectedPathsFor(options);
 
@@ -260,7 +308,7 @@ export class BuildService {
     // targets alongside its own, so a recipe's files are compiled by exactly the
     // same machinery as everything else, and are pruned and cleared by it too.
     if (!options.noCompile) {
-      const recipes = resolveRecipeTargets(settings, rootScope, options.configContext);
+      const recipes = resolveRecipeTargets(settings, rootScope, options.configContext, answers);
       for (const notice of recipes.warnings) warning(notice);
 
       const config = withRecipeTargets(

package/src/lib/markdown-compiler.ts

@@ -129,6 +129,17 @@ export function inferGlobBase(pattern: string): string {
   return joined || "/";
 }
 
+/**
+ * A stable text form of an output's variable scope, for the source hash of a
+ * rendered output. Keys are sorted so two scopes holding the same values hash
+ * the same whatever order they were assembled in.
+ *
+ * @param vars - The variable scope an output renders with.
+ */
+export function stableVarsFingerprint(vars: Record<string, string>): string {
+  return JSON.stringify(Object.keys(vars).sort().map((key) => [key, vars[key]]));
+}
+
 export class CompilationService {
   private strict: boolean;
   private rebuild: boolean;
@@ -447,7 +458,7 @@ ${taskFileContents}
     }
 
     // Compute source hash once per target from the assembled content
-    const srcHash = hashContent(content);
+    const contentHash = hashContent(content);
 
     let allSucceeded = true;
 
@@ -462,6 +473,14 @@ ${taskFileContents}
       if (resolvedDest === undefined) continue;
       destFile = resolvedDest;
 
+      // A rendered output depends on its variables as much as on its source: a
+      // changed answer or `_vars` value with the same template must re-render,
+      // so the variable scope is part of a `.tpl.` output's source hash. A
+      // verbatim copy hashes its content alone.
+      const srcHash = isTpl && output.vars
+        ? hashContent(`${content}\n${stableVarsFingerprint(output.vars)}`)
+        : contentHash;
+
       // Skip if content is unchanged and file already exists (unless --rebuild)
       const existingEntry = state.files.find(f => f.dest === destFile);
       if (

package/src/lib/repos/recipe-targets.ts

@@ -52,6 +52,12 @@ export type RecipeTargetOptions = {
   settings: Settings;
   /** The resolved settings scope, used to substitute `${var}` in destinations. */
   scope?: VarScope;
+  /**
+   * The scope one recipe's own files render with. A recipe's answers to its own
+   * questions are laid over the project scope there, so a recipe sees its own
+   * answer even when another recipe asks the same name. Defaults to `scope`.
+   */
+  scopeFor?: (recipe: LockedRecipeLocation) => VarScope;
   /** The environment to read; decides where the store is. */
   env?: NodeJS.ProcessEnv;
   /** The locked recipes, when the caller has already located them. */
@@ -167,6 +173,8 @@ export function buildRecipeTargets(options: RecipeTargetOptions): RecipeTargets
       for (const destination of kindDestinations) destinations.add(destination);
       if (recipe.linked) watchDirs.add(recipe.dir);
 
+      const recipeScope = options.scopeFor?.(recipe) ?? options.scope ?? {};
+
       const ignore = (content.exclude ?? []).map((pattern) =>
         path.join(recipe.dir, pattern)
       );
@@ -182,7 +190,7 @@ export function buildRecipeTargets(options: RecipeTargetOptions): RecipeTargets
             globBase,
             outputs: kindDestinations.map((destination) => ({
               destinationDir: destination,
-              vars: options.scope ?? {},
+              vars: recipeScope,
             })),
           });
         }

package/src/lib/settings.ts

@@ -18,6 +18,11 @@ 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
@@ -757,20 +762,63 @@ export function resolveEnvScope(settings: Settings, context?: ConfigContext): Va
   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 → env scope → root _vars.
+ * 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): VarScope {
+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, ...envScope };
+  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, always available and reserved (their names begin
  * with `~` so user `_aliases` can never shadow them). Add new entries here as

package/src/lib/vars/answers.ts

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ *
+ * 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[];
+}
+
+/** 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: [] };
+}
+
+/**
+ * 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 (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}.`
+  );
+}

package/src/lib/vars/definition-source.ts

@@ -111,6 +111,15 @@ export class ProjectDefinitionSource implements VariableDefinitionSource {
 
   /** Every variable published by every recipe this project's lockfile pins. */
   async load(): Promise<DefinedVariable[]> {
+    return this.loadSync();
+  }
+
+  /**
+   * The same list, read synchronously. The lockfile and the manifests are
+   * ordinary files, and the settings scope a build renders with is assembled
+   * synchronously, so the build path needs this form.
+   */
+  loadSync(): DefinedVariable[] {
     void this.settings;
 
     const defined: DefinedVariable[] = [];

package/src/lib/vars/index.ts

@@ -6,6 +6,7 @@
  * later phases have one place to look for what this layer offers.
  */
 
+export * from "./answers.js";
 export * from "./definition-source.js";
 export * from "./display.js";
 export * from "./ladder.js";