@sous-io/sous 0.1.1 → 0.2.1

package/src/commands/subscription/add.ts

@@ -0,0 +1,285 @@
+/**
+ * `sous subscription add <ref>`, also reachable as `sous subscribe <ref>`.
+ *
+ * Subscribing is how a recipe enters a project. The ref names a namespace (every
+ * recipe in it, including ones published later) or one recipe, with an optional
+ * version range:
+ *
+ *     sous subscription add workflow/task-files
+ *     sous subscription add workflow/task-files@^1.2.0
+ *     sous subscription add core
+ *     sous subscription add my-recipes:workflow/task-files
+ *
+ * A dry run prints the whole plan, including every question these recipes ask
+ * and where each answer would be stored. Those answers can be supplied on the
+ * command line with `--answer name=value` (or `--answers-file <path>`), which
+ * is how a run with no terminal subscribes to a recipe that asks questions.
+ *
+ * The whole dependency closure is resolved before anything is downloaded. If it
+ * reaches a repository this project has not added, sous stops and asks about it
+ * by name, showing which recipe requires it; a run with no terminal fails
+ * instead, naming the command that grants the trust. Installs are whole or not
+ * at all.
+ */
+
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { buildProjectOutputs } from "../../lib/build-service.js";
+import { ConfigError } from "../../lib/errors.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { formatAskReport } from "../../lib/vars/ask.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  collectProvidedAnswers,
+  formatQuestionPlan,
+} from "../../lib/vars/index.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+  subheading,
+  warning,
+} from "../../utils/formatting.js";
+import { answerFlags, confirmationFlag } from "../../utils/flags.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+/**
+ * The columns the installation report shows: what was installed, at what
+ * version, and why it is there. The reason wraps rather than being cut, because
+ * it is the answer to the question a reader is most likely to have.
+ */
+const INSTALLED_COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "version", header: "Version", overflow: "truncate" },
+  { key: "repo", header: "Repository", overflow: "truncate", priority: "medium" },
+  { key: "why", header: "Why", overflow: "wrap", flex: 1, minWidth: 16 },
+];
+
+export default class SubscriptionAdd extends BaseCommand {
+  static description =
+    "Subscribe this project to a recipe, or to a whole namespace of them";
+
+  /**
+   * `subscriptions:add` is the plural spelling of the topic. `subscribe` is the
+   * original spelling of this command and still works; it is hidden so the
+   * top-level listing names the command once, under its topic.
+   */
+  static aliases = ["subscriptions:add"];
+
+  static hiddenAliases = ["subscribe"];
+
+  static examples = [
+    "<%= config.bin %> subscription add workflow/task-files",
+    "<%= config.bin %> subscription add workflow/task-files@^1.2.0",
+    "<%= config.bin %> subscription add core",
+    "<%= config.bin %> subscription add workflow/task-files --always-pull",
+    "<%= config.bin %> subscription add workflow/task-files --dry-run",
+    "<%= config.bin %> subscription add workflow/task-files --yes --answer apiUrl=https://api.example.com",
+  ];
+
+  static args = {
+    ref: Args.string({
+      description:
+        "What to subscribe to: 'namespace', 'namespace/recipe', or either with an '@<range>'",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    prerelease: Flags.boolean({
+      description: "Let prerelease versions take part in version range matching",
+      default: false,
+    }),
+    "always-pull": Flags.boolean({
+      description:
+        "Install a newer in-range version whenever one exists, rather than holding the locked one",
+      default: false,
+    }),
+    // One flag answers both questions this command can ask: the trust question
+    // for a repository it has to add, and the subscribe confirmation. `--trust`
+    // is kept as a spelling of it because the trust ceremony reads naturally
+    // with that word.
+    yes: confirmationFlag({ extraAliases: ["trust"] }),
+    "accept-first": Flags.boolean({
+      description:
+        "When a one-word ref matches several things, take the first one listed",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Print what would be installed without writing or downloading anything",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Change the subscription without rebuilding the project",
+      default: false,
+    }),
+    ...answerFlags(),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(SubscriptionAdd);
+    const dryRun = flags["dry-run"];
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Subscribing: args.ref,
+      "Dry Run": dryRun,
+    });
+
+    heading("Subscribing");
+
+    if (dryRun) dryRunNotice("Nothing will be downloaded, written or asked.");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    // Answers supplied ahead of the questions. They are validated before
+    // anything is installed, so a typo fails the run rather than being stored
+    // under a name nothing reads.
+    const provided = collectProvidedAnswers({
+      ...(flags.answer === undefined ? {} : { answer: flags.answer }),
+      ...(flags["answers-file"] === undefined
+        ? {}
+        : { answersFile: flags["answers-file"] }),
+    });
+
+    const outcome = await service.subscribe({
+      ref: args.ref,
+      answers: provided,
+      prerelease: flags.prerelease,
+      alwaysPull: flags["always-pull"],
+      trust: flags.yes,
+      yes: flags.yes,
+      acceptFirst: flags["accept-first"],
+      dryRun,
+    });
+
+    blankLine();
+    subheading(dryRun ? "What would be installed" : "What was installed");
+    blankLine();
+
+    const rows = outcome.resolved.map((recipe) => ({
+      key: recipe.key,
+      version: recipe.version,
+      repo: recipe.repo,
+      why: recipe.requestedBy.includes("project")
+        ? "you subscribed to it"
+        : recipe.kind === "subscribes"
+          ? `co-subscribed by ${recipe.requestedBy.join(", ")}`
+          : `needed by ${recipe.requestedBy.join(", ")}`,
+    }));
+
+    for (const line of renderTable(INSTALLED_COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
+    }
+
+    if (outcome.trusted.length > 0) {
+      blankLine();
+      paragraph(
+        `Repositories trusted along the way: ${outcome.trusted.join(", ")}. ` +
+          `They are now recorded in this project's config, and your colleagues ` +
+          `inherit them.`
+      );
+    }
+
+    blankLine();
+    subheading("Lockfile");
+    blankLine();
+    if (outcome.diff.unchanged) {
+      paragraph("Nothing changed; everything asked for was already locked.");
+    } else {
+      for (const line of outcome.diff.lines) log(indent(line));
+    }
+
+    if (outcome.answers !== undefined) {
+      blankLine();
+      subheading("Variables");
+      for (const line of formatAskReport(outcome.answers, dryRun)) {
+        log(line === "" ? "" : indent(line));
+      }
+    }
+
+    // The question plan, printed only by a dry run: it is how a caller with no
+    // terminal learns what this subscription will want to know, so that the
+    // real run can answer everything with '--answer'.
+    if (outcome.questions !== undefined) {
+      blankLine();
+      subheading("Questions these recipes ask");
+      blankLine();
+      // Recipes this machine does not hold yet are named inside the plan, so a
+      // closure that is only partly readable still lists everything it can.
+      for (const line of formatQuestionPlan(outcome.questions, {
+        ...(outcome.unreadable === undefined ? {} : { unreadable: outcome.unreadable }),
+      })) {
+        log(line === "" ? "" : indent(line));
+      }
+    }
+
+    if (outcome.cycles.length > 0) {
+      warning(
+        `Some of these recipes co-subscribe to each other in a circle:\n` +
+          outcome.cycles.map((cycle) => `  ${cycle.join(" -> ")}`).join("\n") +
+          `\nThat is unusual but not broken, and everything above was installed.`
+      );
+    }
+
+    const rebuilding = !dryRun && !flags["no-build"];
+
+    blankLine();
+    paragraph(
+      dryRun
+        ? `Nothing was written. Run the same command without '--dry-run' to install it.`
+        : `The subscription to '${outcome.key}' is recorded in this project's config, ` +
+          `and the exact versions above are recorded in its lockfile.` +
+          (rebuilding ? `` : ` Run 'sous build' to compile what they contribute.`)
+    );
+
+    footer();
+
+    if (rebuilding) await this.rebuildProject(outcome.key);
+  }
+
+  /**
+   * Rebuilds the project now that the subscription has been written, so the
+   * files the new recipes contribute are on disk when this command returns.
+   *
+   * The subscription lives in a managed `conf.d/` layer, so the settings loaded
+   * when this command started no longer describe the project; they are reloaded
+   * before the build, or it would compile the old subscription set. A build that
+   * fails leaves the subscription in place, because it is already written and
+   * locked; the message says so and names the command to run once the cause is
+   * fixed.
+   *
+   * @param key - The subscription that was just added, for the failure message.
+   */
+  private async rebuildProject(key: string): Promise<void> {
+    await this.reloadDiscoveredConfig();
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
+
+    footer();
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `The subscription to '${key}' was saved, but the build that followed it ` +
+          `failed, so this project's outputs may be incomplete. The subscription ` +
+          `itself is recorded and locked; fix what the build reported above and run ` +
+          `'sous build' again.`
+      );
+    }
+  }
+}

package/src/commands/subscription/list.ts

@@ -0,0 +1,129 @@
+/**
+ * `sous subscription list`.
+ *
+ * Prints every subscription this project declares: the ref, the version range
+ * it resolves within, the versions its lockfile currently pins, where the
+ * subscription came from, and whether it is switched on. Entries switched off
+ * with `enabled: false` are listed too, because an opt-out is part of what a
+ * project declares.
+ *
+ * It reads only the config and the lockfile, so it is safe offline and never
+ * downloads anything.
+ */
+
+import { BaseCommand } from "../../base-command.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { BUILT_IN_ADDED_BY } from "../../lib/repos/defaults.js";
+import { USER_ADDED_BY } from "../../lib/repos/trust.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+} from "../../utils/formatting.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+/**
+ * The columns the listing shows. What a project subscribed to, the range it
+ * asked for and the versions it actually holds are the whole point of the
+ * command, so all three stay whatever the terminal's width; where a
+ * subscription came from and whether it is switched on give way first.
+ */
+const COLUMNS: TableColumn[] = [
+  { key: "key", header: "Subscription", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "range", header: "Range", overflow: "truncate", minWidth: 7 },
+  { key: "pinned", header: "Pinned version", flex: 1, minWidth: 14 },
+  { key: "origin", header: "Origin", priority: "medium" },
+  { key: "enabled", header: "Enabled", priority: "medium" },
+];
+
+export default class SubscriptionList extends BaseCommand {
+  static description = "List the recipes and namespaces this project subscribes to";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["subscriptions:list"];
+
+  static examples = ["<%= config.bin %> subscription list"];
+
+  static flags = { ...BaseCommand.baseFlags };
+
+  async run(): Promise<void> {
+    await this.parse(SubscriptionList);
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+    });
+
+    heading("Subscriptions");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const listings = service.listSubscriptions();
+
+    blankLine();
+
+    if (listings.length === 0) {
+      paragraph("This project subscribes to nothing yet.");
+      footer();
+      return;
+    }
+
+    const rows = listings.map((entry) => ({
+      key: entry.key,
+      range: entry.range ?? "any version",
+      pinned: describePinned(entry.pinned, entry.enabled),
+      origin: describeOrigin(entry.addedBy),
+      enabled: entry.enabled ? "yes" : "no",
+    }));
+
+    for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
+    }
+
+    footer();
+  }
+}
+
+/**
+ * The versions the lockfile pins for one subscription. A namespace subscription
+ * holds several recipes, so each is named with the version beside it.
+ *
+ * A subscription with nothing pinned has simply not been built yet, which is
+ * what the cell says; the one exception is a subscription switched off, which
+ * no build will pin.
+ *
+ * @param pinned - The locked recipes the subscription holds.
+ * @param enabled - Whether the subscription is switched on.
+ */
+export function describePinned(
+  pinned: Array<{ key: string; version: string }>,
+  enabled: boolean
+): string {
+  if (pinned.length > 0) return pinned.map((entry) => `${entry.key} ${entry.version}`).join(", ");
+  return enabled ? "pinned on first build" : "not pinned";
+}
+
+/**
+ * Plain-language wording for a subscription entry's `addedBy` field.
+ *
+ * @param addedBy - What the entry recorded, when it recorded anything.
+ */
+function describeOrigin(addedBy: string | undefined): string {
+  if (addedBy === BUILT_IN_ADDED_BY) return "built in";
+  if (addedBy === undefined || addedBy === USER_ADDED_BY) return "user";
+  return addedBy;
+}

package/src/commands/subscription/remove.ts

@@ -0,0 +1,181 @@
+/**
+ * `sous subscription remove <ref>`, also reachable as `sous unsubscribe <ref>`.
+ *
+ * The exact reverse of adding a subscription, and refcounted: removing a subscription
+ * removes what it alone brought in, and leaves alone anything another
+ * subscription or another recipe still needs. Whatever stays is reported, with
+ * who is holding it, so a removal that appears to do nothing explains itself.
+ *
+ * The repository the recipes came from stays trusted; withdrawing that is a
+ * separate, deliberate act.
+ */
+
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { buildProjectOutputs } from "../../lib/build-service.js";
+import { ConfigError } from "../../lib/errors.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+  subheading,
+} from "../../utils/formatting.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+/** The columns the report of what stayed behind shows. */
+const STAYED_COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "heldBy", header: "Still held by", overflow: "wrap", flex: 1, minWidth: 16 },
+];
+
+export default class SubscriptionRemove extends BaseCommand {
+  static description = "Remove a subscription, and everything only it brought in";
+
+  /**
+   * `subscriptions:remove` is the plural spelling of the topic. `unsubscribe` is
+   * the original spelling of this command and still works; it is hidden so the
+   * top-level listing names the command once, under its topic.
+   */
+  static aliases = ["subscriptions:remove"];
+
+  static hiddenAliases = ["unsubscribe"];
+
+  static examples = [
+    "<%= config.bin %> subscription remove workflow/task-files",
+    "<%= config.bin %> subscription remove core",
+    "<%= config.bin %> subscription remove workflow/task-files --dry-run",
+  ];
+
+  static args = {
+    ref: Args.string({
+      description: "What to unsubscribe from: 'namespace' or 'namespace/recipe'",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    "dry-run": Flags.boolean({
+      description: "Print what would be removed without writing anything",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Change the subscription without rebuilding the project",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(SubscriptionRemove);
+    const dryRun = flags["dry-run"];
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Unsubscribing: args.ref,
+      "Dry Run": dryRun,
+    });
+
+    heading("Unsubscribing");
+
+    if (dryRun) dryRunNotice("Nothing will be written.");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const outcome = await service.unsubscribe({ ref: args.ref, dryRun });
+
+    blankLine();
+    subheading("Lockfile");
+    blankLine();
+    if (outcome.diff.unchanged) {
+      paragraph("Nothing changed; nothing was locked because of this subscription.");
+    } else {
+      for (const line of outcome.diff.lines) log(indent(line));
+    }
+
+    if (outcome.stayed.length > 0) {
+      blankLine();
+      subheading("What stayed, and why");
+      blankLine();
+      const rows = outcome.stayed.map((entry) => ({
+        key: entry.key,
+        heldBy: entry.heldBy.join(", "),
+      }));
+
+      for (const line of renderTable(STAYED_COLUMNS, rows, { indent: INDENT })) {
+        log(indent(line, INDENT));
+      }
+    }
+
+    const rebuilding = !dryRun && !flags["no-build"];
+
+    // The closing sentence names the build only when this run is not about to do
+    // it, so nobody is told to run a command that is already running.
+    const pruneHint = rebuilding
+      ? ``
+      : ` Run 'sous build' to prune what it used to write.`;
+
+    blankLine();
+    paragraph(
+      dryRun
+        ? "Nothing was written. Run the same command without '--dry-run' to remove it."
+        : outcome.optedOut
+          ? `The subscription to '${outcome.key}' is one sous provides itself, so it ` +
+            `was switched off rather than deleted: this project's config now records ` +
+            `'${outcome.key}: { enabled: false }'. The repository it came from is ` +
+            `still trusted.${pruneHint}`
+          : `The subscription to '${outcome.key}' is gone. The repositories it came ` +
+            `from are still trusted; remove one of those deliberately if you want ` +
+            `to withdraw that too.${pruneHint}`
+    );
+
+    footer();
+
+    if (rebuilding) await this.rebuildProject(outcome.key);
+  }
+
+  /**
+   * Rebuilds the project now that the subscription has been removed, so the
+   * files it used to contribute are pruned before this command returns.
+   *
+   * The subscription lives in a managed `conf.d/` layer, so the settings loaded
+   * when this command started no longer describe the project; they are reloaded
+   * before the build, or it would compile the old subscription set straight back
+   * onto disk. A build that fails leaves the removal in place, because it is
+   * already written and locked; the message says so and names the command to run
+   * once the cause is fixed.
+   *
+   * @param key - The subscription that was just removed, for the failure message.
+   */
+  private async rebuildProject(key: string): Promise<void> {
+    await this.reloadDiscoveredConfig();
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
+
+    footer();
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `The subscription to '${key}' was removed, but the build that followed it ` +
+          `failed, so this project may still hold files it used to write. The removal ` +
+          `itself is recorded and locked; fix what the build reported above and run ` +
+          `'sous build' again.`
+      );
+    }
+  }
+}