@sous-io/sous 0.2.16 → 0.2.18

package/src/commands/repo/unlink.ts

@@ -1,35 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { ConfigError } from "../../lib/errors.js";
+import { buildProjectOutputs } from "../../lib/build-service.js";
+import { ConfigError, isConfigError } from "../../lib/errors.js";
 import {
+  NonInteractiveError,
+  isInteractive,
+  nonInteractiveError,
+  wantsHelp,
+} from "../../lib/interactive.js";
+import {
+  globalReposDir,
+  projectReposDir,
   readGlobalLinks,
   readProjectLinks,
   writeGlobalLinks,
   writeProjectLinks,
 } from "../../lib/repos/links.js";
+import { hasNoUnsavedWork, unsavedWork, type UnsavedWork } from "../../lib/repos/git-clone.js";
+import {
+  subscriptionServiceFor,
+  type SubscriptionService,
+} from "../../lib/repos/subscription-service.js";
+import type { RepoLink } from "../../lib/repos/formats/links-map.js";
+import { collectProvidedAnswers } from "../../lib/vars/index.js";
+import { formatAskReport } from "../../lib/vars/ask.js";
 import {
+  BULLET,
   blankLine,
   dryRunNotice,
   footer,
+  heading,
+  indent,
   log,
+  note,
+  paragraph,
   section,
   showCommandVars,
   showVariables,
+  subheading,
+  warning,
 } from "../../utils/formatting.js";
+import { askYesNo } from "../../utils/prompts.js";
+import { answerFlags, confirmationFlag } from "../../utils/flags.js";
 
 /**
- * `sous repo unlink` stops reading a repository from a working copy and goes
- * back to published versions.
+ * `sous repo unlink` stops reading a repository from a working copy, goes back
+ * to the versions the lockfile pins, and rebuilds the project.
+ *
+ * Linking never touches the lockfile, so unlinking returns to exactly the
+ * versions pinned before the link. Three ways to finish, one per flag:
+ *
+ *   - On its own, it fetches the repository's index with a short timeout and
+ *     reports, as a fact, any newer published version the ranges allow. Nothing
+ *     moves.
+ *   - `--update` runs the same code as `sous subscription update <repository>`,
+ *     so the pins move to those newer versions before the rebuild.
+ *   - `--remove` deletes the checkout, and only one sous cloned itself. A
+ *     checkout linked by path belongs to its owner and is never deleted. Work
+ *     that exists nowhere else is listed first and asked about.
  *
- * It only ever removes a map entry. The checkout stays exactly where it is,
- * because sous did not necessarily put it there, and even when it did, deleting
- * a directory that may hold uncommitted work is not something a command like
- * this should decide on its own. The path is printed so the user can delete it
- * themselves if they want to.
+ * Without `--remove` the checkout stays exactly where it is, because `sous repo
+ * submit` uses a leftover checkout to revise a proposal that is still open.
  */
 export default class RepoUnlink extends BaseCommand {
   static description =
-    "Stop reading a repository from a working copy and go back to published versions";
+    "Stop reading a repository from a working copy and go back to its pinned versions";
 
   /**
    * The other spelling of the topic. It lives under a hidden topic, so it is
@@ -39,6 +76,8 @@ export default class RepoUnlink extends BaseCommand {
 
   static examples = [
     "<%= config.bin %> repo unlink sous-recipes",
+    "<%= config.bin %> repo unlink sous-recipes --update",
+    "<%= config.bin %> repo unlink sous-recipes --remove",
     "<%= config.bin %> repo unlink sous-recipes --global",
   ];
 
@@ -52,14 +91,31 @@ export default class RepoUnlink extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     global: Flags.boolean({
+      description: "Remove the machine-wide link rather than this project's link",
+      default: false,
+    }),
+    update: Flags.boolean({
       description:
-        "Remove the machine-wide link rather than this project's link",
+        "Move this repository's pins to the newest versions their ranges allow before rebuilding",
       default: false,
     }),
+    remove: Flags.boolean({
+      description: "Delete the checkout as well, when sous cloned it",
+      default: false,
+    }),
+    // One flag answers every question this command can ask: deleting a
+    // checkout that holds work, the update plan, and the trust question for a
+    // repository a newer version needs.
+    yes: confirmationFlag({ extraAliases: ["trust"] }),
     "dry-run": Flags.boolean({
       description: "Print what would change without writing anything",
       default: false,
     }),
+    "no-build": Flags.boolean({
+      description: "Unlink without rebuilding the project",
+      default: false,
+    }),
+    ...answerFlags(),
   };
 
   async run(): Promise<void> {
@@ -67,12 +123,13 @@ export default class RepoUnlink extends BaseCommand {
     const { sousDir } = this.configContext;
     const isGlobal = flags.global;
     const name = args.repo;
+    const dryRun = flags["dry-run"];
 
     showCommandVars({
       Project: this.projectLabel,
       Repository: name,
       Scope: isGlobal ? "this machine" : "this project",
-      "Dry Run": flags["dry-run"],
+      "Dry Run": dryRun,
     });
 
     section("Unlinking a repository");
@@ -84,31 +141,287 @@ export default class RepoUnlink extends BaseCommand {
       throw new ConfigError(this.notLinkedMessage(name, isGlobal, sousDir));
     }
 
-    if (flags["dry-run"]) {
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    // Everything that can refuse is settled before anything is written, so a
+    // refusal leaves the link exactly as it was.
+    if (flags.update && service.currentRepos()[name] === undefined) {
+      throw new ConfigError(
+        `'${name}' is linked, but this project does not trust a repository by that ` +
+          `name, so it has no pins to update.\n` +
+          `  Nothing was changed; the link is still in place.`
+      );
+    }
+    if (flags.remove) this.assertRemovable(name, entry, isGlobal, sousDir);
+    const work = flags.remove ? unsavedWork(entry.path) : undefined;
+
+    if (dryRun) {
       dryRunNotice(`would unlink '${name}', which points at ${entry.path}`);
-      dryRunNotice("the checkout itself would be left where it is");
+      dryRunNotice(
+        flags.remove
+          ? "the checkout would be deleted"
+          : "the checkout itself would be left where it is"
+      );
+      if (work !== undefined && !hasNoUnsavedWork(work)) this.describeUnsavedWork(work);
+      if (flags.update) await service.update({ repo: name, dryRun: true });
       footer();
       return;
     }
 
+    if (work !== undefined) await this.confirmRemoval(entry.path, work, flags.yes);
+
     delete map.links[name];
     const linksPath = isGlobal ? writeGlobalLinks(map) : writeProjectLinks(sousDir, map);
 
     showVariables({
       Repository: name,
-      "Checkout left at": entry.path,
-      "Updated": linksPath,
+      Checkout: entry.path,
+      Updated: linksPath,
+    });
+
+    blankLine();
+    paragraph(`'${name}' is read from the versions the lockfile pins again.`);
+
+    if (flags.update) {
+      await this.updatePins(service, name, flags);
+    } else {
+      await this.reportNewerVersions(service, name);
+    }
+
+    if (flags.remove) {
+      fs.rmSync(entry.path, { recursive: true, force: true });
+      blankLine();
+      paragraph(`The checkout sous cloned at ${entry.path} was deleted.`);
+    } else {
+      blankLine();
+      paragraph(
+        entry.origin === "clone"
+          ? `The checkout sous cloned is still at ${entry.path}.`
+          : `The checkout at ${entry.path} was yours to begin with, and has not been touched.`
+      );
+    }
+
+    footer();
+
+    if (!flags["no-build"]) await this.rebuildProject(name);
+  }
+
+  /**
+   * Refuses to delete a checkout sous did not create, or one that is not where
+   * sous clones to. The link records its origin; a path-linked checkout belongs
+   * to whoever linked it.
+   *
+   * @param name - The repository's short name.
+   * @param entry - The link being removed.
+   * @param isGlobal - Whether it is the machine-wide link.
+   * @param sousDir - The project's `.sous/` directory.
+   */
+  private assertRemovable(
+    name: string,
+    entry: RepoLink,
+    isGlobal: boolean,
+    sousDir: string
+  ): void {
+    if (entry.origin !== "clone") {
+      throw new ConfigError(
+        `Sous did not create the checkout at ${entry.path}, so it will not delete it.\n` +
+          `  '${name}' was linked to a checkout that was already there. Nothing was ` +
+          `changed; unlink without '--remove' to keep the checkout, and delete it ` +
+          `yourself if you want it gone.`
+      );
+    }
+
+    const root = isGlobal ? globalReposDir() : projectReposDir(sousDir);
+    const relative = path.relative(root, entry.path);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+      throw new ConfigError(
+        `The checkout at ${entry.path} is not inside ${root}, where sous clones ` +
+          `checkouts, so sous will not delete it.\n` +
+          `  Nothing was changed; unlink without '--remove' and delete it yourself if ` +
+          `you want it gone.`
+      );
+    }
+  }
+
+  /**
+   * Lists what deleting the checkout would lose, and asks before going on. A
+   * checkout with nothing to lose is deleted without a question.
+   *
+   * @param checkout - The checkout's path.
+   * @param work - What an inspection of it found.
+   * @param yes - Whether the confirmation flag answered the question already.
+   */
+  private async confirmRemoval(
+    checkout: string,
+    work: UnsavedWork,
+    yes: boolean
+  ): Promise<void> {
+    if (hasNoUnsavedWork(work)) return;
+
+    this.describeUnsavedWork(work);
+    if (yes) return;
+
+    if (!isInteractive()) {
+      throw nonInteractiveError({
+        prompt: `whether to delete the checkout at ${checkout}, and the work listed above`,
+        remedy:
+          "pass '--yes' (spelled '-y', '--force' or '-f' if you prefer) to delete it " +
+          "without being asked.",
+      });
+    }
+
+    const proceed = await askYesNo("Delete the checkout, and this work with it?");
+    if (!proceed) {
+      throw new ConfigError(
+        `Nothing was changed: the checkout at ${checkout} was not deleted, and the ` +
+          `link is still in place.`
+      );
+    }
+  }
+
+  /**
+   * Prints what exists only in the checkout, as a list.
+   *
+   * @param work - What an inspection of the checkout found.
+   */
+  private describeUnsavedWork(work: UnsavedWork): void {
+    blankLine();
+    warning("The checkout holds work that exists nowhere else, and deleting it loses that work.");
+    blankLine();
+
+    const group = (title: string, items: string[]): void => {
+      if (items.length === 0) return;
+      log(indent(title));
+      for (const item of items) log(indent(`${BULLET} ${item}`, 4));
+      blankLine();
+    };
+
+    if (work.unknown !== undefined) {
+      group("Sous could not inspect it, so it may hold anything:", [work.unknown]);
+    }
+    group("Uncommitted changes:", work.uncommitted);
+    group("Commits no remote has:", work.unpushed);
+    group("Stashes:", work.stashes);
+  }
+
+  /**
+   * Moves the repository's pins through the same code `sous subscription
+   * update` runs. A failure there is reported with the fact that the link is
+   * already gone, since that part has happened.
+   *
+   * @param service - The subscription service.
+   * @param name - The repository's short name.
+   * @param flags - The confirmation and answer flags.
+   */
+  private async updatePins(
+    service: SubscriptionService,
+    name: string,
+    flags: { yes: boolean; answer?: string[]; "answers-file"?: string }
+  ): Promise<void> {
+    blankLine();
+    subheading("Updating the pins");
+
+    const provided = collectProvidedAnswers({
+      ...(flags.answer === undefined ? {} : { answer: flags.answer }),
+      ...(flags["answers-file"] === undefined ? {} : { answersFile: flags["answers-file"] }),
     });
 
+    let outcome;
+    try {
+      outcome = await service.update({ repo: name, yes: flags.yes, answers: provided });
+    } catch (error) {
+      if (!isConfigError(error)) throw error;
+      // The unlink has already happened, so the message says so before the
+      // reason the update stopped. A blocked question keeps its kind, so the
+      // command's help is still printed under it.
+      const message =
+        `'${name}' was unlinked, but its pins were not updated.\n` +
+        `${(error as ConfigError).message}`;
+      throw wantsHelp(error) ? new NonInteractiveError(message) : new ConfigError(message);
+    }
+
+    if (outcome.nothingToUpdate) return;
+
+    blankLine();
+    paragraph("The lockfile now pins the versions listed above.");
+
+    if (outcome.answers !== undefined) {
+      blankLine();
+      subheading("Variables");
+      for (const line of formatAskReport(outcome.answers)) log(line === "" ? "" : indent(line));
+    }
+  }
+
+  /**
+   * Says whether the repository publishes newer versions the ranges allow,
+   * without moving anything. The index is fetched with a short timeout; when it
+   * cannot be fetched, that is what is reported.
+   *
+   * @param service - The subscription service.
+   * @param name - The repository's short name.
+   */
+  private async reportNewerVersions(service: SubscriptionService, name: string): Promise<void> {
+    if (service.currentRepos()[name] === undefined) return;
+
+    blankLine();
+    subheading("Published versions");
     blankLine();
-    log(`  '${name}' now resolves to its published versions again.`);
-    log(
-      entry.origin === "clone"
-        ? "  sous cloned that checkout; it has been left in place, and you may delete it."
-        : "  That checkout was yours to begin with, and has not been touched."
+
+    const report = await service.newerPublishedVersions(name);
+    if (!report.checked) {
+      note(
+        `Sous could not check '${name}' for newer published versions. ` +
+          `${report.reason.split("\n")[0]!.trim()}`
+      );
+      return;
+    }
+
+    if (report.newer.length === 0) {
+      paragraph(
+        `Every pin from '${name}' is the newest published version its range allows.`
+      );
+      return;
+    }
+
+    paragraph(
+      `'${name}' publishes newer versions within range. The lockfile still pins the ` +
+        `older ones:`
     );
+    blankLine();
+    showVariables(
+      report.newer.map((entry) => ({
+        label: entry.key,
+        value: `${entry.from} pinned, ${entry.to} published`,
+      }))
+    );
+  }
+
+  /**
+   * Rebuilds the project, so its outputs come from the pinned versions rather
+   * than the checkout when this command returns.
+   *
+   * @param name - The repository that was unlinked, for the failure message.
+   */
+  private async rebuildProject(name: string): Promise<void> {
+    await this.reloadDiscoveredConfig();
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
 
     footer();
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `'${name}' was unlinked, but the build that followed failed, so this project's ` +
+          `outputs may still hold what the checkout contributed. The unlink itself is ` +
+          `recorded; fix what the build reported above and run 'sous build' again.`
+      );
+    }
   }
 
   /**

package/src/commands/subscription/update.ts

@@ -0,0 +1,215 @@
+/**
+ * `sous subscription update [ref]`.
+ *
+ * Moves the lockfile's pins to the newest versions their ranges allow. With no
+ * reference it covers every subscription; a reference narrows it to one
+ * repository, one namespace or one recipe:
+ *
+ *     sous subscription update
+ *     sous subscription update sous-recipes
+ *     sous subscription update workflow
+ *     sous subscription update workflow/task-files
+ *
+ * Every trusted repository's index is fetched fresh first. A pin moves only
+ * within the range its subscription (or the recipe depending on it) declares,
+ * and dependencies move with the closure. Only the lockfile changes; the
+ * subscriptions themselves are never edited. The whole change is printed as a
+ * plan and asked about once, and the project is rebuilt afterwards.
+ */
+
+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 { describeUpdateScope } from "../../lib/repos/update-plan.js";
+import { formatAskReport } from "../../lib/vars/ask.js";
+import { collectProvidedAnswers } 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";
+
+export default class SubscriptionUpdate extends BaseCommand {
+  static description =
+    "Move this project's pinned recipe versions to the newest ones their ranges allow";
+
+  /**
+   * 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:update"];
+
+  static examples = [
+    "<%= config.bin %> subscription update",
+    "<%= config.bin %> subscription update sous-recipes",
+    "<%= config.bin %> subscription update workflow/task-files",
+    "<%= config.bin %> subscription update --dry-run",
+    "<%= config.bin %> subscription update --yes",
+  ];
+
+  static args = {
+    ref: Args.string({
+      description:
+        "What to update: a repository, a namespace or a recipe. Leave it out to update everything",
+      required: false,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    // One flag answers both questions this command can ask: the plan, and the
+    // trust question for a repository a newer version needs.
+    yes: confirmationFlag({ extraAliases: ["trust"] }),
+    "accept-first": Flags.boolean({
+      description:
+        "When the reference matches several things, take the first one listed",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description:
+        "Print what would change without writing anything or downloading any recipe",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Change the lockfile without rebuilding the project",
+      default: false,
+    }),
+    ...answerFlags(),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(SubscriptionUpdate);
+    const dryRun = flags["dry-run"];
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Updating: args.ref ?? "every subscription",
+      "Dry Run": dryRun,
+    });
+
+    heading("Updating");
+
+    if (dryRun) {
+      dryRunNotice(
+        "The indexes are fetched so the plan is current; no recipe is downloaded and " +
+          "nothing in this project is written."
+      );
+    }
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const provided = collectProvidedAnswers({
+      ...(flags.answer === undefined ? {} : { answer: flags.answer }),
+      ...(flags["answers-file"] === undefined ? {} : { answersFile: flags["answers-file"] }),
+    });
+
+    const outcome = await service.update({
+      ...(args.ref === undefined ? {} : { ref: args.ref }),
+      yes: flags.yes,
+      acceptFirst: flags["accept-first"],
+      answers: provided,
+      dryRun,
+    });
+
+    const scope = describeUpdateScope(outcome.scope);
+
+    if (outcome.nothingToUpdate) {
+      footer();
+      return;
+    }
+
+    if (dryRun) {
+      paragraph(
+        `Nothing was written. Run the same command without '--dry-run' to update ${scope}.`
+      );
+      footer();
+      return;
+    }
+
+    blankLine();
+    subheading("Lockfile");
+    blankLine();
+    if (outcome.diff.unchanged) {
+      paragraph("Nothing changed.");
+    } else {
+      for (const line of outcome.diff.lines) log(indent(line));
+    }
+
+    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.`
+      );
+    }
+
+    if (outcome.answers !== undefined) {
+      blankLine();
+      subheading("Variables");
+      for (const line of formatAskReport(outcome.answers)) {
+        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 the lockfile was updated.`
+      );
+    }
+
+    const rebuilding = !flags["no-build"] && !outcome.diff.unchanged;
+
+    blankLine();
+    paragraph(
+      `The lockfile now pins the newest versions the ranges allow for ${scope}. ` +
+        `This project's subscriptions are exactly as they were.` +
+        (rebuilding || outcome.diff.unchanged ? "" : " The project was not rebuilt.")
+    );
+
+    footer();
+
+    if (rebuilding) await this.rebuildProject();
+  }
+
+  /**
+   * Rebuilds the project now that the lockfile has moved, so the outputs match
+   * the new versions when this command returns. The config is reloaded first,
+   * because a repository trusted along the way was written into a managed layer.
+   * A build that fails leaves the update in place, because it is already
+   * written; the message says so.
+   */
+  private async rebuildProject(): Promise<void> {
+    await this.reloadDiscoveredConfig();
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
+
+    footer();
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `The lockfile was updated, but the build that followed it failed, so this ` +
+          `project's outputs may not match the new versions yet. The update itself is ` +
+          `recorded; fix what the build reported above and run 'sous build' again.`
+      );
+    }
+  }
+}

package/src/lib/repos/formats/common.ts

@@ -313,6 +313,26 @@ export function extensibleObject<Shape extends z.ZodRawShape>(shape: Shape) {
   return z.preprocess(stripExtensionKeys, z.strictObject(shape));
 }
 
+/**
+ * The `submissions` block a repo manifest and a recipe manifest may both carry:
+ * whether the recipes it covers take proposed changes, and where to send a
+ * change instead when they do not. On a repo manifest it covers every recipe;
+ * on a recipe manifest it covers that recipe, and wins over the repository's.
+ *
+ *     submissions:
+ *       allowed: false
+ *       instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+ */
+export const submissionsSchema = extensibleObject({
+  /** Whether a proposed change to the covered recipes is accepted. Defaults to true. */
+  allowed: z.boolean().default(true),
+  /** Where a change should go instead, printed when one is proposed anyway. */
+  instead: z.string().min(1, "must not be empty").optional(),
+});
+
+/** A validated `submissions` block. */
+export type Submissions = z.infer<typeof submissionsSchema>;
+
 // --- Error reporting ----------------------------------------------------------------------------
 
 /** Renders a zod issue path (`["variables",0,"name"]`) as `variables[0].name`. */

package/src/lib/repos/formats/links-map.ts

@@ -4,7 +4,8 @@
  * A link redirects a repo's resolution away from the store and at a real
  * working copy on disk, which is how a maintainer edits recipes: edits happen
  * in a checkout, never in the store. `sous repo link` writes an entry;
- * `sous repo unlink` removes it and leaves the checkout in place.
+ * `sous repo unlink` removes it and leaves the checkout in place unless asked
+ * to delete one sous cloned.
  *
  * Two maps are read: the project's `.sous/sous.links.json` and the machine-wide
  * `$SOUS_HOME/sous.links.json`, with the project map winning on conflict. The
@@ -34,8 +35,9 @@ export const repoLinkSchema = z.strictObject({
   linkedAt: isoTimestampSchema,
   /**
    * Whether sous cloned the working copy itself ('clone') or was pointed at an
-   * existing checkout ('path'). Unlinking never deletes either, but the origin
-   * tells the user what sous put there.
+   * existing checkout ('path'). Unlinking leaves either in place unless
+   * `--remove` is passed, and even then only a 'clone' is ever deleted: a
+   * 'path' checkout belongs to whoever linked it.
    */
   origin: z.enum(LINK_ORIGINS),
 });