hot-updater 1.0.8 → 1.1.0

package/dist/config.d.mts

@@ -1,52 +1,37 @@
 import { HotUpdaterConfigOptions } from "@hot-updater/cli-tools";
-import { ConfigInput, Platform } from "@hot-updater/plugin-core";
+import { ConfigInput, FingerprintExtraSources, NativeFingerprint, Platform } from "@hot-updater/plugin-core";
 //#region src/utils/fingerprint/common.d.ts
-type FingerprintSource = {
-  type: "file" | "dir";
-  filePath: string;
-  reasons: string[];
-  overrideHashKey?: string;
-  hash: string | null;
-  debugInfo?: any;
-} | {
-  type: "contents";
-  id: string;
-  contents: string | Buffer;
-  reasons: string[];
-  hash: string | null;
-  debugInfo?: any;
-};
-type FingerprintResult = {
-  hash: string;
-  sources: FingerprintSource[];
-};
-//#endregion
-//#region src/utils/fingerprint/index.d.ts
-declare const generateFingerprints: (additionalExtraSources?: readonly string[]) => Promise<{
+interface FingerprintInputs {
+  adapter: string;
+  extraSources?: FingerprintExtraSources;
+  ignorePaths?: string[];
+  nativeVersion?: string | number;
+}
+/** fingerprint.json: each platform's fingerprint and the inputs it came from. */
+interface FingerprintFile {
   ios: FingerprintResult;
   android: FingerprintResult;
-}>;
-declare const generateFingerprint: (platform: "ios" | "android") => Promise<FingerprintResult>;
+  inputs?: FingerprintInputs;
+}
+type FingerprintResult = NativeFingerprint;
+//#endregion
+//#region src/utils/fingerprint/index.d.ts
+declare const generateFingerprints: (additionalExtraSources?: readonly string[]) => Promise<FingerprintFile>;
+declare const generateFingerprint: (platform: "ios" | "android") => Promise<import("@hot-updater/plugin-core").NativeFingerprint>;
+/**
+ * Writes fingerprint.json, which native builds read to embed each platform's
+ * hash. With `platform`, only that platform's fingerprint is replaced.
+ */
 declare const createAndInjectFingerprintFiles: ({ platform }?: {
   platform?: Platform;
 }) => Promise<{
-  fingerprint: {
-    ios: FingerprintResult;
-    android: FingerprintResult;
-  };
-  androidPaths: string[];
-  iosPaths: string[];
-}>;
-declare const createFingerprintJSON: (fingerprint: {
-  ios: FingerprintResult;
-  android: FingerprintResult;
-}) => Promise<{
-  ios: FingerprintResult;
-  android: FingerprintResult;
+  fingerprint: FingerprintFile;
 }>;
+declare const createFingerprintJSON: (fingerprint: FingerprintFile) => Promise<FingerprintFile>;
 declare const readLocalFingerprint: () => Promise<{
   ios: FingerprintResult | null;
   android: FingerprintResult | null;
+  inputs?: FingerprintInputs;
 } | null>;
 //#endregion
 //#region src/config.d.ts

package/dist/config.mjs

@@ -1,4 +1,4 @@
-import { i as generateFingerprints, n as createFingerprintJSON, o as readLocalFingerprint, r as generateFingerprint, t as createAndInjectFingerprintFiles } from "./fingerprint-DyKBEn51.mjs";
+import { a as readLocalFingerprint, i as generateFingerprints, n as createFingerprintJSON, r as generateFingerprint, t as createAndInjectFingerprintFiles } from "./fingerprint-D0bHaE2B.mjs";
 //#region src/config.ts
 const defineConfig = (config) => {
 	return config;

package/dist/fingerprint-D0bHaE2B.mjs

@@ -0,0 +1,348 @@
+import { createRequire } from "node:module";
+import fs from "fs";
+import path from "path";
+import { colors, getCwd, loadConfig, p, reactNativeCliFingerprint } from "@hot-updater/cli-tools";
+import fs$1 from "node:fs";
+import path$1 from "node:path";
+import fs$2 from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+//#region src/utils/fingerprint/common.ts
+const appendFingerprintExtraSources = (extraSources, additions) => {
+	if (additions.length === 0) return extraSources;
+	const append = (sources = []) => [.../* @__PURE__ */ new Set([...sources, ...additions])];
+	if (!extraSources || Array.isArray(extraSources)) return append(extraSources);
+	return {
+		ios: append(extraSources.ios),
+		android: append(extraSources.android)
+	};
+};
+const ensureFingerprintConfig = async (additionalExtraSources) => {
+	const config = await loadConfig(null);
+	if (config.updateStrategy === "appVersion") {
+		p.log.error("The updateStrategy in hot-updater.config.ts is set to 'appVersion'. This command only works with 'fingerprint' strategy.");
+		process.exit(1);
+	}
+	const buildAdapter = await config.build({ cwd: getCwd() });
+	const nativeExtraSources = additionalExtraSources ?? await buildAdapter.nativeBuild?.getFingerprintExtraSources?.() ?? [];
+	return {
+		...config.fingerprint,
+		extraSources: appendFingerprintExtraSources(config.fingerprint.extraSources, nativeExtraSources),
+		adapter: buildAdapter.name,
+		provider: buildAdapter.nativeBuild?.fingerprint
+	};
+};
+/**
+* What fingerprint.json records so a native build can compute the fingerprint
+* without loading hot-updater.config.ts, whose storage and database need
+* deploy secrets a build machine may not have: the build adapter and the
+* fingerprint settings it receives.
+*/
+/** The inputs' adapter for a build adapter without its own fingerprint. */
+const DEFAULT_FINGERPRINT_ADAPTER = "react-native";
+const getFingerprintInputs = (options) => ({
+	adapter: options.provider ? options.adapter ?? "unknown" : DEFAULT_FINGERPRINT_ADAPTER,
+	...options.extraSources === void 0 ? {} : { extraSources: options.extraSources },
+	...options.ignorePaths === void 0 ? {} : { ignorePaths: options.ignorePaths },
+	...options.nativeVersion === void 0 ? {} : { nativeVersion: options.nativeVersion }
+});
+const EXPO_FINGERPRINT = "@expo/fingerprint";
+/** An engine id without its version: `@expo/fingerprint@0.20.14` → `@expo/fingerprint`. */
+const engineName = (engine) => {
+	const at = engine.lastIndexOf("@");
+	return at > 0 ? engine.slice(0, at) : engine;
+};
+/**
+* The engines of two fingerprints when they differ. The hash then changed with
+* the engine, whether or not a native input changed. A fingerprint without a
+* recorded engine counts as `@expo/fingerprint` against another engine.
+*/
+const getFingerprintEngineChange = (before, after) => {
+	if (!before || !after?.engine) return null;
+	const beforeEngine = before.engine ?? (engineName(after.engine) === EXPO_FINGERPRINT ? null : EXPO_FINGERPRINT);
+	return beforeEngine && beforeEngine !== after.engine ? {
+		before: beforeEngine,
+		after: after.engine
+	} : null;
+};
+/**
+* Explains a hash that changed with its engine, for deploy, doctor, and
+* `fingerprint create`.
+*/
+const STILL_DIFFERS = "If the fingerprint still differs with it, native inputs changed too, and builds you shipped need a rebuild.";
+const describeFingerprintEngineChange = (change, label, recorded = false) => ({
+	message: `The ${label} fingerprint changed because fingerprint.json was created with ${change.before} and the project now uses ${change.after}. Native inputs may be unchanged.`,
+	resolution: engineName(change.before) !== engineName(change.after) ? `${recorded ? `fingerprint.json now records the ${change.after} hash. Rebuild` : "Run `npx hot-updater fingerprint create`, then rebuild"} the ${label} app. Builds you already shipped keep the old fingerprint and receive no updates until users install the new build.` : recorded ? `fingerprint.json now records the ${change.after} hash. To keep updating ${label} builds you already shipped, go back to ${change.before} and run \`npx hot-updater fingerprint create\` again, or restore the previous fingerprint.json. ${STILL_DIFFERS} Otherwise rebuild the ${label} app.` : `To keep updating ${label} builds you already shipped, go back to ${change.before}. ${STILL_DIFFERS} Otherwise run \`npx hot-updater fingerprint create\`, then rebuild the ${label} app.`
+});
+function isFingerprintEquals(lhs, rhs) {
+	if (!lhs || !rhs) return false;
+	if (isFingerprintResultsObject(lhs) && isFingerprintResultsObject(rhs)) return lhs.android.hash === rhs.android.hash && lhs.ios.hash === rhs.ios.hash;
+	if (!isFingerprintResultsObject(lhs) && !isFingerprintResultsObject(rhs)) return lhs["hash"] === rhs["hash"];
+	return false;
+	function isFingerprintResultsObject(result) {
+		return typeof result["android"] === "object" && typeof result["ios"] === "object" && !!result["android"]?.hash && !!result["ios"]?.hash;
+	}
+}
+//#endregion
+//#region src/utils/fingerprint/nativeFingerprint.ts
+/**
+* Calculates the project's native fingerprint with the build adapter's
+* fingerprint, or with React Native CLI's for an adapter without one.
+*/
+async function nativeFingerprint(path, options) {
+	const { provider, ...providerOptions } = options;
+	return provider ? provider(providerOptions) : reactNativeCliFingerprint(path, providerOptions);
+}
+//#endregion
+//#region src/utils/fingerprint/nativeSdk.ts
+const SDK = "@hot-updater/react-native";
+const ERROR_NAME = "NativeSdkWithoutBuildFingerprintError";
+/**
+* The installed React Native SDK predates build-time fingerprints: it reads
+* the fingerprint from Info.plist and AndroidManifest.xml, which hot-updater
+* no longer writes, so its builds would carry a stale one.
+*/
+var NativeSdkWithoutBuildFingerprintError = class extends Error {
+	constructor(version) {
+		super(`${SDK}@${version} reads the fingerprint from Info.plist and AndroidManifest.xml, which this hot-updater no longer writes, so its builds would carry a stale fingerprint. Update ${SDK} to the version of hot-updater, then rebuild the app.`);
+		this.name = ERROR_NAME;
+	}
+};
+const isNativeSdkWithoutBuildFingerprintError = (error) => error instanceof Error && error.name === ERROR_NAME;
+/**
+* Throws when the project's React Native SDK can't embed the fingerprint at
+* build time, which it shows by shipping the build step that does.
+*/
+const assertNativeSdkEmbedsFingerprint = (cwd) => {
+	let root = null;
+	for (let dir = path$1.resolve(cwd);; dir = path$1.dirname(dir)) {
+		const candidate = path$1.join(dir, "node_modules", SDK);
+		if (fs$1.existsSync(path$1.join(candidate, "package.json"))) {
+			root = candidate;
+			break;
+		}
+		if (path$1.dirname(dir) === dir) break;
+	}
+	if (root === null) return;
+	const manifest = path$1.join(root, "package.json");
+	if (fs$1.existsSync(path$1.join(root, "android/hot-updater-fingerprint.gradle"))) return;
+	const { version } = JSON.parse(fs$1.readFileSync(manifest, "utf8"));
+	throw new NativeSdkWithoutBuildFingerprintError(version ?? "unknown");
+};
+//#endregion
+//#region src/utils/fingerprint/diff.ts
+const sourceKey = (source) => source.type === "contents" ? `contents:${source.id}` : `${source.type}:${source.filePath}`;
+/**
+* Compares a saved fingerprint with the project's fingerprint now, source by
+* source, whichever engine computes it.
+*/
+async function getFingerprintDiff(oldFingerprint, options) {
+	const current = await nativeFingerprint(getCwd(), options);
+	const before = new Map(oldFingerprint.sources.map((source) => [sourceKey(source), source]));
+	const after = new Map(current.sources.map((source) => [sourceKey(source), source]));
+	const diff = [];
+	for (const [key, beforeSource] of before) {
+		const afterSource = after.get(key);
+		if (!afterSource) diff.push({
+			op: "removed",
+			removedSource: beforeSource
+		});
+		else if (afterSource.hash !== beforeSource.hash) diff.push({
+			op: "changed",
+			beforeSource,
+			afterSource
+		});
+	}
+	for (const [key, afterSource] of after) if (!before.has(key)) diff.push({
+		op: "added",
+		addedSource: afterSource
+	});
+	return diff;
+}
+/** Contents short enough to show, such as `react-native-screens@4.25.2`. */
+const readableContents = (source) => source.type === "contents" && typeof source.contents === "string" && source.contents.length <= 120 && !source.contents.includes("\n") ? source.contents : null;
+/**
+* A source as people read it: a file path, a value such as
+* `react-native-screens@4.25.2` or `android:hermesEnabled=true`, or the
+* source's id when its contents are long.
+*/
+function getSourcePath(source) {
+	if (!("id" in source)) return source.filePath;
+	const contents = readableContents(source);
+	if (contents === null) return source.id;
+	return source.id.startsWith("setting:") ? `${source.id.slice(8)}=${contents}` : source.id === "nativeVersion" ? `nativeVersion=${contents}` : contents;
+}
+/**
+* A changed source with its value before and after, such as
+* `react-native-screens 4.25.2 → 4.26.0`, when both are short.
+*/
+function describeChange(before, after) {
+	const from = readableContents(before);
+	const to = readableContents(after);
+	if (from === null || to === null || !("id" in before)) return getSourcePath(before);
+	const at = from.lastIndexOf("@");
+	if (at > 0 && to.startsWith(from.slice(0, at + 1))) return `${from.slice(0, at)} ${from.slice(at + 1)} → ${to.slice(at + 1)}`;
+	return `${before.id.startsWith("setting:") ? before.id.slice(8) : before.id} ${from} → ${to}`;
+}
+function summarizeFingerprintDiff(diff) {
+	return {
+		added: diff.flatMap((item) => item.op === "added" ? [getSourcePath(item.addedSource)] : []),
+		removed: diff.flatMap((item) => item.op === "removed" ? [getSourcePath(item.removedSource)] : []),
+		changed: diff.flatMap((item) => item.op === "changed" ? [describeChange(item.beforeSource, item.afterSource)] : [])
+	};
+}
+function showFingerprintChanges({ added, removed, changed }, platform) {
+	if (added.length + removed.length + changed.length === 0) return;
+	p.log.info(`${colors.bold(`${platform} Fingerprint Changes:`)}`);
+	if (added.length > 0) p.log.info(`  ${colors.green("Added:")} ${added.join(", ")}`);
+	if (removed.length > 0) p.log.info(`  ${colors.red("Removed:")} ${removed.join(", ")}`);
+	if (changed.length > 0) p.log.info(`  ${colors.yellow("Changed:")} ${changed.join(", ")}`);
+}
+function showFingerprintDiff(diff, platform) {
+	showFingerprintChanges(summarizeFingerprintDiff(diff), platform);
+}
+//#endregion
+//#region src/utils/fingerprint/recorded.ts
+/**
+* The official build adapters whose fingerprint a native build computes from
+* fingerprint.json alone: the package and the export that computes it.
+*/
+const ADAPTER_FINGERPRINTS = {
+	bare: {
+		packageName: "@hot-updater/bare",
+		exportName: "bareFingerprint"
+	},
+	rock: {
+		packageName: "@hot-updater/rock",
+		exportName: "rockFingerprint"
+	},
+	expo: {
+		packageName: "@hot-updater/expo",
+		exportName: "expoFingerprint"
+	}
+};
+const loadAdapterFingerprint = async (cwd, { packageName, exportName }) => {
+	let entry;
+	try {
+		entry = createRequire(path$1.join(cwd, "package.json")).resolve(packageName);
+	} catch {
+		return "missing";
+	}
+	const module = await import(pathToFileURL(entry).href);
+	const fingerprint = module[exportName] ?? module.default?.[exportName];
+	return typeof fingerprint === "function" ? fingerprint : null;
+};
+/**
+* The fingerprint a native build of `platform` embeds, computed from the
+* inputs fingerprint.json records instead of hot-updater.config.ts, whose
+* storage and database need deploy secrets a build machine may not have.
+* `recorded` is the hash fingerprint.json holds for the platform.
+*/
+const computeRecordedFingerprintHash = async (platform) => {
+	const cwd = getCwd();
+	let file;
+	try {
+		file = JSON.parse(await fs$2.readFile(path$1.join(cwd, "fingerprint.json"), "utf8"));
+	} catch {
+		throw new Error("fingerprint.json was not found. Run `npx hot-updater fingerprint create`.");
+	}
+	const recorded = file[platform]?.hash ?? null;
+	const embedRecorded = (reason) => {
+		if (recorded === null) throw new Error(`fingerprint.json has no ${platform} fingerprint. Run \`npx hot-updater fingerprint create\`.`);
+		console.error(`warning: ${reason} The build embeds ${recorded}.`);
+		return {
+			hash: recorded,
+			recorded
+		};
+	};
+	const inputs = file.inputs;
+	if (!inputs) return embedRecorded("fingerprint.json records no inputs to compute the fingerprint from. Run `npx hot-updater fingerprint create`.");
+	const options = {
+		platform,
+		...inputs.extraSources === void 0 ? {} : { extraSources: inputs.extraSources },
+		...inputs.ignorePaths === void 0 ? {} : { ignorePaths: inputs.ignorePaths },
+		...inputs.nativeVersion === void 0 ? {} : { nativeVersion: inputs.nativeVersion }
+	};
+	const adapter = ADAPTER_FINGERPRINTS[inputs.adapter];
+	if (adapter) {
+		const fingerprint = await loadAdapterFingerprint(cwd, adapter);
+		if (fingerprint === "missing") return embedRecorded(`fingerprint.json records the ${inputs.adapter} build adapter, but ${adapter.packageName} is not installed. Run \`npx hot-updater fingerprint create\`.`);
+		if (!fingerprint) return embedRecorded(`The installed ${adapter.packageName} does not export ${adapter.exportName}; update it to compute the fingerprint at build time.`);
+		return {
+			hash: (await fingerprint(cwd, options)).hash,
+			recorded
+		};
+	}
+	if (inputs.adapter === "react-native") return {
+		hash: (await reactNativeCliFingerprint(cwd, options)).hash,
+		recorded
+	};
+	return embedRecorded(`The "${inputs.adapter}" build adapter's fingerprint needs hot-updater.config.ts.`);
+};
+//#endregion
+//#region src/utils/fingerprint/index.ts
+const generateFingerprints = async (additionalExtraSources) => {
+	const fingerprintConfig = await ensureFingerprintConfig(additionalExtraSources);
+	const projectPath = getCwd();
+	assertNativeSdkEmbedsFingerprint(projectPath);
+	const [ios, android] = await Promise.all([nativeFingerprint(projectPath, {
+		platform: "ios",
+		...fingerprintConfig
+	}), nativeFingerprint(projectPath, {
+		platform: "android",
+		...fingerprintConfig
+	})]);
+	return {
+		ios,
+		android,
+		inputs: getFingerprintInputs(fingerprintConfig)
+	};
+};
+const generateFingerprint = async (platform) => {
+	const fingerprintConfig = await ensureFingerprintConfig();
+	return nativeFingerprint(getCwd(), {
+		platform,
+		...fingerprintConfig
+	});
+};
+/**
+* Writes fingerprint.json, which native builds read to embed each platform's
+* hash. With `platform`, only that platform's fingerprint is replaced.
+*/
+const createAndInjectFingerprintFiles = async ({ platform } = {}) => {
+	const localFingerprint = await readLocalFingerprint();
+	const newFingerprint = await generateFingerprints();
+	await createFingerprintJSON(!localFingerprint || !platform ? newFingerprint : {
+		android: localFingerprint.android || newFingerprint.android,
+		ios: localFingerprint.ios || newFingerprint.ios,
+		[platform]: newFingerprint[platform],
+		inputs: newFingerprint.inputs
+	});
+	return { fingerprint: newFingerprint };
+};
+/**
+* Brings fingerprint.json to `fingerprint`, writing it only when a hash or the
+* recorded inputs differ: what `fingerprint create` writes, without rewriting
+* a file that already matches. Returns whether it wrote.
+*/
+const syncFingerprintFiles = async (fingerprint) => {
+	const local = await readLocalFingerprint();
+	const fingerprintJson = !isFingerprintEquals(local, fingerprint) || JSON.stringify(local?.inputs) !== JSON.stringify(fingerprint.inputs) || ["ios", "android"].some((platform) => local?.[platform]?.engine !== fingerprint[platform].engine);
+	if (fingerprintJson) await createFingerprintJSON(fingerprint);
+	return { fingerprintJson };
+};
+const createFingerprintJSON = async (fingerprint) => {
+	const FINGERPRINT_FILE_PATH = path.join(getCwd(), "fingerprint.json");
+	await fs.promises.writeFile(FINGERPRINT_FILE_PATH, JSON.stringify(fingerprint, null, 2));
+	return fingerprint;
+};
+const readLocalFingerprint = async () => {
+	const FINGERPRINT_FILE_PATH = path.join(getCwd(), "fingerprint.json");
+	try {
+		const content = await fs.promises.readFile(FINGERPRINT_FILE_PATH, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { ensureFingerprintConfig as _, readLocalFingerprint as a, getFingerprintDiff as c, summarizeFingerprintDiff as d, assertNativeSdkEmbedsFingerprint as f, describeFingerprintEngineChange as g, appendFingerprintExtraSources as h, generateFingerprints as i, showFingerprintChanges as l, nativeFingerprint as m, createFingerprintJSON as n, syncFingerprintFiles as o, isNativeSdkWithoutBuildFingerprintError as p, generateFingerprint as r, computeRecordedFingerprintHash as s, createAndInjectFingerprintFiles as t, showFingerprintDiff as u, getFingerprintEngineChange as v, isFingerprintEquals as y };