@sous-io/sous 0.2.36 → 1.0.1

package/src/commands/vars/ask.ts

@@ -1,417 +0,0 @@
-/**
- * `sous vars ask [name]`.
- *
- * Asks the questions the project's variable definitions imply and stores the
- * answers in `.sous/.env` or `.sous/.env.local`. By default it asks only what
- * is unanswered or no longer fits; `--all` asks everything again.
- *
- * The optional name is a reference, resolved through `src/services/ref-resolver/` exactly as
- * every other command resolves one. It may name a variable, an environment
- * variable that answers one, a recipe, a namespace or a repository, at any
- * level of qualification; naming anything larger than a variable asks every
- * question that thing publishes:
- *
- *     sous vars ask taskFileRoot                 one variable
- *     sous vars ask SOUS_VAR_TASK_FILE_ROOT      the variable that name answers
- *     sous vars ask task-files                   every question one recipe asks
- *     sous vars ask workflow                     every question one namespace asks
- *     sous vars ask sous-recipes                 every question one repository asks
- *
- * `--repo`, `--namespace` and `--var` say outright which kind of thing is
- * meant, and narrow the same way. A reference that means more than one thing is
- * offered as a list to choose between; `--accept-first` takes the first, and a
- * run with no terminal fails naming that flag.
- *
- * `--file` reads a standalone definitions file instead of the project's
- * recipes, which is how a project asks questions no recipe publishes yet.
- *
- * Answers can be supplied ahead of the questions with `--answer name=value` or
- * `--answers-file <path>`; whatever they answer is stored before anything is
- * asked, and only what is left over is asked for.
- *
- * Without a terminal the command never hangs waiting on a prompt: it fails and
- * names the exact environment variables that would answer each question.
- */
-
-import path from "node:path";
-import { Args, Flags } from "@oclif/core";
-import { BaseCommand } from "../../base-command.js";
-import { ConfigError } from "../../lib/errors.js";
-import {
-  ChainedLookup,
-  RefPickArguments,
-  RefResolveArguments,
-  VariableLookup,
-  namespaceOf,
-  recipeOf,
-  refKey,
-  repoOf,
-  sharedRefPicker,
-  sharedRefResolver,
-  variableRefOf,
-  type CatalogRepo,
-  type RefKind,
-  type SousRef,
-} from "../../services/ref-resolver/index.js";
-import { EnvVarLookup } from "../../services/ref-resolver/lookups/env-var-lookup.js";
-import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
-import {
-  applyProvidedAnswers,
-  askForMissing,
-  collectProvidedAnswers,
-  FileDefinitionSource,
-  formatAskReport,
-  loadLadderContext,
-  loadProjectDefinitions,
-  unknownAnswerError,
-  type DefinedVariable,
-} from "../../lib/vars/index.js";
-import type { LadderContext } from "../../lib/vars/ladder.js";
-import {
-  blankLine,
-  dryRunNotice,
-  footer,
-  heading,
-  indent,
-  log,
-  showCommandVars,
-} from "../../utils/formatting.js";
-import { answerFlags } from "../../utils/flags.js";
-
-/** What the caller said should be asked: the reference, and the three flags. */
-type Selection = {
-  /** The reference argument, when one was given. */
-  name?: string;
-  /** The repository named by `--repo`. */
-  repo?: string;
-  /** The namespace named by `--namespace`. */
-  namespace?: string;
-  /** Every variable named by `--var`. */
-  vars?: string[];
-  /** Take the first match rather than asking which was meant. */
-  acceptFirst: boolean;
-};
-
-/** The line every "this matched nothing" error ends with. */
-const SEE_ALL = "  Run 'sous vars' to see every variable this project's recipes define.";
-
-export default class VarsAsk extends BaseCommand {
-  static description =
-    "Answer the variables this project's recipes define, storing the answers in the .sous env files";
-
-  /**
-   * 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 = ["var:ask"];
-
-  static examples = [
-    "<%= config.bin %> vars ask",
-    "<%= config.bin %> vars ask apiUrl",
-    "<%= config.bin %> vars ask SOUS_VAR_API_URL",
-    "<%= config.bin %> vars ask workflow/task-files",
-    "<%= config.bin %> vars ask workflow --accept-first",
-    "<%= config.bin %> vars ask --namespace workflow --var apiUrl",
-    "<%= config.bin %> vars ask --all",
-    "<%= config.bin %> vars ask --file ./questions.yaml",
-    "<%= config.bin %> vars ask --answer apiUrl=https://api.example.com",
-    "<%= config.bin %> vars ask --answers-file ./answers.yaml",
-  ];
-
-  static args = {
-    name: Args.string({
-      description:
-        "What to ask about: a variable, an environment variable name, a recipe, a namespace or a repository",
-      required: false,
-    }),
-  };
-
-  static flags = {
-    ...BaseCommand.baseFlags,
-    all: Flags.boolean({
-      description: "Ask every variable again, including the ones already answered",
-      default: false,
-    }),
-    repo: Flags.string({
-      description: "Ask only the variables published by this repository",
-    }),
-    namespace: Flags.string({
-      description: "Ask only the variables published in this namespace",
-    }),
-    var: Flags.string({
-      description: "Ask only this variable. Repeat it for each variable",
-      multiple: true,
-    }),
-    "accept-first": Flags.boolean({
-      description: "When a name matches several things, take the first one listed",
-      default: false,
-    }),
-    file: Flags.string({
-      description:
-        "Read the variable definitions from a standalone definitions file instead of the project's recipes",
-    }),
-    "dry-run": Flags.boolean({
-      description: "Report what would be asked and written, without writing anything",
-      default: false,
-    }),
-    ...answerFlags(),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(VarsAsk);
-    const dryRun = flags["dry-run"];
-
-    const selection: Selection = {
-      ...(args.name === undefined ? {} : { name: args.name }),
-      ...(flags.repo === undefined ? {} : { repo: flags.repo }),
-      ...(flags.namespace === undefined ? {} : { namespace: flags.namespace }),
-      ...(flags.var === undefined ? {} : { vars: flags.var }),
-      acceptFirst: flags["accept-first"],
-    };
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Definitions: flags.file ?? "the project's subscribed recipes",
-      Asking: describeSelection(selection, flags.all),
-    });
-
-    if (dryRun) dryRunNotice("No answers will be written.");
-
-    const provided = collectProvidedAnswers({
-      ...(flags.answer === undefined ? {} : { answer: flags.answer }),
-      ...(flags["answers-file"] === undefined
-        ? {}
-        : { answersFile: flags["answers-file"] }),
-    });
-
-    const source =
-      flags.file === undefined
-        ? loadProjectDefinitions(this.settings, this.configContext.sousDir)
-        : new FileDefinitionSource(path.resolve(process.cwd(), flags.file));
-    const defined = await source.load();
-
-    heading("Answering variables");
-    blankLine();
-
-    if (defined.length === 0) {
-      // A supplied answer names a variable nothing declares, which is a typo
-      // until proven otherwise; it fails rather than passing unnoticed.
-      if (provided[0] !== undefined) throw unknownAnswerError(provided[0], defined);
-
-      log(
-        indent(
-          "No recipe in this project defines any variables yet, so there is nothing " +
-            "to ask. Subscribe to a recipe that publishes some, or read a definitions " +
-            "file with --file."
-        )
-      );
-      footer();
-      return;
-    }
-
-    const context = loadLadderContext({
-      sousDir: this.configContext.sousDir,
-      settings: this.settings,
-      shellEnv: this.shellEnv,
-    });
-
-    // What the reference and the flags name, as the fully qualified reference of
-    // every variable to ask. Undefined means everything the usual rules pick.
-    // A reference written as a location settles against the trusted
-    // repositories, read from the cached indexes; a definitions file has none.
-    const trusted = flags.file === undefined ? this.trustedRepos() : [];
-    const only = await this.resolveSelection(defined, context, selection, trusted);
-
-    const askOptions = {
-      sousDir: this.configContext.sousDir,
-      // A project whose conf.d directory has never existed still gets one when
-      // a mapping record needs writing; the writer creates it.
-      confDir:
-        this.configContext.confDir ?? path.join(this.configContext.sousDir, "conf.d"),
-      interactive: this.interactive,
-      dryRun,
-    };
-
-    // Answers supplied on the command line are validated and stored before any
-    // question is asked, so what is left is exactly what nobody answered.
-    const supplied = applyProvidedAnswers(defined, provided, context, askOptions);
-
-    const report = await askForMissing(defined, context, {
-      ...askOptions,
-      ...(only === undefined ? {} : { only }),
-      skip: supplied.keys,
-      reask: flags.all,
-    });
-    report.answered.unshift(...supplied.stored);
-
-    blankLine();
-    for (const line of formatAskReport(report, dryRun)) {
-      log(line === "" ? "" : indent(line));
-    }
-
-    footer();
-  }
-
-  /**
-   * Turns the reference and the three narrowing flags into the exact set of
-   * variables to ask, as fully qualified references.
-   *
-   * Each step narrows the pool and the next step resolves against what is left,
-   * so `--namespace workflow apiUrl` asks about the `apiUrl` of that namespace
-   * even when another namespace declares one too. A step that narrows the pool
-   * to nothing is an error naming what did it, rather than a run that silently
-   * asks no questions.
-   *
-   * @param defined - Every variable definition in play.
-   * @param ladder - The environment layers, for resolving environment variable names.
-   * @param selection - The reference and the flags, as the caller wrote them.
-   * @param trusted - The trusted repositories, which settle a reference written as a location.
-   * @returns The variables to ask, or undefined when nothing narrowed anything.
-   */
-  private async resolveSelection(
-    defined: DefinedVariable[],
-    ladder: LadderContext,
-    selection: Selection,
-    trusted: CatalogRepo[] = []
-  ): Promise<string[] | undefined> {
-    const lookupOf = (pool: DefinedVariable[]) =>
-      new ChainedLookup(new VariableLookup(pool, trusted), new EnvVarLookup(pool, ladder));
-    const { name, repo, namespace, vars } = selection;
-    if (name === undefined && repo === undefined && namespace === undefined && vars === undefined) {
-      return undefined;
-    }
-
-    let pool = defined;
-
-    if (repo !== undefined) {
-      const match = await this.pick(repo, lookupOf(pool), ["repo"], selection);
-      pool = pool.filter((entry) => entry.recipe.repo === repoOf(match)?.name);
-    }
-
-    if (namespace !== undefined) {
-      const match = await this.pick(namespace, lookupOf(pool), ["namespace"], selection);
-      pool = narrowTo(pool, match);
-    }
-
-    if (name !== undefined) {
-      const match = await this.pick(name, lookupOf(pool), undefined, selection);
-      pool = narrowTo(pool, match);
-    }
-
-    if (vars !== undefined) {
-      const chosen: DefinedVariable[] = [];
-      for (const wanted of vars) {
-        const match = await this.pick(wanted, lookupOf(pool), ["variable", "envVar"], selection);
-        chosen.push(...narrowTo(pool, match));
-      }
-      pool = chosen;
-    }
-
-    if (pool.length === 0) {
-      throw new ConfigError(
-        `Nothing is left to ask: ${describeSelection(selection, false)} names no ` +
-          `variable this project holds.\n${SEE_ALL}`
-      );
-    }
-
-    return [...new Set(pool.map((entry) => refKey(variableRefOf(entry))))];
-  }
-
-  /**
-   * The trusted repositories as a reference searches them, from the cached
-   * indexes alone. A project whose repositories cannot be read this way still
-   * answers every other form of reference, so a failure here is an empty list.
-   */
-  private trustedRepos(): CatalogRepo[] {
-    try {
-      return subscriptionServiceFor({
-        configContext: this.configContext,
-        settings: this.settings,
-        shellEnv: this.shellEnv,
-      }).cachedReferenceRepos();
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Settles which of the things a reference could have meant this run proceeds
-   * with, through the rule every command shares.
-   *
-   * @param search - The reference exactly as it was written.
-   * @param lookup - What the reference is searched in.
-   * @param kinds - The kinds of ref this step accepts; every kind when left out.
-   * @param selection - The selection, read for `--accept-first`.
-   */
-  private async pick(
-    search: string,
-    lookup: ChainedLookup,
-    kinds: readonly RefKind[] | undefined,
-    selection: Selection
-  ): Promise<SousRef> {
-    const { refs } = await sharedRefResolver().resolve(
-      new RefResolveArguments({
-        input: search,
-        lookup,
-        refusedIsEmpty: true,
-        ...(kinds === undefined ? {} : { kinds }),
-      })
-    );
-    // A name that answers several variables is one candidate per variable, so
-    // choosing between them is the same question as choosing between variables.
-    const candidates = refs.flatMap((ref) =>
-      ref.kind === "envVar" && (ref.variables?.length ?? 0) > 1
-        ? ref.variables!.map((variable): SousRef => ({ ...ref, variables: [variable] }))
-        : [ref]
-    );
-    return sharedRefPicker().pick(
-      candidates,
-      new RefPickArguments({
-        search,
-        interactive: this.interactive,
-        acceptFirst: selection.acceptFirst,
-        announce: false,
-        details: [SEE_ALL],
-      })
-    );
-  }
-}
-
-/**
- * The variables one ref covers: a whole repository, namespace, recipe, or one
- * variable, or the variable an environment variable name answers.
- */
-function narrowTo(pool: DefinedVariable[], match: SousRef): DefinedVariable[] {
-  const target = match.kind === "envVar" ? match.variables?.[0] : match;
-  if (target === undefined) return [];
-  const repo = repoOf(target)?.name;
-  const namespace = namespaceOf(target)?.name;
-  const recipe = recipeOf(target)?.name;
-
-  return pool.filter((entry) => {
-    if (repo !== undefined && entry.recipe.repo !== repo) return false;
-    if (target.kind === "repo") return true;
-
-    if (namespace !== undefined && entry.recipe.namespace !== namespace) return false;
-    if (target.kind === "namespace") return true;
-
-    if (recipe !== undefined && entry.recipe.name !== recipe) return false;
-    if (target.kind === "recipe") return true;
-
-    return target.kind === "variable" && entry.definition.name === target.name;
-  });
-}
-
-
-/** What this run is asking about, in the words the header shows. */
-function describeSelection(selection: Selection, all: boolean): string {
-  const parts: string[] = [];
-  if (selection.repo !== undefined) parts.push(`the repository '${selection.repo}'`);
-  if (selection.namespace !== undefined) parts.push(`the namespace '${selection.namespace}'`);
-  if (selection.name !== undefined) parts.push(`'${selection.name}'`);
-  for (const wanted of selection.vars ?? []) parts.push(`the variable '${wanted}'`);
-
-  if (parts.length === 0) return all ? "every variable" : "everything unanswered";
-  return parts.join(", ");
-}

package/src/commands/vars/index.ts

@@ -1,79 +0,0 @@
-/**
- * Bare `sous vars`, and `sous vars <name>`.
- *
- * The canonical commands are `sous vars list` and `sous vars show <name>`; this
- * is the shorthand that keeps working, so it prints the listing with no argument
- * and the detail with one. It is hidden from the command list so `sous --help`
- * names `vars` once, as a topic.
- *
- * The optional argument works because oclif collates leading space-separated
- * words into a command id only while they keep matching a real command:
- * `sous vars show` finds the `vars:show` command, and `sous vars apiUrl` does
- * not, so it lands here with `apiUrl` as the argument. The one consequence is
- * that a variable named `list`, `show` or `ask` cannot be reached this way;
- * `sous vars show list` reaches it.
- */
-
-import path from "node:path";
-import { Args, Flags } from "@oclif/core";
-import { BaseCommand } from "../../base-command.js";
-import {
-  FileDefinitionSource,
-  loadLadderContext,
-  loadProjectDefinitions,
-  printVariableDetail,
-  printVariableList,
-} from "../../lib/vars/index.js";
-import { footer, showCommandVars } from "../../utils/formatting.js";
-
-export default class Vars extends BaseCommand {
-  static description = "List every variable this project's recipes define, with its answer";
-
-  /** Hidden so `sous --help` names `vars` once, as a topic. */
-  static hidden = true;
-
-  static examples = ["<%= config.bin %> vars", "<%= config.bin %> vars apiUrl"];
-
-  static args = {
-    name: Args.string({
-      description:
-        "A variable's name (or its namespace/recipe.name key) to show in full",
-      required: false,
-    }),
-  };
-
-  static flags = {
-    ...BaseCommand.baseFlags,
-    file: Flags.string({
-      description:
-        "Read the variable definitions from a standalone definitions file instead of the project's recipes",
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(Vars);
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Definitions: flags.file ?? "the project's subscribed recipes",
-    });
-
-    const source =
-      flags.file === undefined
-        ? loadProjectDefinitions(this.settings, this.configContext.sousDir)
-        : new FileDefinitionSource(path.resolve(process.cwd(), flags.file));
-    const defined = await source.load();
-
-    const context = loadLadderContext({
-      sousDir: this.configContext.sousDir,
-      settings: this.settings,
-      shellEnv: this.shellEnv,
-    });
-
-    if (args.name === undefined) printVariableList(defined, context);
-    else printVariableDetail(defined, context, args.name);
-
-    footer();
-  }
-}

package/src/commands/vars/list.ts

@@ -1,67 +0,0 @@
-/**
- * `sous vars list`.
- *
- * Prints every variable in play: what it is called, which recipe published it,
- * the environment variable that answered it, the value (hidden when the
- * definition says the variable is a secret), and where the value came from.
- */
-
-import path from "node:path";
-import { Flags } from "@oclif/core";
-import { BaseCommand } from "../../base-command.js";
-import {
-  FileDefinitionSource,
-  loadLadderContext,
-  loadProjectDefinitions,
-  printVariableList,
-} from "../../lib/vars/index.js";
-import { footer, showCommandVars } from "../../utils/formatting.js";
-
-export default class VarsList extends BaseCommand {
-  static description = "List every variable this project's recipes define, with its answer";
-
-  /**
-   * 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 = ["var:list"];
-
-  static examples = [
-    "<%= config.bin %> vars list",
-    "<%= config.bin %> vars list --file ./questions.yaml",
-  ];
-
-  static flags = {
-    ...BaseCommand.baseFlags,
-    file: Flags.string({
-      description:
-        "Read the variable definitions from a standalone definitions file instead of the project's recipes",
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { flags } = await this.parse(VarsList);
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Definitions: flags.file ?? "the project's subscribed recipes",
-    });
-
-    const source =
-      flags.file === undefined
-        ? loadProjectDefinitions(this.settings, this.configContext.sousDir)
-        : new FileDefinitionSource(path.resolve(process.cwd(), flags.file));
-
-    printVariableList(
-      await source.load(),
-      loadLadderContext({
-        sousDir: this.configContext.sousDir,
-        settings: this.settings,
-        shellEnv: this.shellEnv,
-      })
-    );
-
-    footer();
-  }
-}

package/src/commands/vars/show.ts

@@ -1,77 +0,0 @@
-/**
- * `sous vars show <name>`.
- *
- * Prints everything about one variable: the question it asks, its documentation
- * and constraints, the recipe that published it, where an answer would be
- * stored, every environment variable name on the resolution ladder, and which
- * rung actually answered.
- */
-
-import path from "node:path";
-import { Args, Flags } from "@oclif/core";
-import { BaseCommand } from "../../base-command.js";
-import {
-  FileDefinitionSource,
-  loadLadderContext,
-  loadProjectDefinitions,
-  printVariableDetail,
-} from "../../lib/vars/index.js";
-import { footer, showCommandVars } from "../../utils/formatting.js";
-
-export default class VarsShow extends BaseCommand {
-  static description = "Show everything about one variable, including how it was answered";
-
-  /**
-   * 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 = ["var:show"];
-
-  static examples = [
-    "<%= config.bin %> vars show apiUrl",
-    "<%= config.bin %> vars show workflow/task-files.apiUrl",
-  ];
-
-  static args = {
-    name: Args.string({
-      description: "A variable's name, or its namespace/recipe.name key",
-      required: true,
-    }),
-  };
-
-  static flags = {
-    ...BaseCommand.baseFlags,
-    file: Flags.string({
-      description:
-        "Read the variable definitions from a standalone definitions file instead of the project's recipes",
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { args, flags } = await this.parse(VarsShow);
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Definitions: flags.file ?? "the project's subscribed recipes",
-    });
-
-    const source =
-      flags.file === undefined
-        ? loadProjectDefinitions(this.settings, this.configContext.sousDir)
-        : new FileDefinitionSource(path.resolve(process.cwd(), flags.file));
-
-    printVariableDetail(
-      await source.load(),
-      loadLadderContext({
-        sousDir: this.configContext.sousDir,
-        settings: this.settings,
-        shellEnv: this.shellEnv,
-      }),
-      args.name,
-      { sousDir: this.configContext.sousDir }
-    );
-
-    footer();
-  }
-}

package/src/config-command.ts

@@ -1,30 +0,0 @@
-import { BaseCommand } from "./base-command.js";
-import { headerTo } from "./utils/formatting.js";
-
-/**
- * Base class for the `sous config *` inspection commands (`show`, `get`).
- *
- * These commands emit machine-readable output (JSON, or a raw scalar) to stdout
- * so `sous config show | jq` and friends work. The decorative CLI header would
- * otherwise land on stdout during BaseCommand.init() and corrupt that output, so
- * it is routed to stderr here instead. Discovery, env loading, flag parsing and
- * ConfigError rendering are all inherited unchanged from BaseCommand.
- */
-export abstract class ConfigCommand extends BaseCommand {
-  private static writeStderr(line: string): void {
-    process.stderr.write(`${line}\n`);
-  }
-
-  protected emitHeader(): void {
-    headerTo(ConfigCommand.writeStderr);
-  }
-
-  /**
-   * Route init()/catch() error rendering to stderr too. Otherwise a discovery or
-   * config-load failure (a not-found config, an invalid merged config, or a
-   * missing `config get` path) would print the red error block to stdout for the
-   * very commands whose contract is clean, machine-readable stdout — corrupting
-   * `sous config show | jq` and any script capturing stdout.
-   */
-  protected errorSink: (line: string) => void = ConfigCommand.writeStderr;
-}