@sous-io/sous 0.2.2 → 0.2.4

package/README.md

@@ -41,16 +41,22 @@ npm install
 npm link
 ```
 
-Then set up a project. A project needs a `.sous/` directory holding a config file, named
-`sous.config.js`, `sous.config.mjs`, `sous.config.json`, or `sous.config.yaml`:
+Then set up a project:
 
 ```bash
 cd /path/to/your/project
-mkdir .sous
-$EDITOR .sous/sous.config.js
+sous init
 ```
 
-A config that compiles one file:
+`sous init` writes the project's `.sous/` directory and runs the first build. It creates a
+commented `sous.config.js` (pass `--format json` for a JSON config bound to the shipped
+schema), a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md`
+at the project root, the two env files described below, and a `.sous/.gitignore` covering the
+files sous keeps local to one machine. The first build compiles the starter prompt and the
+`core` skills every project gets, and pins them in `.sous/sous.lock.json`. A project that
+already holds a config is left untouched.
+
+The config it writes compiles one file:
 
 ```js
 export const config = {
@@ -59,17 +65,19 @@ export const config = {
   compilation: {
     targets: [
       {
-        entryPoint: "${sousDir}/AGENTS.md",
-        outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
+        entryPoint: "${sousDir}/prompts/AGENTS.md",
+        outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
       },
     ],
   },
+  recipeOutputs: { skills: ["${projectRoot}/.claude/skills"] },
 };
 ```
 
 `${sousDir}` is the `.sous/` directory sous found, so a config can name paths relative to
-itself without hardcoding anything machine-specific. One config describes one project. Then
-build:
+itself without hardcoding anything machine-specific. One config describes one project. A
+`.sous/` may hold one config file, named `sous.config.js`, `sous.config.mjs`,
+`sous.config.json`, `sous.config.jsonc` or `sous.config.yaml`. After editing, build:
 
 ```bash
 sous build
@@ -95,6 +103,7 @@ Useful commands:
 
 | Command | What it does |
 |---|---|
+| `sous init` | Set a project up: write `.sous/`, then run the first build |
 | `sous build` | Compile, then prune stale outputs |
 | `sous build --watch` | Rebuild on source changes |
 | `sous compile` | Compile only |

package/docs/markdown/_sidebar.md

@@ -19,3 +19,5 @@
   - [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)
+  - [0003: Project setup with sous init](adrs/0003-project-init.md)

package/docs/markdown/commands.md

@@ -46,6 +46,27 @@ Every topic answers to both spellings of its name: `repo` and `repos`, `subscrip
 
 ## Top-level commands
 
+### `sous init [DIRECTORY]`
+Sets a project up for sous: writes its `.sous/` directory, then runs the first build. It is the one command that
+runs before a config exists, and the starting point for a project that has never used sous. It writes a commented
+primary config, a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md` at the
+project root, `.sous/.env` and `.sous/.env.local.example`, and the sous-managed block in `.sous/.gitignore`. The
+first build compiles the starter prompt and the `core` skills, and pins them in `.sous/sous.lock.json`.
+
+A project whose `.sous/` already holds a primary config is refused, and nothing is written. Setting up a directory
+inside a project that is already set up is a question rather than an error, since a subproject may want its own
+instructions; `-y, --yes` answers it ahead of time, and a run with no terminal fails naming that flag.
+
+- `DIRECTORY`: the project directory to set up; the current one by default. `--sous-dir` and `SOUS_DIR` also say
+  where, when no directory is given.
+- `--format <js|json>`: which config to write, `js` by default. The JSON config carries `$schema`, bound to the
+  schema artifact published for the running sous version.
+- `--name <name>`: the display name written into the config; the directory's own name by default.
+- `--no-build`: write the setup without running the first build.
+- `--dry-run`: print the files that would be written without writing them.
+
+Example: `sous init --format json`
+
 ### `sous build`
 Compiles this project's outputs, then removes the ones its config no longer produces. It is compile plus prune,
 and the command you want almost always. Takes `--dry-run`.

package/docs/markdown/config-discovery.md

@@ -57,8 +57,9 @@ first, so setting a location var inside `.env.local` has no effect on discovery.
 
 All are hard `ConfigError`s; sous never guesses:
 
-- **No config found**: the error lists every directory checked during the walk and shows a
-  minimal starter config.
+- **No config found**: the error lists every directory checked during the walk and names the two
+  fixes: run `sous init` in the project's root directory, which writes the config and everything
+  else a first build needs, or pass `--config <path>`.
 - **Multiple primary configs**: two or more of `sous.config.js|mjs|json|jsonc|yaml` in the same
   `.sous/` is an error naming every candidate.
 - **Duplicate layer baseNames**: any two loaded files (primary or conf.d) whose names differ

package/docs/markdown/config-inspection.md

@@ -27,7 +27,10 @@ tooling:
 { "$schema": "./path/to/sous.config.schema.json" }
 ```
 
-The `$schema` key is accepted at the top level and ignored by sous itself.
+The `$schema` key is accepted at the top level and ignored by sous itself. A config written by
+`sous init --format json` binds it to the same artifact as published on GitHub for the running
+version, so an editor resolves it without a path into the installed package; point it at the
+package-local copy instead when the editor should work offline.
 
 ## sous config show
 

package/docs/markdown/configuration.md

@@ -39,7 +39,8 @@ export const config = {
 ```
 
 A JSON config may set `"$schema"` to bind the `sous.config.schema.json` artifact shipped with
-sous for editor autocompletion; sous accepts and ignores the key.
+sous for editor autocompletion; sous accepts and ignores the key. `sous init --format json`
+writes one already bound to the copy of that artifact published for the running version.
 
 ?> Configs use `${var}` syntax. Template files use LiquidJS double-brace syntax instead; the two
 are resolved at different stages and never mix.

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-quickstart.md

@@ -24,7 +24,10 @@ echo 'name: my-project' > .sous/sous.config.yaml
 ```
 
 Everything else has a default: skills compile into `<project root>/.claude/skills`, and the
-lockfile, the state file and the config layers sous writes land under `.sous/`. `SOUS_HOME` puts
+lockfile, the state file and the config layers sous writes land under `.sous/`. Outside a
+walkthrough, `sous init` writes a fuller starting point (a commented config, a starter prompt,
+the env files and the ignore block) and runs the first build for you; the one-line config is
+used here so that each step shows one thing. `SOUS_HOME` puts
 the machine-wide store somewhere throwaway, so this walkthrough leaves your real one alone. See
 [The config file](configuration.md) for the keys you will want later.
 

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.4",
   "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.4
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/base-command.ts

@@ -40,6 +40,23 @@ import { reportCommandError } from "./utils/command-errors.js";
  * lives in `lib/interactive.ts`, which also treats a truthy `CI` and a
  * non-terminal stdin or stdout the same way.
  */
+/**
+ * What the config-locating flags and environment said on this run, resolved to
+ * absolute paths but not yet turned into a config.
+ */
+export type ConfigLocator = {
+  /** The working directory discovery started from. */
+  cwd: string;
+  /**
+   * The explicit config location, when one was given: the resolved path and
+   * the flag or environment variable that supplied it (`--config`,
+   * `--sous-config`, `SOUS_CONFIG`, `--sous-dir` or `SOUS_DIR`).
+   */
+  primary?: { value: string; source: string };
+  /** The conf.d directory override, when `--sous-confd` or `SOUS_CONFD` gave one. */
+  confDirOverride?: string;
+};
+
 export abstract class BaseCommand extends Command {
   static baseFlags = {
     config: Flags.string({
@@ -60,11 +77,29 @@ export abstract class BaseCommand extends Command {
     "non-interactive": nonInteractiveFlag(),
   };
 
+  /**
+   * Whether a run of this command needs a project config to exist. Every
+   * command that works on a project leaves this true, and a run that finds no
+   * config fails before `run()` with the "No sous config found" block. The one
+   * command whose job is to CREATE the config sets it false: discovery still
+   * runs, so the config-locating flags still say where the project is, but
+   * finding nothing is the expected case rather than an error, and `settings`
+   * stays unset until `adoptConfig` is given the config that was written.
+   */
+  static requiresConfig = true;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
   protected configContext!: ConfigContext;
 
+  /**
+   * What the config-locating flags and environment said, before discovery
+   * turned it into a config. A command that runs without a config reads the
+   * project's location from here.
+   */
+  protected configLocator!: ConfigLocator;
+
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
@@ -142,6 +177,16 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
+    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+
+    this.configLocator = {
+      cwd,
+      primary:
+        primary !== undefined
+          ? { value: path.resolve(cwd, expandHome(primary[0] as string)), source: primary[1] }
+          : undefined,
+      confDirOverride,
+    };
 
     let discovered: DiscoveredConfig | null;
 
@@ -150,6 +195,9 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        // A command that creates the config is pointed at a place with none in
+        // it by design; the flag still says where, so this is not a failure.
+        if (!requiresConfig) return;
         displayError(error instanceof Error ? error.message : String(error), this.errorSink);
         return this.exit(1);
       }
@@ -158,10 +206,29 @@ export abstract class BaseCommand extends Command {
     }
 
     if (!discovered) {
+      if (!requiresConfig) return;
       displayErrorBlock(formatNotFoundMessage(), this.errorSink);
       return this.exit(1);
     }
 
+    await this.adoptConfig(discovered);
+  }
+
+  /** True once a config has been discovered or adopted and its settings loaded. */
+  protected get hasConfig(): boolean {
+    return this.discovered !== undefined;
+  }
+
+  /**
+   * Makes a discovered config THE config for the rest of the run: loads its
+   * env files, enumerates its layers again now that `SOUS_HOME` may have
+   * changed, and loads the settings. `init()` calls it for the config discovery
+   * found; a command that creates a config calls it for the one it wrote, so
+   * both go through the same steps in the same order.
+   *
+   * @param discovered - The config to adopt.
+   */
+  protected async adoptConfig(discovered: DiscoveredConfig): Promise<void> {
     // Inject .sous/.env.local and .sous/.env before anything resolves variables,
     // keeping a copy of what the shell itself set so the variables layer can
     // still tell the two apart.
@@ -172,27 +239,28 @@ export abstract class BaseCommand extends Command {
     // file-settable, and it decides where the store holding a subscribed
     // recipe's config layers is. A first pass already ran during discovery, when
     // only the real environment was known.
+    let refreshed: DiscoveredConfig;
     try {
-      discovered = refreshDiscoveredConfig(discovered);
+      refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
 
-    this.discovered = discovered;
+    this.discovered = refreshed;
     this.configContext = {
-      sousDir: discovered.sousDir,
-      configPath: discovered.configPath,
-      confDir: discovered.confDir,
-      layerPaths: discovered.layerPaths,
+      sousDir: refreshed.sousDir,
+      configPath: refreshed.configPath,
+      confDir: refreshed.confDir,
+      layerPaths: refreshed.layerPaths,
     };
 
     // Routed through the command's error sink, not stdout: a recipe layer
     // warning must not land in the middle of `sous config show | jq`.
-    for (const notice of discovered.recipeLayerWarnings) warning(notice, this.errorSink);
+    for (const notice of refreshed.recipeLayerWarnings) warning(notice, this.errorSink);
 
     try {
-      this.settings = await loadSettings(discovered);
+      this.settings = await loadSettings(refreshed);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);

package/src/commands/build.ts

@@ -5,15 +5,12 @@ import { PidService } from "../lib/pid-service.js";
 import { resolveRootScope } from "../lib/settings.js";
 import { describeLinkedRepos } from "../lib/repos/links.js";
 import { resolveStoreSettings } from "../lib/repos/store/settings.js";
-import {
-  subscriptionServiceFor,
-  type SubscriptionService,
-} from "../lib/repos/subscription-service.js";
+import { prepareRepositoriesForBuild } from "../lib/build-preparation.js";
+import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
 import { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
 import type { WatchHandle } from "../lib/watch-service.js";
 import { WatchService } from "../lib/watch-service.js";
 import {
-  blankLine,
   footer,
   heading,
   log,
@@ -87,7 +84,7 @@ export default class Build extends BaseCommand {
     });
 
     if (!flags["dry-run"] && !flags["no-compile"]) {
-      await this.prepareRepositories(repositories);
+      await prepareRepositoriesForBuild(repositories);
     }
 
     heading("Building");
@@ -196,78 +193,4 @@ export default class Build extends BaseCommand {
       await new Promise(() => {}); // keep process alive
     }
   }
-
-  /**
-   * Gets this project's recipes ready to compile: restores whatever the store is
-   * missing (a fresh clone, or a collected store) and then asks upstream for the
-   * repositories that prefer a newer in-range version.
-   *
-   * Restoring asks nothing and decides nothing; it fetches exactly what the
-   * lockfile pins. An upstream check that fails is reported and then ignored,
-   * because a build must not depend on the network being up.
-   *
-   * @param repositories - The subscription service for this project.
-   */
-  private async prepareRepositories(repositories: SubscriptionService): Promise<void> {
-    const needsRestore = repositories.needsRestore();
-    if (needsRestore) {
-      heading("Restoring recipes");
-      blankLine();
-      paragraph(
-        "This project's lockfile pins recipes that are not in the store on this " +
-          "machine, so they are being fetched at exactly the versions it records."
-      );
-    }
-
-    const { seed, subscriptions, restored, upstream } =
-      await repositories.prepareForBuild();
-
-    // Seeding the packaged core recipe is silent when it works, which is almost
-    // always; it is only worth a word when it could not be done at all.
-    if (seed.skippedBecause !== undefined) warning(seed.skippedBecause);
-
-    // A subscription the lockfile did not pin yet has just been pinned. That is
-    // a change to a committed file, so it is always announced.
-    if (subscriptions.added.length > 0 || subscriptions.moved.length > 0) {
-      heading("Locking subscribed recipes");
-      blankLine();
-      for (const entry of subscriptions.added) {
-        paragraph(`  pinned: ${entry.key} at version ${entry.version}.`);
-      }
-      for (const change of subscriptions.moved) {
-        paragraph(`  ${change.key} moved from version ${change.from} to version ${change.to}.`);
-      }
-      blankLine();
-      paragraph(
-        "The lockfile has been updated. Commit it, so everyone building this project " +
-          "gets exactly these versions."
-      );
-      footer();
-    }
-
-    for (const failure of subscriptions.failed) {
-      warning(
-        `Sous could not work out which version of '${failure.key}' to use, so nothing ` +
-          `from it was compiled.\n${failure.reason}`
-      );
-    }
-
-    if (restored !== undefined && restored.restored.length > 0) {
-      blankLine();
-      for (const key of restored.restored) paragraph(`  restored: ${key}`);
-    }
-
-    for (const change of upstream.updated) {
-      paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
-    }
-
-    for (const failure of upstream.failed) {
-      warning(
-        `Sous could not check the repository '${failure.repo}' for a newer version, so ` +
-          `this build uses the versions it already had.\n${failure.reason}`
-      );
-    }
-
-    if (needsRestore) footer();
-  }
 }

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),