@sous-io/sous 0.1.1 → 0.2.1

package/src/commands/repo/remove.ts

@@ -0,0 +1,193 @@
+/**
+ * `sous repo remove <name>`: stop trusting a repository.
+ *
+ * The exact reverse of adding one. Adding a repository IS trusting it, so
+ * removing the entry is how that trust is withdrawn, and everything the project
+ * held through it goes with it: every subscription that resolves into it, every
+ * recipe those subscriptions alone held, and the files those recipes compiled.
+ *
+ * Informed consent, never prevention: the command prints all of that before it
+ * writes anything, asks once, and then does exactly what it described. The
+ * checkout behind a link is never deleted, because it is somebody's working
+ * copy and sous did not necessarily put it there.
+ */
+
+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 { resolveRootScope } from "../../lib/settings.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { confirmationFlag } from "../../utils/flags.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  indent,
+  log,
+  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 RepoRemove extends BaseCommand {
+  static description = "Stop trusting a repository, and remove everything it brought in";
+
+  /**
+   * 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 = ["repos:remove"];
+
+  static examples = [
+    "<%= config.bin %> repo remove my-recipes",
+    "<%= config.bin %> repo remove my-recipes --dry-run",
+    "<%= config.bin %> repo remove my-recipes --yes",
+  ];
+
+  static args = {
+    repo: Args.string({
+      description: "The repository's short name, as this project records it",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    // The only question this command asks is whether to go ahead with what it
+    // has just described, so the shared confirmation flag answers it.
+    yes: confirmationFlag(),
+    "dry-run": Flags.boolean({
+      description: "Print what would be removed without writing anything",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Remove the repository without rebuilding the project",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(RepoRemove);
+    const dryRun = flags["dry-run"];
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Repository: args.repo,
+      "Dry Run": dryRun,
+    });
+
+    // The heading is not followed by a blank line here: the plan that comes
+    // next opens with one of its own.
+    heading("Removing a repository");
+
+    if (dryRun) dryRunNotice("Nothing will be written.");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const outcome = await service.removeRepo({
+      name: args.repo,
+      yes: flags.yes,
+      dryRun,
+      // The output files a removed recipe wrote can only be named once the
+      // `recipeOutputs` destinations have had their variables substituted.
+      scope: resolveRootScope(this.settings, this.configContext),
+    });
+
+    blankLine();
+    subheading("Lockfile");
+    blankLine();
+    if (outcome.diff.unchanged) {
+      log(indent("Nothing changed; nothing was locked because of this repository."));
+    } 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();
+    log(
+      indent(
+        dryRun
+          ? "Nothing was written. Run the same command without '--dry-run' to remove it."
+          : outcome.optedOut
+            ? `The repository '${outcome.name}' is one sous provides itself, so it was ` +
+              `switched off rather than deleted: this project's config now records ` +
+              `'${outcome.name}: { enabled: false }'.${pruneHint}`
+            : `This project no longer trusts '${outcome.name}'. Nothing is read from it ` +
+              `any more, and its entry is gone from the repositories layer.${pruneHint}`
+      )
+    );
+
+    footer();
+
+    if (rebuilding) await this.rebuildProject(outcome.name);
+  }
+
+  /**
+   * Rebuilds the project now that the repository has been removed, so the files
+   * its recipes used to contribute are pruned before this command returns.
+   *
+   * The repositories and subscriptions both live in managed `conf.d/` layers, 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
+   * recipe 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 name - The repository that was just removed, 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(
+        `The repository '${name}' was removed, but the build that followed it failed, ` +
+          `so this project may still hold files its recipes used to write. The removal ` +
+          `itself is recorded and locked; fix what the build reported above and run ` +
+          `'sous build' again.`
+      );
+    }
+  }
+}

package/src/commands/repo/search.ts

@@ -0,0 +1,189 @@
+/**
+ * `sous repo search <text>`.
+ *
+ * Searches the cached index of every repository this project trusts: recipe
+ * names, namespace names and descriptions. It reads only what is already on
+ * disk, so it works offline and never downloads anything; a repository whose
+ * index has not been fetched yet is named at the end rather than silently left
+ * out of the results.
+ */
+
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  footer,
+  indent,
+  log,
+  paragraph,
+  section,
+  showCommandVars,
+} from "../../utils/formatting.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+/**
+ * The columns the results show. The recipe and its versions are why anybody ran
+ * the search, so they stay however narrow the terminal is; the description takes
+ * whatever room is left and wraps rather than being cut, because half a sentence
+ * helps nobody.
+ */
+const COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "versions", header: "Versions", overflow: "truncate", minWidth: 7 },
+  { key: "repo", header: "Repository", overflow: "truncate", priority: "medium" },
+  {
+    key: "description",
+    header: "What it is",
+    overflow: "wrap",
+    flex: 1,
+    priority: "low",
+    minWidth: 16,
+  },
+];
+
+/** One recipe that matched, ready to be shown. */
+type Match = {
+  repo: string;
+  key: string;
+  description: string;
+  versions: string[];
+};
+
+export default class RepoSearch extends BaseCommand {
+  static description =
+    "Search the recipes every trusted repository publishes, by name or description";
+
+  /**
+   * Searching is the way into every other repository command, so it is also a
+   * top-level `sous search` and is listed as one. `repos:search` is the plural
+   * spelling of the topic.
+   */
+  static aliases = ["search", "repos:search"];
+
+  static examples = [
+    "<%= config.bin %> repo search task",
+    "<%= config.bin %> repo search browser --limit 50",
+  ];
+
+  static args = {
+    text: Args.string({
+      description: "The text to look for in a namespace, recipe name or description",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    limit: Flags.integer({
+      description: "How many matches to show",
+      default: 25,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(RepoSearch);
+    const needle = args.text.trim().toLowerCase();
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Searching: args.text,
+    });
+
+    section("Recipes matching your search");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const repos = Object.keys(service.currentRepos()).sort();
+    const matches: Match[] = [];
+    const notFetched: string[] = [];
+
+    for (const repo of repos) {
+      const index = service.cachedIndex(repo);
+      if (index === undefined) {
+        notFetched.push(repo);
+        continue;
+      }
+
+      for (const [key, recipe] of Object.entries(index.recipes)) {
+        const namespace = key.slice(0, key.indexOf("/"));
+        const haystack = [
+          key,
+          recipe.description ?? "",
+          index.namespaces[namespace]?.description ?? "",
+        ]
+          .join(" ")
+          .toLowerCase();
+        if (!haystack.includes(needle)) continue;
+
+        matches.push({
+          repo,
+          key,
+          description: recipe.description ?? "",
+          versions: Object.keys(recipe.versions).sort(),
+        });
+      }
+    }
+
+    matches.sort((left, right) =>
+      left.key === right.key
+        ? left.repo.localeCompare(right.repo)
+        : left.key.localeCompare(right.key)
+    );
+
+    // Whatever the results themselves could not say goes into one closing
+    // summary, rather than a stack of separate notes under the table.
+    const summary: string[] = [];
+
+    if (matches.length === 0) {
+      paragraph(
+        repos.length === 0
+          ? "This project trusts no repositories yet, so there is nothing to search. " +
+            "Add one with 'sous repo add <url>'."
+          : `Nothing in the repositories this project trusts matches '${args.text}'.`
+      );
+    } else {
+      const shown = matches.slice(0, flags.limit);
+      const rows = shown.map((match) => ({
+        key: match.key,
+        repo: match.repo,
+        versions: match.versions.join(", "),
+        description:
+          match.description.length > 0 ? match.description : "no description published",
+      }));
+
+      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+        log(indent(line, INDENT));
+      }
+
+      if (matches.length > shown.length) {
+        summary.push(
+          `${matches.length - shown.length} more matches are not shown. Raise the ` +
+            `number with '--limit'.`
+        );
+      }
+    }
+
+    if (notFetched.length > 0) {
+      summary.push(
+        `Nothing has been fetched from these repositories yet, so they were not ` +
+          `searched: ${notFetched.join(", ")}.`
+      );
+    }
+
+    if (summary.length > 0) {
+      blankLine();
+      for (const line of summary) log(indent(line));
+    }
+
+    footer();
+  }
+}

package/src/commands/repo/submit.ts

@@ -0,0 +1,133 @@
+import { Command, Flags } from "@oclif/core";
+import { SOUS_VERSION } from "../../lib/settings.js";
+import { findRepoRoot, submitRepo } from "../../lib/repos/release/index.js";
+import { reportCommandError } from "../../utils/command-errors.js";
+import { nonInteractiveFlag } from "../../utils/flags.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  header,
+  log,
+  section,
+  showCommandVars,
+  showVariables,
+} from "../../utils/formatting.js";
+
+/**
+ * `sous repo submit` proposes the committed changes in a recipe repository to
+ * that repository's maintainers.
+ *
+ * Like `sous repo init` and `sous repo release`, this command does NOT extend
+ * BaseCommand: it runs inside a RECIPE repository, which is not a sous project
+ * and has no `.sous/` directory of its own.
+ *
+ * Submitting never publishes and never writes to a repository directly. Sous
+ * validates first, then hands the fork, branch and pull request mechanics to the
+ * provider's own command line tool, which already holds the contributor's
+ * credentials. Every step is printed before it runs, so a failure halfway
+ * through leaves no doubt about what did happen.
+ */
+export default class RepoSubmit extends Command {
+  static description =
+    "Propose this recipe repository's committed changes to its maintainers";
+
+  /**
+   * 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 = ["repos:submit"];
+
+  static examples = [
+    "<%= config.bin %> repo submit",
+    '<%= config.bin %> repo submit --title "Add a linting recipe"',
+    "<%= config.bin %> repo submit --draft",
+    "<%= config.bin %> repo submit --dry-run",
+  ];
+
+  static flags = {
+    title: Flags.string({
+      description: "Title for the proposal. Defaults to the last commit's subject.",
+    }),
+    body: Flags.string({
+      description: "Body for the proposal. Defaults to a summary sous writes.",
+    }),
+    draft: Flags.boolean({
+      description: "Open the proposal as a draft",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Check everything and print the plan without sending anything",
+      default: false,
+    }),
+    // This command does not extend BaseCommand, so it declares the global
+    // non-interactive flag itself; the rule is the same everywhere.
+    "non-interactive": nonInteractiveFlag(),
+  };
+
+  async init(): Promise<void> {
+    await super.init();
+    header();
+  }
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(RepoSubmit);
+    const dryRun = flags["dry-run"];
+    const rootDir = findRepoRoot(process.cwd());
+
+    showCommandVars({
+      Repository: rootDir,
+      Title: flags.title ?? "(the last commit's subject)",
+      Draft: flags.draft,
+      "Dry Run": dryRun,
+    });
+
+    section("Proposing a change");
+
+    const result = await submitRepo({
+      rootDir,
+      title: flags.title,
+      body: flags.body,
+      draft: flags.draft,
+      dryRun,
+      sousVersion: SOUS_VERSION,
+      onStep: (message) => log(`  ${message}`),
+      onNotice: (message) => (dryRun ? dryRunNotice(message) : log(`  ${message}`)),
+    });
+
+    section(dryRun ? "What would be proposed" : "What was proposed");
+    showVariables({
+      Provider: result.provider,
+      Repository: `${result.repo.owner}/${result.repo.name}`,
+      Branch: result.branch,
+      "Target branch": result.baseBranch,
+      "Pushed to": result.dryRun ? "(nothing was pushed)" : result.pushedTo,
+      "Through a fork": result.usedFork,
+      Title: result.title,
+      Proposal: result.url ?? "(the provider printed no address)",
+    });
+
+    blankLine();
+    if (result.dryRun) {
+      log("  Nothing was sent. Run the command again without --dry-run to propose it.");
+    } else {
+      log("  The maintainers decide what happens next; sous never publishes on their");
+      log("  behalf. Anything they ask for goes on the same branch, and the proposal");
+      log("  updates itself when you push again.");
+    }
+
+    footer();
+  }
+
+  /**
+   * Renders a configuration error as a plain, readable message rather than an
+   * oclif stack trace, matching what BaseCommand does for every other command.
+   * An error raised because a question could not be asked also gets this
+   * command's own help underneath it.
+   */
+  protected async catch(error: Error & { exitCode?: number }): Promise<unknown> {
+    const exitCode = await reportCommandError(this, error);
+    if (exitCode === undefined) return super.catch(error);
+    return this.exit(exitCode);
+  }
+}

package/src/commands/repo/unlink.ts

@@ -0,0 +1,147 @@
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { ConfigError } from "../../lib/errors.js";
+import {
+  readGlobalLinks,
+  readProjectLinks,
+  writeGlobalLinks,
+  writeProjectLinks,
+} from "../../lib/repos/links.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  log,
+  section,
+  showCommandVars,
+  showVariables,
+} from "../../utils/formatting.js";
+
+/**
+ * `sous repo unlink` stops reading a repository from a working copy and goes
+ * back to published versions.
+ *
+ * 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.
+ */
+export default class RepoUnlink extends BaseCommand {
+  static description =
+    "Stop reading a repository from a working copy and go back to published versions";
+
+  /**
+   * 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 = ["repos:unlink"];
+
+  static examples = [
+    "<%= config.bin %> repo unlink sous-recipes",
+    "<%= config.bin %> repo unlink sous-recipes --global",
+  ];
+
+  static args = {
+    repo: Args.string({
+      description: "The repository's short name, as it appears in the links map",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    global: Flags.boolean({
+      description:
+        "Remove the machine-wide link rather than this project's link",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Print what would change without writing anything",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(RepoUnlink);
+    const { sousDir } = this.configContext;
+    const isGlobal = flags.global;
+    const name = args.repo;
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Repository: name,
+      Scope: isGlobal ? "this machine" : "this project",
+      "Dry Run": flags["dry-run"],
+    });
+
+    section("Unlinking a repository");
+
+    const map = isGlobal ? readGlobalLinks() : readProjectLinks(sousDir);
+    const entry = map.links[name];
+
+    if (entry === undefined) {
+      throw new ConfigError(this.notLinkedMessage(name, isGlobal, sousDir));
+    }
+
+    if (flags["dry-run"]) {
+      dryRunNotice(`would unlink '${name}', which points at ${entry.path}`);
+      dryRunNotice("the checkout itself would be left where it is");
+      footer();
+      return;
+    }
+
+    delete map.links[name];
+    const linksPath = isGlobal ? writeGlobalLinks(map) : writeProjectLinks(sousDir, map);
+
+    showVariables({
+      Repository: name,
+      "Checkout left at": entry.path,
+      "Updated": linksPath,
+    });
+
+    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."
+    );
+
+    footer();
+  }
+
+  /**
+   * Explains that nothing was unlinked, and says where the link actually is
+   * when the user asked about the wrong scope; getting the scope wrong is the
+   * easiest mistake to make here.
+   *
+   * @param name - The repository's short name, as the user typed it.
+   * @param isGlobal - Which map was searched.
+   * @param sousDir - The project's discovered `.sous/` directory.
+   */
+  private notLinkedMessage(name: string, isGlobal: boolean, sousDir: string): string {
+    const searched = isGlobal ? "the machine-wide links map" : "this project's links map";
+    const other = isGlobal ? readProjectLinks(sousDir) : readGlobalLinks();
+
+    if (other.links[name] !== undefined) {
+      const flag = isGlobal ? "without --global" : "with --global";
+      return (
+        `'${name}' is not linked in ${searched}.\n` +
+          `  It is linked in the ${isGlobal ? "project" : "machine-wide"} map, at ` +
+          `${other.links[name]!.path}.\n` +
+          `  Run the same command ${flag} to remove that one.`
+      );
+    }
+
+    const map = isGlobal ? readGlobalLinks() : readProjectLinks(sousDir);
+    const linked = Object.keys(map.links).sort();
+    return (
+      `'${name}' is not linked in ${searched}.\n` +
+        (linked.length > 0
+          ? `  Linked there: ${linked.join(", ")}.\n`
+          : `  Nothing is linked there.\n`) +
+        `  Run 'sous repo link ${name}' to link it.`
+    );
+  }
+}