kintone-migrator 0.34.5 → 0.35.0

package/dist/index.mjs

@@ -10,6 +10,7 @@ import { realpathSync } from "node:fs";
 import * as v from "valibot";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
+import { createHash } from "node:crypto";
 //#region src/lib/error.ts
 var AnyError = class extends Error {
 	constructor(message, cause) {
@@ -1323,6 +1324,10 @@ var KintoneFileUploader = class {
 */
 const SKIP_REVISION_CHECK = Symbol("skip-revision-check");
 //#endregion
+//#region src/core/domain/formSchema/ports/formReadTarget.ts
+/** The generation read when a caller does not specify a target. */
+const DEFAULT_FORM_READ_TARGET = "preview";
+//#endregion
 //#region src/lib/charValidation.ts
 /** Returns true if the string contains any control characters (0x00–0x1f or 0x7f). */
 function hasControlChars(s) {
@@ -1676,6 +1681,14 @@ function toKintoneLayoutItem(item) {
 		default: throw new SystemError(SystemErrorCode.ExternalApiError, `Unknown layout item type: ${item.type}`);
 	}
 }
+const GET_FIELDS_FAILURE_MESSAGES = {
+	preview: "Failed to get form fields",
+	published: "Failed to get published form fields (the app may not be deployed yet, or the credentials may not be allowed to read it)"
+};
+const GET_LAYOUT_FAILURE_MESSAGES = {
+	preview: "Failed to get form layout",
+	published: "Failed to get published form layout (the app may not be deployed yet, or the credentials may not be allowed to read it)"
+};
 var KintoneFormConfigurator = class {
 	revisionTracker;
 	constructor(client, appId, revisionTracker) {
@@ -1683,13 +1696,14 @@ var KintoneFormConfigurator = class {
 		this.appId = appId;
 		this.revisionTracker = revisionTracker ?? new RevisionTracker();
 	}
-	async getFields() {
+	async getFields(target = DEFAULT_FORM_READ_TARGET) {
+		const preview = target === "preview";
 		try {
 			const { properties, revision } = await this.client.app.getFormFields({
 				app: this.appId,
-				preview: true
+				preview
 			});
-			if (revision) this.revisionTracker.track(revision);
+			if (revision && target === "preview") this.revisionTracker.track(revision);
 			const fields = /* @__PURE__ */ new Map();
 			for (const [code, prop] of Object.entries(properties)) {
 				const kintoneProp = prop;
@@ -1700,7 +1714,7 @@ var KintoneFormConfigurator = class {
 			}
 			return fields;
 		} catch (error) {
-			throw wrapKintoneError(error, "Failed to get form fields");
+			throw wrapKintoneError(error, GET_FIELDS_FAILURE_MESSAGES[target]);
 		}
 	}
 	async getRevision() {
@@ -1763,16 +1777,17 @@ var KintoneFormConfigurator = class {
 			throw wrapKintoneError(error, "Failed to delete form fields");
 		}
 	}
-	async getLayout() {
+	async getLayout(target = DEFAULT_FORM_READ_TARGET) {
+		const preview = target === "preview";
 		try {
 			const response = await this.client.app.getFormLayout({
 				app: this.appId,
-				preview: true
+				preview
 			});
-			if (response.revision) this.revisionTracker.track(response.revision);
+			if (response.revision && target === "preview") this.revisionTracker.track(response.revision);
 			return response.layout.map(fromKintoneLayoutItem);
 		} catch (error) {
-			throw wrapKintoneError(error, "Failed to get form layout");
+			throw wrapKintoneError(error, GET_LAYOUT_FAILURE_MESSAGES[target]);
 		}
 	}
 	async updateLayout(layout, expectedRevision) {
@@ -2705,6 +2720,13 @@ function printCustomizationDiffResult(result) {
 		return `${colorize(prefix)} ${pc.dim("[")}${colorize(location)}${pc.dim("]")} ${entry.name}${pc.dim(":")} ${entry.details}`;
 	});
 }
+function printSchemaDiffTarget(target) {
+	if (target === "published") {
+		p.log.info("Comparing against the published (deployed) form (2-way; base snapshot not used).");
+		return;
+	}
+	p.log.info("Comparing against the preview (unpublished) form.");
+}
 function printDiffResult(result) {
 	if (result.isEmpty) {
 		p.log.info("No changes detected.");
@@ -2739,6 +2761,7 @@ function printThreeWayDiffResult(result, printTwoWay) {
 		printTwoWay(result.diff);
 		return;
 	}
+	for (const note of result.notes ?? []) p.log.warn(note);
 	if (result.isEmpty) {
 		p.log.info("No changes detected (local, remote, and base are in sync).");
 		return;
@@ -3443,7 +3466,7 @@ function resolveActionMerge(merge, resolution) {
 * record-keyed merge (view / report / action / plugin). The caller supplies a
 * `label` extractor (e.g. the view's name) for display.
 */
-function buildRecordThreeWayDiff(merge, label, extras = []) {
+function buildRecordThreeWayDiff(merge, label, extras = [], notes = []) {
 	const localChanges = [];
 	const remoteDrift = [];
 	const conflicts = [];
@@ -3471,13 +3494,15 @@ function buildRecordThreeWayDiff(merge, label, extras = []) {
 			break;
 		default: break;
 	}
+	const isEmpty = localChanges.length === 0 && remoteDrift.length === 0 && conflicts.length === 0 && extras.length === 0;
 	return {
 		mode: "three-way",
 		localChanges,
 		remoteDrift,
 		conflicts,
 		extras,
-		isEmpty: localChanges.length === 0 && remoteDrift.length === 0 && conflicts.length === 0 && extras.length === 0
+		...notes.length > 0 ? { notes } : {},
+		isEmpty
 	};
 }
 /**
@@ -3606,7 +3631,7 @@ async function saveSnapshotState(storage, codec, serialize, snapshot) {
 * Loads the base snapshot, the base app revision, the local config, and the
 * remote config in parallel for a 3-way sync. Generic over the snapshot
 * (`TSnapshot`) and remote (`TRemote`) shapes so every config domain reuses one
-* loader (generalization of schema step1's `loadThreeWayInputs`).
+* loader.
 */
 async function loadThreeWayInputs$1(args) {
 	const [state, appRevision, local, remote] = await Promise.all([
@@ -3980,9 +4005,13 @@ function buildDriftMessage(pullCommand) {
 * The CLI distinguishes this snapshot drift from API optimistic-lock (TOCTOU)
 * conflicts by the `ConfigDrift` code, not by the message string, so the
 * message stays a free-form, domain-specific hint.
+*
+* `extraHint` appends a domain-specific caveat (e.g. customization's "this
+* drift may be inferred") on its own line; omitted, the message is unchanged.
 */
-function buildDriftConflict(pullCommand) {
-	return new ConflictError(ConflictErrorCode.ConfigDrift, buildDriftMessage(pullCommand));
+function buildDriftConflict(pullCommand, extraHint) {
+	const message = buildDriftMessage(pullCommand);
+	return new ConflictError(ConflictErrorCode.ConfigDrift, extraHint === void 0 ? message : `${message}\n${extraHint}`);
 }
 //#endregion
 //#region src/core/application/action/pushAction.ts
@@ -9164,11 +9193,12 @@ function toFieldDto(field) {
 		properties: fieldPropertiesToDto(field)
 	};
 }
-async function detectDiff({ container }) {
+async function detectDiff({ container, input }) {
+	const target = input?.target ?? "preview";
 	const result = await container.schemaStorage.get();
 	if (!result.exists) throw new ValidationError(ValidationErrorCode.InvalidInput, "Schema file not found");
 	const schema = parseSchemaText(container.configCodec, result.content);
-	const [currentFields, currentLayout] = await Promise.all([container.formConfigurator.getFields(), container.formConfigurator.getLayout()]);
+	const [currentFields, currentLayout] = await Promise.all([container.formConfigurator.getFields(target), container.formConfigurator.getLayout(target)]);
 	const diff = DiffDetector.detect(schema, currentFields);
 	const enrichedCurrentLayout = enrichLayoutWithFields(currentLayout, currentFields);
 	const hasLayoutChanges = DiffDetector.detectLayoutChanges(schema.layout, enrichedCurrentLayout);
@@ -10398,63 +10428,130 @@ function createCliCaptureContainers(input) {
 }
 //#endregion
 //#region src/core/domain/customization/services/configSerializer.ts
-function serializeResource(resource) {
-	if (resource.type === "FILE") return {
+function serializeResource(resource, platform, category, decorate) {
+	const serialized = resource.type === "FILE" ? {
 		type: "FILE",
 		path: resource.path
-	};
-	return {
+	} : {
 		type: "URL",
 		url: resource.url
 	};
+	const extra = decorate?.(platform, category, resource);
+	return extra === void 0 ? serialized : {
+		...extra,
+		...serialized
+	};
 }
-function serializeResourceList(resources) {
-	return resources.map(serializeResource);
+function serializeResourceList(resources, platform, category, decorate) {
+	return resources.map((resource) => serializeResource(resource, platform, category, decorate));
 }
 function hasPlatformResources(platform) {
 	return platform.js.length > 0 || platform.css.length > 0;
 }
-function serializePlatform(platform) {
+function serializePlatform(platform, platformName, decorate) {
 	return {
-		...platform.js.length > 0 ? { js: serializeResourceList(platform.js) } : {},
-		...platform.css.length > 0 ? { css: serializeResourceList(platform.css) } : {}
+		...platform.js.length > 0 ? { js: serializeResourceList(platform.js, platformName, "js", decorate) } : {},
+		...platform.css.length > 0 ? { css: serializeResourceList(platform.css, platformName, "css", decorate) } : {}
 	};
 }
-const CustomizationConfigSerializer = { serialize: (config) => {
+const CustomizationConfigSerializer = { serialize: (config, decorate) => {
 	return {
 		...config.scope !== void 0 ? { scope: config.scope } : {},
-		...hasPlatformResources(config.desktop) ? { desktop: serializePlatform(config.desktop) } : {},
-		...hasPlatformResources(config.mobile) ? { mobile: serializePlatform(config.mobile) } : {}
+		...hasPlatformResources(config.desktop) ? { desktop: serializePlatform(config.desktop, "desktop", decorate) } : {},
+		...hasPlatformResources(config.mobile) ? { mobile: serializePlatform(config.mobile, "mobile", decorate) } : {}
 	};
 } };
 //#endregion
 //#region src/core/domain/customization/services/customizationMerge.ts
+/**
+* Per-side placeholder for "no content digest for this key". Distinct per side
+* so an untracked key never compares equal across sides by accident.
+*/
+const UNTRACKED = {
+	base: "untracked:base",
+	local: "untracked:local",
+	remote: "untracked:remote"
+};
+/**
+* The bucket space every walk over a customization config must agree on.
+*
+* Shared rather than redeclared per module: the merge keys, the snapshot's
+* digest keys and the locally/remotely computed digest keys are only comparable
+* while they enumerate the same buckets, and a bucket missing from one walk
+* would not be a type error — it would silently leave digests unrecorded and
+* degrade the classification to an estimate.
+*/
 const PLATFORMS = ["desktop", "mobile"];
 const CATEGORIES = ["js", "css"];
+/**
+* The merge key holding the customization scope rather than a resource.
+*
+* Exported so every consumer branches on the same literal: the CLI's conflict
+* prompt tells scope conflicts and file conflicts apart by this key alone, and a
+* private copy drifting from this one would describe overwriting a file that
+* does not exist.
+*/
 const SCOPE_KEY = "config:scope";
 /**
 * Bucket-qualified resource identity: `platform:category:name`. Shared with the
 * force/firstTime pull path (`preservePaths`) so path preservation matches the
 * merge on the same identity and cross-bucket same-basename files stay distinct.
+*
+* The bucket parameters are the bucket types rather than `string` so a typo or a
+* stale literal at a call site is a compile error instead of a key nobody ever
+* looks up.
 */
 function resourceKey(platform, category, name) {
 	return `${platform}:${category}:${name}`;
 }
+/**
+* The {@link resourceKey} of a remote FILE, from the name kintone reports.
+*
+* The remote name is normalized exactly like a local declared path, because the
+* remote config the merge is built from carries `file.name` as its `path`: a
+* name containing `/` becomes its trailing segment there, and a lookup keyed by
+* the raw name would miss the very entry it describes.
+*/
+function remoteFileResourceKey(platform, category, fileName) {
+	return resourceKey(platform, category, resourceName({
+		type: "FILE",
+		path: fileName
+	}));
+}
+/**
+* Walks every (platform, category) bucket, tagging each resource with the bucket
+* it belongs to. Generic over the resource so the local config, the raw remote
+* shape and a merged config are all walked by the same code.
+*
+* Key-producing walks over a typed config go through here: a hand-written
+* enumeration that misses a bucket is not a type error, and the symptom —
+* digests silently left unrecorded, downloads silently skipped — surfaces far
+* from the cause. Walks over raw `unknown` data (the state parser) cannot be
+* typed as {@link BucketedResources} and instead iterate {@link PLATFORMS} and
+* {@link CATEGORIES} directly, which keeps them on the same bucket space.
+*/
+function* walkCustomizationBuckets(resources) {
+	for (const platform of PLATFORMS) for (const category of CATEGORIES) for (const resource of resources[platform][category]) yield {
+		platform,
+		category,
+		resource
+	};
+}
 function platformList(config, platform, category) {
 	const p = config[platform];
 	return category === "js" ? p.js : p.css;
 }
 /**
-* Builds the per-side map keyed by `platform:category:name`. `contentTag`
-* returns the content marker for a same-name FILE so divergent content surfaces
-* as a conflict. `side` distinguishes local vs remote tags for modified files.
+* Builds the per-side map keyed by `platform:category:name`. A FILE's tag is its
+* content digest for this side, falling back to the side's untracked sentinel so
+* an unknown content never compares equal to another side's unknown content.
 */
-function toMap(config, contentTag) {
+function toMap(config, tags, side) {
 	const map = /* @__PURE__ */ new Map();
-	for (const platform of PLATFORMS) for (const category of CATEGORIES) for (const resource of platformList(config, platform, category)) {
-		const name = resourceName(resource);
-		const tag = resource.type === "FILE" ? `FILE:${contentTag(name)}` : "URL";
-		map.set(resourceKey(platform, category, name), {
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) {
+		const key = resourceKey(platform, category, resourceName(resource));
+		const tag = resource.type === "FILE" ? `FILE:${tags.get(key) ?? UNTRACKED[side]}` : "URL";
+		map.set(key, {
 			resource,
 			tag
 		});
@@ -10463,6 +10560,12 @@ function toMap(config, contentTag) {
 	map.set(SCOPE_KEY, { scope });
 	return map;
 }
+/** The `resourceKey` set of every FILE resource in a config. */
+function fileResourceKeys(config) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) if (resource.type === "FILE") keys.add(resourceKey(platform, category, resourceName(resource)));
+	return keys;
+}
 function isScopeValue(v) {
 	return "scope" in v;
 }
@@ -10471,16 +10574,69 @@ function eq(a, b) {
 	return a.tag === b.tag;
 }
 /**
-* Computes the file-name-keyed 3-way merge of base/local/remote customization.
+* Computes the resource-key-keyed 3-way merge of base/local/remote customization.
 *
-* `modifiedFileNames` is the set of same-name FILE basenames whose local
-* content differs from the remote content (reused from the diffDetector flow).
-* Such files get distinct local/remote tags so they classify as conflicts; all
-* other matched files share the `"same"` tag and classify as unchanged.
+* `tags` carries each side's FILE content tokens (digests, or the base tags
+* produced by {@link resolveBaseFileDigests}). A key whose base tag equals the
+* local tag but not the remote tag is `remoteOnly`, and vice versa — so editing
+* a file locally is a local change, not a conflict.
 */
-function computeCustomizationThreeWayMerge(base, local, remote, modifiedFileNames) {
-	const tagFor = (side) => (name) => modifiedFileNames.has(name) ? side : "same";
-	return classifyThreeWay(toMap(base, () => "same"), toMap(local, tagFor("local")), toMap(remote, tagFor("remote")), eq);
+function computeCustomizationThreeWayMerge(base, local, remote, tags) {
+	return classifyThreeWay(toMap(base, tags.base, "base"), toMap(local, tags.local, "local"), toMap(remote, tags.remote, "remote"), eq);
+}
+/**
+* Determines the base-side comparison tag of every FILE key in the base
+* snapshot, filling in the keys whose digest was never recorded.
+*
+* Rules, highest priority first:
+*
+* 1. a recorded digest wins — the classification is exact;
+* 2. otherwise, for a legacy state (no digest at all) whose app revision has not
+*    moved, the remote digest is assumed to still be the base content, so a
+*    purely local edit is `localOnly` instead of a spurious conflict;
+* 3. otherwise, when the key exists on exactly one side, the base takes that
+*    side's tag, so the classification is decided by existence alone;
+* 4. otherwise, when both sides carry the same tag, the base takes it
+*    (`unchanged`);
+* 5. otherwise the base gets its own sentinel — both sides diverged
+*    (`conflict`), or the key exists on neither side (`bothSame`).
+*
+* Rules 3-5 decide from the two sides alone, which is all a snapshot without
+* digests allows.
+*/
+function resolveBaseFileDigests(baseConfig, baseDigests, localDigests, remoteDigests, options) {
+	const tags = /* @__PURE__ */ new Map();
+	const optimistic = /* @__PURE__ */ new Set();
+	const conservative = /* @__PURE__ */ new Set();
+	for (const key of fileResourceKeys(baseConfig)) {
+		const recorded = baseDigests.get(key);
+		if (recorded !== void 0) {
+			tags.set(key, recorded);
+			continue;
+		}
+		const inLocal = options.localKeys.has(key);
+		const inRemote = options.remoteKeys.has(key);
+		const classifiable = inLocal || inRemote;
+		const remoteDigest = remoteDigests.get(key);
+		if (options.legacyState && options.remoteUnchanged && remoteDigest !== void 0) {
+			tags.set(key, remoteDigest);
+			if (classifiable) optimistic.add(key);
+			continue;
+		}
+		const localTag = localDigests.get(key) ?? UNTRACKED.local;
+		const remoteTag = remoteDigest ?? UNTRACKED.remote;
+		if (inLocal !== inRemote) tags.set(key, inLocal ? localTag : remoteTag);
+		else if (inLocal && localTag === remoteTag) tags.set(key, localTag);
+		else tags.set(key, UNTRACKED.base);
+		if (classifiable) conservative.add(key);
+	}
+	return {
+		tags,
+		estimatedKeys: {
+			optimistic,
+			conservative
+		}
+	};
 }
 /**
 * Applies a resolved 3-way merge, returning the merged customization config.
@@ -10597,8 +10753,6 @@ function sanitizeFileName(name) {
 * Unlike {@link deduplicateName} from `@/lib/deduplicateName`, this function is
 * file-name-aware: it inserts the counter before the extension (e.g. `file_1.js`)
 * rather than appending it at the end (which would produce `file.js_1`).
-* This extension-aware behavior cannot be achieved by the generic lib utility,
-* so a local implementation is necessary.
 */
 function deduplicateFileName(baseName, usedNames) {
 	if (!usedNames.has(baseName)) {
@@ -10633,7 +10787,7 @@ function planResources(resources, platformName, platformDir, resourceType, relat
 	});
 	else {
 		const fileName = deduplicateFileName(sanitizeFileName(resource.file.name), usedNames);
-		const declaredPath = preservePaths?.get(resourceKey(platformName, resourceType, resource.file.name));
+		const declaredPath = preservePaths?.get(remoteFileResourceKey(platformName, resourceType, resource.file.name));
 		if (declaredPath !== void 0) {
 			planned.push({
 				type: "FILE",
@@ -10642,7 +10796,7 @@ function planResources(resources, platformName, platformDir, resourceType, relat
 			filesToDownload.push({
 				fileName,
 				fileKey: resource.file.fileKey,
-				absolutePath: join(contentBase, declaredPath)
+				absolutePath: resolve(contentBase, declaredPath)
 			});
 		} else {
 			const absolutePath = join(dir, fileName);
@@ -11702,6 +11856,215 @@ var apply_default$9 = define({
 	}
 });
 //#endregion
+//#region src/lib/contentDigest.ts
+const PREFIX = "sha256:";
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+* Computes the digest of raw bytes.
+*
+* The bytes are hashed as-is: no newline / BOM / trailing-newline normalization.
+* kintone stores the uploaded byte sequence verbatim, so normalizing here would
+* report "no changes" for content that actually changes once uploaded. A
+* zero-byte input is a normal input and yields the sha256 of the empty string,
+* so "no digest recorded" stays distinguishable from "the content is empty".
+*/
+function computeContentDigest(data) {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	return `${PREFIX}${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+* Narrows an untrusted value (e.g. a parsed state file) to a {@link ContentDigest}.
+*
+* The full `sha256:<64 lowercase hex chars>` shape is enforced, not just the
+* prefix: state files are hand-editable, and a truncated or otherwise malformed
+* digest would be adopted as a comparison token and silently report the remote
+* as changed. Every value {@link computeContentDigest} produces matches.
+*/
+function isContentDigest(value) {
+	return typeof value === "string" && DIGEST_PATTERN.test(value);
+}
+//#endregion
+//#region src/core/application/customization/customizationDigests.ts
+/**
+* Digests the given local FILE resources.
+*
+* Paths resolve with `resolve(basePath, path)` — the same resolution push
+* uploads from and pull writes downloads to — so the digest always describes the
+* bytes that actually travel to kintone, including when an absolute path is
+* declared.
+*
+* `keys` restricts the read to the resource keys the caller needs; keys whose
+* body cannot be read are simply absent from the result (see
+* {@link readLocalDigest}).
+*/
+async function computeFileDigests(config, basePath, reader, keys) {
+	return digestLocalFiles(config, basePath, reader, keys);
+}
+/**
+* Digests every local FILE resource of a config about to be persisted as the new
+* base snapshot. Same path resolution and same failure handling as
+* {@link computeFileDigests}; unreadable files stay untracked in the snapshot.
+*/
+async function computeSnapshotFileDigests(config, basePath, reader) {
+	return digestLocalFiles(config, basePath, reader, void 0);
+}
+async function digestLocalFiles(config, basePath, reader, keys) {
+	const targets = [];
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) {
+		if (resource.type !== "FILE") continue;
+		const key = resourceKey(platform, category, resourceName(resource));
+		if (keys !== void 0 && !keys.has(key)) continue;
+		targets.push({
+			key,
+			absolutePath: resolve(basePath, resource.path)
+		});
+	}
+	const results = await Promise.all(targets.map(async ({ key, absolutePath }) => ({
+		key,
+		digest: await readLocalDigest(reader, absolutePath)
+	})));
+	const digests = /* @__PURE__ */ new Map();
+	for (const { key, digest } of results) if (digest !== void 0) digests.set(key, digest);
+	return digests;
+}
+/**
+* Reads and digests one local file, or reports "unknown" when it cannot be read.
+*
+* The swallow is deliberate (the one try/catch of this flow): a config may
+* declare a build artifact that has not been generated yet, and neither `diff`
+* nor `pull` nor drift detection should fail because of it. The key stays
+* untracked and the merge falls back to its conservative classification.
+*/
+async function readLocalDigest(reader, absolutePath) {
+	try {
+		return computeContentDigest(await reader.read(absolutePath));
+	} catch {
+		return;
+	}
+}
+/**
+* Downloads and digests the given remote FILE resources.
+*
+* The resource key and the fileKey are paired in a single walk of the raw remote
+* shape: an index keyed by the remote file name could not be looked up when a
+* name contains `/`, because the merge key uses the trailing segment only. A
+* download failure propagates — a transient network error must not silently
+* degrade into "the remote has no content for this key" and change the
+* classification.
+*/
+async function computeRemoteFileDigests(remote, downloader, keys) {
+	const targets = [];
+	for (const { platform, category, resource } of walkCustomizationBuckets(remote)) {
+		if (resource.type !== "FILE") continue;
+		const key = remoteFileResourceKey(platform, category, resource.file.name);
+		if (!keys.has(key)) continue;
+		targets.push({
+			key,
+			fileKey: resource.file.fileKey
+		});
+	}
+	const results = await Promise.all(targets.map(async ({ key, fileKey }) => [key, computeContentDigest(await downloader.download(fileKey))]));
+	return new Map(results);
+}
+//#endregion
+//#region src/core/application/customization/customizationThreeWayMerge.ts
+/**
+* Assembles the customization 3-way merge shared by `diff`, `push` and `pull`.
+*
+* Only the contents that can change a classification are fetched: a key present
+* on one side alone is decided by existence, so local reads are limited to
+* `local ∩ (base ∪ remote)` and downloads to `remote ∩ (base ∪ local)`. Base
+* tags come from the snapshot's recorded digests, with
+* {@link resolveBaseFileDigests} filling in whatever was never recorded.
+*/
+async function buildCustomizationThreeWayMerge({ container, state, baseRevision, local, remote, basePath, localDigests: precomputedLocalDigests }) {
+	const baseKeys = fileResourceKeys(state.config);
+	const localKeys = fileResourceKeys(local);
+	const remoteKeys = fileResourceKeys(remote.config);
+	const localNeeded = intersect(localKeys, union(baseKeys, remoteKeys));
+	const remoteNeeded = intersect(remoteKeys, union(baseKeys, localKeys));
+	const [localDigests, remoteDigests] = await Promise.all([precomputedLocalDigests !== void 0 ? Promise.resolve(subset(precomputedLocalDigests, localNeeded)) : computeFileDigests(local, basePath, container.fileContentReader, localNeeded), computeRemoteFileDigests(remote.raw, container.fileDownloader, remoteNeeded)]);
+	const { tags: baseTags, estimatedKeys } = resolveBaseFileDigests(state.config, state.fileDigests, localDigests, remoteDigests, {
+		localKeys,
+		remoteKeys,
+		legacyState: state.fileDigests.size === 0,
+		remoteUnchanged: baseRevision !== void 0 && baseRevision === remote.revision
+	});
+	return {
+		merge: computeCustomizationThreeWayMerge(state.config, local, remote.config, {
+			base: baseTags,
+			local: localDigests,
+			remote: remoteDigests
+		}),
+		estimatedKeys,
+		remoteDigests,
+		unreadableLocalKeys: difference(localNeeded, localDigests)
+	};
+}
+function difference(keys, digests) {
+	return new Set([...keys].filter((key) => !digests.has(key)));
+}
+function union(a, b) {
+	return new Set([...a, ...b]);
+}
+function intersect(a, b) {
+	const result = /* @__PURE__ */ new Set();
+	for (const key of a) if (b.has(key)) result.add(key);
+	return result;
+}
+function subset(digests, keys) {
+	return new Map([...digests].filter(([key]) => keys.has(key)));
+}
+//#endregion
+//#region src/core/domain/customization/services/customizationStateParser.ts
+/**
+* Collects the per-FILE `digest` entries into the merge's key space. The
+* structure itself is already validated by {@link CustomizationConfigParser},
+* so this pass only reads the extra key and rejects malformed values. A missing
+* `digest` means "untracked", not an error: a state file carrying no digest at
+* all parses into an empty map.
+*/
+function parseFileDigests(parsed) {
+	const digests = /* @__PURE__ */ new Map();
+	if (!isRecord(parsed)) return digests;
+	for (const platform of PLATFORMS) {
+		const platformValue = parsed[platform];
+		if (!isRecord(platformValue)) continue;
+		for (const category of CATEGORIES) {
+			const list = platformValue[category];
+			if (!Array.isArray(list)) continue;
+			for (const raw of list) {
+				const entry = digestEntry(raw, platform, category);
+				if (entry !== void 0) digests.set(entry[0], entry[1]);
+			}
+		}
+	}
+	return digests;
+}
+/** The `[resourceKey, digest]` pair of one serialized resource, if it has one. */
+function digestEntry(raw, platform, category) {
+	if (!isRecord(raw) || raw.type !== "FILE" || typeof raw.path !== "string") return;
+	const digest = raw.digest;
+	if (digest === void 0 || digest === null) return;
+	if (!isContentDigest(digest)) throw new BusinessRuleError(CustomizationErrorCode.CzInvalidConfigStructure, `FILE resource "${raw.path}" has an invalid "digest": ${String(digest)}. Must be a "sha256:<64 lowercase hex chars>" string`);
+	return [resourceKey(platform, category, resourceName({
+		type: "FILE",
+		path: raw.path
+	})), digest];
+}
+/**
+* Parses pre-parsed (codec-decoded) data into a {@link CustomizationState}.
+*
+* The inverse of {@link CustomizationStateSerializer}: the captured config is
+* parsed via the same {@link CustomizationConfigParser} as the local YAML, so
+* the base snapshot is validated identically, then the per-FILE `digest` keys
+* are collected into the snapshot's digest map.
+*/
+const CustomizationStateParser = { parse: (parsed) => ({
+	config: CustomizationConfigParser.parse(parsed),
+	fileDigests: parseFileDigests(parsed)
+}) };
+//#endregion
 //#region src/core/application/customization/customizationRemote.ts
 /**
 * Converts the kintone remote customization (file metadata) into a
@@ -11730,59 +12093,6 @@ function toResource(resource) {
 		path: resource.file.name
 	};
 }
-/**
-* Computes the set of same-name FILE basenames whose local content differs from
-* the remote content, across all platforms/categories — the same signal the
-* 2-way `detectCustomizationDiff` uses for the `modified` entries. Reused here so
-* the 3-way merge marks divergent same-name files as conflicts.
-*/
-async function computeModifiedFileNames(local, remote, basePath, container) {
-	const pairs = [
-		...matchedPairs(local.desktop.js, remote.desktop.js),
-		...matchedPairs(local.desktop.css, remote.desktop.css),
-		...matchedPairs(local.mobile.js, remote.mobile.js),
-		...matchedPairs(local.mobile.css, remote.mobile.css)
-	];
-	const modified = /* @__PURE__ */ new Set();
-	if (pairs.length === 0) return modified;
-	const results = await Promise.all(pairs.map(async ({ localResource, remoteFileKey }) => {
-		const localPath = join(basePath, localResource.path);
-		const [localContent, remoteContent] = await Promise.all([container.fileContentReader.read(localPath), container.fileDownloader.download(remoteFileKey)]);
-		const isEqual = Buffer.from(localContent).equals(Buffer.from(remoteContent));
-		return {
-			name: resourceName(localResource),
-			isEqual
-		};
-	}));
-	for (const { name, isEqual } of results) if (!isEqual) modified.add(name);
-	return modified;
-}
-/** Finds matched local-FILE + remote-FILE pairs by basename. */
-function matchedPairs(localResources, remoteResources) {
-	const remoteFileMap = /* @__PURE__ */ new Map();
-	for (const r of remoteResources) if (r.type === "FILE") remoteFileMap.set(remoteResourceName(r), r.file.fileKey);
-	const pairs = [];
-	for (const local of localResources) {
-		if (local.type !== "FILE") continue;
-		const remoteFileKey = remoteFileMap.get(resourceName(local));
-		if (remoteFileKey !== void 0) pairs.push({
-			localResource: local,
-			remoteFileKey
-		});
-	}
-	return pairs;
-}
-//#endregion
-//#region src/core/domain/customization/services/customizationStateParser.ts
-/**
-* Parses pre-parsed (codec-decoded) data into a {@link CustomizationState}.
-*
-* The inverse of {@link CustomizationStateSerializer}: the captured config is
-* parsed via the same {@link CustomizationConfigParser} as the local YAML, so
-* the base snapshot is validated identically. The domain layer does not depend
-* on YAML; the application layer handles codec decoding before calling this.
-*/
-const CustomizationStateParser = { parse: (parsed) => ({ config: CustomizationConfigParser.parse(parsed) }) };
 //#endregion
 //#region src/core/application/customization/loadCustomizationThreeWayInputs.ts
 /**
@@ -11796,7 +12106,7 @@ async function loadCustomizationThreeWayInputs(container) {
 		codec: container.configCodec,
 		stateStorage: container.customizationStateStorage,
 		appRevisionStorage: container.appRevisionStorage,
-		parseState: (parsed) => CustomizationStateParser.parse(parsed).config,
+		parseState: (parsed) => CustomizationStateParser.parse(parsed),
 		stateLabel: "Customization state",
 		loadLocal: async () => {
 			const result = await container.customizationStorage.get();
@@ -11820,17 +12130,58 @@ async function loadCustomizationThreeWayInputs(container) {
 }
 //#endregion
 //#region src/core/application/customization/detectCustomizationThreeWayDiff.ts
+/** How many resource keys a note lists inline before summarizing the rest. */
+const MAX_LISTED_KEYS = 10;
+/**
+* Renders the affected resource keys so the note identifies its subjects.
+*
+* The counts alone cannot be acted on: neither the diff lines nor `customize
+* push` mark which entries were inferred, so "N file(s)" leaves the user with no
+* way to tell them apart from the exactly-compared ones.
+*/
+function formatKeys(keys) {
+	const listed = keys.slice(0, MAX_LISTED_KEYS).join(", ");
+	const rest = keys.length - MAX_LISTED_KEYS;
+	return rest > 0 ? `${listed}, and ${rest} more` : listed;
+}
+function optimisticNote(keys) {
+	return [`Base snapshot has no content digest for ${keys.length} file(s); they were classified by assuming the remote still matches the base (app revision unchanged): ${formatKeys(keys)}.`, "A normal (non-force) `customize push` or `customize pull` records the baseline. If the remote may have been edited outside this tool, run `customize pull --force` first to take the remote side — that replaces every local customization file and your customization config file with the remote copy, discarding the local edits listed above, so save them elsewhere first."].join("\n");
+}
+function conservativeNote(keys) {
+	return [`Base snapshot has no content digest for ${keys.length} file(s); their classification is inferred: ${formatKeys(keys)}.`, "Run `customize pull` once (resolve the entries, or use `--ours` to keep every local copy) to record the baseline for files that exist on the remote or can be read from disk. Subsequent runs use exact content comparison for those files. `--theirs` records the baseline too, but it replaces the local files on disk with the remote copies wherever the remote side has a body, so save the local edits elsewhere first."].join("\n");
+}
+function unreadableNote(keys) {
+	return [`${keys.length} file(s) declared in the customization config file could not be read from disk, so their content counted as unknown and they are listed as changed: ${formatKeys(keys)}.`, "Build or restore those files (or fix the declared paths) and run `customize diff` again to see the real classification."].join("\n");
+}
+/**
+* Builds the caveats for keys the classification could not compare exactly:
+* those whose base content was inferred rather than read from the snapshot, and
+* those whose local body was unreadable. Only keys that actually surfaced as a
+* diff line are reported: such a key classified as `unchanged` tells the user
+* nothing, and over-reporting would train them to ignore the note.
+*/
+function buildNotes(estimatedKeys, unreadableLocalKeys, changedKeys) {
+	const changedIn = (keys) => [...keys].filter((key) => changedKeys.has(key));
+	const notes = [];
+	const optimistic = changedIn(estimatedKeys.optimistic);
+	if (optimistic.length > 0) notes.push(optimisticNote(optimistic));
+	const conservative = changedIn(estimatedKeys.conservative);
+	if (conservative.length > 0) notes.push(conservativeNote(conservative));
+	const unreadable = changedIn(unreadableLocalKeys);
+	if (unreadable.length > 0) notes.push(unreadableNote(unreadable));
+	return notes;
+}
 /**
 * Detects customization differences with 3-way awareness.
 *
 * When a state (base snapshot) exists, classifies changes into local-only,
-* remote drift, and conflicts via the file-name-keyed merge. Same-name files
-* whose content diverges are conflicts. When no state exists, falls back to the
-* existing 2-way `detectCustomizationDiff` (the CLI renders it with its 2-way
-* printer).
+* remote drift, and conflicts via the resource-key-keyed merge, comparing FILE
+* contents by digest against the base snapshot. When no state exists, falls back
+* to the existing 2-way `detectCustomizationDiff` (the CLI renders it with its
+* 2-way printer).
 */
 async function detectCustomizationThreeWayDiff({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (state === void 0 || local === void 0) return {
 		mode: "two-way",
 		diff: await detectCustomizationDiff({
@@ -11838,8 +12189,15 @@ async function detectCustomizationThreeWayDiff({ container, input }) {
 			input: { basePath: input.basePath }
 		})
 	};
-	const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
-	return buildRecordThreeWayDiff(computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames), (entry) => entry.key);
+	const { merge, estimatedKeys, unreadableLocalKeys } = await buildCustomizationThreeWayMerge({
+		container,
+		state,
+		baseRevision,
+		local,
+		remote,
+		basePath: input.basePath
+	});
+	return buildRecordThreeWayDiff(merge, (entry) => entry.key, [], buildNotes(estimatedKeys, unreadableLocalKeys, new Set(merge.entries.filter((entry) => entry.change.kind === "localOnly" || entry.change.kind === "remoteOnly" || entry.change.kind === "conflict").map((entry) => entry.key))));
 }
 //#endregion
 //#region src/cli/commands/customize/diff.ts
@@ -11894,20 +12252,37 @@ var diff_default$10 = define({
 * stringification (via the codec port in the application layer).
 *
 * The snapshot is serialized through the exact same path as `capture`
-* ({@link CustomizationConfigSerializer}) so the state file is round-trip
-* compatible with the captured config. The app revision is NOT written here; it
-* is persisted separately via `AppRevisionStorage`.
+* ({@link CustomizationConfigSerializer}), with the recorded content digest
+* injected into each FILE entry via the serializer's decorate hook. URL
+* resources and FILE resources with no recorded digest are written unchanged,
+* so the state file stays round-trip compatible with the captured config. The
+* app revision is NOT written here; it is persisted separately via
+* `AppRevisionStorage`.
 */
-const CustomizationStateSerializer = { serialize: (state) => CustomizationConfigSerializer.serialize(state.config) };
+const CustomizationStateSerializer = { serialize: (state) => CustomizationConfigSerializer.serialize(state.config, (platform, category, resource) => {
+	if (resource.type !== "FILE") return;
+	const digest = state.fileDigests.get(resourceKey(platform, category, resourceName(resource)));
+	return digest === void 0 ? void 0 : { digest };
+}) };
 //#endregion
 //#region src/core/application/customization/customizationStateIo.ts
 /**
-* Persists the new base: the customization snapshot (state file) and the app
-* revision (`state/<appName>/revision.yaml`) side by side. The two writes are
-* kept together so they always advance as a pair (snapshot → revision).
+* Persists the new base: the customization snapshot (config + FILE content
+* digests) and the app revision (`state/<appName>/revision.yaml`) side by side.
+* The two writes are kept together so they always advance as a pair
+* (snapshot → revision).
+*
+* `fileDigests` is computed by the caller rather than here: this function runs
+* after `updateCustomization` (it needs the resulting revision), while push must
+* digest its files *before* uploading them, and pull's merge path records the
+* remote's digests rather than what is on disk. Keeping the parameter required
+* still makes a digest-less snapshot impossible to write by accident.
 */
-async function saveCustomizationSnapshotAndRevision(container, config, revision) {
-	await saveSnapshotState(container.customizationStateStorage, container.configCodec, CustomizationStateSerializer.serialize, { config });
+async function saveCustomizationSnapshotAndRevision(container, config, fileDigests, revision) {
+	await saveSnapshotState(container.customizationStateStorage, container.configCodec, CustomizationStateSerializer.serialize, {
+		config,
+		fileDigests
+	});
 	await saveAppRevision(container.appRevisionStorage, container.configCodec, revision);
 }
 //#endregion
@@ -11924,7 +12299,7 @@ async function saveCustomizationSnapshotAndRevision(container, config, revision)
 *   resolution, so an aborted resolution leaves the working copy untouched.
 */
 async function pullCustomization({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (input.force || state === void 0 || local === void 0) {
 		const preservePaths = local !== void 0 ? buildPreservePaths(local) : void 0;
 		const captured = await captureCustomization({
@@ -11936,17 +12311,28 @@ async function pullCustomization({ container, input }) {
 			}
 		});
 		await container.customizationStorage.update(captured.configText);
-		await saveCustomizationSnapshotAndRevision(container, captured.config, remote.revision);
+		const fileDigests = await computeSnapshotFileDigests(captured.config, input.basePath, container.fileContentReader);
+		await saveCustomizationSnapshotAndRevision(container, captured.config, fileDigests, remote.revision);
 		return { mode: input.force ? "force" : "firstTime" };
 	}
-	const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
+	const { merge, remoteDigests, estimatedKeys, unreadableLocalKeys } = await buildCustomizationThreeWayMerge({
+		container,
+		state,
+		baseRevision,
+		local,
+		remote,
+		basePath: input.basePath
+	});
 	return {
 		mode: "merged",
-		merge: computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames),
+		merge,
 		local,
 		remote: remote.raw,
 		remoteConfig: remote.config,
-		remoteRevision: remote.revision
+		remoteRevision: remote.revision,
+		remoteDigests,
+		estimatedKeys,
+		unreadableLocalKeys
 	};
 }
 /**
@@ -11962,18 +12348,15 @@ async function pullCustomization({ container, input }) {
 async function applyPulledCustomizationMerge({ container, input }) {
 	const merged = wrapBusinessRuleError(() => resolveCustomizationMerge(input.merge, input.resolution, input.local, input.remoteConfig));
 	const fromRemote = /* @__PURE__ */ new Set();
-	for (const entry of input.merge.entries) {
-		const name = nameFromKey(entry.key);
-		if (name === void 0) continue;
-		if (entry.change.kind === "remoteOnly") fromRemote.add(name);
-		else if (entry.change.kind === "conflict" && input.resolution.get(entry.key) === "remote") fromRemote.add(name);
-	}
+	for (const entry of input.merge.entries) if (entry.change.kind === "remoteOnly") fromRemote.add(entry.key);
+	else if (entry.change.kind === "conflict" && input.resolution.get(entry.key) === "remote") fromRemote.add(entry.key);
 	const remoteFileKeys = remoteFileKeyMap(input.remote);
 	const downloads = [];
-	for (const resource of allFileResources(merged)) {
-		const name = resourceName(resource);
-		if (!fromRemote.has(name)) continue;
-		const fileKey = remoteFileKeys.get(name);
+	for (const { platform, category, resource } of walkCustomizationBuckets(merged)) {
+		if (resource.type !== "FILE") continue;
+		const key = resourceKey(platform, category, resourceName(resource));
+		if (!fromRemote.has(key)) continue;
+		const fileKey = remoteFileKeys.get(key);
 		if (fileKey === void 0) continue;
 		const absolutePath = resolve(input.basePath, resource.path);
 		downloads.push((async () => {
@@ -11984,7 +12367,28 @@ async function applyPulledCustomizationMerge({ container, input }) {
 	await Promise.all(downloads);
 	const configText = stringifyConfig(container.configCodec, CustomizationConfigSerializer.serialize(merged));
 	await container.customizationStorage.update(configText);
-	await saveCustomizationSnapshotAndRevision(container, merged, input.remoteRevision);
+	await saveCustomizationSnapshotAndRevision(container, merged, await buildMergedBaseDigests(merged, input.basePath, input.remoteDigests, container), input.remoteRevision);
+}
+/**
+* Base digests for a merge that was just applied.
+*
+* A key the remote still holds records the *remote's* digest, even when the
+* local side won the merge: the base means "what local and remote last agreed
+* on", and content that stayed local was never uploaded. Recording the on-disk
+* bytes instead would make the very next diff report the local edit as remote
+* drift and block the push. Keys the remote does not have (locally added files,
+* or remote-only files freshly downloaded) take the on-disk digest.
+*/
+async function buildMergedBaseDigests(merged, basePath, remoteDigests, container) {
+	const mergedKeys = fileResourceKeys(merged);
+	const fromDisk = new Set([...mergedKeys].filter((key) => !remoteDigests.has(key)));
+	const diskDigests = await computeFileDigests(merged, basePath, container.fileContentReader, fromDisk);
+	const digests = /* @__PURE__ */ new Map();
+	for (const key of mergedKeys) {
+		const digest = remoteDigests.get(key) ?? diskDigests.get(key);
+		if (digest !== void 0) digests.set(key, digest);
+	}
+	return digests;
 }
 /**
 * Builds the path-preservation map for `captureCustomization`: bucket-qualified
@@ -11996,41 +12400,19 @@ async function applyPulledCustomizationMerge({ container, input }) {
 */
 function buildPreservePaths(config) {
 	const map = /* @__PURE__ */ new Map();
-	const add = (platform, category, resources) => {
-		for (const resource of resources) if (resource.type === "FILE") map.set(resourceKey(platform, category, resourceName(resource)), resource.path);
-	};
-	add("desktop", "js", config.desktop.js);
-	add("desktop", "css", config.desktop.css);
-	add("mobile", "js", config.mobile.js);
-	add("mobile", "css", config.mobile.css);
+	for (const { platform, category, resource } of walkCustomizationBuckets(config)) if (resource.type === "FILE") map.set(resourceKey(platform, category, resourceName(resource)), resource.path);
 	return map;
 }
-function allFileResources(config) {
-	return [
-		...config.desktop.js,
-		...config.desktop.css,
-		...config.mobile.js,
-		...config.mobile.css
-	].filter((r) => r.type === "FILE");
-}
 /**
-* Extracts the file/resource name from a merge key. Resource keys are
-* `platform:category:name`; the `config:scope` key has no resource name.
+* Remote FILE `fileKey`s under the merge identity, so a body is looked up by the
+* same key the merge decided to take from the remote. A flat basename map would
+* make cross-bucket same-basename files (e.g. `desktop/js/main.js` and
+* `mobile/js/main.js`) resolve to whichever bucket was registered last,
+* overwriting one bucket's body with the other's.
 */
-function nameFromKey(key) {
-	const parts = key.split(":");
-	if (parts.length < 3) return void 0;
-	return parts.slice(2).join(":");
-}
 function remoteFileKeyMap(remote) {
 	const map = /* @__PURE__ */ new Map();
-	const add = (resources) => {
-		for (const r of resources) if (r.type === "FILE") map.set(remoteResourceName(r), r.file.fileKey);
-	};
-	add(remote.desktop.js);
-	add(remote.desktop.css);
-	add(remote.mobile.js);
-	add(remote.mobile.css);
+	for (const { platform, category, resource } of walkCustomizationBuckets(remote)) if (resource.type === "FILE") map.set(remoteFileResourceKey(platform, category, resource.file.name), resource.file.fileKey);
 	return map;
 }
 //#endregion
@@ -12054,6 +12436,42 @@ function derivePullPaths(customizeFilePath) {
 		filePrefix: deriveFilePrefix(customizeFilePath)
 	};
 }
+/**
+* What each choice does. `pull` never writes to kintone, so the destruction is
+* one-directional: only the copy on disk can be lost here, and the wording says
+* which choice loses it.
+*
+* The scope is a single value in the customization config file, so no file moves
+* either way. A resource whose remote side is a URL — or gone — carries no body
+* to write over the local copy, hence "wherever the remote side has a body"
+* rather than a flat promise that the file on disk is replaced.
+*/
+const SCOPE_EFFECT = "remote takes the remote scope; local keeps the local one, and the remote stays untouched until the next `customize push`";
+const RESOURCE_EFFECT = "remote replaces the local file on disk wherever the remote side has a body; local keeps the copy on disk, and the remote stays untouched until the next `customize push`";
+/**
+* Why the divergence may not be real, when it may not be.
+*
+* An unreadable local file counts as unknown content, so it conflicts with any
+* remote change even where a baseline was recorded — a separate case from a
+* missing baseline, and the only one where picking `local` leaves the merge
+* pointing at a file that is not on disk.
+*/
+function conflictCaveat(context, key) {
+	if (context.unreadableLocalKeys.has(key)) return "the local file could not be read, so this may not be a real conflict";
+	if (context.estimatedKeys.conservative.has(key)) return "no recorded baseline for this file, so this may not be a real conflict";
+}
+/**
+* The conflict prompt. Exported so its wording is pinned by a test: this prompt
+* is the only place where picking the wrong side discards content, and both the
+* caveat and the effect are chosen here.
+*/
+function buildConflictPrompt(context, key) {
+	const isScope = key === SCOPE_KEY;
+	const effect = isScope ? SCOPE_EFFECT : RESOURCE_EFFECT;
+	const caveat = conflictCaveat(context, key);
+	const detail = caveat === void 0 ? effect : `${caveat}; ${effect}`;
+	return `Conflict on ${isScope ? "scope" : `entry "${key}"`}. Keep which side? (${detail})`;
+}
 async function resolveConflicts$1(merged, options) {
 	const resolution = /* @__PURE__ */ new Map();
 	for (const conflict of merged.merge.conflicts) {
@@ -12066,7 +12484,7 @@ async function resolveConflicts$1(merged, options) {
 			continue;
 		}
 		const selected = await p.select({
-			message: `Conflict on file "${conflict.key}". Keep which side?`,
+			message: buildConflictPrompt(merged, conflict.key),
 			options: [{
 				value: "local",
 				label: "local (ours)"
@@ -12120,7 +12538,8 @@ async function runPull$1(containerConfig, options) {
 				local: result.local,
 				remote: result.remote,
 				remoteConfig: result.remoteConfig,
-				remoteRevision: result.remoteRevision
+				remoteRevision: result.remoteRevision,
+				remoteDigests: result.remoteDigests
 			}
 		});
 		p.log.success("Local customization merged and written.");
@@ -12142,7 +12561,8 @@ async function runPull$1(containerConfig, options) {
 			local: result.local,
 			remote: result.remote,
 			remoteConfig: result.remoteConfig,
-			remoteRevision: result.remoteRevision
+			remoteRevision: result.remoteRevision,
+			remoteDigests: result.remoteDigests
 		}
 	});
 	p.log.success("Conflicts resolved. Local customization written.");
@@ -12196,6 +12616,9 @@ var pull_default$10 = define({
 //#region src/core/application/customization/pushCustomization.ts
 /** Pull command name surfaced in the drift hint message. */
 const CUSTOMIZE_PULL_COMMAND = "customize pull";
+function inferredDriftHint(count) {
+	return `Drift possibly inferred: no recorded content baseline for ${count} of the drifted file(s). Run \`customize diff\` for the affected file(s); the pull above also records the baseline.`;
+}
 async function resolvePlatform(platform, basePath, fileUploader) {
 	const resolveList = async (resources) => Promise.all(resources.map(async (resource) => {
 		if (resource.type === "URL") return resource;
@@ -12216,10 +12639,11 @@ async function resolvePlatform(platform, basePath, fileUploader) {
 /**
 * Applies the local customization config to the remote with drift detection.
 *
-* - Loads base/local/remote and computes the file-name-keyed 3-way merge. drift
-*   (remoteOnly or conflict entries) && !force → {@link buildDriftConflict}
-*   tagged with `ConfigDrift`. Same-name files whose content
-*   diverges count as conflicts and block a non-forced push.
+* - Loads base/local/remote and computes the resource-key-keyed 3-way merge.
+*   drift (remoteOnly or conflict entries) && !force → {@link buildDriftConflict}
+*   tagged with `ConfigDrift`. A file edited only locally is a local change, not
+*   drift, so it pushes without `--force`; a file whose remote body moved away
+*   from the base blocks the push.
 * - Replaces the full js/css lists with the local config's resolved (uploaded)
 *   resources via `updateAppCustomize`, so renames are expressed as old-name
 *   removal + new-name add (full-list replace — NOT an inexpressible
@@ -12230,12 +12654,25 @@ async function resolvePlatform(platform, basePath, fileUploader) {
 * post-apply revision as the new base (snapshot → revision).
 */
 async function pushCustomization({ container, input }) {
-	const { state, local, remote } = await loadCustomizationThreeWayInputs(container);
+	const { state, baseRevision, local, remote } = await loadCustomizationThreeWayInputs(container);
 	if (local === void 0) throw new ValidationError(ValidationErrorCode.InvalidInput, "Customization config file not found");
 	const firstTime = state === void 0;
-	if (!firstTime && !input.force) {
-		const modifiedFileNames = await computeModifiedFileNames(local, remote.raw, input.basePath, container);
-		if (computeCustomizationThreeWayMerge(state, local, remote.config, modifiedFileNames).entries.some((e) => e.change.kind === "remoteOnly" || e.change.kind === "conflict")) throw buildDriftConflict(CUSTOMIZE_PULL_COMMAND);
+	const localDigests = await computeSnapshotFileDigests(local, input.basePath, container.fileContentReader);
+	if (state !== void 0 && !input.force) {
+		const { merge, estimatedKeys } = await buildCustomizationThreeWayMerge({
+			container,
+			state,
+			baseRevision,
+			local,
+			remote,
+			basePath: input.basePath,
+			localDigests
+		});
+		const driftKeys = merge.entries.filter((e) => e.change.kind === "remoteOnly" || e.change.kind === "conflict").map((e) => e.key);
+		if (driftKeys.length > 0) {
+			const inferred = driftKeys.filter((key) => estimatedKeys.conservative.has(key)).length;
+			throw buildDriftConflict(CUSTOMIZE_PULL_COMMAND, inferred > 0 ? inferredDriftHint(inferred) : void 0);
+		}
 	}
 	const [desktop, mobile] = await Promise.all([resolvePlatform(local.desktop, input.basePath, container.fileUploader), resolvePlatform(local.mobile, input.basePath, container.fileUploader)]);
 	ResourceMerger.assertResourceCount("desktop.js", desktop.js);
@@ -12259,7 +12696,7 @@ async function pushCustomization({ container, input }) {
 		scope: local.scope,
 		desktop: local.desktop,
 		mobile: local.mobile
-	}, newRevision);
+	}, localDigests, newRevision);
 	return {
 		mode: firstTime ? "firstTime" : "push",
 		revision: newRevision
@@ -15665,7 +16102,8 @@ function buildTasks(args) {
 						local: result.local,
 						remote: result.remote,
 						remoteConfig: result.remoteConfig,
-						remoteRevision: result.remoteRevision
+						remoteRevision: result.remoteRevision,
+						remoteDigests: result.remoteDigests
 					}
 				});
 				return "merged";
@@ -17320,41 +17758,71 @@ function buildLayoutExtras(layoutConflict, layoutLocalChanged, layoutRemoteChang
 	return [];
 }
 //#endregion
+//#region src/cli/commands/schema/formReadTarget.ts
+/**
+* Shared `--published` flag for the schema commands that read a form definition
+* (`dump` / `diff`). Kept next to its users rather than in `src/cli/config.ts`,
+* which holds only domain-agnostic connection/execution-mode options.
+*/
+const formReadTargetArgs = { published: {
+	type: "boolean",
+	description: "Read the published (deployed) form instead of the preview (unpublished) one"
+} };
+function resolveFormReadTarget(values) {
+	return values.published ? "published" : "preview";
+}
+//#endregion
 //#region src/cli/commands/schema/diff.ts
-async function runDiff$2(container) {
+async function runDiff$2(container, target) {
+	printSchemaDiffTarget(target);
 	const s = p.spinner();
 	s.start("Comparing schema...");
 	let result;
 	try {
-		result = await detectThreeWayDiff({ container });
+		result = target === "published" ? {
+			kind: "published",
+			value: await detectDiff({
+				container,
+				input: { target }
+			})
+		} : {
+			kind: "preview",
+			value: await detectThreeWayDiff({ container })
+		};
 	} catch (error) {
 		s.stop("Comparison failed.");
 		throw error;
 	}
 	s.stop("Comparison complete.");
-	printThreeWayDiffResult(result, printDiffResult);
+	if (result.kind === "published") {
+		printDiffResult(result.value);
+		return;
+	}
+	printThreeWayDiffResult(result.value, printDiffResult);
 }
 var diff_default$2 = define({
 	name: "diff",
 	description: "Detect differences between schema file and current kintone form",
 	args: {
 		...kintoneArgs,
-		...multiAppArgs
+		...multiAppArgs,
+		...formReadTargetArgs
 	},
 	run: async (ctx) => {
 		try {
+			const target = resolveFormReadTarget(ctx.values);
 			await routeMultiApp(ctx.values, {
 				singleLegacy: async () => {
-					await runDiff$2(createCliContainer(resolveConfig(ctx.values)));
+					await runDiff$2(createCliContainer(resolveConfig(ctx.values)), target);
 				},
 				singleApp: async (app, projectConfig) => {
-					await runDiff$2(createCliContainer(resolveAppCliConfig(app, projectConfig, ctx.values)));
+					await runDiff$2(createCliContainer(resolveAppCliConfig(app, projectConfig, ctx.values)), target);
 				},
 				multiApp: async (plan, projectConfig) => {
 					await runMultiAppWithFailCheck(plan, async (app) => {
 						const container = createCliContainer(resolveAppCliConfig(app, projectConfig, ctx.values));
 						printAppHeader(app.name, app.appId);
-						await runDiff$2(container);
+						await runDiff$2(container, target);
 					}, "All schema diffs completed successfully.");
 				}
 			});
@@ -17365,26 +17833,31 @@ var diff_default$2 = define({
 });
 //#endregion
 //#region src/core/adapters/kintone/formDumpReader.ts
+const GET_RAW_FORM_DATA_FAILURE_MESSAGES = {
+	preview: "Failed to fetch raw form data for dump",
+	published: "Failed to fetch published raw form data for dump (the app may not be deployed yet, or the credentials may not be allowed to read it)"
+};
 var KintoneFormDumpReader = class {
 	constructor(client, appId) {
 		this.client = client;
 		this.appId = appId;
 	}
-	async getRawFormData() {
+	async getRawFormData(target = DEFAULT_FORM_READ_TARGET) {
+		const preview = target === "preview";
 		try {
 			const [fields, layout] = await Promise.all([this.client.app.getFormFields({
 				app: this.appId,
-				preview: true
+				preview
 			}), this.client.app.getFormLayout({
 				app: this.appId,
-				preview: true
+				preview
 			})]);
 			return {
 				fields,
 				layout
 			};
 		} catch (error) {
-			throw wrapKintoneError(error, "Failed to fetch raw form data for dump");
+			throw wrapKintoneError(error, GET_RAW_FORM_DATA_FAILURE_MESSAGES[target]);
 		}
 	}
 };
@@ -17428,29 +17901,38 @@ function createDumpCliContainer(config) {
 }
 //#endregion
 //#region src/core/application/formSchema/dumpForm.ts
-async function dumpForm({ container }) {
-	const rawData = await container.formDumpReader.getRawFormData();
+async function dumpForm({ container, input }) {
+	const rawData = await container.formDumpReader.getRawFormData(input?.target ?? "preview");
 	await Promise.all([container.dumpStorage.saveFields(JSON.stringify(rawData.fields, null, 2)), container.dumpStorage.saveLayout(JSON.stringify(rawData.layout, null, 2))]);
 }
 //#endregion
 //#region src/cli/commands/schema/dump.ts
-async function runSingleDump(config) {
-	const container = createDumpCliContainer(config);
+async function runSingleDump(config, basePrefix, target) {
+	const filePrefix = `${basePrefix}${target === "published" ? "published-" : ""}`;
+	const container = createDumpCliContainer({
+		...config,
+		filePrefix
+	});
 	const s = p.spinner();
-	s.start("Fetching form fields and layout...");
-	await dumpForm({ container });
+	s.start(target === "published" ? "Fetching published form fields and layout..." : "Fetching form fields and layout...");
+	await dumpForm({
+		container,
+		input: { target }
+	});
 	s.stop("Form data fetched.");
-	p.log.success(`Saved ${pc.cyan(`${config.filePrefix}fields.json`)} and ${pc.cyan(`${config.filePrefix}layout.json`)}`);
+	p.log.success(`Saved ${pc.cyan(`${filePrefix}fields.json`)} and ${pc.cyan(`${filePrefix}layout.json`)}`);
 }
 var dump_default = define({
 	name: "dump",
 	description: "Dump current kintone form fields and layout as JSON",
 	args: {
 		...kintoneArgs,
-		...multiAppArgs
+		...multiAppArgs,
+		...formReadTargetArgs
 	},
 	run: async (ctx) => {
 		try {
+			const target = resolveFormReadTarget(ctx.values);
 			await routeMultiApp(ctx.values, {
 				singleLegacy: async () => {
 					const config = resolveConfig(ctx.values);
@@ -17458,9 +17940,8 @@ var dump_default = define({
 						baseUrl: config.baseUrl,
 						auth: config.auth,
 						appId: config.appId,
-						guestSpaceId: config.guestSpaceId,
-						filePrefix: ""
-					});
+						guestSpaceId: config.guestSpaceId
+					}, "", target);
 				},
 				singleApp: async (app, projectConfig) => {
 					const config = resolveAppCliConfig(app, projectConfig, ctx.values);
@@ -17468,9 +17949,8 @@ var dump_default = define({
 						baseUrl: config.baseUrl,
 						auth: config.auth,
 						appId: config.appId,
-						guestSpaceId: config.guestSpaceId,
-						filePrefix: `${app.name}-`
-					});
+						guestSpaceId: config.guestSpaceId
+					}, `${app.name}-`, target);
 				},
 				multiApp: async (plan, projectConfig) => {
 					await runMultiAppWithFailCheck(plan, async (app) => {
@@ -17480,9 +17960,8 @@ var dump_default = define({
 							baseUrl: config.baseUrl,
 							auth: config.auth,
 							appId: config.appId,
-							guestSpaceId: config.guestSpaceId,
-							filePrefix: `${app.name}-`
-						});
+							guestSpaceId: config.guestSpaceId
+						}, `${app.name}-`, target);
 					}, "All dumps completed successfully.");
 				}
 			});