@sous-io/sous 0.2.37 → 1.0.2

package/src/commands/subscription/add.ts

@@ -1,286 +0,0 @@
-/**
- * `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 { runProjectBuild } 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();
-
-    const succeeded = await runProjectBuild({
-      settings: this.settings,
-      configContext: this.configContext,
-      shellEnv: this.shellEnv,
-      heading: "Building the project",
-    });
-
-    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

@@ -1,208 +0,0 @@
-/**
- * `sous subscription list`.
- *
- * Prints every subscription this project declares: the ref, the version range
- * it resolves within, the versions its lockfile currently pins, the latest
- * version each of those recipes has published, 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.
- *
- * By default it reads only the config, the lockfile and the cached indexes, so
- * it is safe offline and never downloads anything. `--latest` reads the latest
- * versions from upstream instead, saving nothing, and `--installed` narrows the
- * listing to the subscriptions the lockfile pins something for.
- */
-
-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 { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
-import { listRecipes } from "../../lib/repos/catalog.js";
-import {
-  describeIndexSource,
-  pinnedCell,
-  printBrowsingNotes,
-} from "../../lib/repos/catalog-display.js";
-import { renderTable, type TableColumn } from "../../utils/table.js";
-import { browsingFlags } from "../../utils/flags.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: "latest", header: "Latest version", overflow: "wrap", priority: "medium", 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",
-    "<%= config.bin %> subscription list --installed --latest",
-  ];
-
-  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
-
-  async run(): Promise<void> {
-    const { flags } = await this.parse(SubscriptionList);
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Reading: describeIndexSource(flags.latest),
-      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
-    });
-
-    heading("Subscriptions");
-
-    const service = subscriptionServiceFor({
-      configContext: this.configContext,
-      settings: this.settings,
-      shellEnv: this.shellEnv,
-    });
-
-    const listings = service
-      .listSubscriptions()
-      .filter((entry) => !flags.installed || entry.pinned.length > 0);
-
-    blankLine();
-
-    if (listings.length === 0) {
-      paragraph(
-        flags.installed
-          ? "No subscription of this project has installed anything yet."
-          : "This project subscribes to nothing yet."
-      );
-      footer();
-      return;
-    }
-
-    // The latest version of each pinned recipe, from the repository the
-    // lockfile says it came from; the linked checkout, when there is one.
-    const { inputs, notChecked } = await loadCatalogContext({
-      service,
-      sousDir: this.configContext.sousDir,
-      settings: this.settings,
-      latest: flags.latest,
-    });
-    const published = new Map(
-      listRecipes(inputs).map((recipe) => [`${recipe.repo}:${recipe.key}`, recipe])
-    );
-    const lock = inputs.lock;
-
-    let anyLinked = false;
-    const rows = listings.map((entry) => {
-      const held = entry.pinned.map((pin) => {
-        const recipe = published.get(`${lock.recipes[pin.key]?.repo}:${pin.key}`);
-        if (recipe?.linkedPath !== undefined) anyLinked = true;
-        return { ...pin, recipe };
-      });
-      return {
-        key: entry.key,
-        range: entry.range ?? "any version",
-        pinned:
-          held.length === 0
-            ? describePinned([], entry.enabled)
-            : held
-                .map((pin) => `${pin.key} ${pinnedCell(pin.version, pin.recipe?.linkedPath)}`)
-                .join(", "),
-        latest: describeLatest(held.map((pin) => ({ key: pin.key, latest: pin.recipe?.latest }))),
-        origin: describeOrigin(entry.addedBy),
-        enabled: entry.enabled ? "yes" : "no",
-      };
-    });
-
-    const columns = flags.installed
-      ? COLUMNS.map((column) =>
-          column.key === "pinned" ? { ...column, header: "Installed version" } : column
-        )
-      : COLUMNS;
-
-    for (const line of renderTable(columns, rows, { indent: INDENT })) {
-      log(indent(line, INDENT));
-    }
-
-    printBrowsingNotes({ notChecked, anyLinked });
-
-    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";
-}
-
-/**
- * The latest published version of each recipe a subscription holds. One held
- * recipe is the usual case, and it shows the version alone; several (a
- * namespace subscription) are each named with the version beside them. A
- * recipe no readable index publishes says so; a subscription holding nothing
- * yet has no latest version to show.
- *
- * describeLatest([{ key: "workflow/task-files", latest: "1.2.0" }])
- * // -> "1.2.0"
- *
- * @param held - Each held recipe, with its latest version when an index names one.
- */
-export function describeLatest(held: Array<{ key: string; latest: string | undefined }>): string {
-  if (held.length === 0) return "";
-  const unknown = "not in any index sous has read";
-  if (held.length === 1) return held[0]!.latest ?? unknown;
-  return held
-    .map((entry) => `${entry.key} ${entry.latest ?? unknown}`)
-    .join(", ");
-}
-
-/**
- * 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

@@ -1,182 +0,0 @@
-/**
- * `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 { runProjectBuild } 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();
-
-    const succeeded = await runProjectBuild({
-      settings: this.settings,
-      configContext: this.configContext,
-      shellEnv: this.shellEnv,
-      heading: "Building the project",
-    });
-
-    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.`
-      );
-    }
-  }
-}