@sous-io/sous 0.2.30 → 0.2.31

package/README.md

@@ -40,6 +40,18 @@ output. When the two versions differ, one line on standard error names the versi
 to; `--verbose` announces every hand-off and adds where both installs are. Set
 `SOUS_NO_DELEGATE=1` to run the copy you invoked instead.
 
+To update, run `sous update`. It updates the global install, the project's own install, or both
+(whichever this directory has), through the package manager that installed each one (npm, pnpm or
+Yarn), and asks before each one. By default each install moves to the newest version in its current
+major; `--major` goes past it, `--version <version|range|tag>` picks one (a downgrade included),
+`--global` and `--project` narrow the run, `--yes` answers every question and `--dry-run` only
+prints the plan. After a project update, the new copy builds the project, so its lockfile moves to
+the new version too.
+
+```bash
+sous update --dry-run     # show what would be installed where, and install nothing
+```
+
 Or run it from a clone (useful when developing sous itself):
 
 ```bash

package/docs/markdown/README.md

@@ -59,6 +59,58 @@ $ SOUS_NO_DELEGATE=1 sous --version
 v0.3.0
 ```
 
+### Updating
+
+`sous update` moves each copy of sous to a newer version (or one you choose) through the package
+manager that installed it, so you never need to remember which one that was or its syntax:
+
+- **Outside a project**, or in a project that does not install sous, it updates the global install.
+  Each of npm, pnpm and Yarn classic is asked where its global packages live, and every global
+  install found is updated with its own manager (`npm i -g`, `pnpm add -g`, `yarn global add`).
+- **In a project that installs sous**, it updates the project's install with the project's own
+  manager (`npm i -D -E`, `pnpm add -D -E`, `yarn add -D -E`), which pins the exact version in
+  `package.json` and updates the lockfile. A dependency declared under `dependencies` stays there.
+  It updates the global install as well when there is one. A Yarn Plug'n'Play project, which has
+  no `node_modules`, counts as installing sous when its `package.json` declares it and a `.pnp.cjs`
+  sits beside it or above it; the installed version is read from `yarn.lock`.
+- **After a project update**, the newly installed copy builds the project, so
+  `.sous/sous.lock.json` pins the core recipe at the new version. Under Yarn Plug'n'Play, Yarn
+  runs that build (`yarn run --binaries-only sous build`). `--no-build` skips it.
+
+Under Yarn Plug'n'Play, sous runs only from a copy Yarn has unpacked; from inside Yarn's zip cache
+it fails with `EBADF: bad file descriptor`. Unpack it in `package.json`, then run `yarn install`:
+
+```json
+"dependenciesMeta": { "@sous-io/sous": { "unplugged": true } }
+```
+
+`update` always runs in the copy you invoked, never handed off to the project's own; a project copy
+may be too old to have the command. A project config this copy cannot load (one written for a newer
+sous, say) is a warning rather than a stop, since installing a newer copy may be the fix.
+
+Every plan is worked out before anything is installed, and each install prints its plan and asks
+its own question. Each is judged on its own version:
+
+- By default, the newest published version in the install's current major (for a 0.x install,
+  anything below 1.0.0). A default run never downgrades.
+- `--major`: the newest published version, whatever its major.
+- `--version <version|range|tag>`: exactly that version, the newest one in that range, or the one a
+  dist-tag such as `next` points at. This is how you downgrade, and the plan says when it is one.
+- `--prerelease` counts prerelease versions, and is on by default when the installed version is a
+  prerelease; `--no-prerelease` switches it off.
+- `--global` or `--project` updates only that install; `-y, --yes` answers every question;
+  `--dry-run` prints the plans, with the command each would run, and installs nothing.
+
+A copy run through `npx`, or one managed by Volta or by a manager sous does not drive, is listed
+with the command to run by hand, and the rest are still updated. A package manager's own failure
+is printed as the manager reported it; sous never retries with `sudo`.
+
+```term
+$ sous update --dry-run
+// every install's plan, and nothing installed
+$ sous update --global --yes
+```
+
 ## Where to look
 
 - Watch the [animated introduction](../) for the full pitch

package/docs/markdown/_sidebar.md

@@ -29,3 +29,4 @@
   - [0008: One ref parser, told where the ref came from](adrs/0008-one-ref-parser.md)
   - [0009: One whole build, everywhere](adrs/0009-whole-build-everywhere.md)
   - [0010: The index describes each version's dependencies and questions](adrs/0010-index-describes-recipes.md)
+  - [0011: `sous update` updates sous through the package managers](adrs/0011-self-update.md)

package/docs/markdown/commands.md

@@ -146,6 +146,27 @@ so it works offline. `--limit <n>` sets how many matches to show, defaulting to
 only installed recipes and adds an Installed column. Also spelled `sous repo search`.
 Example: `sous search task --limit 50`
 
+### `sous update`
+Updates sous itself: the global install, this project's own install, or both, each through the package manager
+that installed it. It works outside a project too, and it always runs in the copy you invoked, never handed off
+to the project's own. Every plan is printed before anything is installed, and each install asks its own
+question. After a project update the new copy builds the project, so the lockfile pins the core recipe at the new
+version. A project config this copy cannot load is one warning, not a stop. Takes `-y, --yes` and `--dry-run`
+(which also prints the command each install would run). See [Updating](README.md#updating).
+
+- `--major`: install the newest published version, whatever its major. By default each install moves to the
+  newest version in its current major, and never down.
+- `--version <version|range|tag>`: install exactly this version, the newest in this range, or the one this
+  dist-tag names. This is how you downgrade.
+- `--prerelease`, `--no-prerelease`: count prerelease versions as candidates, or not. On by default when the
+  installed version is a prerelease. `--pre` is the same flag.
+- `--global`, `--project`: update only that install.
+- `--no-build`: update the project install without building the project afterwards.
+
+`--major` and `--version` exclude each other, and so do `--global` and `--project`.
+
+Example: `sous update --version next --dry-run`
+
 ### `sous help [COMMAND]`
 Prints the help for sous, or for one command or topic. Works from any directory, including one with no config
 above it. Example: `sous help repo add`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -60,6 +60,7 @@
     "jsonc-parser": "^3.3.1",
     "liquidjs": "^10.25.0",
     "minimatch": "^10.2.4",
+    "package-manager-detector": "^1.8.0",
     "semver": "^7.8.5",
     "tiktoken": "^1.0.22",
     "tsx": "^4",

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

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

package/src/base-command.ts

@@ -88,6 +88,20 @@ export abstract class BaseCommand extends Command {
    */
   static requiresConfig = true;
 
+  /**
+   * Whether a config that cannot be located or loaded stops this command. It
+   * is false on every command but the one whose job may be to repair that
+   * config: `sous update` installs a sous that may understand a config this
+   * copy rejects (one written for a newer version, say). When true, a failure
+   * to locate or load the config becomes one warning, naming the config and
+   * quoting the error, and the run carries on with no config adopted:
+   * `hasConfig` is false, the env files are not applied, and `rejectedConfig`
+   * says where the config that failed to load was, when discovery found it.
+   * It only changes what a FAILURE does; finding no config at all is still
+   * decided by `requiresConfig`.
+   */
+  static toleratesConfigErrors = false;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
@@ -103,6 +117,13 @@ export abstract class BaseCommand extends Command {
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
+  /**
+   * The config discovery found but could not load, on a command that
+   * `toleratesConfigErrors`. Undefined when the config loaded, when there was
+   * none, or when the failure came before any config file was identified.
+   */
+  protected rejectedConfig?: { configPath: string; sousDir: string };
+
   /**
    * The real shell environment, snapshotted BEFORE the `.sous/` env files are
    * injected into `process.env`. The variables layer needs it to tell a value
@@ -177,7 +198,7 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
-    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+    const { requiresConfig, toleratesConfigErrors } = this.constructor as typeof BaseCommand;
 
     this.configLocator = {
       cwd,
@@ -195,6 +216,12 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        if (toleratesConfigErrors) {
+          return this.warnConfigNotLoaded(
+            error,
+            `the project config at ${this.configLocator.primary?.value} (named by ${sourceLabel})`
+          );
+        }
         // 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;
@@ -202,7 +229,12 @@ export abstract class BaseCommand extends Command {
         return this.exit(1);
       }
     } else {
-      discovered = discoverConfig(cwd, confDirOverride);
+      try {
+        discovered = discoverConfig(cwd, confDirOverride);
+      } catch (error) {
+        if (!toleratesConfigErrors) throw error;
+        return this.warnConfigNotLoaded(error, `the project config it found searching up from ${cwd}`);
+      }
     }
 
     if (!discovered) {
@@ -243,6 +275,7 @@ export abstract class BaseCommand extends Command {
     try {
       refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(discovered, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
@@ -262,11 +295,51 @@ export abstract class BaseCommand extends Command {
     try {
       this.settings = await loadSettings(refreshed);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(refreshed, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
   }
 
+  /** The `toleratesConfigErrors` setting of the running command's class. */
+  private get toleratesConfigErrors(): boolean {
+    return (this.constructor as typeof BaseCommand).toleratesConfigErrors;
+  }
+
+  /**
+   * Undoes a config adoption that failed on a command that tolerates it: the
+   * env files it injected are taken back out of `process.env`, nothing is left
+   * adopted, and one warning says what happened.
+   */
+  private rejectConfig(discovered: DiscoveredConfig, error: unknown): void {
+    for (const name of Object.keys(process.env)) {
+      if (!(name in this.shellEnv)) delete process.env[name];
+    }
+    this.shellEnv = {};
+    this.discovered = undefined as unknown as DiscoveredConfig;
+    this.configContext = undefined as unknown as ConfigContext;
+    this.rejectedConfig = { configPath: discovered.configPath, sousDir: discovered.sousDir };
+    this.warnConfigNotLoaded(error, `the project config at ${discovered.configPath}`);
+  }
+
+  /**
+   * The one warning a command that tolerates config errors prints in place of
+   * failing.
+   *
+   * @param error - What locating or loading the config threw.
+   * @param config - Which config: its file, or where it was looked for.
+   */
+  private warnConfigNotLoaded(error: unknown, config: string): void {
+    const message = error instanceof Error ? error.message : String(error);
+    warning(
+      `Sous could not load ${config}, so this command carries on without it.\n` +
+        "\n" +
+        "The error was:\n" +
+        message,
+      this.errorSink
+    );
+  }
+
   /**
    * 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

package/src/commands/update.ts

@@ -0,0 +1,178 @@
+/**
+ * `sous update` moves sous itself to a newer (or a chosen) version, for the
+ * global install, the project's own install, or both, through whichever
+ * package manager owns each one (sous-io/sous#135).
+ *
+ *     sous update
+ *     sous update --global
+ *     sous update --major
+ *     sous update --version 0.2.18
+ *     sous update --dry-run
+ *
+ * It runs outside a project as readily as inside one, so it opts out of the
+ * config requirement, as `sous init` does. `bin/run.js` never hands this
+ * command to a project's own copy: updating the copy that was invoked is the
+ * point. The flow itself lives in `lib/self-update/run.ts`; this class turns
+ * the flags into its options and decides the exit code.
+ */
+
+import path from "node:path";
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../base-command.js";
+import { SOUS_DIR_NAME, findConfigInSousDir } from "../lib/config-discovery.js";
+import { ConfigError, isConfigError } from "../lib/errors.js";
+import { CLI_ROOT } from "../lib/package-info.js";
+import { registryUrl, runSelfUpdate } from "../lib/self-update/run.js";
+import type { UpdateScope, VersionRequest } from "../lib/self-update/index.js";
+import { confirmationFlag } from "../utils/flags.js";
+import { footer, showCommandVars } from "../utils/formatting.js";
+
+export default class Update extends BaseCommand {
+  static description =
+    "Update sous itself, globally and in this project, through the package manager that installed each copy";
+
+  /** This command updates sous wherever it is installed; a project config is optional. */
+  static override requiresConfig = false;
+
+  /**
+   * A config this copy cannot load (one written for a newer sous, say) is the
+   * very thing an update may fix, so it is a warning here rather than a stop.
+   */
+  static override toleratesConfigErrors = true;
+
+  static examples = [
+    "<%= config.bin %> update",
+    "<%= config.bin %> update --global",
+    "<%= config.bin %> update --major",
+    "<%= config.bin %> update --version 0.2.18",
+    "<%= config.bin %> update --version next",
+    "<%= config.bin %> update --dry-run",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    major: Flags.boolean({
+      description: "Install the newest published version, whatever its major version",
+      default: false,
+      exclusive: ["version"],
+    }),
+    version: Flags.string({
+      description: "Install this version, the newest version in this range, or the version this dist-tag names",
+      exclusive: ["major"],
+    }),
+    prerelease: Flags.boolean({
+      description:
+        "Count prerelease versions as candidates; on by default when the installed version is a prerelease",
+      allowNo: true,
+      aliases: ["pre"],
+    }),
+    global: Flags.boolean({
+      description: "Update only the global install",
+      default: false,
+      exclusive: ["project"],
+    }),
+    project: Flags.boolean({
+      description: "Update only this project's own install",
+      default: false,
+      exclusive: ["global"],
+    }),
+    yes: confirmationFlag(),
+    "dry-run": Flags.boolean({
+      description: "Print every install's plan without installing anything",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Update the project install without building the project afterwards",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Update);
+    const dryRun = flags["dry-run"];
+    const request: VersionRequest =
+      flags.version !== undefined
+        ? { kind: "spec", spec: flags.version }
+        : flags.major
+          ? { kind: "major" }
+          : { kind: "default" };
+    const only: UpdateScope | undefined = flags.global
+      ? "global"
+      : flags.project
+        ? "project"
+        : undefined;
+
+    showCommandVars({
+      Directory: this.configLocator.cwd,
+      Installs: only === undefined ? "global and project" : `${only} only`,
+      Version: describeRequest(request),
+      Prereleases:
+        flags.prerelease === undefined
+          ? "counted when the installed version is one"
+          : flags.prerelease
+            ? "counted"
+            : "not counted",
+      Registry: registryUrl(),
+      "Dry Run": dryRun,
+    });
+
+    const outcome = await runSelfUpdate({
+      cwd: this.configLocator.cwd,
+      ownRoot: CLI_ROOT,
+      request,
+      ...(flags.prerelease === undefined ? {} : { prerelease: flags.prerelease }),
+      ...(only === undefined ? {} : { only }),
+      dryRun,
+      yes: flags.yes,
+      interactive: this.interactive,
+      build: !flags["no-build"],
+      buildDirFor: (projectRoot) => this.buildDirFor(projectRoot),
+    });
+
+    footer();
+
+    if (outcome.failed) {
+      throw new ConfigError(
+        "Not every step of the update succeeded; the summary above lists what completed and what failed."
+      );
+    }
+  }
+
+  /**
+   * Where a build after a project update runs: the directory of the config
+   * discovery found, when it lies inside the project that was updated, and
+   * otherwise the project root when its own `.sous/` holds a primary config.
+   * A config this copy could not load counts as found: the new copy may
+   * understand it, and its build is where any real problem is reported.
+   * Undefined means the project has no sous config, so nothing is built.
+   */
+  private buildDirFor(projectRoot: string): string | undefined {
+    const found = this.hasConfig ? this.discovered.sousDir : this.rejectedConfig?.sousDir;
+    if (found !== undefined) {
+      const configDir = path.dirname(found);
+      const relative = path.relative(projectRoot, configDir);
+      if (!relative.startsWith("..") && !path.isAbsolute(relative)) return configDir;
+    }
+    return holdsPrimaryConfig(path.join(projectRoot, SOUS_DIR_NAME)) ? projectRoot : undefined;
+  }
+}
+
+/**
+ * Whether a `.sous/` directory holds a primary config. Holding several is
+ * still holding one: the build that follows reports that mistake itself.
+ */
+function holdsPrimaryConfig(sousDir: string): boolean {
+  try {
+    return findConfigInSousDir(sousDir) !== null;
+  } catch (error) {
+    if (isConfigError(error)) return true;
+    throw error;
+  }
+}
+
+/** The version request, as the opening block says it. */
+function describeRequest(request: VersionRequest): string {
+  if (request.kind === "default") return "the newest in each install's major version";
+  if (request.kind === "major") return "the newest published, whatever its major version";
+  return request.spec;
+}

package/src/lib/project-install.d.mts

@@ -18,7 +18,11 @@ export type HandoffPlan =
 
 export function isEnvFlagOn(value: string | undefined): boolean;
 export function binEntryOf(pkg: unknown): string | undefined;
+export function readPackageJson(dir: string): Record<string, unknown> | undefined;
 export function findProjectInstall(startDir: string, ownRoot: string): ProjectInstall | undefined;
+export function findProjectCopy(startDir: string): string | undefined;
+export function realpathOr(p: string): string;
+export function describeInstall(candidate: string, ownRoot: string): ProjectInstall | undefined;
 export function formatHandoffNotice(input: {
   install: Extract<ProjectInstall, { same: false }>;
   ownVersion: string;

package/src/lib/project-install.mjs

@@ -27,6 +27,10 @@
  *   - Anything unreadable or ambiguous means "run the copy that was invoked".
  *     A hand-off is a convenience; a refusal to run is not.
  *   - `SOUS_NO_DELEGATE` (anything but 0/false/no/off) runs the invoked copy.
+ *   - `sous update` runs the invoked copy: updating the copy that was invoked
+ *     is its job, and a project copy may be too old to have the command. The
+ *     command word is the first entry on the command line that is not a flag,
+ *     so `sous subscription update` still hands off.
  *   - The notice goes to stderr, so piped stdout stays clean. It prints when
  *     the two versions differ, and on every hand-off under `SOUS_DEBUG` or
  *     with `--verbose` anywhere on the command line. Plain, it is one line
@@ -50,6 +54,20 @@ export const DEBUG_ENV = "SOUS_DEBUG";
 /** The flag that makes the notice say where both installs are. */
 export const VERBOSE_FLAG = "--verbose";
 
+/** The command that always runs in the copy that was invoked. */
+export const SELF_UPDATE_COMMAND = "update";
+
+/**
+ * The command word on a command line: its first entry that does not start
+ * with `-`, or undefined when every entry is a flag.
+ *
+ * commandWordOf(["--verbose", "update", "--yes"]) -> "update"
+ * commandWordOf(["subscription", "update"]) -> "subscription"
+ */
+export function commandWordOf(argv) {
+  return argv.find((arg) => !arg.startsWith("-"));
+}
+
 /**
  * Whether an on/off environment variable is on: set to anything but an empty
  * string, `0`, `false`, `no` or `off` (case-insensitive, whitespace trimmed).
@@ -60,10 +78,10 @@ export function isEnvFlagOn(value) {
 }
 
 /**
- * Reads a package.json, returning the parsed object or undefined for a file
- * that is missing, unreadable or not JSON.
+ * Reads the package.json in `dir`, returning the parsed object or undefined
+ * for a file that is missing, unreadable or not JSON.
  */
-function readPackageJson(dir) {
+export function readPackageJson(dir) {
   try {
     return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
   } catch {
@@ -103,19 +121,32 @@ export function binEntryOf(pkg) {
  * older one further up would be a guess.
  */
 export function findProjectInstall(startDir, ownRoot) {
+  const candidate = findProjectCopy(startDir);
+  return candidate === undefined ? undefined : describeInstall(candidate, ownRoot);
+}
+
+/**
+ * Looks up from `startDir` for the nearest `node_modules/@sous-io/sous` that
+ * holds a package.json, and returns that path as found, WITHOUT resolving
+ * symlinks (pnpm links it into its own store, so only the unresolved path says
+ * which project holds it). Undefined when no ancestor holds one.
+ */
+export function findProjectCopy(startDir) {
   let dir = path.resolve(startDir);
   for (;;) {
     const candidate = path.join(dir, "node_modules", ...PACKAGE_NAME.split("/"));
-    if (fs.existsSync(path.join(candidate, "package.json"))) {
-      return describeInstall(candidate, ownRoot);
-    }
+    if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) return undefined;
     dir = parent;
   }
 }
 
-function realpathOr(p) {
+/**
+ * The real path of `p`, or `p` resolved when it cannot be read (it does not
+ * exist, or a link in it is broken).
+ */
+export function realpathOr(p) {
   try {
     return fs.realpathSync(p);
   } catch {
@@ -123,7 +154,13 @@ function realpathOr(p) {
   }
 }
 
-function describeInstall(candidate, ownRoot) {
+/**
+ * Describes the copy of the package at `candidate` the way `findProjectInstall`
+ * does: `{ same: true, root }` when it is `ownRoot`, compared by real path,
+ * `{ same: false, root, version, bin }` for a usable other copy, and undefined
+ * for one that is not usable.
+ */
+export function describeInstall(candidate, ownRoot) {
   const root = realpathOr(candidate);
   if (root === realpathOr(ownRoot)) return { same: true, root };
   const pkg = readPackageJson(root);
@@ -162,6 +199,7 @@ export function formatHandoffNotice({ install, ownVersion, ownRoot, verbose }) {
  */
 export function planHandoff({ cwd, ownRoot, env, argv = [] }) {
   if (isEnvFlagOn(env[NO_DELEGATE_ENV])) return { kind: "run-self" };
+  if (commandWordOf(argv) === SELF_UPDATE_COMMAND) return { kind: "run-self" };
   const install = findProjectInstall(cwd, ownRoot);
   if (!install || install.same) return { kind: "run-self" };
 

package/src/lib/repos/providers/http.ts

@@ -38,15 +38,48 @@ export type FetchTextOptions = {
   label?: string;
   /** Cancels the request, for a caller that will not wait past a deadline. */
   signal?: AbortSignal;
+  /** The `Accept` header to send. Defaults to `application/json`. */
+  accept?: string;
+  /**
+   * The lines that explain a failed status to the reader. Defaults to the
+   * hints about a sous repository (a missing index, a private repository), so
+   * a caller fetching anything else names its own.
+   */
+  statusHints?: (status: number) => string[];
 };
 
+/**
+ * What a failed status usually means when the URL names a file in a sous
+ * repository: the default for `FetchTextOptions.statusHints`.
+ *
+ * @param status - The HTTP status the server answered with.
+ */
+function repositoryStatusHints(status: number): string[] {
+  if (status === 404) {
+    return [
+      "  Either the repository publishes no sous index yet, or the URL names a " +
+        "repository that does not exist.",
+    ];
+  }
+  if (status === 401 || status === 403) {
+    return [
+      "  The repository is private or the request was not authorized. Sous uses a " +
+        "token from the environment, or from the provider's command line tool when " +
+        "one is installed and signed in.",
+    ];
+  }
+  return [];
+}
+
 /**
  * GETs a URL and returns its body as text. Any non-2xx response, or a transport
  * failure, becomes a ConfigError that names the URL and the status, and says
- * plainly what a 404 or a 401 usually means for a sous repository.
+ * plainly what the status usually means (for a sous repository, unless the
+ * caller passes `statusHints`).
  *
  * @param url - The absolute HTTPS URL to fetch.
- * @param options - Bearer token, fetch implementation and error label.
+ * @param options - Bearer token, fetch implementation, error label, `Accept`
+ *   header and status hints.
  */
 export async function fetchText(
   url: string,
@@ -62,7 +95,7 @@ export async function fetchText(
     );
   }
 
-  const headers: Record<string, string> = { Accept: "application/json" };
+  const headers: Record<string, string> = { Accept: options.accept ?? "application/json" };
   if (options.token !== undefined && options.token.length > 0) {
     headers["Authorization"] = `Bearer ${options.token}`;
   }
@@ -85,19 +118,7 @@ export async function fetchText(
       `Sous could not fetch the ${label} from ${url}.`,
       `  The server answered ${response.status} ${response.statusText}.`,
     ];
-    if (response.status === 404) {
-      lines.push(
-        "  Either the repository publishes no sous index yet, or the URL names a " +
-          "repository that does not exist."
-      );
-    }
-    if (response.status === 401 || response.status === 403) {
-      lines.push(
-        "  The repository is private or the request was not authorized. Sous uses a " +
-          "token from the environment, or from the provider's command line tool when " +
-          "one is installed and signed in."
-      );
-    }
+    lines.push(...(options.statusHints ?? repositoryStatusHints)(response.status));
     throw new ConfigError(lines.join("\n"));
   }
 

package/src/lib/self-update/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The self-update layer: which copies of sous are installed, which version
+ * each should move to, and the package manager command that moves it.
+ *
+ * Import from here rather than from the individual modules. Nothing exported
+ * here installs anything; `run.ts`, imported on its own by `sous update`, is
+ * the flow that runs the commands the plans name.
+ */
+
+export * from "./versions.js";
+export * from "./registry.js";
+export * from "./managers.js";
+export * from "./installs.js";
+export * from "./plan.js";