@getrefino/onboarding 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/lockfiles.js

@@ -0,0 +1,443 @@
+/**
+ * Moving `@getrefino/*` from one release to another inside an existing
+ * lockfile, without running a package manager.
+ *
+ * This is only sound because of a property Refino's runtime packages keep on
+ * purpose: they have no third-party dependencies, so the dependency graph of
+ * a site does not change shape when they move. Under that condition a
+ * package manager's own upgrade rewrites nothing but the Refino entries'
+ * version, tarball and integrity (verified against real npm 11, pnpm 11 and
+ * yarn 1 output in lockfiles.test.ts), and so can this. The caller proves the
+ * condition from the registry manifests (`releaseShapeChange`) before asking.
+ *
+ * Everything else refuses rather than guesses:
+ *
+ *   - only lockfile formats whose layout is pinned here (npm v3, pnpm v9,
+ *     yarn classic v1);
+ *   - every line (or JSON value) that mentions a package being moved must be
+ *     one this code consumed, so a second workspace, an override, a patch or
+ *     a peer that names Refino stops the update instead of being left behind;
+ *   - the old entries must be the registry's (same integrity, same tarball),
+ *     so a mirror or a local build is never silently swapped for npmjs;
+ *   - npm's JSON must re-serialize to the exact bytes it was read from before
+ *     anything changes, so formatting is never rewritten.
+ */
+/** The lockfile names this module understands, and the ones it recognises only to refuse. */
+export const LOCKFILES = {
+    "package-lock.json": "npm",
+    "pnpm-lock.yaml": "pnpm",
+    "yarn.lock": "yarn",
+    "npm-shrinkwrap.json": "unsupported",
+    "bun.lockb": "unsupported",
+    "bun.lock": "unsupported",
+};
+class Refusal extends Error {
+}
+function refuse(reason) {
+    throw new Refusal(reason);
+}
+function attempt(run) {
+    try {
+        return { ok: true, text: run() };
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            return { ok: false, reason: error.message };
+        throw error;
+    }
+}
+/** `0.1.0-rc.3` or `0.1.0-rc.3(react-dom@19.1.0(react@19.1.0))`: the version followed by a peer suffix or nothing. */
+function withVersion(value, from, to, what) {
+    if (value === from || value.startsWith(`${from}(`))
+        return `${to}${value.slice(from.length)}`;
+    return refuse(`${what} is locked at ${value}, not ${from}.`);
+}
+/** Refuse when a line mentions a moved package and nothing above consumed it. */
+function assertAccounted(lines, handled, names) {
+    lines.forEach((line, index) => {
+        if (handled.has(index))
+            return;
+        const name = names.find((candidate) => line.includes(`${candidate}@`) || line.includes(`'${candidate}'`) || line.includes(`"${candidate}"`));
+        if (name)
+            refuse(`The lockfile refers to ${name} somewhere Refino does not update (line ${index + 1}), for example another workspace, an override or a patch.`);
+    });
+}
+function assertSeen(seen, expected, where) {
+    const missing = expected.filter((name) => !seen.has(name));
+    if (missing.length > 0)
+        refuse(`${missing.join(", ")} not found in the lockfile's ${where}.`);
+}
+function unquote(key) {
+    return key.replace(/^(['"])(.*)\1$/, "$2");
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function detectIndent(text) {
+    return /^\{\n( +|\t+)"/.exec(text)?.[1] ?? "  ";
+}
+const DEPENDENCY_GROUPS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+function rewriteNpm(text, request) {
+    let lock;
+    try {
+        lock = JSON.parse(text);
+    }
+    catch {
+        return refuse("package-lock.json is not valid JSON.");
+    }
+    if (!isObject(lock) || lock.lockfileVersion !== 3 || !isObject(lock.packages))
+        return refuse("Only package-lock.json version 3 (npm 9 and later) is supported.");
+    const indent = detectIndent(text);
+    const serialize = (value) => `${JSON.stringify(value, null, indent)}\n`;
+    if (serialize(lock) !== text)
+        return refuse("package-lock.json is not formatted the way npm writes it.");
+    const names = request.packages;
+    const appKey = request.importer === "." ? "" : request.importer;
+    const seenInstalled = new Set();
+    const seenSpecs = new Set();
+    for (const [key, entry] of Object.entries(lock.packages)) {
+        if (!isObject(entry))
+            continue;
+        const installed = names.find((name) => key === `node_modules/${name}` || key.endsWith(`/node_modules/${name}`));
+        if (installed) {
+            const prefix = key.slice(0, key.length - `node_modules/${installed}`.length);
+            if (prefix !== "" && prefix !== `${appKey}/`)
+                refuse(`${installed} is also installed for ${prefix.replace(/\/$/, "")}.`);
+            const from = request.fromReleases[installed];
+            const to = request.toReleases[installed];
+            if (entry.link === true || entry.version !== request.from)
+                refuse(`${installed} is locked at ${String(entry.version)}, not ${request.from}.`);
+            if (entry.resolved !== from.tarball || entry.integrity !== from.integrity)
+                refuse(`${installed} ${request.from} in the lockfile did not come from the public npm registry.`);
+            entry.version = request.to;
+            entry.resolved = to.tarball;
+            entry.integrity = to.integrity;
+            for (const group of DEPENDENCY_GROUPS) {
+                const deps = entry[group];
+                if (!isObject(deps))
+                    continue;
+                for (const name of names) {
+                    if (deps[name] === undefined)
+                        continue;
+                    if (deps[name] !== request.from)
+                        refuse(`${installed} ${request.from} depends on ${name} ${String(deps[name])}.`);
+                    deps[name] = request.to;
+                }
+            }
+            seenInstalled.add(installed);
+            continue;
+        }
+        const isWorkspace = !key.includes("node_modules/");
+        for (const group of DEPENDENCY_GROUPS) {
+            const deps = entry[group];
+            if (!isObject(deps))
+                continue;
+            for (const name of names) {
+                if (deps[name] === undefined)
+                    continue;
+                if (!isWorkspace || key !== appKey)
+                    refuse(`${key || "the repository root"} also depends on ${name}.`);
+                const spec = request.specs[name];
+                if (!spec || deps[name] !== spec.from)
+                    refuse(`The lockfile records ${name} as ${String(deps[name])}, but package.json says ${spec?.from ?? "nothing"}.`);
+                deps[name] = spec.to;
+                seenSpecs.add(name);
+            }
+        }
+    }
+    assertSeen(seenInstalled, names, "installed packages");
+    assertSeen(seenSpecs, Object.keys(request.specs), "dependencies of the app");
+    const next = serialize(lock);
+    // The safety net for JSON: every mention of a moved package must be one of the values replaced above.
+    const residue = names.filter((name) => next.includes(`${name}/-/${name.split("/")[1]}-${request.from}.tgz`) && request.from !== request.to);
+    if (residue.length > 0)
+        refuse(`The lockfile still refers to ${residue.join(", ")} ${request.from}.`);
+    return next;
+}
+function readNpm(text, importer, names) {
+    let lock;
+    try {
+        lock = JSON.parse(text);
+    }
+    catch {
+        return refuse("package-lock.json is not valid JSON.");
+    }
+    if (!isObject(lock) || !isObject(lock.packages))
+        return refuse("package-lock.json has no packages section.");
+    const packages = lock.packages;
+    const appKey = importer === "." ? "" : importer;
+    const versions = {};
+    for (const name of names) {
+        // Node resolves from the app outwards: a copy nested under the app wins over a hoisted one.
+        const entry = packages[appKey ? `${appKey}/node_modules/${name}` : `node_modules/${name}`] ?? packages[`node_modules/${name}`];
+        if (isObject(entry) && typeof entry.version === "string")
+            versions[name] = entry.version;
+    }
+    return versions;
+}
+// ---------------------------------------------------------------------------
+// pnpm (lockfileVersion 9)
+function indentOf(line) {
+    return line.length - line.trimStart().length;
+}
+function keyOf(line) {
+    return unquote(line.trim().replace(/:(\s.*)?$/, ""));
+}
+function checkPnpmVersion(first) {
+    if (!first || !/^lockfileVersion: '9\.\d+'$/.test(first))
+        refuse("Only pnpm lockfile version 9 (pnpm 9 and later) is supported.");
+}
+function rewritePnpm(text, request) {
+    const lines = text.split("\n");
+    checkPnpmVersion(lines[0]);
+    const names = request.packages;
+    const handled = new Set([0]);
+    const seen = { importer: new Set(), packages: new Set(), snapshots: new Set() };
+    let section = "";
+    let importer = null;
+    let dependency = null;
+    let block = null;
+    const entryKey = /^ {2}'(@[^@']+\/[^@']+)@([^'(]+)(\(.*\))?'(:.*)$/;
+    lines.forEach((line, index) => {
+        if (line.trim() === "")
+            return;
+        const indent = indentOf(line);
+        if (indent === 0) {
+            section = keyOf(line);
+            importer = dependency = null;
+            block = null;
+            return;
+        }
+        if (section === "importers") {
+            if (indent === 2) {
+                importer = keyOf(line);
+                dependency = null;
+            }
+            else if (indent === 6) {
+                dependency = keyOf(line);
+                if (names.includes(dependency)) {
+                    if (importer !== request.importer)
+                        refuse(`Workspace ${importer} also depends on ${dependency}.`);
+                    handled.add(index);
+                }
+            }
+            else if (indent === 8 && dependency && names.includes(dependency)) {
+                const match = /^(\s+)(specifier|version): (.+)$/.exec(line);
+                if (!match)
+                    return;
+                const [, pad, field, value] = match;
+                if (field === "specifier") {
+                    const spec = request.specs[dependency];
+                    if (!spec || value !== spec.from)
+                        refuse(`The lockfile records ${dependency} as ${value}, but package.json says ${spec?.from ?? "nothing"}.`);
+                    lines[index] = `${pad}specifier: ${spec.to}`;
+                }
+                else {
+                    lines[index] = `${pad}version: ${withVersion(value, request.from, request.to, dependency)}`;
+                    seen.importer.add(dependency);
+                }
+                handled.add(index);
+            }
+            return;
+        }
+        if (section !== "packages" && section !== "snapshots")
+            return;
+        if (indent === 2) {
+            const match = entryKey.exec(line);
+            block = null;
+            if (!match || !names.includes(match[1]))
+                return;
+            const [, name, version, peers = "", rest] = match;
+            if (version !== request.from)
+                refuse(`The lockfile also holds ${name} ${version}.`);
+            lines[index] = `  '${name}@${request.to}${peers}'${rest}`;
+            handled.add(index);
+            seen[section].add(name);
+            block = { name };
+            return;
+        }
+        if (section === "packages" && block && indent === 4 && line.trimStart().startsWith("resolution:")) {
+            const from = request.fromReleases[block.name];
+            if (line !== `    resolution: {integrity: ${from.integrity}}`)
+                refuse(`${block.name} ${request.from} in the lockfile did not come from the public npm registry.`);
+            lines[index] = `    resolution: {integrity: ${request.toReleases[block.name].integrity}}`;
+            handled.add(index);
+            return;
+        }
+        if (section === "snapshots" && block && indent === 6) {
+            const match = /^(\s+)'(@[^']+)': (.+)$/.exec(line);
+            if (!match || !names.includes(match[2]))
+                return;
+            lines[index] = `${match[1]}'${match[2]}': ${withVersion(match[3], request.from, request.to, match[2])}`;
+            handled.add(index);
+        }
+    });
+    assertAccounted(lines, handled, names);
+    assertSeen(seen.importer, Object.keys(request.specs), "importer");
+    assertSeen(seen.packages, names, "packages");
+    assertSeen(seen.snapshots, names, "snapshots");
+    return lines.join("\n");
+}
+function readPnpm(text, importer, names) {
+    const lines = text.split("\n");
+    checkPnpmVersion(lines[0]);
+    const versions = {};
+    let section = "";
+    let current = null;
+    let dependency = null;
+    for (const line of lines) {
+        if (line.trim() === "")
+            continue;
+        const indent = indentOf(line);
+        if (indent === 0)
+            section = keyOf(line);
+        if (section !== "importers")
+            continue;
+        if (indent === 2)
+            current = keyOf(line);
+        else if (indent === 6)
+            dependency = keyOf(line);
+        else if (indent === 8 && current === importer && dependency && names.includes(dependency)) {
+            const version = /^\s+version: ([^(\s]+)/.exec(line)?.[1];
+            if (version)
+                versions[dependency] = version;
+        }
+    }
+    return versions;
+}
+// ---------------------------------------------------------------------------
+// yarn classic (lockfile v1)
+function checkYarnVersion(text) {
+    if (!text.includes("# yarn lockfile v1") || /^__metadata:/m.test(text))
+        refuse("Only yarn classic (yarn 1) lockfiles are supported.");
+}
+function parseDescriptor(raw) {
+    const descriptor = unquote(raw.trim());
+    const at = descriptor.lastIndexOf("@");
+    if (at <= 0)
+        return null;
+    return { name: descriptor.slice(0, at), range: descriptor.slice(at + 1) };
+}
+function rewriteYarn(text, request) {
+    checkYarnVersion(text);
+    const lines = text.split("\n");
+    const names = request.packages;
+    const handled = new Set();
+    const seen = new Set();
+    let block = null;
+    lines.forEach((line, index) => {
+        if (line.trim() === "" || line.startsWith("#"))
+            return;
+        if (indentOf(line) === 0) {
+            block = null;
+            const descriptors = line.replace(/:$/, "").split(/,\s*/).map(parseDescriptor);
+            const name = descriptors[0]?.name;
+            if (!name || !names.includes(name))
+                return;
+            const spec = request.specs[name];
+            const next = descriptors.map((descriptor) => {
+                if (!descriptor || descriptor.name !== name)
+                    return refuse(`Unexpected lockfile entry: ${line}`);
+                if (spec && descriptor.range === spec.from)
+                    return spec.to;
+                // Refino packages depend on each other at one exact version.
+                if (descriptor.range === request.from)
+                    return request.to;
+                return refuse(`Something else in the repository asks for ${name}@${descriptor.range}.`);
+            });
+            lines[index] = `${[...new Set(next)].map((range) => `"${name}@${range}"`).sort().join(", ")}:`;
+            handled.add(index);
+            seen.add(name);
+            block = name;
+            return;
+        }
+        if (!block)
+            return;
+        const from = request.fromReleases[block];
+        const to = request.toReleases[block];
+        const field = /^ {2}(version|resolved|integrity) (.+)$/.exec(line);
+        if (field) {
+            const [, key, value] = field;
+            if (key === "version") {
+                if (value !== `"${request.from}"`)
+                    refuse(`${block} is locked at ${value}, not ${request.from}.`);
+                lines[index] = `  version "${request.to}"`;
+            }
+            else if (key === "resolved") {
+                const match = /^"(https:\/\/registry\.(?:yarnpkg\.com|npmjs\.org))\/(.+)#([0-9a-f]{40})"$/.exec(value);
+                const path = new URL(from.tarball).pathname.slice(1);
+                if (!match || match[2] !== path || match[3] !== from.shasum)
+                    refuse(`${block} ${request.from} in the lockfile did not come from the public npm registry.`);
+                lines[index] = `  resolved "${match[1]}/${new URL(to.tarball).pathname.slice(1)}#${to.shasum}"`;
+            }
+            else {
+                if (value !== from.integrity)
+                    refuse(`${block} ${request.from} in the lockfile did not come from the public npm registry.`);
+                lines[index] = `  integrity ${to.integrity}`;
+            }
+            handled.add(index);
+            return;
+        }
+        const dependency = /^ {4}"(@[^"]+)" "([^"]+)"$/.exec(line);
+        if (dependency && names.includes(dependency[1])) {
+            if (dependency[2] !== request.from)
+                refuse(`${block} depends on ${dependency[1]} ${dependency[2]}.`);
+            lines[index] = `    "${dependency[1]}" "${request.to}"`;
+            handled.add(index);
+        }
+    });
+    assertAccounted(lines, handled, names);
+    assertSeen(seen, names, "entries");
+    return lines.join("\n");
+}
+function readYarn(text, specs) {
+    checkYarnVersion(text);
+    const versions = {};
+    let block = null;
+    for (const line of text.split("\n")) {
+        if (line.trim() === "" || line.startsWith("#"))
+            continue;
+        if (indentOf(line) === 0) {
+            block = null;
+            const descriptors = line.replace(/:$/, "").split(/,\s*/).map(parseDescriptor);
+            const match = descriptors.find((descriptor) => descriptor && specs[descriptor.name] === descriptor.range);
+            if (match)
+                block = match.name;
+            continue;
+        }
+        const version = block ? /^ {2}version "([^"]+)"$/.exec(line)?.[1] : undefined;
+        if (block && version)
+            versions[block] = version;
+    }
+    return versions;
+}
+// ---------------------------------------------------------------------------
+/**
+ * The versions a lockfile resolves the app's direct Refino dependencies to.
+ * `specs` maps each dependency name to its package.json specifier.
+ */
+export function readLockedVersions(kind, text, importer, specs) {
+    try {
+        const names = Object.keys(specs);
+        const versions = kind === "npm" ? readNpm(text, importer, names) : kind === "pnpm" ? readPnpm(text, importer, names) : readYarn(text, specs);
+        return { ok: true, versions };
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            return { ok: false, reason: error.message };
+        throw error;
+    }
+}
+/** Rewrite a lockfile so the Refino packages move from `request.from` to `request.to`, or say why it cannot be done safely. */
+export function rewriteLockfile(kind, text, request) {
+    return attempt(() => {
+        switch (kind) {
+            case "npm":
+                return rewriteNpm(text, request);
+            case "pnpm":
+                return rewritePnpm(text, request);
+            case "yarn":
+                return rewriteYarn(text, request);
+        }
+    });
+}

package/dist/plan.d.ts

@@ -1,11 +1,5 @@
 import type { HostIntegration, HostKind, MigrationPlan, PlanOptions, RefinoSite, RepositoryInspection, ScanResult } from "./types.js";
-export declare const TOOL_NAME = "refino";
-/**
- * The published version of this package. A prerelease build names the commit
- * it came from, so plans, instructions and the dependency pins a site
- * receives say exactly which build produced them.
- */
-export declare const TOOL_VERSION: string;
+export { BOILERPLATE_DIR, CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_DIR, PLAN_FILE, TOOL_NAME, TOOL_VERSION } from "./constants.js";
 /**
  * Dependency range for the runtime packages. Any prerelease (a smoke build or
  * a release candidate) is pinned exactly, so a site records the one build it
@@ -13,11 +7,6 @@ export declare const TOOL_VERSION: string;
  * eventual stable release. Stable versions get a caret.
  */
 export declare function dependencyRange(version?: string): string;
-export declare const PLAN_DIR = ".refino";
-export declare const PLAN_FILE = ".refino/plan.json";
-export declare const INSTRUCTIONS_FILE = ".refino/AGENT_INSTRUCTIONS.md";
-export declare const CONFIG_FILE = "refino.config.json";
-export declare const BOILERPLATE_DIR = "refino";
 export declare function defaultContentFile(inspection: RepositoryInspection): string;
 /** Validate and normalize the Refino connection given on the command line. */
 export declare function resolveRefinoSite(option: PlanOptions["refino"]): RefinoSite | null;

package/dist/plan.js

@@ -3,20 +3,14 @@
  * plan is the contract between the CLI, the agent instructions, the safe
  * apply step and the verifier.
  */
-import { createRequire } from "node:module";
 import { join } from "node:path";
 import { parseCopy } from "@getrefino/core";
+import { BOILERPLATE_DIR, CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE, TOOL_NAME, TOOL_VERSION } from "./constants.js";
 import { exists, isDirectory, readText } from "./fs.js";
 import { appDirectory, packageManagerExec, packageManagerRun } from "./inspect.js";
 import { scanCopy } from "./scan.js";
 import { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN } from "./templates-hosted.js";
-export const TOOL_NAME = "refino";
-/**
- * The published version of this package. A prerelease build names the commit
- * it came from, so plans, instructions and the dependency pins a site
- * receives say exactly which build produced them.
- */
-export const TOOL_VERSION = createRequire(import.meta.url)("../package.json").version;
+export { BOILERPLATE_DIR, CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_DIR, PLAN_FILE, TOOL_NAME, TOOL_VERSION } from "./constants.js";
 const PRERELEASE_VERSION = /^\d+\.\d+\.\d+-/;
 /**
  * Dependency range for the runtime packages. Any prerelease (a smoke build or
@@ -27,11 +21,6 @@ const PRERELEASE_VERSION = /^\d+\.\d+\.\d+-/;
 export function dependencyRange(version = TOOL_VERSION) {
     return PRERELEASE_VERSION.test(version) ? version : `^${version}`;
 }
-export const PLAN_DIR = ".refino";
-export const PLAN_FILE = `${PLAN_DIR}/plan.json`;
-export const INSTRUCTIONS_FILE = `${PLAN_DIR}/AGENT_INSTRUCTIONS.md`;
-export const CONFIG_FILE = "refino.config.json";
-export const BOILERPLATE_DIR = "refino";
 export function defaultContentFile(inspection) {
     if (inspection.refino.contentFile)
         return inspection.refino.contentFile;

package/dist/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the npm registry says about one published version of a package, and
+ * the one question an in-place upgrade needs answered from it: does moving
+ * from this release to that one change anything a lockfile records other
+ * than the version, the tarball and its hashes?
+ */
+import type { PackageRelease } from "./lockfiles.js";
+export declare const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** The fields of a version manifest (`GET /<name>/<version>`) that this code reads. */
+export interface RegistryManifest {
+    readonly name: string;
+    readonly version: string;
+    readonly dist: {
+        readonly tarball: string;
+        readonly integrity: string;
+        readonly shasum: string;
+    };
+    readonly deprecated?: string;
+    readonly [field: string]: unknown;
+}
+export interface PackageRegistry {
+    /** The manifest of one exact version, or null when the registry has no such version. Throws when the registry cannot be reached. */
+    manifest(name: string, version: string): Promise<RegistryManifest | null>;
+}
+export interface NpmRegistryOptions {
+    readonly url?: string;
+    readonly fetch?: typeof fetch;
+}
+export declare function createNpmRegistry(options?: NpmRegistryOptions): PackageRegistry;
+export declare function toRelease(manifest: RegistryManifest): PackageRelease;
+/**
+ * The Refino packages a release depends on (`dependencies` only). Refino
+ * publishes them in lockstep, so each is at the release's own version.
+ */
+export declare function refinoDependencies(manifest: RegistryManifest, scope?: string): string[];
+/**
+ * Why moving from `from` to `to` would change a lockfile beyond the
+ * version, tarball and hashes of the packages being moved, or null when it
+ * would not. `moving` is every package that moves; each may depend on the
+ * others at exactly its own version and at nothing else.
+ */
+export declare function releaseShapeChange(from: RegistryManifest, to: RegistryManifest, moving: readonly string[]): string | null;

package/dist/registry.js

@@ -0,0 +1,111 @@
+export const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+function isManifest(value, name, version) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const manifest = value;
+    const dist = manifest.dist;
+    return (manifest.name === name &&
+        manifest.version === version &&
+        typeof dist === "object" &&
+        dist !== null &&
+        typeof dist.tarball === "string" &&
+        typeof dist.integrity === "string" &&
+        /^sha512-/.test(dist.integrity) &&
+        typeof dist.shasum === "string" &&
+        /^[0-9a-f]{40}$/.test(dist.shasum));
+}
+export function createNpmRegistry(options = {}) {
+    const base = (options.url ?? NPM_REGISTRY_URL).replace(/\/+$/, "");
+    const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    return {
+        async manifest(name, version) {
+            const response = await doFetch(`${base}/${name.replace("/", "%2f")}/${encodeURIComponent(version)}`, {
+                headers: { accept: "application/json" },
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok)
+                throw new Error(`The npm registry answered HTTP ${response.status} for ${name}@${version}.`);
+            const body = await response.json();
+            if (!isManifest(body, name, version))
+                throw new Error(`The npm registry returned an unexpected manifest for ${name}@${version}.`);
+            return body;
+        },
+    };
+}
+export function toRelease(manifest) {
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        tarball: manifest.dist.tarball,
+        integrity: manifest.dist.integrity,
+        shasum: manifest.dist.shasum,
+    };
+}
+/** Manifest fields that npm, pnpm or yarn copy into a lockfile entry or act on at install time. */
+const LOCKFILE_FIELDS = [
+    "dependencies",
+    "optionalDependencies",
+    "peerDependencies",
+    "peerDependenciesMeta",
+    "bundleDependencies",
+    "bundledDependencies",
+    "engines",
+    "os",
+    "cpu",
+    "libc",
+    "bin",
+    "license",
+    "funding",
+];
+const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall"];
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stable(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+/**
+ * The Refino packages a release depends on (`dependencies` only). Refino
+ * publishes them in lockstep, so each is at the release's own version.
+ */
+export function refinoDependencies(manifest, scope = "@getrefino/") {
+    const dependencies = (manifest.dependencies ?? {});
+    return Object.keys(dependencies).filter((name) => name.startsWith(scope));
+}
+/**
+ * Why moving from `from` to `to` would change a lockfile beyond the
+ * version, tarball and hashes of the packages being moved, or null when it
+ * would not. `moving` is every package that moves; each may depend on the
+ * others at exactly its own version and at nothing else.
+ */
+export function releaseShapeChange(from, to, moving) {
+    if (to.deprecated)
+        return `${to.name}@${to.version} is deprecated.`;
+    const normalize = (manifest, field) => {
+        const value = manifest[field];
+        if (field !== "dependencies" || typeof value !== "object" || value === null)
+            return stable(value);
+        const own = {};
+        for (const [name, range] of Object.entries(value)) {
+            own[name] = moving.includes(name) && range === manifest.version ? "<release>" : range;
+        }
+        return stable(own);
+    };
+    for (const field of LOCKFILE_FIELDS) {
+        if (normalize(from, field) !== normalize(to, field))
+            return `${to.name}@${to.version} changes its ${field}.`;
+    }
+    const scripts = (manifest) => {
+        const all = (manifest.scripts ?? {});
+        return INSTALL_SCRIPTS.filter((name) => name in all).join(",");
+    };
+    if (scripts(from) !== scripts(to))
+        return `${to.name}@${to.version} changes its install scripts.`;
+    return null;
+}

package/dist/semver.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Just enough semver for comparing Refino release versions: exact versions
+ * only (`1.2.3`, `0.1.0-rc.4`), ordered by the semver 2.0 precedence rules.
+ * Ranges are never interpreted here; code that meets one treats it as
+ * something to preserve or refuse, not something to reason about.
+ */
+/** Whether `value` is one exact version (no range, no tag, no `v` prefix). */
+export declare function isExactVersion(value: string): boolean;
+/**
+ * Negative when `a` precedes `b`, positive when it follows, zero when they
+ * are the same release. Throws on anything that is not an exact version, so
+ * a caller can never mistake "could not compare" for "equal".
+ */
+export declare function compareVersions(a: string, b: string): number;