fix(platforms): make multi-platform builds work on latest MC versions

When Paper publishes a new calendar-versioned release (e.g. 26.1.2)
pluggy init defaults to it, but the downstream platform providers
weren't ready: sponge resolved spongeapi to a version only published as
-SNAPSHOT on Maven, and folia still hardcoded the old <mc>-R0.1-SNAPSHOT
artifact name even though folia-api moved to the build-stamped form
(26.1.2.build.8-stable) like paper did. Both now probe maven-metadata
and pick a published variant.

Also surfaced while testing: build output displayed absolute paths, and
--platform bungeecord was rejected even though that's the natural name
for the waterfall-backed proxy.

- sponge: resolvePublishedApiVersion checks the spongeapi metadata for
  a release variant before falling back to -SNAPSHOT.
- folia/paper: share papermc.resolveApiVersion, which prefers the
  highest <mc>.build.<N>-<channel> entry and falls back to the SNAPSHOT
  form on miss.
- build: print outputPath relative to the cwd pluggy was invoked from
  (paper/bin/foo.jar instead of /Users/.../paper/bin/foo.jar); absolute
  path retained when --output points outside cwd and in the JSON
  payload.
- platforms: new resolve()/aliases() on the registry; parsePlatform
  resolves aliases (bungee, bungeecord -> waterfall).

Author: ch99q

src/commands/build.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import process from "node:process";
 
 import { Command, InvalidArgumentError } from "commander";
@@ -91,18 +92,32 @@ export async function runBuildCommand(opts: BuildCommandOptions): Promise<BuildC
 
   const targets = selectBuildTargets(context, opts);
 
-  const initial = await buildTargets(targets, opts);
+  const initial = await buildTargets(targets, opts, cwd);
 
   if (opts.watch === true) {
-    await runWatchLoop(targets, opts);
+    await runWatchLoop(targets, opts, cwd);
   }
 
   return initial;
 }
 
+/**
+ * Render an absolute jar path relative to where `pluggy build` ran. At a
+ * multi-workspace root that produces `paper/bin/foo.jar` instead of the full
+ * `/Users/.../paper/bin/foo.jar`; for paths outside cwd (rare, but possible
+ * via `--output`) it falls back to the absolute form so the user can still
+ * find the file.
+ */
+function displayPath(absPath: string, cwd: string): string {
+  const rel = relative(cwd, absPath);
+  if (rel === "" || rel.startsWith("..")) return absPath;
+  return rel;
+}
+
 async function buildTargets(
   targets: WorkspaceNode[],
   opts: BuildCommandOptions,
+  cwd: string,
 ): Promise<BuildCommandResult> {
   const runResults = await runWorkspaces<BuildOneResult>(
     targets,
@@ -137,7 +152,7 @@ async function buildTargets(
       }
 
       log.success(
-        `${bold(label)} → ${build.outputPath} ${dim(`(${formatBytes(build.sizeBytes)}, ${build.durationMs}ms)`)}`,
+        `${bold(label)} → ${displayPath(build.outputPath, cwd)} ${dim(`(${formatBytes(build.sizeBytes)}, ${build.durationMs}ms)`)}`,
       );
       return { build, platformChecks };
     },
@@ -202,7 +217,7 @@ async function buildTargets(
     for (const r of results) {
       if (r.ok) {
         log.step(
-          `${r.workspace} → ${r.outputPath} ${dim(`(${formatBytes(r.sizeBytes ?? 0)}, ${r.durationMs}ms)`)}`,
+          `${r.workspace} → ${r.outputPath !== undefined ? displayPath(r.outputPath, cwd) : "(no output)"} ${dim(`(${formatBytes(r.sizeBytes ?? 0)}, ${r.durationMs}ms)`)}`,
         );
       } else {
         log.step(`${red(r.workspace)} failed: ${r.error ?? "unknown error"}`);
@@ -223,7 +238,11 @@ async function buildTargets(
  * Watch-mode output stays unbuffered: users expect live progress as they
  * iterate, even when `--concurrency > 1`.
  */
-async function runWatchLoop(allTargets: WorkspaceNode[], opts: BuildCommandOptions): Promise<void> {
+async function runWatchLoop(
+  allTargets: WorkspaceNode[],
+  opts: BuildCommandOptions,
+  cwd: string,
+): Promise<void> {
   if (allTargets.length === 0) return;
   const debounceMs = opts.watchDebounceMs ?? 100;
   const reverseGraph = computeReverseDependents(allTargets);
@@ -245,7 +264,7 @@ async function runWatchLoop(allTargets: WorkspaceNode[], opts: BuildCommandOptio
     log.heading(
       `Rebuild triggered for ${subset.length} workspace${subset.length === 1 ? "" : "s"} (${subset.map((s) => s.name).join(", ")})`,
     );
-    await buildTargets(subset, { ...opts, watch: false }).catch((err) => {
+    await buildTargets(subset, { ...opts, watch: false }, cwd).catch((err) => {
       log.error(err instanceof Error ? err.message : String(err));
     });
     building = false;

src/commands/parsers.ts

@@ -31,14 +31,12 @@ export function parseSemver(value: string): string {
 }
 
 export function parsePlatform(value: string): string {
+  const resolved = platforms.resolve(value);
+  if (resolved !== undefined) return resolved;
   const registered = platforms.list();
-  const id = value.toLowerCase();
-  if (!registered.includes(id)) {
-    throw new InvalidArgumentError(
-      `Invalid platform: "${value}". Available platforms: ${registered.join(", ")}`,
-    );
-  }
-  return id;
+  throw new InvalidArgumentError(
+    `Invalid platform: "${value}". Available platforms: ${registered.join(", ")}`,
+  );
 }
 
 export function parseMcVersion(value: string): string {

src/platform/papermc/folia.ts

@@ -31,13 +31,15 @@ export default createPlatform((ctx) => ({
     return versionsList.map((v) => v.version.id);
   },
 
-  api(version) {
-    return Promise.resolve({
+  async api(version: string) {
+    const resolved = await papermc.resolveApiVersion(
+      "https://repo.papermc.io/repository/maven-public/dev/folia/folia-api/maven-metadata.xml",
+      version,
+    );
+    return {
       repositories: ["https://repo.papermc.io/repository/maven-public/"],
-      dependencies: [
-        { groupId: "dev.folia", artifactId: "folia-api", version: `${version}-R0.1-SNAPSHOT` },
-      ],
-    });
+      dependencies: [{ groupId: "dev.folia", artifactId: "folia-api", version: resolved }],
+    };
   },
 
   async download(version: Version, ignoreCache = false) {

src/platform/papermc/paper.ts

@@ -10,41 +10,6 @@ import * as papermc from "./papermc.ts";
 const PAPER_MAVEN_METADATA =
   "https://repo.papermc.io/repository/maven-public/io/papermc/paper/paper-api/maven-metadata.xml";
 
-/**
- * Resolve an MC version (e.g. `"1.21.8"`, `"26.1.2"`) to the Maven
- * coordinate Paper publishes for `paper-api`.
- *
- * Paper has two formats in the wild:
- *   - Old SNAPSHOT form: `<mc>-R0.1-SNAPSHOT` (1.17 to 1.21.x)
- *   - New build-stamped form: `<mc>.build.<N>-alpha` (26.x+)
- *
- * The provider fetches Paper's top-level `maven-metadata.xml` and picks
- * the highest matching entry. Falls back to the old SNAPSHOT form when
- * no published artifact is found, so the Maven resolver can surface a
- * specific 404 instead of a cryptic "no match".
- */
-async function resolvePaperApiVersion(mcVersion: string): Promise<string> {
-  const res = await fetch(PAPER_MAVEN_METADATA);
-  if (!res.ok) return `${mcVersion}-R0.1-SNAPSHOT`;
-  const xml = await res.text();
-  const all = Array.from(xml.matchAll(/<version>([^<]+)<\/version>/g), (m) => m[1]);
-
-  const newFormat = all.filter((v) => v.startsWith(`${mcVersion}.build.`));
-  if (newFormat.length > 0) {
-    return newFormat.sort((a, b) => buildNumber(b) - buildNumber(a))[0];
-  }
-
-  const oldFormat = all.find((v) => v === `${mcVersion}-R0.1-SNAPSHOT`);
-  if (oldFormat !== undefined) return oldFormat;
-
-  return `${mcVersion}-R0.1-SNAPSHOT`;
-}
-
-function buildNumber(versionString: string): number {
-  const match = versionString.match(/\.build\.(\d+)/);
-  return match ? Number.parseInt(match[1], 10) : 0;
-}
-
 export default createPlatform((ctx) => ({
   id: "paper",
   descriptor: bukkitDescriptor,
@@ -71,7 +36,7 @@ export default createPlatform((ctx) => ({
 
   async api(version: string) {
     const repo = "https://repo.papermc.io/repository/maven-public/";
-    const resolved = await resolvePaperApiVersion(version);
+    const resolved = await papermc.resolveApiVersion(PAPER_MAVEN_METADATA, version);
     return {
       repositories: [repo],
       dependencies: [

src/platform/papermc/papermc.ts

@@ -39,6 +39,39 @@ export function versions(project: Project): Promise<Version[]> {
     .then((data) => data.versions.filter((v) => v.builds.length > 0));
 }
 
+/**
+ * Resolve a Minecraft version (e.g. `1.21.8`, `26.1.2`) to the Maven
+ * coordinate published for a PaperMC artifact (paper-api, folia-api, …).
+ *
+ * Two formats coexist:
+ *   - Old SNAPSHOT form: `<mc>-R0.1-SNAPSHOT` (used through 1.21.x)
+ *   - New build-stamped form: `<mc>.build.<N>-<channel>` (26.x+)
+ *
+ * Fetches the artifact's top-level `maven-metadata.xml` and prefers the
+ * highest build-stamped entry. Falls back to the SNAPSHOT form when no
+ * build-stamped entry exists (or metadata isn't reachable) so the Maven
+ * resolver surfaces a specific 404 instead of a cryptic "no match".
+ */
+export async function resolveApiVersion(metadataUrl: string, mcVersion: string): Promise<string> {
+  const snapshotForm = `${mcVersion}-R0.1-SNAPSHOT`;
+  const res = await fetch(metadataUrl);
+  if (!res.ok) return snapshotForm;
+  const xml = await res.text();
+  const all = Array.from(xml.matchAll(/<version>([^<]+)<\/version>/g), (m) => m[1]);
+
+  const buildStamped = all.filter((v) => v.startsWith(`${mcVersion}.build.`));
+  if (buildStamped.length > 0) {
+    return buildStamped.sort((a, b) => buildNumber(b) - buildNumber(a))[0];
+  }
+
+  return snapshotForm;
+}
+
+function buildNumber(versionString: string): number {
+  const match = versionString.match(/\.build\.(\d+)/);
+  return match ? Number.parseInt(match[1], 10) : 0;
+}
+
 /**
  * Download a specific build (or the latest build when `build` is omitted)
  * for `project`/`version` and return the bytes. `target` selects the

src/platform/platform.test.ts

@@ -37,3 +37,29 @@ describe("platforms.assertSameFamily", () => {
     expect(() => platforms.assertSameFamily(["paper", "bogus"])).toThrow(/'bogus' not found/);
   });
 });
+
+describe("platforms.resolve", () => {
+  test("returns the canonical id for a registered platform", () => {
+    expect(platforms.resolve("paper")).toBe("paper");
+  });
+
+  test("is case-insensitive", () => {
+    expect(platforms.resolve("PAPER")).toBe("paper");
+  });
+
+  test("resolves bungeecord to waterfall", () => {
+    expect(platforms.resolve("bungeecord")).toBe("waterfall");
+    expect(platforms.resolve("BungeeCord")).toBe("waterfall");
+    expect(platforms.resolve("bungee")).toBe("waterfall");
+  });
+
+  test("returns undefined for unknown ids", () => {
+    expect(platforms.resolve("totally-fake")).toBeUndefined();
+  });
+});
+
+describe("platforms.get with aliases", () => {
+  test("get('bungeecord') returns the waterfall provider", () => {
+    expect(platforms.get("bungeecord").id).toBe("waterfall");
+  });
+});

src/platform/platform.ts

@@ -96,6 +96,17 @@ export interface PlatformContext {
 
 const PLATFORMS: Record<string, PlatformProvider> = {};
 
+/**
+ * Human-friendly aliases that resolve to a registered platform id.
+ * BungeeCord proxies are served by the Waterfall provider (Waterfall is the
+ * actively-maintained PaperMC fork of BungeeCord), so users typing the
+ * upstream name land on the right provider.
+ */
+const ALIASES: Record<string, string> = {
+  bungee: "waterfall",
+  bungeecord: "waterfall",
+};
+
 /**
  * Define and register a platform provider. The factory runs at module-load
  * time and must not perform I/O. The Bun-compiled binary ships a read-only
@@ -115,10 +126,10 @@ export function createPlatform<T extends PlatformProvider>(
  * supplies context, so the actions stay concise.
  */
 export const platforms = {
-  /** Look up a registered platform by id (case-insensitive). Throws if missing. */
+  /** Look up a registered platform by id or alias (case-insensitive). Throws if missing. */
   get(this: void, providerId: string): PlatformProvider {
-    const id = providerId.toLowerCase();
-    if (!PLATFORMS[id]) {
+    const id = platforms.resolve(providerId);
+    if (id === undefined) {
       const known = Object.keys(PLATFORMS).sort();
       throw new UserError(`Platform with id '${providerId}' not found`, {
         code: "E_PLATFORM_UNKNOWN",
@@ -130,11 +141,29 @@ export const platforms = {
     return PLATFORMS[id];
   },
 
+  /**
+   * Resolve an id-or-alias to a canonical platform id. Returns `undefined`
+   * when neither matches. Callers that want a hard failure should use
+   * `platforms.get()`.
+   */
+  resolve(this: void, providerId: string): string | undefined {
+    const key = providerId.toLowerCase();
+    if (PLATFORMS[key]) return key;
+    const aliased = ALIASES[key];
+    if (aliased !== undefined && PLATFORMS[aliased]) return aliased;
+    return undefined;
+  },
+
   /** List every registered platform id, lowercased. */
   list(this: void): string[] {
     return Object.keys(PLATFORMS);
   },
 
+  /** Aliases that resolve to canonical ids. Keys are user-facing inputs. */
+  aliases(this: void): Record<string, string> {
+    return { ...ALIASES };
+  },
+
   /**
    * Validate that every id in `ids` resolves to a registered platform and
    * that they all share one `descriptor.family`. Returns that family.

src/platform/sponge/sponge.ts

@@ -131,6 +131,28 @@ async function findLatestArtifactForMc(mcVersion: string): Promise<ResolvedArtif
   return matches[0];
 }
 
+/**
+ * SpongeAPI tags from the dl-api (e.g. `19.0.0`) often outpace what's
+ * published as a release on the Maven repo. Anything past the current
+ * `<release>` only exists as `<api>-SNAPSHOT`. Probe the spongeapi
+ * `maven-metadata.xml` and pick the matching variant; fall back to the raw
+ * tag so the Maven resolver can surface a precise 404 if the metadata fetch
+ * itself fails.
+ */
+async function resolvePublishedApiVersion(api: string): Promise<string> {
+  try {
+    const res = await fetch(`${SPONGE_REPO}org/spongepowered/spongeapi/maven-metadata.xml`);
+    if (!res.ok) return api;
+    const xml = await res.text();
+    const versions = new Set(Array.from(xml.matchAll(/<version>([^<]+)<\/version>/g), (m) => m[1]));
+    if (versions.has(api)) return api;
+    if (versions.has(`${api}-SNAPSHOT`)) return `${api}-SNAPSHOT`;
+    return api;
+  } catch {
+    return api;
+  }
+}
+
 export default createPlatform((ctx) => ({
   id: "sponge",
   descriptor: spongeDescriptor,
@@ -161,13 +183,14 @@ export default createPlatform((ctx) => ({
 
   async api(mcVersion: string) {
     const artifact = await findLatestArtifactForMc(mcVersion);
+    const version = await resolvePublishedApiVersion(artifact.api);
     return {
       repositories: [SPONGE_REPO],
       dependencies: [
         {
           groupId: "org.spongepowered",
           artifactId: "spongeapi",
-          version: artifact.api,
+          version,
         },
       ],
     };