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

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+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 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";

package/dist/constants.js

@@ -0,0 +1,19 @@
+/**
+ * Names and the version, with no filesystem or inspection code attached, so
+ * modules that only need them (generated-file rendering and classification,
+ * integration updates) can be loaded somewhere that must not pull in the
+ * repository scanner, such as the hosted app's server.
+ */
+import { createRequire } from "node:module";
+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 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";

package/dist/generated.d.ts

@@ -11,6 +11,8 @@ export declare const GENERATED_MANIFEST_FILE = ".refino/generated.json";
 export declare const COMPARISON_SUFFIX = ".refino-new";
 export declare function hashContent(text: string): string;
 export declare function readGeneratedManifest(appDir: string): GeneratedManifest | null;
+/** `readGeneratedManifest` over text the caller already read. */
+export declare function parseGeneratedManifest(text: string | null): GeneratedManifest | null;
 export declare function serializeGeneratedManifest(manifest: GeneratedManifest): string;
 /**
  * Classify one generated file against the repository. Read-only: deciding and
@@ -18,6 +20,12 @@ export declare function serializeGeneratedManifest(manifest: GeneratedManifest):
  * without touching anything.
  */
 export declare function classifyGeneratedFile(appDir: string, file: TemplateFile, manifest: GeneratedManifest | null): GeneratedFileState;
+/**
+ * The same decision over bytes the caller already has (`null` when the file
+ * does not exist), for a repository that is not on this machine's disk:
+ * Refino's hosted update reads it through the GitHub API.
+ */
+export declare function classifyGeneratedContent(file: TemplateFile, current: string | null, manifest: GeneratedManifest | null): GeneratedFileState;
 export declare function classifyGeneratedFiles(appDir: string, files: readonly TemplateFile[], manifest: GeneratedManifest | null): GeneratedFileState[];
 /** A file whose bytes Refino is leaving behind although its template moved on. */
 export declare function needsReview(states: readonly GeneratedFileState[]): boolean;

package/dist/generated.js

@@ -27,7 +27,7 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { exists, readJson, readText } from "./fs.js";
-import { PLAN_DIR } from "./plan.js";
+import { PLAN_DIR } from "./constants.js";
 /** The repository's record of what Refino generated. Machine-owned, committed. */
 export const GENERATED_MANIFEST_FILE = `${PLAN_DIR}/generated.json`;
 /**
@@ -41,7 +41,20 @@ export function hashContent(text) {
     return createHash("sha256").update(text, "utf8").digest("hex");
 }
 export function readGeneratedManifest(appDir) {
-    const manifest = readJson(join(appDir, GENERATED_MANIFEST_FILE));
+    return validManifest(readJson(join(appDir, GENERATED_MANIFEST_FILE)));
+}
+/** `readGeneratedManifest` over text the caller already read. */
+export function parseGeneratedManifest(text) {
+    if (text === null)
+        return null;
+    try {
+        return validManifest(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+function validManifest(manifest) {
     if (!manifest || manifest.version !== 1 || typeof manifest.files !== "object" || manifest.files === null)
         return null;
     return manifest;
@@ -82,13 +95,20 @@ function renderingIsCurrent(file, sha) {
  * without touching anything.
  */
 export function classifyGeneratedFile(appDir, file, manifest) {
+    const absolute = join(appDir, file.path);
+    return classifyGeneratedContent(file, exists(absolute) ? (readText(absolute) ?? "") : null, manifest);
+}
+/**
+ * The same decision over bytes the caller already has (`null` when the file
+ * does not exist), for a repository that is not on this machine's disk:
+ * Refino's hosted update reads it through the GitHub API.
+ */
+export function classifyGeneratedContent(file, current, manifest) {
     const to = file.version;
     const base = { path: file.path, ownership: file.ownership, to };
-    const absolute = join(appDir, file.path);
-    if (!exists(absolute)) {
+    if (current === null) {
         return { ...base, status: "create", from: null, reason: "Not present; generated by this run." };
     }
-    const current = readText(absolute) ?? "";
     const recorded = manifest?.files[file.path];
     if (current === file.content) {
         return { ...base, status: "current", from: to, reason: `Already the ${to} version.` };

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { applyPlan } from "./apply.js";
 export type { ApplyOptions, RefinoConfig } from "./apply.js";
 export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
 export type { TemplateFile, TemplateRendering } from "./templates.js";
-export { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.js";
+export { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedContent, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, parseGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.js";
 export { INSTALL_METHODS, isInstallMethod, resolveInstallMethod } from "./install-method.js";
 export type { InstallMethod } from "./install-method.js";
 export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, analyticsFramework, analyticsHosting, hostedFiles } from "./templates-hosted.js";
@@ -17,3 +17,10 @@ export type { RefinoSiteConfig } from "./templates-hosted.js";
 export { verifyIntegration } from "./verify.js";
 export type { VerifyOptions } from "./verify.js";
 export type { ApplyResult, CandidateStatus, CheckStatus, CopyCandidate, CopyClassification, DetectedPackage, Framework, GeneratedFileState, GeneratedFileStatus, GeneratedManifest, GeneratedManifestEntry, GeneratedOwnership, GitState, HostIntegration, HostKind, Language, MigrationPlan, PackageManager, PlanOptions, PlannedFile, RefinoSite, RepositoryInspection, RouteInfo, Router, ScanResult, ScriptSet, VerificationCheck, VerificationResult, } from "./types.js";
+export { RUNTIME_PACKAGES, nextSpecifier, planIntegrationUpdate, setDependencySpecifiers, updateCommitMessage } from "./integration-update.js";
+export type { FileChange, IntegrationUpdateOptions, IntegrationUpdatePlan, ManualUpdateReason, PackageManagerName, RepositoryFiles } from "./integration-update.js";
+export { LOCKFILES, readLockedVersions, rewriteLockfile } from "./lockfiles.js";
+export type { LockfileKind, LockfileResult, LockfileRewrite, PackageRelease } from "./lockfiles.js";
+export { NPM_REGISTRY_URL, createNpmRegistry, refinoDependencies, releaseShapeChange, toRelease } from "./registry.js";
+export type { NpmRegistryOptions, PackageRegistry, RegistryManifest } from "./registry.js";
+export { compareVersions, isExactVersion } from "./semver.js";

package/dist/index.js

@@ -5,7 +5,11 @@ export { buildPlan, planMigration, planContent, defaultContentFile, integrationP
 export { renderAgentInstructions } from "./agent.js";
 export { applyPlan } from "./apply.js";
 export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
-export { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.js";
+export { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedContent, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, parseGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.js";
 export { INSTALL_METHODS, isInstallMethod, resolveInstallMethod } from "./install-method.js";
 export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, analyticsFramework, analyticsHosting, hostedFiles } from "./templates-hosted.js";
 export { verifyIntegration } from "./verify.js";
+export { RUNTIME_PACKAGES, nextSpecifier, planIntegrationUpdate, setDependencySpecifiers, updateCommitMessage } from "./integration-update.js";
+export { LOCKFILES, readLockedVersions, rewriteLockfile } from "./lockfiles.js";
+export { NPM_REGISTRY_URL, createNpmRegistry, refinoDependencies, releaseShapeChange, toRelease } from "./registry.js";
+export { compareVersions, isExactVersion } from "./semver.js";

package/dist/integration-update.d.ts

@@ -0,0 +1,83 @@
+import type { LockfileKind } from "./lockfiles.js";
+import type { PackageRegistry } from "./registry.js";
+/** The runtime packages a site declares. The CLI and onboarding are tools and are never moved here. */
+export declare const RUNTIME_PACKAGES: readonly ["@getrefino/core", "@getrefino/react", "@getrefino/github"];
+/** A repository at one commit, read lazily. Paths are repository-relative with `/` separators. */
+export interface RepositoryFiles {
+    readonly paths: readonly string[];
+    /** The file's text, or null when it does not exist. */
+    read(path: string): Promise<string | null>;
+}
+export interface IntegrationUpdateOptions {
+    /** Repository-relative path of the site's copy file: which app in the repository is the site. */
+    readonly copyPath: string;
+    readonly registry: PackageRegistry;
+}
+export type PackageManagerName = LockfileKind | "none";
+/**
+ * Why an update Refino knows about cannot be applied automatically. A closed
+ * vocabulary, so a caller can explain each in plain words without showing a
+ * developer-facing detail to a site owner.
+ */
+export type ManualUpdateReason = "unsupported-package-manager" | "multiple-lockfiles" | "unsupported-specifier" | "inconsistent-versions" | "dependency-change" | "lockfile" | "package-json" | "customized-integration" | "removed-integration" | "registry";
+export interface FileChange {
+    readonly path: string;
+    readonly content: string;
+}
+export type IntegrationUpdatePlan = 
+/** Nothing to do: packages and generated files are this release. */
+{
+    readonly kind: "current";
+    readonly installed: string;
+    readonly target: string;
+}
+/** The site runs a newer release than this Refino renders. Never downgraded. */
+ | {
+    readonly kind: "ahead";
+    readonly installed: string;
+    readonly target: string;
+}
+/** The target release is not on the registry (yet); there is nothing to offer. */
+ | {
+    readonly kind: "unreleased";
+    readonly installed: string;
+    readonly target: string;
+}
+/** Not a Refino-hosted integration this code can read; say nothing to the owner. */
+ | {
+    readonly kind: "unknown";
+    readonly detail: string;
+}
+/** An update exists and needs a developer. */
+ | {
+    readonly kind: "manual";
+    readonly installed: string;
+    readonly target: string;
+    readonly reason: ManualUpdateReason;
+    readonly detail: string;
+} | {
+    readonly kind: "update";
+    readonly installed: string;
+    readonly target: string;
+    readonly packageManager: PackageManagerName;
+    readonly files: readonly FileChange[];
+    readonly message: string;
+};
+export declare function updateCommitMessage(version: string): string;
+/** The specifier to write for `to`, in the style of the one already there; null when the style is not one to reason about. */
+export declare function nextSpecifier(spec: string, to: string): string | null;
+/**
+ * Change dependency specifiers in package.json text without re-serializing
+ * it: the owner's formatting, key order and every other value stay byte for
+ * byte. Refuses when a name appears anywhere else in the file (an override,
+ * a resolution), because that would be left pointing at the old release.
+ */
+export declare function setDependencySpecifiers(text: string, changes: Readonly<Record<string, {
+    readonly from: string;
+    readonly to: string;
+}>>): string | null;
+/**
+ * Decide what updating this repository's Refino integration to this
+ * release means, without changing anything.
+ */
+export declare function planIntegrationUpdate(files: RepositoryFiles, options: IntegrationUpdateOptions): Promise<IntegrationUpdatePlan>;

package/dist/integration-update.js

@@ -0,0 +1,281 @@
+/**
+ * Updating a Refino-hosted site's integration in its repository, decided
+ * from the repository's own files and nothing else.
+ *
+ * An integration update is exactly what the documented manual upgrade does
+ * (move the `@getrefino/*` packages, then run `init` from the new version),
+ * minus everything `init` does that is not an upgrade: no inspection, no
+ * scan, no plan or instructions rewritten, no copy touched. What changes:
+ *
+ *   - the app's package.json: the Refino specifiers, and nothing else;
+ *   - the lockfile the repository already has, through lockfiles.ts;
+ *   - Refino's generated files, where generated.ts can prove they are still
+ *     Refino's, and `.refino/generated.json`, which records that.
+ *
+ * The plan is pure: files in (through `RepositoryFiles`), a list of file
+ * contents out, or a reason it cannot be done safely. It never writes. The
+ * hosted app commits the result through its GitHub integration; a CLI could
+ * write the same result to disk.
+ *
+ * The target is always this package's own version, because it is the only
+ * version whose generated files this code can render.
+ */
+import { classifyGeneratedContent, GENERATED_MANIFEST_FILE, nextGeneratedManifest, parseGeneratedManifest, serializeGeneratedManifest } from "./generated.js";
+import { LOCKFILES, readLockedVersions, rewriteLockfile } from "./lockfiles.js";
+import { PLAN_FILE, TOOL_VERSION } from "./constants.js";
+import { refinoDependencies, releaseShapeChange, toRelease } from "./registry.js";
+import { compareVersions, isExactVersion } from "./semver.js";
+import { boilerplateFiles } from "./templates.js";
+/** The runtime packages a site declares. The CLI and onboarding are tools and are never moved here. */
+export const RUNTIME_PACKAGES = ["@getrefino/core", "@getrefino/react", "@getrefino/github"];
+function dirname(path) {
+    const index = path.lastIndexOf("/");
+    return index === -1 ? "." : path.slice(0, index);
+}
+function join(dir, path) {
+    return dir === "." ? path : `${dir}/${path}`;
+}
+/** `dir` relative to `base`, both repository-relative; "." when equal. */
+function relative(base, dir) {
+    if (base === dir)
+        return ".";
+    return base === "." ? dir : dir.slice(base.length + 1);
+}
+function parseJson(text) {
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function updateCommitMessage(version) {
+    return `chore: update Refino to ${version}`;
+}
+/** The specifier to write for `to`, in the style of the one already there; null when the style is not one to reason about. */
+export function nextSpecifier(spec, to) {
+    if (isExactVersion(spec))
+        return to;
+    const match = /^([\^~])(.+)$/.exec(spec);
+    return match && isExactVersion(match[2]) ? `${match[1]}${to}` : null;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Change dependency specifiers in package.json text without re-serializing
+ * it: the owner's formatting, key order and every other value stay byte for
+ * byte. Refuses when a name appears anywhere else in the file (an override,
+ * a resolution), because that would be left pointing at the old release.
+ */
+export function setDependencySpecifiers(text, changes) {
+    let next = text;
+    for (const [name, { from, to }] of Object.entries(changes)) {
+        if (next.split(`"${name}"`).length !== 2)
+            return null;
+        const pattern = new RegExp(`("${escapeRegExp(name)}"\\s*:\\s*)"${escapeRegExp(from)}"`);
+        if (!pattern.test(next))
+            return null;
+        next = next.replace(pattern, (_, prefix) => `${prefix}"${to}"`);
+    }
+    const before = parseJson(text);
+    const after = parseJson(next);
+    if (!before || !after)
+        return null;
+    for (const [name, { to }] of Object.entries(changes)) {
+        for (const group of ["dependencies", "devDependencies"]) {
+            if (before[group]?.[name] !== undefined)
+                before[group][name] = to;
+        }
+    }
+    return JSON.stringify(before) === JSON.stringify(after) ? next : null;
+}
+async function locateApp(files, copyPath) {
+    const candidates = files.paths.filter((path) => path === PLAN_FILE || path.endsWith(`/${PLAN_FILE}`));
+    for (const path of candidates) {
+        const dir = path === PLAN_FILE ? "." : path.slice(0, -(PLAN_FILE.length + 1));
+        const plan = parseJson(await files.read(path));
+        if (plan?.contentFile?.path && join(dir, plan.contentFile.path) === copyPath)
+            return { dir, plan };
+    }
+    return null;
+}
+function findLockfile(paths, appDir) {
+    let dir = appDir;
+    for (;;) {
+        const present = Object.keys(LOCKFILES).filter((name) => paths.has(join(dir, name)));
+        if (present.length > 1)
+            return { kind: "refused", reason: "multiple-lockfiles", detail: `${dir} has more than one lockfile: ${present.join(", ")}.` };
+        const name = present[0];
+        if (name) {
+            const kind = LOCKFILES[name];
+            if (kind === "unsupported")
+                return { kind: "refused", reason: "unsupported-package-manager", detail: `${join(dir, name)} is not a lockfile Refino can update.` };
+            return { kind, path: join(dir, name) };
+        }
+        if (dir === ".")
+            return { kind: "none" };
+        dir = dirname(dir);
+    }
+}
+function lowest(versions) {
+    return [...versions].sort(compareVersions)[0];
+}
+/**
+ * Decide what updating this repository's Refino integration to this
+ * release means, without changing anything.
+ */
+export async function planIntegrationUpdate(files, options) {
+    const target = TOOL_VERSION;
+    const paths = new Set(files.paths);
+    const app = await locateApp(files, options.copyPath);
+    if (!app)
+        return { kind: "unknown", detail: `No ${PLAN_FILE} in the repository describes ${options.copyPath}.` };
+    if (!app.plan.refino)
+        return { kind: "unknown", detail: "The integration is self-hosted; it is not updated through Refino." };
+    const packageJsonPath = join(app.dir, "package.json");
+    const packageJsonText = await files.read(packageJsonPath);
+    const packageJson = parseJson(packageJsonText);
+    if (!packageJson || packageJsonText === null)
+        return { kind: "unknown", detail: `${packageJsonPath} is missing or not valid JSON.` };
+    const specs = {};
+    for (const name of RUNTIME_PACKAGES) {
+        const spec = packageJson.dependencies?.[name] ?? packageJson.devDependencies?.[name];
+        if (typeof spec === "string")
+            specs[name] = spec;
+    }
+    if (Object.keys(specs).length === 0)
+        return { kind: "unknown", detail: `${packageJsonPath} declares no Refino packages.` };
+    // What is installed: what the lockfile resolves, or failing that an exact pin.
+    const lockfile = findLockfile(paths, app.dir);
+    let lockText = null;
+    let resolved = {};
+    if (lockfile.kind !== "none" && lockfile.kind !== "refused") {
+        lockText = await files.read(lockfile.path);
+        const read = lockText === null ? null : readLockedVersions(lockfile.kind, lockText, relative(dirname(lockfile.path), app.dir), specs);
+        if (read?.ok)
+            resolved = { ...read.versions };
+    }
+    for (const [name, spec] of Object.entries(specs)) {
+        if (resolved[name] === undefined && isExactVersion(spec))
+            resolved[name] = spec;
+    }
+    const versions = Object.values(resolved).filter(isExactVersion);
+    if (versions.length === 0)
+        return { kind: "unknown", detail: "No installed Refino version can be read from the repository." };
+    const installed = lowest(versions);
+    if (compareVersions(installed, target) > 0)
+        return { kind: "ahead", installed, target };
+    // Refino's generated files, judged exactly as `init` and `verify` judge them.
+    let templates;
+    try {
+        templates = boilerplateFiles(app.plan);
+    }
+    catch (error) {
+        return { kind: "unknown", detail: `${join(app.dir, PLAN_FILE)} could not be read as a plan: ${String(error)}` };
+    }
+    const manifestPath = join(app.dir, GENERATED_MANIFEST_FILE);
+    const manifestText = await files.read(manifestPath);
+    const manifest = parseGeneratedManifest(manifestText);
+    const states = await Promise.all(templates.map(async (file) => classifyGeneratedContent(file, await files.read(join(app.dir, file.path)), manifest)));
+    const packagesCurrent = Object.keys(specs).every((name) => resolved[name] === target);
+    const filesCurrent = states.every((state) => state.status === "current" || state.status === "customized");
+    if (packagesCurrent && filesCurrent)
+        return { kind: "current", installed, target };
+    const manual = (reason, detail) => ({ kind: "manual", installed, target, reason, detail });
+    // From here on there is an update. Is the target actually published?
+    let targetManifests;
+    try {
+        targetManifests = await manifestsFor(options.registry, Object.keys(specs), target);
+    }
+    catch (error) {
+        return manual("registry", String(error));
+    }
+    if (Object.keys(targetManifests).length === 0)
+        return { kind: "unreleased", installed, target };
+    const review = states.find((state) => state.status === "review");
+    if (review)
+        return manual("customized-integration", `${join(app.dir, review.path)}: ${review.reason}`);
+    const removed = states.find((state) => state.status === "create" && manifest?.files[state.path]);
+    if (removed)
+        return manual("removed-integration", `${join(app.dir, removed.path)} was generated by Refino and has since been deleted.`);
+    const changes = [];
+    let packageManager = "none";
+    if (!packagesCurrent) {
+        if (new Set(versions).size > 1 || versions.length !== Object.keys(specs).length) {
+            return manual("inconsistent-versions", `The Refino packages are not all at one version: ${JSON.stringify(resolved)}.`);
+        }
+        if (lockfile.kind === "refused")
+            return manual(lockfile.reason, lockfile.detail);
+        const specChanges = {};
+        for (const [name, spec] of Object.entries(specs)) {
+            const to = nextSpecifier(spec, target);
+            if (!to)
+                return manual("unsupported-specifier", `${packageJsonPath} asks for ${name}@${spec}; only exact versions and ^/~ ranges are updated automatically.`);
+            specChanges[name] = { from: spec, to };
+        }
+        const moving = [...new Set([...Object.keys(specs), ...Object.values(targetManifests).flatMap((manifest) => refinoDependencies(manifest))])];
+        let fromManifests;
+        let toManifests;
+        try {
+            toManifests = await manifestsFor(options.registry, moving, target);
+            fromManifests = await manifestsFor(options.registry, moving, installed);
+        }
+        catch (error) {
+            return manual("registry", String(error));
+        }
+        for (const name of moving) {
+            const from = fromManifests[name];
+            const to = toManifests[name];
+            if (!from || !to)
+                return manual("registry", `${name} is not on the registry at ${from ? target : installed}.`);
+            const change = releaseShapeChange(from, to, moving);
+            if (change)
+                return manual("dependency-change", change);
+        }
+        const nextPackageJson = setDependencySpecifiers(packageJsonText, specChanges);
+        if (nextPackageJson === null)
+            return manual("package-json", `${packageJsonPath} names a Refino package somewhere other than its dependencies, or could not be edited in place.`);
+        if (nextPackageJson !== packageJsonText)
+            changes.push({ path: packageJsonPath, content: nextPackageJson });
+        if (lockfile.kind !== "none") {
+            if (lockText === null)
+                return manual("lockfile", `${lockfile.path} could not be read.`);
+            const releases = (manifests) => Object.fromEntries(Object.entries(manifests).map(([name, manifest]) => [name, toRelease(manifest)]));
+            const rewritten = rewriteLockfile(lockfile.kind, lockText, {
+                importer: relative(dirname(lockfile.path), app.dir),
+                specs: specChanges,
+                packages: moving,
+                from: installed,
+                to: target,
+                fromReleases: releases(fromManifests),
+                toReleases: releases(toManifests),
+            });
+            if (!rewritten.ok)
+                return manual("lockfile", rewritten.reason);
+            if (rewritten.text !== lockText)
+                changes.push({ path: lockfile.path, content: rewritten.text });
+            packageManager = lockfile.kind;
+        }
+    }
+    const byPath = new Map(templates.map((file) => [file.path, file]));
+    for (const state of states) {
+        if (state.status === "create" || state.status === "update")
+            changes.push({ path: join(app.dir, state.path), content: byPath.get(state.path).content });
+    }
+    const nextManifest = serializeGeneratedManifest(nextGeneratedManifest(templates, states, manifest, target));
+    if (nextManifest !== manifestText)
+        changes.push({ path: manifestPath, content: nextManifest });
+    return { kind: "update", installed, target, packageManager, files: changes, message: updateCommitMessage(target) };
+}
+async function manifestsFor(registry, names, version) {
+    const found = {};
+    for (const name of names) {
+        const manifest = await registry.manifest(name, version);
+        if (manifest)
+            found[name] = manifest;
+    }
+    return found;
+}

package/dist/lockfiles.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+export type LockfileKind = "npm" | "pnpm" | "yarn";
+/** The lockfile names this module understands, and the ones it recognises only to refuse. */
+export declare const LOCKFILES: Readonly<Record<string, LockfileKind | "unsupported">>;
+/** One published version of a package, as the registry describes its tarball. */
+export interface PackageRelease {
+    readonly name: string;
+    readonly version: string;
+    readonly tarball: string;
+    /** Subresource-integrity string, e.g. `sha512-…`. */
+    readonly integrity: string;
+    /** Hex sha1 of the tarball; yarn classic appends it to the resolved URL. */
+    readonly shasum: string;
+}
+export interface LockfileRewrite {
+    /** App directory relative to the lockfile's directory; "." when they are the same. */
+    readonly importer: string;
+    /** Direct dependencies of the app, by name: the specifier now and the one to write. */
+    readonly specs: Readonly<Record<string, {
+        readonly from: string;
+        readonly to: string;
+    }>>;
+    /** Every package being moved: the direct ones plus Refino packages they depend on. */
+    readonly packages: readonly string[];
+    /** The one version every moved package resolves to now. */
+    readonly from: string;
+    readonly to: string;
+    readonly fromReleases: Readonly<Record<string, PackageRelease>>;
+    readonly toReleases: Readonly<Record<string, PackageRelease>>;
+}
+export type LockfileResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The versions a lockfile resolves the app's direct Refino dependencies to.
+ * `specs` maps each dependency name to its package.json specifier.
+ */
+export declare function readLockedVersions(kind: LockfileKind, text: string, importer: string, specs: Readonly<Record<string, string>>): {
+    readonly ok: true;
+    readonly versions: Readonly<Record<string, string>>;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Rewrite a lockfile so the Refino packages move from `request.from` to `request.to`, or say why it cannot be done safely. */
+export declare function rewriteLockfile(kind: LockfileKind, text: string, request: LockfileRewrite): LockfileResult;