@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/constants/package-manager.js

@@ -0,0 +1,56 @@
+/**
+ * Package managers a project may use and how each one runs its scripts.
+ *
+ * @module constants/package-manager
+ */
+
+/** Package managers astra-rp recognizes. */
+export const PACKAGE_MANAGER = Object.freeze({
+  pnpm: "pnpm",
+  npm: "npm",
+  yarn: "yarn",
+  bun: "bun",
+});
+
+/** Package manager assumed when a project declares none and has no lockfile: the historical default. */
+export const DEFAULT_PACKAGE_MANAGER = PACKAGE_MANAGER.pnpm;
+
+/** `packageManager` field of `package.json` (Corepack format, `<name>@<version>`). */
+export const PACKAGE_MANAGER_FIELD = "packageManager";
+
+/** Name part of a `packageManager` value such as `bun@1.3.11`. */
+export const PACKAGE_MANAGER_FIELD_PATTERN = /^(pnpm|npm|yarn|bun)@/u;
+
+/**
+ * Lockfiles of each package manager, checked in order to reveal the package manager when
+ * `packageManager` is missing. The generated CI workflow installs with a frozen lockfile, so it
+ * also needs one of its package manager's lockfiles committed.
+ */
+export const LOCKFILE_PACKAGE_MANAGERS = Object.freeze([
+  ["bun.lock", PACKAGE_MANAGER.bun],
+  ["bun.lockb", PACKAGE_MANAGER.bun],
+  ["pnpm-lock.yaml", PACKAGE_MANAGER.pnpm],
+  ["yarn.lock", PACKAGE_MANAGER.yarn],
+  ["package-lock.json", PACKAGE_MANAGER.npm],
+  ["npm-shrinkwrap.json", PACKAGE_MANAGER.npm],
+]);
+
+/** Every lockfile name in {@link LOCKFILE_PACKAGE_MANAGERS}, whatever its package manager. */
+export const LOCKFILE_NAMES = Object.freeze(LOCKFILE_PACKAGE_MANAGERS.map(([lockfileName]) => lockfileName));
+
+/**
+ * Prefix that runs a `package.json` script by name. `bun create-version` would run `bun create`
+ * and `npm create-version` is not a command, so both need `run`; pnpm and yarn run scripts directly.
+ */
+export const SCRIPT_RUNNER = Object.freeze({
+  [PACKAGE_MANAGER.pnpm]: "pnpm",
+  [PACKAGE_MANAGER.npm]: "npm run",
+  [PACKAGE_MANAGER.yarn]: "yarn",
+  [PACKAGE_MANAGER.bun]: "bun run",
+});
+
+/** `package.json` script projects declare to run `astra-rp create-version`. */
+export const CREATE_VERSION_SCRIPT = "create-version";
+
+/** How a pnpm project runs `astra-rp create-version`: the default quoted by messages when no project is known. */
+export const DEFAULT_CREATE_VERSION_COMMAND = `${SCRIPT_RUNNER[DEFAULT_PACKAGE_MANAGER]} ${CREATE_VERSION_SCRIPT}`;

package/src/constants/registry.js

@@ -0,0 +1,72 @@
+/**
+ * Defines providers, authentication modes and transport defaults for one-registry releases.
+ *
+ * @module constants/registry
+ */
+
+/** npm package registry provider. */
+export const NPM_REGISTRY_PROVIDER = "npm";
+/** GitHub Packages provider. */
+export const GITHUB_REGISTRY_PROVIDER = "github";
+/** GitLab package registry provider. */
+export const GITLAB_REGISTRY_PROVIDER = "gitlab";
+/** Native JSR provider. */
+export const JSR_REGISTRY_PROVIDER = "jsr";
+/** Providers that can publish without a project-defined hook. */
+export const REGISTRY_PROVIDERS = Object.freeze([NPM_REGISTRY_PROVIDER, GITHUB_REGISTRY_PROVIDER, GITLAB_REGISTRY_PROVIDER, JSR_REGISTRY_PROVIDER]);
+
+/** Token-based authentication mode. */
+export const TOKEN_AUTHENTICATION = "token";
+/** Tokenless CI authentication mode. */
+export const OIDC_AUTHENTICATION = "oidc";
+/** Interactive JSR browser authentication mode. */
+export const BROWSER_AUTHENTICATION = "browser";
+/** Authentication modes accepted in project configuration. */
+export const REGISTRY_AUTHENTICATION_MODES = Object.freeze([TOKEN_AUTHENTICATION, OIDC_AUTHENTICATION, BROWSER_AUTHENTICATION]);
+
+/** Provider names used in terminal feedback. */
+export const REGISTRY_LABELS = Object.freeze({ npm: "npm", github: "GitHub Packages", gitlab: "GitLab", jsr: "JSR" });
+/** Host of the GitHub Packages npm endpoint. */
+export const GITHUB_PACKAGES_HOST = "npm.pkg.github.com";
+/** Public GitHub Packages npm endpoint. */
+export const GITHUB_PACKAGES_REGISTRY_URL = `https://${GITHUB_PACKAGES_HOST}/`;
+/** Public native JSR endpoint. */
+export const JSR_REGISTRY_URL = "https://jsr.io/";
+/** Hostname of JSR's npm compatibility endpoint, which installs JSR packages but cannot publish them. */
+export const JSR_NPM_COMPATIBILITY_HOSTNAME = "npm.jsr.io";
+/** Default credential variable for each provider. */
+export const NPM_REGISTRY_TOKEN_VARIABLE = "NPM_TOKEN";
+/** GitHub Actions token or a classic PAT stored under this variable. */
+export const GITHUB_REGISTRY_TOKEN_VARIABLE = "GITHUB_TOKEN";
+/** GitLab access token; a project may configure CI_JOB_TOKEN instead. */
+export const GITLAB_REGISTRY_TOKEN_VARIABLE = "GITLAB_TOKEN";
+/** Personal JSR publishing token. */
+export const JSR_REGISTRY_TOKEN_VARIABLE = "JSR_TOKEN";
+/** Default token variables indexed by the selected provider. */
+export const REGISTRY_TOKEN_VARIABLES = Object.freeze({ npm: NPM_REGISTRY_TOKEN_VARIABLE, github: GITHUB_REGISTRY_TOKEN_VARIABLE, gitlab: GITLAB_REGISTRY_TOKEN_VARIABLE, jsr: JSR_REGISTRY_TOKEN_VARIABLE });
+/** Variable names safe to reference from npm configuration and child-process environments. */
+export const REGISTRY_TOKEN_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/** Distribution tags safe to pass as one npm CLI operand. */
+export const REGISTRY_DIST_TAG_PATTERN = /^[A-Za-z][A-Za-z0-9._-]*$/u;
+/** npm access modes supported by registry publishers. */
+export const REGISTRY_ACCESS_MODES = Object.freeze(["public", "restricted"]);
+/** HTTP timeout for direct metadata lookups, in milliseconds. */
+export const REGISTRY_LOOKUP_TIMEOUT_MS = 15_000;
+/** GitLab publishing uses a project endpoint, including on self-managed instances. */
+export const GITLAB_PROJECT_REGISTRY_PATTERN = /\/api\/v4\/projects\/[^/]+\/packages\/npm\/?$/u;
+/** JSR configuration filenames, in preferred lookup order. */
+export const JSR_CONFIG_FILES = Object.freeze(["jsr.json", "jsr.jsonc", "deno.json", "deno.jsonc"]);
+/** Scoped JSR names with command-line-safe scope and package components. */
+export const JSR_PACKAGE_NAME_PATTERN = /^@[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/u;
+/** Pinned official npm client used when JSR does not use an installed Deno client. */
+export const JSR_NPM_CLIENT_SPEC = "jsr@0.14.3";
+/** JSR client choices. */
+export const JSR_CLIENTS = Object.freeze(["npx", "deno"]);
+/** Child-only JSR token variable expanded by the command shell, never logged by astra-rp. */
+export const JSR_CHILD_TOKEN_VARIABLE = "ASTRA_RP_JSR_TOKEN";
+/** Opaque JSR tokens safe to substitute as one shell-quoted operand. */
+export const JSR_SHELL_SAFE_TOKEN_PATTERN = /^[A-Za-z0-9._~+/=-]+$/u;
+/** Minimum npm CLI version that implements trusted publishing. */
+export const NPM_OIDC_MINIMUM_VERSION = "11.5.1";
+/** Minimum Node version needed by npm trusted publishing. */
+export const NPM_OIDC_MINIMUM_NODE_VERSION = "22.14.0";

package/src/constants/terminal-ui.js

@@ -0,0 +1,93 @@
+/**
+ * Layout, ANSI and key contracts of the dependency-free terminal UI.
+ *
+ * @module constants/terminal-ui
+ */
+
+/** Widest box drawn, so lines stay readable on large terminals. */
+export const MAX_BOX_WIDTH = 84;
+
+/** Width assumed when stdout does not report its columns. */
+export const FALLBACK_TERMINAL_WIDTH = 80;
+
+/** Columns kept free at the right of the terminal when sizing a box. */
+export const TERMINAL_RIGHT_MARGIN = 2;
+
+/** Horizontal padding inside a box, per side. */
+export const BOX_PADDING = 1;
+
+/** Width of the label column of status rows. */
+export const ROW_LABEL_WIDTH = 16;
+
+/** Spinner animation frames. */
+export const SPINNER_FRAMES = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+
+/** Delay between spinner frames. */
+export const SPINNER_INTERVAL_MS = 80;
+
+/** Exit code conventionally used after Ctrl+C. */
+export const INTERRUPTED_EXIT_CODE = 130;
+
+/** Splits styled text into ANSI escape sequences and single code points. */
+export const ANSI_TOKEN_PATTERN = /\x1b\[[0-9;]*m|[\s\S]/gu;
+
+/** First character of every ANSI escape sequence. */
+export const ANSI_ESCAPE = "\x1b";
+
+/** ANSI control sequences used by boxes, spinners and prompts. */
+export const ANSI_SEQUENCE = Object.freeze({
+  reset: "\x1b[0m",
+  hideCursor: "\x1b[?25l",
+  showCursor: "\x1b[?25h",
+  clearLine: "\r\x1b[2K",
+  clearBelow: "\x1b[0J",
+});
+
+/** Border color of each box tone. */
+export const BOX_TONE = Object.freeze({
+  neutral: "gray",
+  info: "cyan",
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  accent: "magenta",
+});
+
+/** Nerd Font glyphs (Font Awesome and Octicons sets) used as status icons. */
+export const ICON_GLYPH = Object.freeze({
+  success: "", // nf-fa-check
+  failure: "", // nf-fa-times
+  warning: "", // nf-fa-warning
+  info: "", // nf-fa-info_circle
+  pending: "", // nf-fa-circle_o
+  arrow: "", // nf-fa-chevron_right
+  bullet: "", // nf-oct-dot_fill
+  star: "", // nf-fa-star
+  rocket: "", // nf-fa-rocket
+});
+
+/** Label/value rows (`renderRow`): the value starts after a gap of two or more spaces. */
+export const VALUE_COLUMN_PATTERN = /^\s*\S(?:.*?\S)?\s{2,}(?=\S)/u;
+
+/** Leading marker (icon, arrow, bullet or `1.`, never a word) followed by a space, used as hanging indent. */
+export const HANGING_MARKER_PATTERN = /^(\s*)((?:[^\p{L}\p{N}\s]{1,2}|\d{1,2}\.)\s+)?/u;
+
+/** Options that can be picked with a single digit key (1-9). */
+export const MAX_NUMBERED_OPTIONS = 9;
+
+/** A single digit key that picks a numbered option. */
+export const NUMBER_KEY_PATTERN = /^[1-9]$/u;
+
+/** Seconds in a minute, used to format durations. */
+export const SECONDS_PER_MINUTE = 60;
+
+/** Milliseconds in a second, used to format durations. */
+export const MILLISECONDS_PER_SECOND = 1000;
+
+/** Key names (`readline` keypress events) handled by the select prompt. */
+export const PROMPT_KEY = Object.freeze({
+  interrupt: "c",
+  previous: Object.freeze(["up", "k"]),
+  next: Object.freeze(["down", "j", "tab"]),
+  confirm: Object.freeze(["return", "enter"]),
+});

package/src/constants/version-files.js

@@ -0,0 +1,63 @@
+/**
+ * Markers of `versionFiles`: lines and blocks whose version `create-version`
+ * rewrites in the release commit, besides `package.json`.
+ *
+ * @module constants/version-files
+ */
+
+import { PACKAGE_MANIFEST_FILE } from "./build-gate.js";
+import { CHANGELOG_FILE } from "./changelog.js";
+
+/**
+ * Comment marking a single line whose version is rewritten. The release-please marker is also
+ * accepted, so a project moving from release-please keeps its files untouched.
+ */
+export const VERSION_LINE_MARKERS = Object.freeze(["astra-rp-version", "x-release-please-version"]);
+
+/** Comments opening a block whose every version is rewritten, paired by index with {@link VERSION_BLOCK_END_MARKERS}. */
+export const VERSION_BLOCK_START_MARKERS = Object.freeze(["astra-rp-start-version", "x-release-please-start-version"]);
+
+/** Comments closing a version block, paired by index with {@link VERSION_BLOCK_START_MARKERS}. */
+export const VERSION_BLOCK_END_MARKERS = Object.freeze(["astra-rp-end", "x-release-please-end"]);
+
+/**
+ * Ways a file can pair its version block markers wrongly. Any of them stops the rewrite, since
+ * guessing where a block ends could rewrite versions outside the intended section.
+ *
+ * - `unterminated`: a start marker without its end marker before the end of the file.
+ * - `unopened`: an end marker outside any block.
+ * - `nested`: a start marker inside a block that is still open.
+ * - `mismatched`: an end marker of the other tool (`x-release-please-end` closing `astra-rp-start-version`, or the reverse).
+ */
+export const VERSION_BLOCK_PROBLEM = Object.freeze({
+  unterminated: "unterminated",
+  unopened: "unopened",
+  nested: "nested",
+  mismatched: "mismatched",
+});
+
+/**
+ * A semantic version inside a marked line (`1.2.3`, `1.2.3-beta.1`, `1.2.3+build`), not glued to
+ * other version-like digits (`10.0.0.1`, `1.2.3.4`). A period that ends a sentence (`is 1.2.3.`)
+ * is not part of the version and is kept. Global: every version of a marked line is rewritten.
+ */
+export const MARKED_VERSION_PATTERN =
+  /(?<![\d.])\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?!\.?\d)/gu;
+
+/**
+ * Splits a versioned file into lines right after each terminator (`\r\n`, `\n` or a lone `\r`),
+ * so every line keeps its own terminator and joining the lines gives back the original content.
+ */
+export const LINE_TERMINATOR_BOUNDARY_PATTERN = /(?<=\n)|(?<=\r)(?!\n)/u;
+
+/**
+ * Files the release owns: the bumped `package.json` and the CHANGELOG whose `[Unreleased]` it closes.
+ * `versionFiles` cannot list either: rewriting them would undo the bump or the closed section.
+ */
+export const RELEASE_COMMIT_BUILT_IN_FILES = Object.freeze([PACKAGE_MANIFEST_FILE, CHANGELOG_FILE]);
+
+/**
+ * Git pathspec magic that matches a configured path literally, so names starting with `:` or
+ * holding `*`/`?` are never read as pathspec syntax.
+ */
+export const GIT_LITERAL_PATHSPEC_PREFIX = ":(literal)";

package/src/constants/versions.js

@@ -0,0 +1,60 @@
+/**
+ * Release version rules shared by `create-version` and the Vercel build gate.
+ *
+ * @module constants/versions
+ */
+
+/** Semver release types, from the smallest to the largest change. */
+export const RELEASE_TYPE = Object.freeze({
+  patch: "patch",
+  minor: "minor",
+  major: "major",
+});
+
+/**
+ * Suggested release type before `1.0.0` with `preMajorShift`: one level down, the `0.x` convention
+ * where a minor carries breaking changes and a patch carries features (release-please's
+ * `bump-minor-pre-major` plus `bump-patch-for-minor-pre-major`).
+ */
+export const PRE_MAJOR_SHIFTED_RELEASE_TYPE = Object.freeze({
+  patch: RELEASE_TYPE.patch,
+  minor: RELEASE_TYPE.patch,
+  major: RELEASE_TYPE.minor,
+});
+
+/** Major version of the `0.x` line, where `preMajorShift` applies. */
+export const PRE_MAJOR_VERSION = 0;
+
+/**
+ * Version of a package that was never released (the release-please placeholder): the commit that
+ * sets it is not a release, and its first release keeps the unshifted suggestion (a feature gives
+ * `0.1.0`, not `0.0.1`).
+ */
+export const UNRELEASED_PLACEHOLDER_VERSION = "0.0.0";
+
+/** Release types in the order they are offered: patch, minor, major. */
+export const RELEASE_TYPE_ORDER = Object.freeze([RELEASE_TYPE.patch, RELEASE_TYPE.minor, RELEASE_TYPE.major]);
+
+/** Stable `X.Y.Z` release version: no prerelease, build metadata, prefix or leading zeros. */
+export const RELEASE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+/** Any semver version, capturing its `X.Y.Z` core and optional prerelease. */
+export const SEMVER_PATTERN = /^((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Prefix of the annotated Git tags that mark each release (`v0.93.0`). */
+export const RELEASE_TAG_PREFIX = "v";
+
+/** `git log --grep` pattern of release commit subjects (`0.93.0`). */
+export const RELEASE_COMMIT_SUBJECT_GREP = String.raw`^[0-9]+\.[0-9]+\.[0-9]+$`;
+
+/** Conventional commit header: `type(scope)!: subject`. */
+export const CONVENTIONAL_HEADER_PATTERN = /^(?<type>[a-z]+)(?:\([^)]*\))?(?<breaking>!)?:\s/i;
+
+/** Footer that marks a breaking change in a conventional commit body. */
+export const BREAKING_CHANGE_FOOTER_PATTERN = /^BREAKING[ -]CHANGE:/m;
+
+/** Conventional commit type that ships user-visible features. */
+export const FEATURE_COMMIT_TYPE = "feat";
+
+/** Imperative verbs used by legacy, non-conventional feature subjects. */
+export const LEGACY_FEATURE_SUBJECT_PATTERN = /^(add|implement|introduce|support|enable|create|allow)\b/i;