@stealthscale/tool-cli 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,513 @@
+import { CommandDef, CommandMeta } from "citty";
+import { Manifest } from "@stealthscale/tool-workspace";
+//#region src/cli.d.ts
+/**
+ * Reads what a command calls itself off the manifest of the package that ships it, so the
+ * name, the summary and the version have one source.
+ *
+ * @param {Manifest} manifest - The manifest of the package that ships the bin.
+ * @returns {CommandMeta} The first command the manifest installs, its summary and its version.
+ */
+declare function commandMeta(manifest: Manifest): CommandMeta;
+/**
+ * The `stealth` command: the bin's name, its own version, and the subcommands under it.
+ */
+declare const stealth: CommandDef;
+//#endregion
+//#region src/release/changesets.d.ts
+/**
+ * Describes one published package, in the shape changesets/action reads. Every field is
+ * theirs, `type` included, and an entry it does not recognise it skips.
+ */
+interface TagEvent {
+  /**
+   * Names the package the tag belongs to.
+   */
+  packageName: string;
+  /**
+   * Names the tag to create: `<name>@<version>`, which is what changesets tags a package
+   * in a workspace of several.
+   */
+  tag: string;
+  /**
+   * Marks the entry as a tag. It is the only kind the action reads.
+   */
+  type: 'git-tag';
+}
+/**
+ * Builds the entry for one published package.
+ *
+ * @param {Manifest} manifest - The package that went out.
+ * @returns {TagEvent} The entry, naming the package and its tag.
+ */
+declare function tagEvent(manifest: Manifest): TagEvent;
+/**
+ * Writes the entries where changesets/action reads them, one JSON object per line.
+ *
+ * A run that published nothing still writes the file, empty. The action reports a file it
+ * cannot read as a warning and then creates no tag for anything, so an empty file and a
+ * missing one differ.
+ *
+ * @param {string} file - The path the action handed the run, from `CHANGESETS_OUTPUT`.
+ * @param {readonly TagEvent[]} events - One entry per published package.
+ */
+declare function writeTagEvents(file: string, events: readonly TagEvent[]): void;
+//#endregion
+//#region src/shell/shell.d.ts
+/**
+ * @fileoverview Runs the commands the `stealth` tool needs: bun, npm and a registry, as real
+ * processes that the tool owns. A specification hands the tool a shell that records instead.
+ */
+/**
+ * Describes what a finished command left behind.
+ */
+interface CommandOutcome {
+  /**
+   * Carries the exit code. It is `1` when the command could not start or a signal killed it.
+   */
+  code: number;
+  /**
+   * Carries everything the command wrote to stderr.
+   */
+  stderr: string;
+  /**
+   * Carries everything the command wrote to stdout.
+   */
+  stdout: string;
+}
+/**
+ * Describes where a command runs and what it sees.
+ */
+interface RunOptions {
+  /**
+   * Names the working directory.
+   */
+  cwd: string;
+  /**
+   * Adds variables to this process's environment for the command.
+   */
+  env?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Describes where a long-lived process runs and where its output goes.
+ */
+interface StartOptions extends RunOptions {
+  /**
+   * Names the file its stdout and stderr are appended to.
+   */
+  log: string;
+}
+/**
+ * Describes a process the tool started and so may stop.
+ */
+interface StartedProcess {
+  /**
+   * Carries the process id, so the tool stops exactly what it started. It is `0` when the
+   * process never started.
+   */
+  pid: number;
+  /**
+   * Ends the process and resolves once it has exited.
+   *
+   * It sends `SIGTERM` first and gives the process five seconds to leave on its own, then
+   * sends `SIGKILL`, so a child that traps the first signal cannot hold the tool open. It
+   * resolves after the exit either way, and closing the log file is part of that exit.
+   *
+   * @returns {Promise<void>} Resolves after the exit.
+   */
+  stop: () => Promise<void>;
+}
+/**
+ * Describes how the tool runs commands. A specification hands one that answers.
+ */
+interface Shell {
+  /**
+   * Finds a port nothing is listening on right now.
+   *
+   * @returns {Promise<number>} A port that was free when asked.
+   */
+  freePort: () => Promise<number>;
+  /**
+   * Runs a command to completion and returns what it wrote. A non-zero exit does not throw.
+   *
+   * @param {string} file - The executable.
+   * @param {readonly string[]} args - The arguments.
+   * @param {RunOptions} options - The working directory and the environment.
+   * @returns {Promise<CommandOutcome>} The exit code and both streams.
+   */
+  run: (file: string, args: readonly string[], options: RunOptions) => Promise<CommandOutcome>;
+  /**
+   * Starts a long-lived process. Its output goes to the log file.
+   *
+   * @param {string} file - The executable.
+   * @param {readonly string[]} args - The arguments.
+   * @param {StartOptions} options - The working directory, the environment and the log file.
+   * @returns {StartedProcess} The process, with its pid and a way to stop it.
+   */
+  start: (file: string, args: readonly string[], options: StartOptions) => StartedProcess;
+}
+/**
+ * Builds the shell the tool runs under: real processes and real ports. `start` returns the
+ * very process it spawned, so `stop` never reaches a process somebody else owns.
+ *
+ * @returns {Shell} A shell backed by real processes and real ports.
+ */
+declare function shell(): Shell;
+//#endregion
+//#region src/release/command.d.ts
+/**
+ * What `stealth release` takes from the command line.
+ *
+ * The registry and the token are absent by default: npm reads its own configuration, and a
+ * manifest's `publishConfig` overrides it per package. Naming either here is for a run that
+ * publishes somewhere else, such as a local registry in a smoke test.
+ */
+declare const RELEASE_ARGS: {
+  readonly 'dry-run': {
+    readonly default: false;
+    readonly description: 'Report what would be published, and publish nothing.';
+    readonly type: 'boolean';
+  };
+  readonly provenance: {
+    readonly default: false;
+    readonly description: "Attest provenance through the CI job's token. Npm refuses it elsewhere.";
+    readonly type: 'boolean';
+  };
+  readonly registry: {
+    readonly description: 'Publish to this registry instead of the one npm is configured for.';
+    readonly type: 'string';
+    readonly valueHint: 'url';
+  };
+  readonly tarballs: {
+    readonly description: 'Write the tarballs here instead of a new temporary directory.';
+    readonly type: 'string';
+    readonly valueHint: 'dir';
+  };
+  readonly userconfig: {
+    readonly description: "Read npm's configuration, and so the token, from this file.";
+    readonly type: 'string';
+    readonly valueHint: 'file';
+  };
+};
+/**
+ * Describes everything the release command reaches outside itself.
+ */
+interface ReleaseDeps {
+  /**
+   * Names the file changesets/action reads the published tags from, which it hands the run
+   * in `CHANGESETS_OUTPUT`. Outside that action there is nothing to tell and nothing here.
+   */
+  changesetsOutput: string | undefined;
+  /**
+   * Names the directory the command was run in, which is where the workspace is looked for.
+   */
+  cwd: string;
+  /**
+   * Asks a registry what it already holds.
+   */
+  fetch: typeof fetch;
+  /**
+   * Writes the report where a person reads it. Whatever it answers is not read, so a stream's
+   * own `write` is passed straight in.
+   */
+  log: (text: string) => unknown;
+  /**
+   * Runs bun and npm.
+   */
+  shell: Shell;
+}
+/**
+ * Builds the release command against the outside world it is given.
+ *
+ * @param {ReleaseDeps} deps - The workspace, the registry, the shell and where to write.
+ * @returns {CommandDef} The command, ready to hand to citty.
+ */
+declare function releaseCommandWith(deps: ReleaseDeps): CommandDef<typeof RELEASE_ARGS>;
+/**
+ * The release command as the `stealth` bin runs it: this process, the real registry, a real
+ * shell and the terminal.
+ */
+declare const releaseCommand: CommandDef<{
+  readonly 'dry-run': {
+    readonly default: false;
+    readonly description: 'Report what would be published, and publish nothing.';
+    readonly type: 'boolean';
+  };
+  readonly provenance: {
+    readonly default: false;
+    readonly description: "Attest provenance through the CI job's token. Npm refuses it elsewhere.";
+    readonly type: 'boolean';
+  };
+  readonly registry: {
+    readonly description: 'Publish to this registry instead of the one npm is configured for.';
+    readonly type: 'string';
+    readonly valueHint: 'url';
+  };
+  readonly tarballs: {
+    readonly description: 'Write the tarballs here instead of a new temporary directory.';
+    readonly type: 'string';
+    readonly valueHint: 'dir';
+  };
+  readonly userconfig: {
+    readonly description: "Read npm's configuration, and so the token, from this file.";
+    readonly type: 'string';
+    readonly valueHint: 'file';
+  };
+}>;
+//#endregion
+//#region src/report/report.d.ts
+/**
+ * @fileoverview Records what a run of the tool did, step by step, and renders it for a
+ * terminal: one line per step, the reason under a failure, and where the run's files are.
+ */
+/**
+ * Describes one thing a run did, and how it went.
+ */
+interface Step {
+  /**
+   * Carries what was found or what went wrong. It is empty when there is nothing to add.
+   */
+  detail: string;
+  /**
+   * Names the stage and its subject: `publish @stealthscale/core-schema@0.1.0`.
+   */
+  name: string;
+  /**
+   * Marks whether the step went as it should.
+   */
+  ok: boolean;
+}
+/**
+ * Describes everything a run did, in order, and where its files are.
+ */
+interface Report {
+  /**
+   * Lists the steps in the order they ran.
+   */
+  steps: readonly Step[];
+  /**
+   * Names the directory that holds the run's tarballs and logs, kept for reading after a
+   * failure.
+   */
+  workdir: string;
+}
+/**
+ * Builds a step that went as it should.
+ *
+ * @param {string} name - The stage and its subject.
+ * @param {string} [detail] - Text worth reading even so, such as a checker's warnings.
+ *     Default: nothing.
+ * @returns {Step} The step.
+ */
+declare function passed(name: string, detail?: string): Step;
+/**
+ * Builds a step that did not go as it should.
+ *
+ * @param {string} name - The stage and its subject.
+ * @param {string} detail - The reason: the command's last lines, or what was found wanting.
+ * @returns {Step} The step.
+ */
+declare function failed(name: string, detail: string): Step;
+/**
+ * Lists the steps of a run that failed.
+ *
+ * @param {Report} report - The run.
+ * @returns {Step[]} The failed steps, in order.
+ */
+declare function failures(report: Report): Step[];
+/**
+ * Keeps the end of what a command wrote, which is where the reason usually is. Stack frames
+ * go first: a bundler's failure is one line of cause over thirty lines of frames.
+ *
+ * @param {string} output - Everything the command wrote, both streams together.
+ * @param {number} [keep] - How many lines to keep at most. Default: 20.
+ * @returns {string} The last lines, with blank lines at either end dropped.
+ */
+declare function lastLines(output: string, keep?: number): string;
+/**
+ * Renders a report as text: one line per step, a step's detail indented under it, then the
+ * count and, when something failed, where to look.
+ *
+ * @param {Report} report - The run.
+ * @returns {string} The text, ending in a newline.
+ */
+declare function render(report: Report): string;
+//#endregion
+//#region src/release/packages.d.ts
+/**
+ * Describes a package that was packed, and where its tarball is.
+ */
+interface Packed {
+  /**
+   * Carries the package's manifest.
+   */
+  manifest: Manifest;
+  /**
+   * Names the tarball, absolute.
+   */
+  tarball: string;
+}
+/**
+ * Describes how one tarball is published.
+ */
+interface PublishOptions {
+  /**
+   * Says what would be published, and publishes nothing.
+   */
+  dryRun: boolean;
+  /**
+   * Attests provenance through the CI job's OIDC token. Npm refuses it outside a CI it
+   * knows.
+   */
+  provenance: boolean;
+  /**
+   * Names the registry to ask and to publish to, with or without its trailing slash. Left
+   * out, npm is asked in the directory the publish runs in for the registry it is configured
+   * for. A manifest's `publishConfig.registry` wins over both, because npm reads it from the
+   * tarball.
+   */
+  registry?: string | undefined;
+  /**
+   * Names an npm user config that holds the registry's token. Without one, npm uses its own
+   * login or the CI's OIDC token.
+   */
+  userconfig?: string | undefined;
+}
+/**
+ * Describes what packing one package came to.
+ */
+interface PackResult {
+  /**
+   * Carries the tarball, when bun wrote one.
+   */
+  packed?: Packed | undefined;
+  /**
+   * Carries the step, with the tarball's path or bun's last lines as its detail.
+   */
+  step: Step;
+}
+/**
+ * Lists the paths a manifest's `files` names that are missing from the package. A glob
+ * entry names no one path and is not checked; a manifest without `files` names nothing.
+ *
+ * @param {Manifest} manifest - The package to check.
+ * @returns {string[]} The missing paths, relative to the package, in `files` order.
+ */
+declare function missingFiles(manifest: Manifest): string[];
+/**
+ * Packs one built package into the destination directory.
+ *
+ * @param {Manifest} manifest - The package to pack.
+ * @param {string} destination - The directory the tarball goes into.
+ * @param {Shell} shell - The shell that runs bun.
+ * @param {ReadonlyMap<string, string>} [versions] - Each workspace package mapped to the
+ *     version it is being published at. Default: none, leaving every range as written.
+ * @returns {Promise<PackResult>} The step, and the tarball when there is one.
+ */
+declare function pack(manifest: Manifest, destination: string, shell: Shell, versions?: ReadonlyMap<string, string>): Promise<PackResult>;
+/**
+ * Publishes one tarball with npm. The token, when there is one, travels in a user config
+ * file npm is pointed at, so nothing else npm reads is touched.
+ *
+ * The run's registry is passed on the command line rather than the manifest's. Npm reads
+ * `publishConfig.registry` out of the tarball and lets it win over the flag, which is the
+ * rule the asking side applies as well.
+ *
+ * @param {string} tarball - The tarball to publish, absolute.
+ * @param {string} cwd - The directory npm runs in.
+ * @param {PublishOptions} options - How to publish. `PublishOptions` documents every member.
+ * @param {Shell} shell - The shell that runs npm.
+ * @returns {Promise<CommandOutcome>} Npm's exit code and both streams.
+ */
+declare function publishTarball(tarball: string, cwd: string, options: PublishOptions, shell: Shell): Promise<CommandOutcome>;
+//#endregion
+//#region src/release/registry.d.ts
+/**
+ * Ends a registry URL with the slash bun and npm write.
+ *
+ * @param {string} url - The registry as npm or a manifest names it.
+ * @returns {string} The URL with exactly one trailing slash.
+ */
+declare function withTrailingSlash(url: string): string;
+/**
+ * Asks npm for the registry it is configured to publish to.
+ *
+ * Ask this in the directory the publish will run in. Npm reads its configuration, and the
+ * manifest beside it, from where it runs, so asking anywhere else can name a registry the
+ * publish will not use, and asking in a workspace whose manifest names another package
+ * manager makes npm refuse outright.
+ *
+ * @param {Shell} shell - The shell that runs npm.
+ * @param {string} cwd - The directory the publish will run in.
+ * @returns {Promise<string>} The registry, with its trailing slash.
+ * @throws {Error} When npm names no registry.
+ */
+declare function configuredRegistry(shell: Shell, cwd: string): Promise<string>;
+/**
+ * Returns `true` when the registry already holds this version of the package.
+ *
+ * @param {string} registry - The registry, with its trailing slash.
+ * @param {Manifest} manifest - The package to ask about.
+ * @param {typeof fetch} fetchImpl - The fetch that asks the registry.
+ * @returns {Promise<boolean>} `true` when that exact version is there.
+ * @throws {Error} When the registry answers with anything but the package or a 404.
+ */
+declare function registryHasVersion(registry: string, manifest: Manifest, fetchImpl: typeof fetch): Promise<boolean>;
+//#endregion
+//#region src/release/release.d.ts
+/**
+ * Describes what the release set came to.
+ */
+interface ReleaseSet {
+  /**
+   * Lists the private packages the set depends on, which a consumer could never install.
+   */
+  hidden: string[];
+  /**
+   * Lists the public packages, dependencies before their dependents.
+   */
+  ordered: Manifest[];
+}
+/**
+ * Describes what a release run is told. `PublishOptions` documents the members it inherits,
+ * the registry among them.
+ */
+interface ReleaseOptions extends PublishOptions {
+  /**
+   * Names the file changesets/action reads the published tags from, as it handed it over in
+   * `CHANGESETS_OUTPUT`. Left out, a run tells nothing and no tag is created.
+   */
+  changesetsOutput?: string | undefined;
+  /**
+   * Asks the registry whether it has a version already.
+   */
+  fetch: typeof fetch;
+  /**
+   * Names the workspace root.
+   */
+  root: string;
+  /**
+   * Names the directory the tarballs go into.
+   */
+  tarballs: string;
+}
+/**
+ * Collects the release set: every public package of the workspace and every workspace
+ * package it depends on, dependencies before dependents.
+ *
+ * @param {string} root - The workspace root.
+ * @returns {ReleaseSet} The set, and the private packages it would need and cannot have.
+ */
+declare function releaseSet(root: string): ReleaseSet;
+/**
+ * Releases every package of the set the registry does not have yet, packed and published in
+ * dependency order. It refuses the whole set when the set depends on a private package.
+ *
+ * @param {ReleaseOptions} options - The registry, how to publish, the workspace and where
+ *     the tarballs go.
+ * @param {Shell} shell - The shell that runs bun and npm.
+ * @returns {Promise<Report>} Every step, in order.
+ */
+declare function release(options: ReleaseOptions, shell: Shell): Promise<Report>;
+//#endregion
+export { type CommandOutcome, type PackResult, type Packed, type PublishOptions, type ReleaseDeps, type ReleaseOptions, type ReleaseSet, type Report, type RunOptions, type Shell, type StartOptions, type StartedProcess, type Step, type TagEvent, commandMeta, configuredRegistry, failed, failures, lastLines, missingFiles, pack, passed, publishTarball, registryHasVersion, release, releaseCommand, releaseCommandWith, releaseSet, render, shell, stealth, tagEvent, withTrailingSlash, writeTagEvents };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { n as stealth, t as commandMeta } from "./cli-DC07sdDR.mjs";
+import { _ as tagEvent, a as configuredRegistry, c as missingFiles, d as shell, f as failed, g as render, h as passed, i as releaseSet, l as pack, m as lastLines, n as releaseCommandWith, o as registryHasVersion, p as failures, r as release, s as withTrailingSlash, t as releaseCommand, u as publishTarball, v as writeTagEvents } from "./command-wCHt33VW.mjs";
+export { commandMeta, configuredRegistry, failed, failures, lastLines, missingFiles, pack, passed, publishTarball, registryHasVersion, release, releaseCommand, releaseCommandWith, releaseSet, render, shell, stealth, tagEvent, withTrailingSlash, writeTagEvents };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@stealthscale/tool-cli",
+  "version": "0.1.0",
+  "description": "Ships the stealth command, and publishes a workspace's public packages in dependency order.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/tooling.git",
+    "directory": "tools/cli"
+  },
+  "bin": {
+    "stealth": "./src/bin/stealth.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "tooling-source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./bin/stealth": {
+      "tooling-source": "./src/bin/stealth.ts",
+      "default": "./dist/bin/stealth.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "bin": {
+      "stealth": "./dist/bin/stealth.mjs"
+    },
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./bin/stealth": "./dist/bin/stealth.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/index.ts src/bin/stealth.ts"
+  },
+  "dependencies": {
+    "@stealthscale/core-schema": "^0.1.0",
+    "@stealthscale/tool-workspace": "^0.1.0",
+    "citty": "~0.2.2"
+  },
+  "devDependencies": {
+    "@stealthscale/tool-config": "^0.1.0",
+    "@stealthscale/tool-testing": "^0.1.0"
+  }
+}

package/src/bin/stealth.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview The `stealth` bin. It hands the command to citty and does nothing else, so
+ * everything worth a specification lives beside it rather than in an entry a build rewrites.
+ */
+
+import { runMain } from 'citty'
+
+import { stealth } from '#cli.ts'
+
+await runMain(stealth)