@sous-io/sous 0.2.29 → 0.2.31

package/src/commands/recipe/show.ts

@@ -2,27 +2,41 @@
  * `sous recipe show <ref>`.
  *
  * Shows one recipe in full: where it is published, every version it publishes,
- * what the version this project would use depends on, the questions it asks,
- * and where its files land in this project. It reads only what sous already has
- * on disk: the repository's cached index, the project's lockfile, and the
- * recipe's own files when they are in the store or a linked working copy.
- * `--latest` reads the repository's index from upstream instead, saving
- * nothing, and `--installed` looks the ref up among installed recipes only.
+ * what the version this project would use depends on and how each dependency is
+ * declared, everything subscribing to it would install, every question that
+ * would ask, and where its files land in this project. It reads only what sous
+ * already has on disk: the repository's cached index, the project's lockfile,
+ * and the recipe's own files when they are in the store or a linked working
+ * copy. The index describes each version's dependencies and questions, so a
+ * recipe nothing has installed is described as fully as one in the store, its
+ * files excepted. `--latest` reads the repository's index from upstream
+ * instead, saving nothing, and `--installed` looks the ref up among installed
+ * recipes only.
  */
 
 import { Args } from "@oclif/core";
+import semver from "semver";
 import { BaseCommand } from "../../base-command.js";
 import { resolveRootScope } from "../../lib/settings.js";
-import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import {
+  subscriptionServiceFor,
+  type SubscriptionPreview,
+  type SubscriptionService,
+} from "../../lib/repos/subscription-service.js";
 import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
 import {
   describeInstalled,
   describeRecipe,
+  type CatalogInputs,
   type RecipeContentListing,
   type RecipeDependencyListing,
-  type RecipeVariableListing,
+  type RecipeDetail,
   type RecipeVersionListing,
 } from "../../lib/repos/catalog.js";
+import { PROJECT_REQUESTER } from "../../lib/repos/resolver.js";
+import { describeDeclaration, describeDependencyKind } from "../../lib/repos/declarations.js";
+import { formatQuestionPlan } from "../../lib/vars/question-plan.js";
+import { describeError } from "../../lib/repos/release/validate.js";
 import {
   INDENT,
   describeIndexSource,
@@ -61,14 +75,19 @@ const DEPENDENCY_COLUMNS: TableColumn[] = [
   { key: "kind", header: "Kind", overflow: "wrap", priority: "medium", minWidth: 16 },
 ];
 
-/** The columns the variable listing shows. */
-const VARIABLE_COLUMNS: TableColumn[] = [
-  { key: "name", header: "Variable", overflow: "truncate", minWidth: 10 },
-  { key: "type", header: "Type", priority: "medium" },
-  { key: "env", header: "Environment variable", overflow: "truncate", minWidth: 12 },
-  { key: "required", header: "Required", priority: "medium" },
-  { key: "secret", header: "Secret", priority: "low" },
-  { key: "prompt", header: "What it asks", overflow: "wrap", flex: 1, priority: "low", minWidth: 16 },
+/** The columns the listing of everything a subscription installs shows. */
+const INSTALLS_COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "version", header: "Version", overflow: "truncate", minWidth: 7 },
+  { key: "kind", header: "Kind", overflow: "wrap", minWidth: 16 },
+  {
+    key: "neededBy",
+    header: "Needed by",
+    overflow: "wrap",
+    flex: 1,
+    priority: "medium",
+    minWidth: 12,
+  },
 ];
 
 /** The columns the content listing shows. */
@@ -86,7 +105,8 @@ const CONTENT_COLUMNS: TableColumn[] = [
 ];
 
 export default class RecipeShow extends BaseCommand {
-  static description = "Show one recipe: its versions, dependencies, variables and files";
+  static description =
+    "Show one recipe: its versions, dependencies, what subscribing installs and asks, and its files";
 
   /**
    * The other spelling of the topic. It lives under a hidden topic, so it is
@@ -165,24 +185,76 @@ export default class RecipeShow extends BaseCommand {
     printBrowsingNotes({ notChecked: notChecked.filter((name) => name === detail.repo) });
 
     this.printVersions(detail.versions);
-    this.printDependencies(detail.dependencies, detail.manifestRead);
+    this.printDependencies(
+      detail.dependencies,
+      detail.manifestRead || detail.dependenciesRecorded
+    );
 
-    if (!detail.manifestRead) {
+    const preview = await this.preview(service, inputs, detail);
+    if (typeof preview === "string") {
+      blankLine();
+      paragraph(preview);
+    } else {
+      this.printInstalls(preview);
+      this.printQuestions(preview);
+    }
+
+    if (detail.manifestRead) {
+      this.printContents(detail.contents);
+    } else {
+      blankLine();
+      subheading("Where its files land in this project");
       blankLine();
       paragraph(
-        "The recipe's own files are not on this machine, so the questions it asks and " +
-          "the files it publishes are not known here. Subscribing to it fetches them."
+        "The recipe's own files are not on this machine, so the files it publishes are " +
+          "not known here. Subscribing to it fetches them."
       );
-      footer();
-      return;
     }
 
-    this.printVariables(detail.variables);
-    this.printContents(detail.contents);
-
     footer();
   }
 
+  /**
+   * Works out what subscribing to the described version would install and ask,
+   * from the same indexes the rest of the page reads, fetching nothing. The
+   * answer is a sentence instead when it cannot be worked out.
+   *
+   * @param service - The project's subscription service.
+   * @param inputs - The catalog's inputs, whose indexes the preview resolves against.
+   * @param detail - The recipe being described.
+   */
+  private async preview(
+    service: SubscriptionService,
+    inputs: CatalogInputs,
+    detail: RecipeDetail
+  ): Promise<SubscriptionPreview | string> {
+    if (detail.describing === undefined) {
+      return (
+        "This recipe publishes no version a subscription would install, so nothing " +
+        "is described below."
+      );
+    }
+    try {
+      return await service.previewSubscription(
+        {
+          repo: detail.repo,
+          namespace: detail.namespace,
+          recipe: detail.name,
+          range: detail.describing,
+        },
+        {
+          indexes: new Map(inputs.repos.map((repo) => [repo.name, repo.index])),
+          ...(semver.prerelease(detail.describing) === null ? {} : { prerelease: true }),
+        }
+      );
+    } catch (error) {
+      return (
+        `Sous could not work out what subscribing to version ${detail.describing} ` +
+        `would install. ${describeError(error)}`
+      );
+    }
+  }
+
   /**
    * Every published version, newest first, with what each one is to this
    * project.
@@ -207,24 +279,21 @@ export default class RecipeShow extends BaseCommand {
   }
 
   /**
-   * What the described version depends on, from both sides: what the recipe's
-   * manifest declares, and what its repository's index resolved that to when it
-   * was released.
+   * What the described version depends on: the manifest entry that brings each
+   * dependency in and whether it is a co-subscription or a build dependency,
+   * and what its repository's index resolved it to when it was released.
    *
    * @param dependencies - The dependencies the catalog listed.
-   * @param manifestRead - Whether the recipe's own manifest could be read.
+   * @param known - Whether the manifest or the index says what the version declares.
    */
-  private printDependencies(
-    dependencies: RecipeDependencyListing[],
-    manifestRead: boolean
-  ): void {
+  private printDependencies(dependencies: RecipeDependencyListing[], known: boolean): void {
     blankLine();
     subheading("What it depends on");
     blankLine();
 
     if (dependencies.length === 0) {
       paragraph(
-        manifestRead
+        known
           ? "This recipe depends on nothing else."
           : "The repository's index records no dependencies for this version."
       );
@@ -233,7 +302,10 @@ export default class RecipeShow extends BaseCommand {
 
     const rows = dependencies.map((entry) => ({
       key: entry.key,
-      declared: entry.declared ?? "not declared in the manifest",
+      declared:
+        entry.declared === undefined
+          ? "not recorded in the index"
+          : describeDeclaration(entry.declared),
       resolved:
         entry.resolvedVersion ??
         (entry.resolvedRange === undefined
@@ -249,32 +321,69 @@ export default class RecipeShow extends BaseCommand {
   }
 
   /**
-   * The questions the recipe asks, and the environment variable each answer is
-   * stored under.
+   * Every recipe a subscription to the described version would install, each
+   * with whether its files land in the project and what brings it in, and the
+   * repositories it would need that the project does not trust yet.
    *
-   * @param variables - The variables the catalog listed.
+   * @param preview - What subscribing would install and ask.
    */
-  private printVariables(variables: RecipeVariableListing[]): void {
+  private printInstalls(preview: SubscriptionPreview): void {
     blankLine();
-    subheading("What it asks you");
+    subheading("What subscribing installs");
     blankLine();
 
-    if (variables.length === 0) {
-      paragraph("This recipe asks no questions.");
-      return;
+    const rows = preview.resolved.map((recipe) => {
+      const subscribed = recipe.requestedBy.includes(PROJECT_REQUESTER);
+      const holders = recipe.requestedBy.filter((holder) => holder !== PROJECT_REQUESTER);
+      return {
+        key: recipe.key,
+        version: recipe.version,
+        kind: subscribed ? "the subscription itself" : describeDependencyKind(recipe.kind),
+        neededBy: holders.length === 0 ? "this subscription" : holders.join(", "),
+      };
+    });
+
+    for (const line of renderTable(INSTALLS_COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
     }
 
-    const rows = variables.map((entry) => ({
-      name: entry.name,
-      type: entry.type,
-      env: entry.env,
-      required: entry.required ? "yes" : "no",
-      secret: entry.secret ? "yes" : "no",
-      prompt: entry.prompt,
-    }));
+    if (preview.missingRepos.length > 0) {
+      blankLine();
+      paragraph(
+        `Subscribing also needs ${
+          preview.missingRepos.length === 1 ? "a repository" : "repositories"
+        } this project does not trust yet, so what ${
+          preview.missingRepos.length === 1 ? "it publishes" : "they publish"
+        } is not listed above: ` +
+          preview.missingRepos
+            .map(
+              (missing) =>
+                `${missing.name}${missing.url === undefined ? "" : ` (${missing.url})`}, ` +
+                `needed by ${missing.requiredBy.map((entry) => entry.requestedBy).join(", ")}`
+            )
+            .join("; ") +
+          "."
+      );
+    }
+  }
 
-    for (const line of renderTable(VARIABLE_COLUMNS, rows, { indent: INDENT })) {
-      log(indent(line, INDENT));
+  /**
+   * Every question a subscription to the described version would ask, laid out
+   * exactly as `sous subscription add --dry-run` lays them out, without the
+   * flags that answer them ahead of time.
+   *
+   * @param preview - What subscribing would install and ask.
+   */
+  private printQuestions(preview: SubscriptionPreview): void {
+    blankLine();
+    subheading("What subscribing asks you");
+    blankLine();
+
+    for (const line of formatQuestionPlan(preview.questions, {
+      unreadable: preview.unreadable,
+      answerHints: false,
+    })) {
+      log(line === "" ? "" : indent(line));
     }
   }
 
@@ -311,13 +420,3 @@ export default class RecipeShow extends BaseCommand {
   }
 }
 
-/**
- * Plain-language wording for how a dependency was declared.
- *
- * @param kind - What the manifest declared it as, when the manifest was read.
- */
-function describeDependencyKind(kind: "depends" | "subscribes" | undefined): string {
-  if (kind === "depends") return "build dependency";
-  if (kind === "subscribes") return "co-subscription";
-  return "unknown";
-}

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" };