@rrlab/cli 0.0.2 → 0.0.3-git-aeeb52d.0

package/README.md

@@ -35,6 +35,26 @@ pnpm rr help
 
 See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release).
 
+## Plugins
+
+`rr` is a microkernel: every tool (Biome, TypeScript, tsdown, …) lives in its own `@rrlab/<tool>-plugin` package. Install one with:
+
+```sh
+rr plugins add biome
+```
+
+This installs `@rrlab/biome-plugin` plus its peer tool and shared config, scaffolds `biome.json` if missing, and wires the plugin into `run-run.config.{ts,mts}`.
+
+To install from a specific dist-tag (e.g. a PR preview release published as `pr-<N>`, or a custom tag), append `@<spec>`:
+
+```sh
+rr plugins add biome@pr-226   # preview tag
+rr plugins add biome@next     # any dist-tag
+rr plugins add biome@^0.1.0   # explicit version range (sibling configs still use latest)
+```
+
+When the spec is a dist-tag, `rr` resolves any `@rrlab/*-config` sibling at the same tag, falling back to `latest` if the registry doesn't have the sibling at that tag.
+
 ## Shell completion
 
 `rr` ships a `completion` subcommand that prints a shell-specific script.

package/dist/cli.usage.kdl

@@ -1,7 +1,7 @@
 // @generated by @usage-spec/commander from Commander.js metadata
 name rr
 bin rr
-version "0.0.2"
+version "0.0.3-git-aeeb52d.0"
 usage "<command...> [options...]"
 flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
 cmd completion help="print shell completion script (usage)" {
@@ -49,9 +49,7 @@ cmd plugins subcommand_required=#true help="manage @rrlab plugins" {
 		flag --force help="re-run install even if the plugin is already configured"
 		flag --yes help="skip prompts and use defaults (non-interactive)"
 		flag --dry-run help="show what would happen, without applying changes"
-		arg <name> help="plugin alias" {
-			choices ts eslint biome oxc tsdown
-		}
+		arg <name> help="plugin alias (ts|eslint|biome|oxc|tsdown), optionally with @<spec> e.g. biome@pr-226"
 	}
 	cmd remove help="uninstall an @rrlab plugin and undo its config files + deps" {
 		flag --yes help="skip the confirmation prompt"

package/dist/config.d.mts

@@ -1,4 +1,4 @@
-import { u as Plugin } from "./types-C3V27_kd.mjs";
+import { u as Plugin } from "./types-BPHxibPr.mjs";
 
 //#region src/types/config.d.ts
 type UserConfig = {

package/dist/plugin.d.mts

@@ -1,4 +1,4 @@
-import { C as Linter, D as TypeChecker, E as TypeCheckOptions, S as LintOptions, T as StaticCheckerOptions, _ as Doctor, a as InstallFlags, b as FormatOptions, c as PLUGIN_KINDS, d as PluginCapabilities, f as PluginContext, g as UninstallResult, h as UninstallFlags, i as InstallContext, l as Packer, m as UninstallContext, n as ClackPromptsSelectOption, o as InstallResult, p as PluginKind, r as FileOp, s as JsonEdit, t as ClackPrompts, u as Plugin, v as DoctorOutput, w as StaticChecker, x as Formatter, y as DoctorResult } from "./types-C3V27_kd.mjs";
+import { C as Linter, D as TypeChecker, E as TypeCheckOptions, O as ReleaseService, S as LintOptions, T as StaticCheckerOptions, _ as Doctor, a as InstallFlags, b as FormatOptions, c as PLUGIN_KINDS, d as PluginCapabilities, f as PluginContext, g as UninstallResult, h as UninstallFlags, i as InstallContext, k as ReleaseServiceOptions, l as Packer, m as UninstallContext, n as ClackPromptsSelectOption, o as InstallResult, p as PluginKind, r as FileOp, s as JsonEdit, t as ClackPrompts, u as Plugin, v as DoctorOutput, w as StaticChecker, x as Formatter, y as DoctorResult } from "./types-BPHxibPr.mjs";
 import { ShellService } from "@vlandoss/clibuddy";
 
 //#region src/plugin/define-plugin.d.ts
@@ -49,4 +49,4 @@ declare class ToolService {
   doctor(): Promise<DoctorResult>;
 }
 //#endregion
-export { type ClackPrompts, type ClackPromptsSelectOption, type Doctor, type DoctorOutput, type DoctorResult, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, PLUGIN_KINDS, type Packer, type Plugin, type PluginCapabilities, type PluginContext, type PluginKind, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, definePlugin };
+export { type ClackPrompts, type ClackPromptsSelectOption, type Doctor, type DoctorOutput, type DoctorResult, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, PLUGIN_KINDS, type Packer, type Plugin, type PluginCapabilities, type PluginContext, type PluginKind, ReleaseService, type ReleaseServiceOptions, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, definePlugin };

package/dist/plugin.mjs

@@ -62,4 +62,49 @@ const PLUGIN_KINDS = [
 	"pack"
 ];
 //#endregion
-export { PLUGIN_KINDS, ToolService, definePlugin };
+//#region src/services/release.ts
+const REGISTRY = "https://registry.npmjs.org";
+const PROBE_TIMEOUT_MS = 5e3;
+/**
+* Represents the "release" the current `rr plugins add` runs against — the
+* dist-tag the user picked (default: latest), plus the logic to resolve install
+* specs for related packages under that release.
+*
+* - With no `tag`, `resolve()` always returns `"latest"` and never hits the
+*   registry.
+* - With a `tag` (e.g. `"pr-226"`), probes `<pkg>@<tag>`: returns the tag when
+*   it exists, falls back to `"latest"` otherwise so a partial preview release
+*   (where only a subset of packages got published) still installs cleanly.
+* - Per-package result is cached within the service instance.
+*/
+var ReleaseService = class {
+	tag;
+	#fetcher;
+	#cache = /* @__PURE__ */ new Map();
+	constructor(tag, { fetcher = fetch } = {}) {
+		this.tag = tag;
+		this.#fetcher = fetcher;
+	}
+	resolve(pkg) {
+		if (!this.tag || this.tag === "latest") return Promise.resolve("latest");
+		const cached = this.#cache.get(pkg);
+		if (cached) return cached;
+		const promise = this.#probe(pkg);
+		this.#cache.set(pkg, promise);
+		return promise;
+	}
+	async #probe(pkg) {
+		const tag = this.tag;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+		try {
+			return (await this.#fetcher(`${REGISTRY}/${pkg}/${encodeURIComponent(tag)}`, { signal: controller.signal })).ok ? tag : "latest";
+		} catch {
+			return "latest";
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+};
+//#endregion
+export { PLUGIN_KINDS, ReleaseService, ToolService, definePlugin };

package/dist/run.mjs

@@ -762,6 +762,51 @@ function createClackPrompts() {
 	};
 }
 //#endregion
+//#region src/services/release.ts
+const REGISTRY = "https://registry.npmjs.org";
+const PROBE_TIMEOUT_MS = 5e3;
+/**
+* Represents the "release" the current `rr plugins add` runs against — the
+* dist-tag the user picked (default: latest), plus the logic to resolve install
+* specs for related packages under that release.
+*
+* - With no `tag`, `resolve()` always returns `"latest"` and never hits the
+*   registry.
+* - With a `tag` (e.g. `"pr-226"`), probes `<pkg>@<tag>`: returns the tag when
+*   it exists, falls back to `"latest"` otherwise so a partial preview release
+*   (where only a subset of packages got published) still installs cleanly.
+* - Per-package result is cached within the service instance.
+*/
+var ReleaseService = class {
+	tag;
+	#fetcher;
+	#cache = /* @__PURE__ */ new Map();
+	constructor(tag, { fetcher = fetch } = {}) {
+		this.tag = tag;
+		this.#fetcher = fetcher;
+	}
+	resolve(pkg) {
+		if (!this.tag || this.tag === "latest") return Promise.resolve("latest");
+		const cached = this.#cache.get(pkg);
+		if (cached) return cached;
+		const promise = this.#probe(pkg);
+		this.#cache.set(pkg, promise);
+		return promise;
+	}
+	async #probe(pkg) {
+		const tag = this.tag;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+		try {
+			return (await this.#fetcher(`${REGISTRY}/${pkg}/${encodeURIComponent(tag)}`, { signal: controller.signal })).ok ? tag : "latest";
+		} catch {
+			return "latest";
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+};
+//#endregion
 //#region src/services/workspace-target.ts
 function resolveWorkspaceChoice(appPkg, pm) {
 	if (!appPkg.isMonorepo()) return { kind: "current" };
@@ -787,7 +832,7 @@ function pmNeedsRootFlag(pm) {
 function createPluginsCommand(ctx) {
 	const cmd = createCommand("plugins").description("manage @rrlab plugins");
 	cmd.command("list").description("list plugins configured in run-run.config.{ts,mts}").action(() => runList(ctx));
-	cmd.command("add").description("install and configure an @rrlab plugin").addArgument(new Argument("<name>", "plugin alias").choices(officialAliases())).option("--force", "re-run install even if the plugin is already configured").option("--yes", "skip prompts and use defaults (non-interactive)").option("--dry-run", "show what would happen, without applying changes").action((name, opts) => runAdd(ctx, name, opts));
+	cmd.command("add").description("install and configure an @rrlab plugin").addArgument(new Argument("<name>", `plugin alias (${officialAliases().join("|")}), optionally with @<spec> e.g. biome@pr-226`)).option("--force", "re-run install even if the plugin is already configured").option("--yes", "skip prompts and use defaults (non-interactive)").option("--dry-run", "show what would happen, without applying changes").action((name, opts) => runAdd(ctx, name, opts));
 	cmd.command("remove").description("uninstall an @rrlab plugin and undo its config files + deps").addArgument(new Argument("<name>", "plugin alias to remove").choices(officialAliases())).option("--yes", "skip the confirmation prompt").option("--dry-run", "print the plan without applying changes").action((name, opts) => runRemove(ctx, name, opts));
 	return cmd;
 }
@@ -807,9 +852,13 @@ async function runList(ctx) {
 	logger.info(`${rel}:`);
 	for (const name of plugins) logger.info(`  - ${name}`);
 }
-async function runAdd(ctx, alias, opts) {
+async function runAdd(ctx, name, opts) {
+	const { alias, spec } = parseAliasSpec(name);
+	if (!(alias in OFFICIAL_PLUGINS)) throw new Error(`'${alias}' is invalid for argument 'name'. Allowed choices are ${officialAliases().join(", ")}.`);
 	const { pkg: pkgName, exportName } = OFFICIAL_PLUGINS[alias];
-	clack.intro(` rr plugins add ${alias} `);
+	const tag = spec && isDistTag(spec) ? spec : void 0;
+	const installSpec = spec ? `${pkgName}@${spec}` : pkgName;
+	clack.intro(` rr plugins add ${name} `);
 	const inPkg = hasInPackageJson(ctx, pkgName);
 	const ast = new ConfigAstService();
 	const loaded = await ast.load(ctx.appPkg.dirPath);
@@ -824,7 +873,7 @@ async function runAdd(ctx, alias, opts) {
 	const workspace = toNypmWorkspace(wsChoice);
 	const targetLabel = describeWorkspaceChoice(wsChoice);
 	if (opts.dryRun) {
-		clack.log.info(`Would: install ${pkgName} as a devDependency in ${targetLabel}${inPkg ? " (already present, skipped)" : ""}.`);
+		clack.log.info(`Would: install ${installSpec} as a devDependency in ${targetLabel}${inPkg ? " (already present, skipped)" : ""}.`);
 		if (!inConfig) {
 			const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
 			clack.log.info(`Would: add ${exportName}() to ${rel} (plugins[]).`);
@@ -835,8 +884,8 @@ async function runAdd(ctx, alias, opts) {
 	}
 	let installedNow = false;
 	if (!inPkg) {
-		await withSpinner(`Installing ${pkgName}`, async () => {
-			await addDependency([pkgName], {
+		await withSpinner(`Installing ${installSpec}`, async () => {
+			await addDependency([installSpec], {
 				cwd: ctx.appPkg.dirPath,
 				dev: true,
 				silent: true,
@@ -860,7 +909,8 @@ async function runAdd(ctx, alias, opts) {
 					force: !!opts.force,
 					yes: !!opts.yes,
 					nonInteractive: !!opts.yes
-				}
+				},
+				release: new ReleaseService(tag)
 			};
 			installResult = await plugin.install(installCtx);
 		}
@@ -969,6 +1019,18 @@ async function runRemove(ctx, alias, opts) {
 	});
 	clack.outro(`Plugin '${alias}' removed.`);
 }
+function parseAliasSpec(input) {
+	const at = input.indexOf("@");
+	if (at <= 0) return { alias: input };
+	return {
+		alias: input.slice(0, at),
+		spec: input.slice(at + 1)
+	};
+}
+/** A dist-tag starts with a letter and contains only safe identifier chars. Version ranges (`^0.1`, `>=1`, `0.0.2`, `*`) don't match. */
+function isDistTag(spec) {
+	return /^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(spec) && spec !== "latest";
+}
 function hasInPackageJson(ctx, pkgName) {
 	const pkg = ctx.appPkg.packageJson;
 	return pkgName in {

package/dist/{types-C3V27_kd.d.mts → types-BPHxibPr.d.mts}

@@ -1,6 +1,31 @@
 import { Pkg, ShellService } from "@vlandoss/clibuddy";
 import { AnyLogger } from "@vlandoss/loggy";
 
+//#region src/services/release.d.ts
+type ReleaseServiceOptions = {
+  /** Override the HTTP probe — used by tests. */fetcher?: typeof fetch;
+};
+/**
+ * Represents the "release" the current `rr plugins add` runs against — the
+ * dist-tag the user picked (default: latest), plus the logic to resolve install
+ * specs for related packages under that release.
+ *
+ * - With no `tag`, `resolve()` always returns `"latest"` and never hits the
+ *   registry.
+ * - With a `tag` (e.g. `"pr-226"`), probes `<pkg>@<tag>`: returns the tag when
+ *   it exists, falls back to `"latest"` otherwise so a partial preview release
+ *   (where only a subset of packages got published) still installs cleanly.
+ * - Per-package result is cached within the service instance.
+ */
+declare class ReleaseService {
+  #private;
+  readonly tag: string | undefined;
+  constructor(tag: string | undefined, {
+    fetcher
+  }?: ReleaseServiceOptions);
+  resolve(pkg: string): Promise<string>;
+}
+//#endregion
 //#region src/types/tool.d.ts
 type FormatOptions = {
   fix?: boolean;
@@ -110,6 +135,13 @@ type InstallContext = {
   appPkg: Pkg;
   prompts: ClackPrompts;
   flags: InstallFlags;
+  /**
+   * The release this install is running against — encapsulates the dist-tag the
+   * user picked (`rr plugins add biome@pr-226`) and resolves install specs for
+   * related packages under it. Use `ctx.release.resolve(pkg)` for every
+   * `@rrlab/*-config` sibling so previews and `latest` work uniformly.
+   */
+  release: ReleaseService;
 };
 type UninstallContext = {
   shell: ShellService;
@@ -170,4 +202,4 @@ type UninstallResult = {
   files?: FileOp[];
 };
 //#endregion
-export { Linter as C, TypeChecker as D, TypeCheckOptions as E, LintOptions as S, StaticCheckerOptions as T, Doctor as _, InstallFlags as a, FormatOptions as b, PLUGIN_KINDS as c, PluginCapabilities as d, PluginContext as f, UninstallResult as g, UninstallFlags as h, InstallContext as i, Packer as l, UninstallContext as m, ClackPromptsSelectOption as n, InstallResult as o, PluginKind as p, FileOp as r, JsonEdit as s, ClackPrompts as t, Plugin as u, DoctorOutput as v, StaticChecker as w, Formatter as x, DoctorResult as y };
+export { Linter as C, TypeChecker as D, TypeCheckOptions as E, ReleaseService as O, LintOptions as S, StaticCheckerOptions as T, Doctor as _, InstallFlags as a, FormatOptions as b, PLUGIN_KINDS as c, PluginCapabilities as d, PluginContext as f, UninstallResult as g, UninstallFlags as h, InstallContext as i, ReleaseServiceOptions as k, Packer as l, UninstallContext as m, ClackPromptsSelectOption as n, InstallResult as o, PluginKind as p, FileOp as r, JsonEdit as s, ClackPrompts as t, Plugin as u, DoctorOutput as v, StaticChecker as w, Formatter as x, DoctorResult as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rrlab/cli",
-  "version": "0.0.2",
+  "version": "0.0.3-git-aeeb52d.0",
   "description": "The CLI toolbox to fullstack common scripts in Variable Land",
   "homepage": "https://github.com/variableland/dx/tree/main/run-run/cli#readme",
   "bugs": {

package/src/lib/plugin.ts

@@ -29,3 +29,4 @@ export type {
   UninstallResult,
 } from "#src/plugin/types.ts";
 export { PLUGIN_KINDS } from "#src/plugin/types.ts";
+export { ReleaseService, type ReleaseServiceOptions } from "#src/services/release.ts";

package/src/plugin/types.ts

@@ -1,5 +1,6 @@
 import type { Pkg, ShellService } from "@vlandoss/clibuddy";
 import type { AnyLogger as Logger } from "@vlandoss/loggy";
+import type { ReleaseService } from "#src/services/release.ts";
 import type { Doctor, Formatter, Linter, StaticChecker, TypeChecker } from "#src/types/tool.ts";
 
 export type {
@@ -83,6 +84,13 @@ export type InstallContext = {
   appPkg: Pkg;
   prompts: ClackPrompts;
   flags: InstallFlags;
+  /**
+   * The release this install is running against — encapsulates the dist-tag the
+   * user picked (`rr plugins add biome@pr-226`) and resolves install specs for
+   * related packages under it. Use `ctx.release.resolve(pkg)` for every
+   * `@rrlab/*-config` sibling so previews and `latest` work uniformly.
+   */
+  release: ReleaseService;
 };
 
 export type UninstallContext = {

package/src/program/commands/plugins.ts

@@ -10,6 +10,7 @@ import { applyJsonEdits } from "#src/services/json-edit.ts";
 import { logger } from "#src/services/logger.ts";
 import { OFFICIAL_PLUGINS, type OfficialAlias, officialAliases } from "#src/services/plugins-registry.ts";
 import { createClackPrompts } from "#src/services/prompts.ts";
+import { ReleaseService } from "#src/services/release.ts";
 import { describeWorkspaceChoice, resolveWorkspaceChoice, toNypmWorkspace } from "#src/services/workspace-target.ts";
 
 type AddOptions = {
@@ -38,11 +39,13 @@ export function createPluginsCommand(ctx: Context) {
   cmd
     .command("add")
     .description("install and configure an @rrlab plugin")
-    .addArgument(new Argument("<name>", "plugin alias").choices(officialAliases()))
+    .addArgument(
+      new Argument("<name>", `plugin alias (${officialAliases().join("|")}), optionally with @<spec> e.g. biome@pr-226`),
+    )
     .option("--force", "re-run install even if the plugin is already configured")
     .option("--yes", "skip prompts and use defaults (non-interactive)")
     .option("--dry-run", "show what would happen, without applying changes")
-    .action((name: OfficialAlias, opts: AddOptions) => runAdd(ctx, name, opts));
+    .action((name: string, opts: AddOptions) => runAdd(ctx, name, opts));
 
   cmd
     .command("remove")
@@ -74,10 +77,16 @@ async function runList(ctx: Context) {
   }
 }
 
-async function runAdd(ctx: Context, alias: OfficialAlias, opts: AddOptions) {
-  const { pkg: pkgName, exportName } = OFFICIAL_PLUGINS[alias];
+async function runAdd(ctx: Context, name: string, opts: AddOptions) {
+  const { alias, spec } = parseAliasSpec(name);
+  if (!(alias in OFFICIAL_PLUGINS)) {
+    throw new Error(`'${alias}' is invalid for argument 'name'. Allowed choices are ${officialAliases().join(", ")}.`);
+  }
+  const { pkg: pkgName, exportName } = OFFICIAL_PLUGINS[alias as OfficialAlias];
+  const tag = spec && isDistTag(spec) ? spec : undefined;
+  const installSpec = spec ? `${pkgName}@${spec}` : pkgName;
 
-  clack.intro(` rr plugins add ${alias} `);
+  clack.intro(` rr plugins add ${name} `);
 
   const inPkg = hasInPackageJson(ctx, pkgName);
   const ast = new ConfigAstService();
@@ -97,7 +106,7 @@ async function runAdd(ctx: Context, alias: OfficialAlias, opts: AddOptions) {
 
   if (opts.dryRun) {
     clack.log.info(
-      `Would: install ${pkgName} as a devDependency in ${targetLabel}${inPkg ? " (already present, skipped)" : ""}.`,
+      `Would: install ${installSpec} as a devDependency in ${targetLabel}${inPkg ? " (already present, skipped)" : ""}.`,
     );
     if (!inConfig) {
       const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
@@ -110,8 +119,8 @@ async function runAdd(ctx: Context, alias: OfficialAlias, opts: AddOptions) {
 
   let installedNow = false;
   if (!inPkg) {
-    await withSpinner(`Installing ${pkgName}`, async () => {
-      await addDependency([pkgName], { cwd: ctx.appPkg.dirPath, dev: true, silent: true, workspace });
+    await withSpinner(`Installing ${installSpec}`, async () => {
+      await addDependency([installSpec], { cwd: ctx.appPkg.dirPath, dev: true, silent: true, workspace });
     });
     installedNow = true;
   }
@@ -135,6 +144,7 @@ async function runAdd(ctx: Context, alias: OfficialAlias, opts: AddOptions) {
           yes: !!opts.yes,
           nonInteractive: !!opts.yes,
         },
+        release: new ReleaseService(tag),
       };
       installResult = await plugin.install(installCtx);
     }
@@ -260,6 +270,17 @@ async function runRemove(ctx: Context, alias: OfficialAlias, opts: RemoveOptions
   clack.outro(`Plugin '${alias}' removed.`);
 }
 
+function parseAliasSpec(input: string): { alias: string; spec?: string } {
+  const at = input.indexOf("@");
+  if (at <= 0) return { alias: input };
+  return { alias: input.slice(0, at), spec: input.slice(at + 1) };
+}
+
+/** A dist-tag starts with a letter and contains only safe identifier chars. Version ranges (`^0.1`, `>=1`, `0.0.2`, `*`) don't match. */
+function isDistTag(spec: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(spec) && spec !== "latest";
+}
+
 function hasInPackageJson(ctx: Context, pkgName: string): boolean {
   const pkg = ctx.appPkg.packageJson;
   const deps = {

package/src/services/release.ts

@@ -0,0 +1,53 @@
+const REGISTRY = "https://registry.npmjs.org";
+const PROBE_TIMEOUT_MS = 5_000;
+
+export type ReleaseServiceOptions = {
+  /** Override the HTTP probe — used by tests. */
+  fetcher?: typeof fetch;
+};
+
+/**
+ * Represents the "release" the current `rr plugins add` runs against — the
+ * dist-tag the user picked (default: latest), plus the logic to resolve install
+ * specs for related packages under that release.
+ *
+ * - With no `tag`, `resolve()` always returns `"latest"` and never hits the
+ *   registry.
+ * - With a `tag` (e.g. `"pr-226"`), probes `<pkg>@<tag>`: returns the tag when
+ *   it exists, falls back to `"latest"` otherwise so a partial preview release
+ *   (where only a subset of packages got published) still installs cleanly.
+ * - Per-package result is cached within the service instance.
+ */
+export class ReleaseService {
+  readonly tag: string | undefined;
+  readonly #fetcher: typeof fetch;
+  readonly #cache = new Map<string, Promise<string>>();
+
+  constructor(tag: string | undefined, { fetcher = fetch }: ReleaseServiceOptions = {}) {
+    this.tag = tag;
+    this.#fetcher = fetcher;
+  }
+
+  resolve(pkg: string): Promise<string> {
+    if (!this.tag || this.tag === "latest") return Promise.resolve("latest");
+    const cached = this.#cache.get(pkg);
+    if (cached) return cached;
+    const promise = this.#probe(pkg);
+    this.#cache.set(pkg, promise);
+    return promise;
+  }
+
+  async #probe(pkg: string): Promise<string> {
+    const tag = this.tag as string;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+      const res = await this.#fetcher(`${REGISTRY}/${pkg}/${encodeURIComponent(tag)}`, { signal: controller.signal });
+      return res.ok ? tag : "latest";
+    } catch {
+      return "latest";
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}