@sous-io/sous 0.1.1 → 0.2.1

package/src/base-command.ts

@@ -1,43 +1,63 @@
+import path from "node:path";
 import { Command, Flags } from "@oclif/core";
 import {
   discoverConfig,
+  expandHome,
   formatNotFoundMessage,
+  refreshDiscoveredConfig,
   resolveConfigFlag,
   type DiscoveredConfig,
 } from "./lib/config-discovery.js";
 import { loadEnvFiles } from "./lib/env-local.js";
-import {
-  isConfigError,
-  loadSettings,
-  type ConfigContext,
-  type RawProject,
-  type Settings,
-} from "./lib/settings.js";
-import { displayError, displayErrorBlock, header } from "./utils/formatting.js";
+import { loadSettings, type ConfigContext, type Settings } from "./lib/settings.js";
+import { isInteractive } from "./lib/interactive.js";
+import { displayError, displayErrorBlock, header, log, warning } from "./utils/formatting.js";
+import { nonInteractiveFlag } from "./utils/flags.js";
+import { reportCommandError } from "./utils/command-errors.js";
 
 /**
  * Base class for all CLI commands.
  *
  * Startup sequence:
- *   1. Locate the config — `--config <path>` wins, otherwise walk up from cwd
- *      looking for a `.sous/` directory holding sous.config.{js,mjs,json}.
+ *   1. Locate the config. Primary-config precedence, highest first:
+ *      `--config`/`-c`/`--sous-config` flag > `SOUS_CONFIG` env >
+ *      `--sous-dir` flag > `SOUS_DIR` env > walk up from cwd looking for a
+ *      `.sous/` directory holding sous.config.{js,mjs,json,yaml}. The conf.d
+ *      drop-in directory precedence is: `--sous-confd` flag > `SOUS_CONFD` env >
+ *      `<sousDir>/conf.d`. Env vars are read from the REAL environment only
+ *      (never `.env.local`), because they decide where `.env.local` lives.
  *   2. Load `<.sous>/.env.local`, then `<.sous>/.env`, into process.env (never
  *      overwriting real env vars). Precedence: shell > .env.local > .env.
- *   3. Load the config file. Variable resolution happens later, per command.
+ *   3. Load every config layer (primary + conf.d) through the config kernel and
+ *      deep-merge them. Variable resolution happens later, per command.
  *
  * There is no user-level config: nothing is read from `~/.sous`.
+ *
+ * Every command also carries `--non-interactive`, which tells sous never to ask
+ * a question: a run that would have prompted fails instead, naming the prompt
+ * and the flag (or environment variables) that would have answered it, and this
+ * class prints the command's own help underneath that error. The rule itself
+ * lives in `lib/interactive.ts`, which also treats a truthy `CI` and a
+ * non-terminal stdin or stdout the same way.
  */
 export abstract class BaseCommand extends Command {
   static baseFlags = {
-    project: Flags.string({
-      char: "p",
-      description: "Project key to operate on",
-    }),
     config: Flags.string({
       char: "c",
       description:
         "Path to a sous config file (or a directory containing one). Overrides .sous/ discovery",
     }),
+    "sous-config": Flags.string({
+      description:
+        "Alias of --config: path to a sous config file (or a directory containing one)",
+    }),
+    "sous-dir": Flags.string({
+      description: "Path to the .sous directory to use (overrides walk-up discovery)",
+    }),
+    "sous-confd": Flags.string({
+      description: "Path to the conf.d drop-in layer directory (overrides <sousDir>/conf.d)",
+    }),
+    "non-interactive": nonInteractiveFlag(),
   };
 
   protected settings!: Settings;
@@ -48,29 +68,114 @@ export abstract class BaseCommand extends Command {
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
+  /**
+   * The real shell environment, snapshotted BEFORE the `.sous/` env files are
+   * injected into `process.env`. The variables layer needs it to tell a value
+   * the shell supplied from one an env file supplied; after injection the two
+   * are indistinguishable.
+   */
+  protected shellEnv: NodeJS.ProcessEnv = {};
+
+  /**
+   * Emits the decorative CLI header during init(). The default writes it to
+   * stdout. Commands whose stdout must stay machine-readable (the `sous config *`
+   * JSON commands) override this to route the banner to stderr.
+   */
+  protected emitHeader(): void {
+    header();
+  }
+
+  /**
+   * Line sink for error rendering during init()/catch(). Defaults to stdout (via
+   * `log`). Commands whose stdout must stay machine-readable (the `sous config *`
+   * JSON commands) override this to route error text to stderr, so a broken
+   * config never corrupts a piped stdout stream (e.g. `sous config show | jq`).
+   */
+  protected errorSink: (line: string) => void = log;
+
+  /**
+   * Whether this run may ask the user a question. One rule, shared by every
+   * prompt in sous: see `lib/interactive.ts`.
+   */
+  protected get interactive(): boolean {
+    return isInteractive();
+  }
+
   async init(): Promise<void> {
     await super.init();
-    header();
+    this.emitHeader();
+
+    // Read config-locating flags off argv directly. oclif's parse() runs inside
+    // each command's run(), which is too late: the config (and thus the env
+    // files) must be located before any variable resolution. `SOUS_*` env vars
+    // are read from the REAL environment here, BEFORE loadEnvFiles below, because
+    // they decide where `.env.local` itself lives.
+    const cwd = process.cwd();
+    const configFlag = blankToUndefined(readConfigFlagFromArgv(this.argv));
+    const sousConfigFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-config"));
+    const sousDirFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-dir"));
+    const sousConfdFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-confd"));
 
-    // Read --config off argv directly. oclif's parse() runs inside each command's
-    // run(), which is too late: env vars must be injected before any resolution.
-    const configFlag = readConfigFlagFromArgv(this.argv);
+    // Empty-string env vars are coerced to undefined and treated as unset. A
+    // bare `export SOUS_CONFD=` (or a variable that expands empty) must not turn
+    // cwd into the conf.d dir, and an empty SOUS_CONFIG/SOUS_DIR must not mask a
+    // lower-precedence source or disable walk-up discovery.
+    const sousConfdEnv = blankToUndefined(process.env.SOUS_CONFD);
+    const sousConfigEnv = blankToUndefined(process.env.SOUS_CONFIG);
+    const sousDirEnv = blankToUndefined(process.env.SOUS_DIR);
+
+    // conf.d directory: --sous-confd flag > SOUS_CONFD env > <sousDir>/conf.d.
+    const confdRaw = sousConfdFlag ?? sousConfdEnv;
+    const confDirOverride =
+      confdRaw !== undefined ? path.resolve(cwd, expandHome(confdRaw)) : undefined;
+
+    // Primary config, highest precedence first: --config/-c/--sous-config flag,
+    // SOUS_CONFIG env, --sous-dir flag, SOUS_DIR env. All resolve with the same
+    // rules as --config (a file, or a directory holding/containing a config).
+    // The paired source label is carried through to resolveConfigFlag so an
+    // error names the source the user actually set (not always `--config`).
+    const primaryCandidates: [string | undefined, string][] = [
+      [configFlag, "--config"],
+      [sousConfigFlag, "--sous-config"],
+      [sousConfigEnv, "SOUS_CONFIG"],
+      [sousDirFlag, "--sous-dir"],
+      [sousDirEnv, "SOUS_DIR"],
+    ];
+    const primary = primaryCandidates.find(([value]) => value !== undefined);
 
     let discovered: DiscoveredConfig | null;
 
-    if (configFlag !== undefined) {
+    if (primary !== undefined) {
+      const [primarySource, sourceLabel] = primary as [string, string];
       try {
-        discovered = resolveConfigFlag(configFlag);
+        discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
-        displayError(error instanceof Error ? error.message : String(error));
+        displayError(error instanceof Error ? error.message : String(error), this.errorSink);
         return this.exit(1);
       }
     } else {
-      discovered = discoverConfig();
+      discovered = discoverConfig(cwd, confDirOverride);
     }
 
     if (!discovered) {
-      displayErrorBlock(formatNotFoundMessage());
+      displayErrorBlock(formatNotFoundMessage(), this.errorSink);
+      return this.exit(1);
+    }
+
+    // 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.
+    this.shellEnv = { ...process.env };
+    loadEnvFiles(discovered.sousDir);
+
+    // Enumerated a second time now that the env files are loaded: `SOUS_HOME` is
+    // 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.
+    try {
+      discovered = refreshDiscoveredConfig(discovered);
+    } catch (error) {
+      displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
 
@@ -78,69 +183,70 @@ export abstract class BaseCommand extends Command {
     this.configContext = {
       sousDir: discovered.sousDir,
       configPath: discovered.configPath,
+      confDir: discovered.confDir,
+      layerPaths: discovered.layerPaths,
     };
 
-    // Inject .sous/.env.local and .sous/.env before anything resolves variables.
-    loadEnvFiles(discovered.sousDir);
+    // 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);
 
     try {
-      this.settings = await loadSettings(discovered.configPath);
+      this.settings = await loadSettings(discovered);
     } catch (error) {
-      displayErrorBlock(error instanceof Error ? error.message : String(error));
+      displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
   }
 
   /**
-   * Renders a configuration error as a plain, readable message instead of an
-   * oclif stack trace. The stack for a ConfigError points at Sous internals and
-   * tells the user nothing about the config mistake they need to fix.
+   * Renders any failure as a plain, readable message instead of an oclif stack
+   * trace: a config mistake, a mistyped command line, or a question sous could
+   * not ask. A stack pointing into oclif's parser or into sous's internals
+   * tells the user nothing about the mistake they need to fix, so it is printed
+   * only when `SOUS_DEBUG` asks for it. The rules live in
+   * `utils/command-errors.ts`, so every command in sous fails the same way.
    *
-   * Anything that is not a ConfigError falls through to oclif's normal handling,
-   * where a stack trace IS useful (it is a bug in Sous).
+   * A clean `this.exit()` and a command rendering JSON still belong to oclif,
+   * and fall through to its handling untouched.
    */
   protected async catch(error: Error & { exitCode?: number }): Promise<unknown> {
-    if (isConfigError(error)) {
-      displayErrorBlock(error.message);
-      return this.exit(1);
-    }
-    return super.catch(error);
+    const exitCode = await reportCommandError(this, error, { write: this.errorSink });
+    if (exitCode === undefined) return super.catch(error);
+    return this.exit(exitCode);
   }
 
   /**
-   * Resolves the active project from the --project flag or settings.defaultProject.
-   * Exits with an error if no project key is available or the key is not found.
+   * Re-runs discovery and reloads settings, committing the result onto this
+   * command only if everything loads cleanly (last-good semantics: a failed
+   * reload throws and leaves the previously loaded config untouched).
+   *
+   * Used by watch mode when a full-rebuild path (the config file, the conf.d
+   * directory, or the templating dir) changes: conf.d layer files can appear or
+   * disappear at runtime, so the ordered layer list must be rebuilt (and the
+   * duplicate-baseName check re-run) before settings reload.
    */
-  protected resolveProject(flagValue: string | undefined): RawProject & { key: string } {
-    const keys = Object.keys(this.settings.projects ?? {});
-    const key = flagValue ?? this.settings.defaultProject ?? (keys.length === 1 ? keys[0] : undefined);
-
-    if (!key) {
-      displayError(
-        "No project specified.\n" +
-          `  Config: ${this.configContext.configPath}\n` +
-          `  Projects defined: ${keys.length > 0 ? keys.join(", ") : "(none)"}\n` +
-          "  Use --project <key>, or set defaultProject in your config."
-      );
-      this.exit(1);
-    }
-
-    const project = this.settings.projects?.[key!];
+  protected async reloadDiscoveredConfig(): Promise<void> {
+    const refreshed = refreshDiscoveredConfig(this.discovered);
+    const reloaded = await loadSettings(refreshed);
 
-    if (!project) {
-      displayError(
-        `Project '${key}' not found in ${this.configContext.configPath}\n` +
-          `  Projects defined: ${keys.length > 0 ? keys.join(", ") : "(none)"}`
-      );
-      this.exit(1);
-    }
-
-    return { ...project!, key: key! };
+    // Commit only after a clean load, so a broken edit keeps the last-good config.
+    this.discovered = refreshed;
+    this.configContext = {
+      sousDir: refreshed.sousDir,
+      configPath: refreshed.configPath,
+      confDir: refreshed.confDir,
+      layerPaths: refreshed.layerPaths,
+    };
+    this.settings = reloaded;
   }
 
-  /** Number of projects defined in the active config. */
-  protected get projectCount(): number {
-    return Object.keys(this.settings.projects ?? {}).length;
+  /**
+   * Human-readable label for the configured project: the config's `name` when
+   * set, otherwise the basename of the directory holding `.sous/`.
+   */
+  protected get projectLabel(): string {
+    return this.settings.name ?? path.basename(path.dirname(this.configContext.sousDir));
   }
 }
 
@@ -148,6 +254,9 @@ export abstract class BaseCommand extends Command {
  * Pulls the value of `--config` / `-c` out of a raw argv array.
  * Supports `--config X`, `--config=X`, `-c X`, and `-cX`.
  *
+ * Scanning stops at a bare `--`: anything after it belongs to a launched tool
+ * (see `launch`'s pass-through args), never to sous.
+ *
  * @param argv - Raw arguments (oclif's `this.argv`, i.e. argv minus the command).
  * @returns The flag value, or undefined when the flag is absent.
  */
@@ -155,9 +264,53 @@ export function readConfigFlagFromArgv(argv: string[]): string | undefined {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
 
+    if (arg === "--") return undefined;
     if (arg === "--config" || arg === "-c") return argv[i + 1];
     if (arg.startsWith("--config=")) return arg.slice("--config=".length);
     if (arg.startsWith("-c") && arg.length > 2 && !arg.startsWith("-c-")) return arg.slice(2);
   }
   return undefined;
 }
+
+/**
+ * Coerces an empty or whitespace-only string to `undefined`, passing every other
+ * value through unchanged.
+ *
+ * Config-locating inputs (`SOUS_CONFIG`, `SOUS_DIR`, `SOUS_CONFD`, and their flag
+ * aliases) must treat an empty value as "unset", never as a real path. A bare
+ * `export SOUS_CONFD=` (or a variable that expands empty) would otherwise resolve
+ * to cwd and load every file in the working directory as a config layer; an empty
+ * `SOUS_CONFIG` / `SOUS_DIR` would mask a lower-precedence source and disable
+ * walk-up discovery. Normalising to `undefined` up front lets the plain `??`
+ * precedence chain fall through correctly.
+ */
+export function blankToUndefined(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return value.trim() === "" ? undefined : value;
+}
+
+/**
+ * Pulls the value of a long-only flag (`--<flagName> VALUE` or
+ * `--<flagName>=VALUE`) out of a raw argv array. Used for the `--sous-config`,
+ * `--sous-dir` and `--sous-confd` aliases, which (like `--config`) must be
+ * read before oclif's parse() so the config is located before env files load.
+ *
+ * Scanning stops at a bare `--` for the same reason as `readConfigFlagFromArgv`:
+ * anything after it belongs to a launched tool, never to sous.
+ *
+ * @param argv - Raw arguments (oclif's `this.argv`).
+ * @param flagName - The flag name without leading dashes (e.g. `sous-dir`).
+ * @returns The flag value, or undefined when the flag is absent (or has no value).
+ */
+export function readLongFlagFromArgv(argv: string[], flagName: string): string | undefined {
+  const long = `--${flagName}`;
+  const eq = `${long}=`;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--") return undefined;
+    if (arg === long) return argv[i + 1];
+    if (arg.startsWith(eq)) return arg.slice(eq.length);
+  }
+  return undefined;
+}

package/src/commands/build.ts

@@ -1,15 +1,30 @@
-import path from "node:path";
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
 import { BuildService } from "../lib/build-service.js";
 import { PidService } from "../lib/pid-service.js";
-import { CLI_ROOT, loadSettings, resolveRootScope, resolveScope, resolveWatchConfig } from "../lib/settings.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 { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
 import type { WatchHandle } from "../lib/watch-service.js";
 import { WatchService } from "../lib/watch-service.js";
-import { footer, heading, log, showCommandVars } from "../utils/formatting.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  log,
+  paragraph,
+  showCommandVars,
+  warning,
+} from "../utils/formatting.js";
 
 export default class Build extends BaseCommand {
-  static description = "Compile outputs and prune stale files (compile + prune)";
+  static description =
+    "Compile this project's outputs and remove the ones its config no longer produces";
 
   static examples = [
     "<%= config.bin %> build",
@@ -50,10 +65,8 @@ export default class Build extends BaseCommand {
   async run(): Promise<void> {
     const { flags } = await this.parse(Build);
 
-    const project = this.resolveProject(flags.project);
-
     showCommandVars({
-      Project: project.name,
+      Project: this.projectLabel,
       Config: this.configContext.configPath,
       Rebuild: flags.rebuild,
       "Dry Run": flags["dry-run"],
@@ -61,6 +74,22 @@ export default class Build extends BaseCommand {
       "No Prune": flags["no-prune"],
     });
 
+    // A linked repository is read from a working copy instead of a published
+    // version, so it is announced every single time; a build that silently
+    // produced something different would be far worse than a noisy one.
+    const linked = describeLinkedRepos(this.configContext.sousDir);
+    if (linked.length > 0) warning(linked.join("\n"));
+
+    const repositories = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    if (!flags["dry-run"] && !flags["no-compile"]) {
+      await this.prepareRepositories(repositories);
+    }
+
     heading("Building");
 
     const buildOptions = {
@@ -73,7 +102,7 @@ export default class Build extends BaseCommand {
     };
 
     const buildService = new BuildService();
-    const success = await buildService.build(project.key, this.settings, buildOptions);
+    const success = await buildService.build(this.settings, buildOptions);
 
     footer();
 
@@ -82,17 +111,12 @@ export default class Build extends BaseCommand {
     }
 
     if (flags.watch) {
-      const configPath = this.configContext.configPath;
-
       const rootScope = resolveRootScope(this.settings, this.configContext);
-      const projectScope = resolveScope(project._vars ?? {}, rootScope);
 
       // --- PID file enforcement ---
       const pidService = new PidService();
-      const pidFilePath = pidService.getFilePath(project.key, projectScope, this.projectCount);
-      await pidService.acquire(pidFilePath, project.key);
-
-      let isRebuilding = false;
+      const pidFilePath = pidService.getFilePath(rootScope);
+      await pidService.acquire(pidFilePath, this.projectLabel);
 
       const cleanup = async (watchHandle?: WatchHandle) => {
         if (process.stdin.isTTY) {
@@ -108,68 +132,47 @@ export default class Build extends BaseCommand {
 
       const watchService = new WatchService();
 
-      /**
-       * Builds a WatchConfig from current settings, injecting the config file path
-       * and the templating directory into fullRebuildPaths.
-       */
-      const buildWatchConfig = () => {
-        const currentRootScope = resolveRootScope(this.settings, this.configContext);
-        const config = resolveWatchConfig(project, currentRootScope, project.key);
-        config.fullRebuildPaths = [
-          ...(config.fullRebuildPaths ?? []),
-          configPath,
-          path.join(CLI_ROOT, "src", "templating"),
-        ];
-        return config;
-      };
-
-      /** Starts a new watcher and updates the shared handle reference. */
-      const startWatcher = (handle: { current: WatchHandle | null }) => {
-        const watchConfig = buildWatchConfig();
-        handle.current = watchService.watch(watchConfig, async (event) => {
-          if (event.type === "partial") {
-            if (isRebuilding) return;
-            isRebuilding = true;
-            log(`\nChange detected: ${event.filePath}`);
-            heading("Rebuilding");
-            await buildService.build(project.key, this.settings, {
-              ...buildOptions,
-              // --rebuild means full clean build on every trigger; skip partial optimisation
-              changedFile: buildOptions.rebuild ? undefined : event.filePath,
-            });
-            footer();
-            isRebuilding = false;
-          } else {
-            // Full rebuild: stop current watcher, reload settings, restart
-            if (isRebuilding) return;
-            isRebuilding = true;
-            log(`\nConfig changed (${event.filePath}), reloading settings and restarting watcher...`);
-            await handle.current!.stop();
-
-            this.settings = await loadSettings(configPath);
-
-            heading("Rebuilding");
-            await buildService.build(project.key, this.settings, buildOptions);
-            footer();
-            isRebuilding = false;
-
-            startWatcher(handle);
-          }
+      // Reruns compile + prune with the command's current settings. Called for
+      // partial rebuilds (with the changed file) and, after a clean reload, for
+      // full rebuilds. Owns the "Rebuilding" heading/footer.
+      const rebuild = async (changedFile?: string) => {
+        heading("Rebuilding");
+        await buildService.build(this.settings, {
+          ...buildOptions,
+          // --rebuild means full clean build on every trigger; skip partial optimisation
+          changedFile: buildOptions.rebuild ? undefined : changedFile,
         });
+        footer();
       };
 
-      const handle: { current: WatchHandle | null } = { current: null };
-      startWatcher(handle);
+      const { handle, triggerFullRebuild } = startConfigReloadWatch({
+        watchService,
+        buildWatchConfig: () => buildReloadWatchConfig(this.settings, this.configContext),
+        rebuild,
+        reloadConfig: () => this.reloadDiscoveredConfig(),
+      });
 
-      const triggerFullRebuild = async (reason: string) => {
-        if (isRebuilding) return;
-        isRebuilding = true;
-        log(`\n${reason}`);
-        heading("Rebuilding");
-        await buildService.build(project.key, this.settings, buildOptions);
-        footer();
-        isRebuilding = false;
-      };
+      // Watch mode polls upstream for the repositories that prefer a newer
+      // in-range version. The poll is cheap (one index request per repository)
+      // and a failure never breaks the watch; the last good answer stands.
+      const pollSeconds = resolveStoreSettings(this.settings).watchPollSeconds;
+      if (pollSeconds > 0) {
+        const poll = setInterval(() => {
+          void repositories
+            .checkUpstream()
+            .then(async (report) => {
+              if (report.updated.length === 0) return;
+              for (const change of report.updated) {
+                paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
+              }
+              await triggerFullRebuild("A newer recipe version arrived upstream.");
+            })
+            .catch(() => {
+              // checkUpstream already reports its own failures as warnings.
+            });
+        }, pollSeconds * 1000);
+        poll.unref();
+      }
 
       // Display the interactive prompt
       log("[ Press Q to quit  |  any other key: rebuild ]");
@@ -193,4 +196,78 @@ 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();
+  }
 }