@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/utils/markers.ts

@@ -0,0 +1,48 @@
+const MARKER_START = "<!-- loam:start -->";
+const MARKER_END = "<!-- loam:end -->";
+
+export { MARKER_START, MARKER_END };
+
+/**
+ * Check whether content contains the loam marker section.
+ */
+export function hasMarkerSection(content: string): boolean {
+	return content.includes(MARKER_START);
+}
+
+/**
+ * Replace the marker-bounded section with new content.
+ * Returns null if no markers found.
+ */
+export function replaceMarkerSection(content: string, newSection: string): string | null {
+	const startIdx = content.indexOf(MARKER_START);
+	const endIdx = content.indexOf(MARKER_END);
+	if (startIdx === -1 || endIdx === -1) return null;
+
+	const before = content.substring(0, startIdx);
+	const after = content.substring(endIdx + MARKER_END.length);
+
+	return before + newSection + after;
+}
+
+/**
+ * Remove the marker-bounded section entirely.
+ * Cleans up extra newlines left behind.
+ */
+export function removeMarkerSection(content: string): string {
+	const startIdx = content.indexOf(MARKER_START);
+	const endIdx = content.indexOf(MARKER_END);
+	if (startIdx === -1 || endIdx === -1) return content;
+
+	const before = content.substring(0, startIdx);
+	const after = content.substring(endIdx + MARKER_END.length);
+
+	return `${(before + after).replace(/\n{3,}/g, "\n\n").trim()}\n`;
+}
+
+/**
+ * Wrap a snippet in loam markers.
+ */
+export function wrapInMarkers(snippet: string): string {
+	return `${MARKER_START}\n${snippet}${MARKER_END}`;
+}

package/src/tools/loam/utils/numeric-flags.ts

@@ -0,0 +1,20 @@
+// Strict numeric-flag parsers. `Number.parseFloat("10abc")` silently strips
+// trailing garbage and `Number.parseInt("3.7", 10)` truncates to 3 — both
+// would let typos through and write nonsense (NaN, partial values) to
+// .loam/expertise/*.jsonl. Use a regex gate + Number() to reject anything
+// that isn't a clean numeric literal. Convention: mx-5b9578.
+
+const POSITIVE_INT_RE = /^\d+$/;
+const NON_NEGATIVE_NUMBER_RE = /^\d+(\.\d+)?$/;
+
+export function parseStrictPositiveInt(raw: string): number | null {
+	if (!POSITIVE_INT_RE.test(raw)) return null;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 1 ? n : null;
+}
+
+export function parseStrictNonNegativeNumber(raw: string): number | null {
+	if (!NON_NEGATIVE_NUMBER_RE.test(raw)) return null;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? n : null;
+}

package/src/tools/loam/utils/palette.ts

@@ -0,0 +1,44 @@
+import chalk from "chalk";
+
+// Loam brand color: brown / soil
+export const brand = chalk.rgb(139, 90, 43);
+
+// Shared semantic colors
+export const accent = chalk.rgb(255, 183, 77); // amber — IDs, references
+export const muted = chalk.rgb(120, 120, 110); // stone gray — metadata
+
+// Status icons (Set D — minimal, maximum terminal compatibility)
+export const icons = {
+	pass: brand("✓"), // success / pass
+	warn: chalk.yellow("!"), // warning / blocked
+	fail: chalk.red("✗"), // error / fail
+	open: brand("-"), // open / pending
+	active: chalk.cyan(">"), // in_progress / active
+	done: chalk.dim("x"), // closed / done
+} as const;
+
+// Quiet mode state
+let _quiet = false;
+
+export function setQuiet(v: boolean): void {
+	_quiet = v;
+}
+
+export function isQuiet(): boolean {
+	return _quiet;
+}
+
+// Message formatters — mirroring visual-spec.md patterns
+export function printSuccess(msg: string): void {
+	if (_quiet) return;
+	console.log(`${icons.pass} ${brand(msg)}`);
+}
+
+export function printError(msg: string): void {
+	console.error(`${icons.fail} ${chalk.red(msg)}`);
+}
+
+export function printWarning(msg: string): void {
+	if (_quiet) return;
+	console.log(`${icons.warn} ${chalk.yellow(msg)}`);
+}

package/src/tools/loam/utils/prime-ranking.ts

@@ -0,0 +1,135 @@
+import { DEFAULT_PRIME_TIER_WEIGHTS, type PrimeTierWeights } from "../schemas/config.ts";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { TRACKERS, type TrackerName } from "./active-work.ts";
+import { fileLivesUnderDir } from "./dir-anchors.ts";
+import type { ActiveContext } from "./git.ts";
+import { fileMatchesAny } from "./git.ts";
+import { computeConfirmationScore } from "./scoring.ts";
+
+// Trust-tier ranking for `lm prime` full-mode output (v0.10 slice 3 of the
+// prime overhaul). The corpus is ordered so the most trustworthy records
+// surface first within the budget cap: star-confirmed > foundational >
+// tactical > observational. Within-tier ties preserve insertion order so a
+// stable run-to-run shape lets agents notice when the top of the list shifts.
+
+export type ResolvedTierWeights = Required<PrimeTierWeights>;
+
+export function resolveTierWeights(override?: PrimeTierWeights): ResolvedTierWeights {
+	return { ...DEFAULT_PRIME_TIER_WEIGHTS, ...(override ?? {}) };
+}
+
+export function computeTrustScore(r: ExpertiseRecord, weights: ResolvedTierWeights): number {
+	const stars = computeConfirmationScore(r);
+	const tier = weights[r.classification] ?? 0;
+	return stars * weights.star + tier;
+}
+
+export function sortByTrust<T extends ExpertiseRecord>(
+	records: T[],
+	weights: ResolvedTierWeights,
+): T[] {
+	// Stable sort: equal scores keep insertion order so within-tier output is
+	// deterministic. Array.prototype.sort is stable in Node ≥ 12 but the
+	// index decorator makes the contract explicit and survives engine quirks.
+	const decorated = records.map((r, i) => ({
+		r,
+		i,
+		score: computeTrustScore(r, weights),
+	}));
+	decorated.sort((a, b) => b.score - a.score || a.i - b.i);
+	return decorated.map((d) => d.r);
+}
+
+// "Why surfaced now" reasons — one per record, picked in priority order so the
+// strongest signal wins. The agent-facing suffix shows the picked reason; the
+// structured shape stays in the type system for future consumers (warren UI,
+// audit reports).
+export type SurfaceReason =
+	| { kind: "file_match"; anchor: string }
+	| { kind: "tracker_match"; tracker: TrackerName; id: string }
+	| { kind: "stars"; count: number }
+	| { kind: "recent"; daysAgo: number }
+	| { kind: "universal" };
+
+// Recency window for the "recent authorship" reason. Aligned with the
+// tactical shelf-life floor so newly-recorded conventions get a why-surfaced
+// hint even before they accumulate confirmations.
+export const RECENT_AUTHORSHIP_DAYS = 7;
+
+export function whySurfaced(r: ExpertiseRecord, ctx: ActiveContext | null): SurfaceReason {
+	if (ctx) {
+		const files = "files" in r && Array.isArray(r.files) ? r.files : undefined;
+		if (files && files.length > 0) {
+			for (const f of files) {
+				if (fileMatchesAny(f, ctx.changedFiles)) {
+					return { kind: "file_match", anchor: f };
+				}
+			}
+		}
+		if (Array.isArray(r.dir_anchors) && r.dir_anchors.length > 0) {
+			for (const d of r.dir_anchors) {
+				for (const cf of ctx.changedFiles) {
+					if (fileLivesUnderDir(cf, d)) {
+						return { kind: "file_match", anchor: d };
+					}
+				}
+			}
+		}
+		for (const t of TRACKERS) {
+			const active = ctx.trackers[t];
+			const evValue = r.evidence?.[t];
+			if (
+				typeof active === "string" &&
+				active !== "" &&
+				typeof evValue === "string" &&
+				active === evValue
+			) {
+				return { kind: "tracker_match", tracker: t, id: active };
+			}
+		}
+	}
+	const stars = computeConfirmationScore(r);
+	if (stars > 0) return { kind: "stars", count: stars };
+	const recordedAt = new Date(r.recorded_at);
+	if (!Number.isNaN(recordedAt.getTime())) {
+		const days = Math.floor((Date.now() - recordedAt.getTime()) / (1000 * 60 * 60 * 24));
+		if (days < RECENT_AUTHORSHIP_DAYS) {
+			return { kind: "recent", daysAgo: Math.max(0, days) };
+		}
+	}
+	return { kind: "universal" };
+}
+
+export function formatSurfaceReason(reason: SurfaceReason): string {
+	switch (reason.kind) {
+		case "file_match":
+			return `why: file match (${reason.anchor})`;
+		case "tracker_match":
+			return `why: in-progress ${reason.tracker}:${reason.id}`;
+		case "stars": {
+			const formatted = Number.isInteger(reason.count)
+				? `★${reason.count}`
+				: `★${reason.count.toFixed(1)}`;
+			return `why: ${formatted} confirmations`;
+		}
+		case "recent":
+			return reason.daysAgo === 0 ? "why: recorded today" : `why: recorded ${reason.daysAgo}d ago`;
+		case "universal":
+			return "why: applies broadly (no anchors)";
+	}
+}
+
+// Build a per-record-id annotation map for downstream formatters. Records
+// without an id are skipped — pre-id corpora exist in older projects and the
+// formatters key on id-bearing lines.
+export function buildSurfaceAnnotations(
+	records: ExpertiseRecord[],
+	ctx: ActiveContext | null,
+): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const r of records) {
+		if (!r.id) continue;
+		map.set(r.id, formatSurfaceReason(whySurfaced(r, ctx)));
+	}
+	return map;
+}

package/src/tools/loam/utils/recipe-discovery.ts

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+export interface RecipeResult {
+	success: boolean;
+	message: string;
+}
+
+export interface ProviderRecipe {
+	install(cwd: string): Promise<RecipeResult>;
+	check(cwd: string): Promise<RecipeResult>;
+	remove(cwd: string): Promise<RecipeResult>;
+}
+
+export type RecipeSource = "builtin" | "filesystem-ts" | "filesystem-sh" | "npm";
+
+export interface RecipeWithSource {
+	name: string;
+	source: RecipeSource;
+	recipe: ProviderRecipe;
+	path?: string;
+}
+
+export interface FilesystemRecipeListing {
+	name: string;
+	source: "filesystem-ts" | "filesystem-sh";
+	path: string;
+}
+
+export const NPM_RECIPE_PREFIX = "loam-recipe-";
+
+export function recipesDir(cwd: string): string {
+	return join(cwd, ".loam", "recipes");
+}
+
+export function validateRecipeShape(obj: unknown): obj is ProviderRecipe {
+	if (!obj || typeof obj !== "object") return false;
+	const r = obj as Record<string, unknown>;
+	return (
+		typeof r.install === "function" &&
+		typeof r.check === "function" &&
+		typeof r.remove === "function"
+	);
+}
+
+function makeShellRecipe(name: string, scriptPath: string): ProviderRecipe {
+	const run = (action: "install" | "check" | "remove", cwd: string): Promise<RecipeResult> =>
+		new Promise((resolve) => {
+			const child = spawn(scriptPath, [action], {
+				cwd,
+				env: {
+					...process.env,
+					LOAM_RECIPE_NAME: name,
+					LOAM_RECIPE_ACTION: action,
+				},
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.on("data", (d: Buffer) => {
+				stdout += d.toString();
+			});
+			child.stderr?.on("data", (d: Buffer) => {
+				stderr += d.toString();
+			});
+			child.on("error", (err) => {
+				resolve({
+					success: false,
+					message: `Failed to execute ${scriptPath}: ${err.message}`,
+				});
+			});
+			child.on("close", (code) => {
+				const out = stdout.trim();
+				const err = stderr.trim();
+				const ok = code === 0;
+				const fallback = ok
+					? `${name} ${action} succeeded`
+					: `${name} ${action} exited with code ${code ?? "?"}${err ? `: ${err}` : ""}`;
+				resolve({ success: ok, message: out || fallback });
+			});
+		});
+
+	return {
+		install: (cwd) => run("install", cwd),
+		check: (cwd) => run("check", cwd),
+		remove: (cwd) => run("remove", cwd),
+	};
+}
+
+export async function loadFilesystemRecipe(
+	name: string,
+	cwd: string,
+): Promise<RecipeWithSource | null> {
+	const dir = recipesDir(cwd);
+	const tsPath = join(dir, `${name}.ts`);
+	const shPath = join(dir, `${name}.sh`);
+
+	if (existsSync(tsPath)) {
+		const mod = (await import(tsPath)) as { default?: unknown };
+		// Spec is `export default { install, check, remove }`. Reject named-only
+		// exports — accepting them silently let users ship recipes that resolved
+		// in development (where they remembered the right named imports) but
+		// surprised the next consumer who imported them as a default.
+		if (mod.default === undefined) {
+			throw new Error(
+				`Recipe "${name}" at ${tsPath} has no default export. ProviderRecipes must be exposed via \`export default { install, check, remove }\`; named exports alone are not accepted. See examples/recipes/internal-ide.ts for a template.`,
+			);
+		}
+		if (!validateRecipeShape(mod.default)) {
+			throw new Error(
+				`Recipe "${name}" at ${tsPath} default export is not a valid ProviderRecipe (must have async install/check/remove functions). See examples/recipes/internal-ide.ts for a template.`,
+			);
+		}
+		return { name, source: "filesystem-ts", recipe: mod.default, path: tsPath };
+	}
+
+	if (existsSync(shPath)) {
+		return {
+			name,
+			source: "filesystem-sh",
+			recipe: makeShellRecipe(name, shPath),
+			path: shPath,
+		};
+	}
+
+	return null;
+}
+
+export async function loadNpmRecipe(name: string, cwd: string): Promise<RecipeWithSource | null> {
+	const pkgName = `${NPM_RECIPE_PREFIX}${name}`;
+	const requireFn = createRequire(import.meta.url);
+	let resolved: string;
+	try {
+		resolved = requireFn.resolve(pkgName, { paths: [cwd] });
+	} catch {
+		return null;
+	}
+	const mod = (await import(resolved)) as { default?: unknown };
+	if (mod.default === undefined) {
+		throw new Error(
+			`Recipe package "${pkgName}" has no default export. ProviderRecipes must be exposed via \`export default { install, check, remove }\`; named exports alone are not accepted.`,
+		);
+	}
+	if (!validateRecipeShape(mod.default)) {
+		throw new Error(
+			`Recipe package "${pkgName}" default export is not a valid ProviderRecipe (must have async install/check/remove functions).`,
+		);
+	}
+	return { name, source: "npm", recipe: mod.default, path: resolved };
+}
+
+export async function listFilesystemRecipes(cwd: string): Promise<FilesystemRecipeListing[]> {
+	const dir = recipesDir(cwd);
+	if (!existsSync(dir)) return [];
+	const entries = await readdir(dir);
+	const out: FilesystemRecipeListing[] = [];
+	for (const entry of entries) {
+		if (entry.endsWith(".ts")) {
+			out.push({
+				name: entry.slice(0, -3),
+				source: "filesystem-ts",
+				path: join(dir, entry),
+			});
+		} else if (entry.endsWith(".sh")) {
+			out.push({
+				name: entry.slice(0, -3),
+				source: "filesystem-sh",
+				path: join(dir, entry),
+			});
+		}
+	}
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function resolveRecipe(
+	name: string,
+	cwd: string,
+	builtins: Record<string, ProviderRecipe>,
+): Promise<RecipeWithSource | null> {
+	const fs = await loadFilesystemRecipe(name, cwd);
+	if (fs) return fs;
+
+	const npm = await loadNpmRecipe(name, cwd);
+	if (npm) return npm;
+
+	const builtin = builtins[name];
+	if (builtin) {
+		return { name, source: "builtin", recipe: builtin };
+	}
+
+	return null;
+}

package/src/tools/loam/utils/runtime-flags.ts

@@ -0,0 +1,28 @@
+// Process-wide runtime flags set during CLI bootstrap. Mirrors the
+// setQuiet/isQuiet pattern in palette.ts so global CLI options can opt
+// commands out of strict policies without threading the flag through
+// every function signature.
+
+let _allowUnknownTypes = false;
+let _allowDomainMismatch = false;
+
+export function setAllowUnknownTypes(value: boolean): void {
+	_allowUnknownTypes = value;
+}
+
+export function isAllowUnknownTypes(): boolean {
+	return _allowUnknownTypes;
+}
+
+export function setAllowDomainMismatch(value: boolean): void {
+	_allowDomainMismatch = value;
+}
+
+export function isAllowDomainMismatch(): boolean {
+	return _allowDomainMismatch;
+}
+
+export function resetRuntimeFlags(): void {
+	_allowUnknownTypes = false;
+	_allowDomainMismatch = false;
+}

package/src/tools/loam/utils/scoring.ts

@@ -0,0 +1,94 @@
+import type { ExpertiseRecord, Outcome } from "../schemas/record.ts";
+
+export type { Outcome };
+
+/**
+ * An ExpertiseRecord with outcome history for confirmation-frequency scoring.
+ * Since ExpertiseRecord now includes outcomes?: Outcome[], this is an alias.
+ */
+export type ScoredRecord = ExpertiseRecord;
+
+/**
+ * Returns the number of successful outcomes for a record.
+ * Successful outcomes indicate confirmed, working applications of the record.
+ */
+export function getSuccessCount(record: ScoredRecord): number {
+	if (!record.outcomes || record.outcomes.length === 0) return 0;
+	return record.outcomes.filter((o) => o.status === "success").length;
+}
+
+/**
+ * Returns the number of failed outcomes for a record.
+ */
+export function getFailureCount(record: ScoredRecord): number {
+	if (!record.outcomes || record.outcomes.length === 0) return 0;
+	return record.outcomes.filter((o) => o.status === "failure").length;
+}
+
+/**
+ * Returns the total number of recorded outcomes (applications) for a record.
+ */
+export function getTotalApplications(record: ScoredRecord): number {
+	return record.outcomes?.length ?? 0;
+}
+
+/**
+ * Returns the success rate (0-1) for a record.
+ * Partial outcomes are counted as 0.5 (half success).
+ * Returns 0 for records with no outcomes.
+ */
+export function getSuccessRate(record: ScoredRecord): number {
+	const total = getTotalApplications(record);
+	if (total === 0) return 0;
+	const partialCount = record.outcomes?.filter((o) => o.status === "partial").length ?? 0;
+	const successCount = getSuccessCount(record);
+	return (successCount + partialCount * 0.5) / total;
+}
+
+/**
+ * Computes the confirmation-frequency score for a record.
+ *
+ * The score is the count of successful confirmations (applications where
+ * the record's guidance was applied and the outcome was "success").
+ * Partial outcomes contribute 0.5 to the score.
+ *
+ * Records with no outcomes return 0.
+ * Records with only failures return 0.
+ */
+export function computeConfirmationScore(record: ScoredRecord): number {
+	if (!record.outcomes || record.outcomes.length === 0) return 0;
+	const successCount = getSuccessCount(record);
+	const partialCount = record.outcomes.filter((o) => o.status === "partial").length;
+	return successCount + partialCount * 0.5;
+}
+
+/**
+ * Applies a confirmation-frequency boost to a base score (e.g., a BM25 relevance score).
+ *
+ * Records with no outcomes (score = 0) are returned unchanged.
+ * Records with confirmed applications receive a multiplicative boost proportional
+ * to their confirmation score.
+ *
+ * @param baseScore - The base relevance score (e.g., from BM25)
+ * @param record - The record to score
+ * @param boostFactor - Multiplier controlling boost magnitude (default: 0.1)
+ * @returns The boosted score
+ */
+export function applyConfirmationBoost(
+	baseScore: number,
+	record: ScoredRecord,
+	boostFactor = 0.1,
+): number {
+	const confirmationScore = computeConfirmationScore(record);
+	if (confirmationScore === 0) return baseScore;
+	return baseScore * (1 + boostFactor * confirmationScore);
+}
+
+/**
+ * Sorts records by confirmation-frequency score, highest first.
+ * Records with equal scores maintain their original relative order (stable sort).
+ * Records with no outcomes (score = 0) sort to the end.
+ */
+export function sortByConfirmationScore<T extends ScoredRecord>(records: T[]): T[] {
+	return [...records].sort((a, b) => computeConfirmationScore(b) - computeConfirmationScore(a));
+}

package/src/tools/loam/utils/version.ts

@@ -0,0 +1,116 @@
+import { execFileSync } from "node:child_process";
+import { VERSION } from "../../../version.ts";
+
+/**
+ * Current CLI version. loam is now bundled in @ag-eco/agentplate-cli, so the
+ * version comes from the shared package version (src/version.ts) rather than a
+ * package.json read relative to this file.
+ */
+export function getCurrentVersion(): string {
+	return VERSION;
+}
+
+/**
+ * Fetch the latest published version of loam-cli from npm.
+ * Returns null if the registry is unreachable.
+ */
+export function getLatestVersion(): string | null {
+	try {
+		const result = execFileSync("npm", ["view", "@ag-eco/loam-cli", "version"], {
+			encoding: "utf-8",
+			timeout: 10000,
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		return result.trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Split a semver string into its main (major.minor.patch) segment and its
+ * optional prerelease tail. Build metadata (after `+`) is ignored per semver
+ * 2.0.0 precedence rules.
+ */
+function splitSemver(v: string): { main: string; prerelease: string | null } {
+	const noBuild = v.split("+", 1)[0] ?? v;
+	const dashIdx = noBuild.indexOf("-");
+	if (dashIdx === -1) return { main: noBuild, prerelease: null };
+	return {
+		main: noBuild.slice(0, dashIdx),
+		prerelease: noBuild.slice(dashIdx + 1),
+	};
+}
+
+/**
+ * Parse a single main-version segment to a non-negative integer. Returns 0
+ * for empty / non-numeric input so e.g. `"1.2"` still compares cleanly
+ * against `"1.2.0"`.
+ */
+function parseMainSegment(s: string | undefined): number {
+	if (!s) return 0;
+	const n = Number(s);
+	return Number.isFinite(n) && n >= 0 ? Math.trunc(n) : 0;
+}
+
+/**
+ * Compare two prerelease identifier lists per semver 2.0.0 §11.4:
+ *   - identifiers are split on '.'
+ *   - numeric identifiers compare numerically and rank below non-numeric
+ *   - non-numeric identifiers compare lexically (ASCII)
+ *   - a longer prerelease list wins when all leading identifiers match
+ */
+function comparePrerelease(a: string, b: string): -1 | 0 | 1 {
+	const idsA = a.split(".");
+	const idsB = b.split(".");
+	const len = Math.max(idsA.length, idsB.length);
+	for (let i = 0; i < len; i++) {
+		const x = idsA[i];
+		const y = idsB[i];
+		if (x === undefined) return -1;
+		if (y === undefined) return 1;
+		const xNumeric = /^\d+$/.test(x);
+		const yNumeric = /^\d+$/.test(y);
+		if (xNumeric && yNumeric) {
+			const nx = Number(x);
+			const ny = Number(y);
+			if (nx < ny) return -1;
+			if (nx > ny) return 1;
+			continue;
+		}
+		if (xNumeric) return -1;
+		if (yNumeric) return 1;
+		if (x < y) return -1;
+		if (x > y) return 1;
+	}
+	return 0;
+}
+
+/**
+ * Compare two semver strings (major.minor.patch with optional prerelease).
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ *
+ * Handles prerelease / non-numeric segments per semver 2.0.0: a version with
+ * a prerelease tail (e.g. "1.2.3-beta") ranks below the same main version
+ * without one ("1.2.3"), and never causes a misleading 0 result when the
+ * main components differ.
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+	const sa = splitSemver(a);
+	const sb = splitSemver(b);
+	const partsA = sa.main.split(".");
+	const partsB = sb.main.split(".");
+
+	for (let i = 0; i < 3; i++) {
+		const segA = parseMainSegment(partsA[i]);
+		const segB = parseMainSegment(partsB[i]);
+		if (segA < segB) return -1;
+		if (segA > segB) return 1;
+	}
+
+	// Main parts equal — apply prerelease precedence.
+	if (sa.prerelease === null && sb.prerelease === null) return 0;
+	if (sa.prerelease === null) return 1; // a is release, b is prerelease
+	if (sb.prerelease === null) return -1;
+	return comparePrerelease(sa.prerelease, sb.prerelease);
+}