kintone-migrator 0.31.6 → 0.32.0

package/dist/index.mjs

@@ -67,7 +67,10 @@ const FormSchemaErrorCode = {
 	FsInvalidFieldType: "FS_INVALID_FIELD_TYPE",
 	FsInvalidLayoutStructure: "FS_INVALID_LAYOUT_STRUCTURE",
 	FsInvalidDecorationElement: "FS_INVALID_DECORATION_ELEMENT",
-	FsEmptyFields: "FS_EMPTY_FIELDS"
+	FsEmptyFields: "FS_EMPTY_FIELDS",
+	FsInvalidStateStructure: "FS_INVALID_STATE_STRUCTURE",
+	FsInvalidMergeResolution: "FS_INVALID_MERGE_RESOLUTION",
+	FsOrphanMergedField: "FS_ORPHAN_MERGED_FIELD"
 };
 //#endregion
 //#region src/core/domain/generalSettings/errorCode.ts
@@ -226,7 +229,10 @@ var NotFoundError = class extends ApplicationError {
 function isNotFoundError(error) {
 	return error instanceof NotFoundError;
 }
-const ConflictErrorCode = { Conflict: "CONFLICT" };
+const ConflictErrorCode = {
+	Conflict: "CONFLICT",
+	SchemaDrift: "SCHEMA_DRIFT"
+};
 var ConflictError = class extends ApplicationError {
 	name = "ConflictError";
 	constructor(code, message, cause) {
@@ -668,6 +674,68 @@ function buildDiffResult(entries, warnings = []) {
 		warnings
 	};
 }
+/**
+* Classifies every key present in any of base/local/remote into a 3-way change.
+*
+* Pure and domain-agnostic: the caller supplies the equality function `eq`
+* and the value type `V`. Presence/absence of a key is treated as a value, so
+* `eq` is only ever called with two defined values; an `undefined` on one side
+* (absence) compared to a defined value (presence) is always "changed".
+*/
+function classifyThreeWay(base, local, remote, eq) {
+	const keys = new Set([
+		...base.keys(),
+		...local.keys(),
+		...remote.keys()
+	]);
+	const entries = [];
+	const conflicts = [];
+	const sidesEqual = (a, b) => {
+		if (a === void 0 && b === void 0) return true;
+		if (a === void 0 || b === void 0) return false;
+		return eq(a, b);
+	};
+	for (const key of keys) {
+		const baseValue = base.get(key);
+		const localValue = local.get(key);
+		const remoteValue = remote.get(key);
+		const dl = !sidesEqual(baseValue, localValue);
+		const dr = !sidesEqual(baseValue, remoteValue);
+		let change;
+		let merged;
+		if (!dl && !dr) {
+			change = { kind: "unchanged" };
+			merged = baseValue;
+		} else if (dl && !dr) {
+			change = { kind: "localOnly" };
+			merged = localValue;
+		} else if (!dl && dr) {
+			change = { kind: "remoteOnly" };
+			merged = remoteValue;
+		} else if (sidesEqual(localValue, remoteValue)) {
+			change = { kind: "bothSame" };
+			merged = localValue;
+		} else {
+			change = { kind: "conflict" };
+			merged = void 0;
+		}
+		const entry = {
+			key,
+			change,
+			...baseValue !== void 0 ? { base: baseValue } : {},
+			...localValue !== void 0 ? { local: localValue } : {},
+			...remoteValue !== void 0 ? { remote: remoteValue } : {},
+			...merged !== void 0 ? { merged } : {}
+		};
+		entries.push(entry);
+		if (change.kind === "conflict") conflicts.push(entry);
+	}
+	return {
+		entries,
+		conflicts,
+		hasConflict: conflicts.length > 0
+	};
+}
 //#endregion
 //#region src/core/domain/services/formatValue.ts
 function formatValue(v) {
@@ -1188,6 +1256,16 @@ var KintoneFileUploader = class {
 	}
 };
 //#endregion
+//#region src/core/domain/formSchema/ports/formConfigurator.ts
+/**
+* Sentinel passed as `expectedRevision` to explicitly skip the kintone revision
+* check (sends `-1` / omits the expected revision). Used by `--force` push so
+* that the apply succeeds even when the remote drifted (AC-9 / ADR-005 /
+* ADR-010). This is distinct from `undefined`, which means "use the adapter's
+* default tracked revision" (existing migrate behaviour).
+*/
+const SKIP_REVISION_CHECK = Symbol("skip-revision-check");
+//#endregion
 //#region src/lib/charValidation.ts
 /** Returns true if the string contains any control characters (0x00–0x1f or 0x7f). */
 function hasControlChars(s) {
@@ -1568,40 +1646,60 @@ var KintoneFormConfigurator = class {
 			throw wrapKintoneError(error, "Failed to get form fields");
 		}
 	}
-	async addFields(fields) {
+	async getRevision() {
+		try {
+			const { revision } = await this.client.app.getFormFields({
+				app: this.appId,
+				preview: true
+			});
+			if (!revision) throw new SystemError(SystemErrorCode.ExternalApiError, "kintone API did not return a form revision");
+			this.revisionTracker.track(revision);
+			return revision;
+		} catch (error) {
+			throw wrapKintoneError(error, "Failed to get form revision");
+		}
+	}
+	resolveMutationRevision(expectedRevision) {
+		if (expectedRevision === SKIP_REVISION_CHECK) return null;
+		return expectedRevision ?? this.revisionTracker.current ?? null;
+	}
+	async addFields(fields, expectedRevision) {
 		try {
 			const properties = {};
 			for (const field of fields) properties[field.code] = toKintoneProperty(field);
+			const revision = this.resolveMutationRevision(expectedRevision);
 			const response = await this.client.app.addFormFields({
 				app: this.appId,
 				properties,
-				...this.revisionTracker.current !== void 0 ? { revision: this.revisionTracker.current } : {}
+				...revision !== null ? { revision } : {}
 			});
 			if (response.revision) this.revisionTracker.track(response.revision);
 		} catch (error) {
 			throw wrapKintoneError(error, "Failed to add form fields");
 		}
 	}
-	async updateFields(fields) {
+	async updateFields(fields, expectedRevision) {
 		try {
 			const properties = {};
 			for (const field of fields) properties[field.code] = toKintoneProperty(field);
+			const revision = this.resolveMutationRevision(expectedRevision);
 			const response = await this.client.app.updateFormFields({
 				app: this.appId,
 				properties,
-				...this.revisionTracker.current !== void 0 ? { revision: this.revisionTracker.current } : {}
+				...revision !== null ? { revision } : {}
 			});
 			if (response.revision) this.revisionTracker.track(response.revision);
 		} catch (error) {
 			throw wrapKintoneError(error, "Failed to update form fields");
 		}
 	}
-	async deleteFields(fieldCodes) {
+	async deleteFields(fieldCodes, expectedRevision) {
 		try {
+			const revision = this.resolveMutationRevision(expectedRevision);
 			const response = await this.client.app.deleteFormFields({
 				app: this.appId,
 				fields: fieldCodes.map((code) => code),
-				...this.revisionTracker.current !== void 0 ? { revision: this.revisionTracker.current } : {}
+				...revision !== null ? { revision } : {}
 			});
 			if (response.revision) this.revisionTracker.track(response.revision);
 		} catch (error) {
@@ -1620,13 +1718,14 @@ var KintoneFormConfigurator = class {
 			throw wrapKintoneError(error, "Failed to get form layout");
 		}
 	}
-	async updateLayout(layout) {
+	async updateLayout(layout, expectedRevision) {
 		try {
 			const kintoneLayout = layout.map(toKintoneLayoutItem);
+			const revision = this.resolveMutationRevision(expectedRevision);
 			const response = await this.client.app.updateFormLayout({
 				app: this.appId,
 				layout: kintoneLayout,
-				revision: this.revisionTracker.current !== void 0 ? Number(this.revisionTracker.current) : -1
+				revision: revision !== null ? Number(revision) : -1
 			});
 			if (response.revision) this.revisionTracker.track(response.revision);
 		} catch (error) {
@@ -1831,6 +1930,11 @@ var LocalFileWriter = class {
 	}
 };
 //#endregion
+//#region src/core/adapters/local/schemaStateStorage.ts
+function createLocalFileSchemaStateStorage(filePath) {
+	return createLocalFileStorage(filePath, "schema state file");
+}
+//#endregion
 //#region src/core/adapters/local/schemaStorage.ts
 function createLocalFileSchemaStorage(filePath) {
 	return createLocalFileStorage(filePath, "schema file");
@@ -1855,6 +1959,7 @@ function createCliContainer(config) {
 		configCodec,
 		formConfigurator: new KintoneFormConfigurator(client, config.appId),
 		schemaStorage: createLocalFileSchemaStorage(config.schemaFilePath),
+		schemaStateStorage: createLocalFileSchemaStateStorage(config.stateSchemaFilePath),
 		appDeployer: new KintoneAppDeployer(client, config.appId)
 	};
 }
@@ -1899,6 +2004,48 @@ function createActionCliContainer(config) {
 	};
 }
 //#endregion
+//#region src/core/domain/projectConfig/appFilePaths.ts
+function buildAppFilePaths(appName, baseDir) {
+	const prefix = (path) => baseDir ? join(baseDir, path) : path;
+	return {
+		schema: prefix(`${appName}/schema.yaml`),
+		seed: prefix(`${appName}/seed.yaml`),
+		customize: prefix(`${appName}/customize.yaml`),
+		view: prefix(`${appName}/view.yaml`),
+		settings: prefix(`${appName}/settings.yaml`),
+		notification: prefix(`${appName}/notification.yaml`),
+		report: prefix(`${appName}/report.yaml`),
+		action: prefix(`${appName}/action.yaml`),
+		process: prefix(`${appName}/process.yaml`),
+		fieldAcl: prefix(`${appName}/field-acl.yaml`),
+		appAcl: prefix(`${appName}/app-acl.yaml`),
+		recordAcl: prefix(`${appName}/record-acl.yaml`),
+		adminNotes: prefix(`${appName}/admin-notes.yaml`),
+		plugin: prefix(`${appName}/plugin.yaml`)
+	};
+}
+/**
+* Resolves the path to the schema state (base snapshot) file.
+*
+* State uses an app-scoped directory layout (`state/<appName>/schema.yaml`)
+* whose hierarchy is the inverse of {@link buildAppFilePaths} (`<appName>/...`).
+* They are intentionally kept as separate functions: the state convention is
+* chosen so that future per-app revision unification (e.g.
+* `state/<appName>/revision.yaml`) can live alongside without churn.
+*/
+function buildStateFilePath(appName, baseDir) {
+	const path = `state/${appName}/schema.yaml`;
+	return baseDir ? join(baseDir, path) : path;
+}
+/**
+* Resolves the path to the legacy single-app schema state file
+* (`state/schema.yaml`).
+*/
+function buildLegacyStateFilePath(baseDir) {
+	const path = "state/schema.yaml";
+	return baseDir ? join(baseDir, path) : path;
+}
+//#endregion
 //#region src/cli/config.ts
 const CliConfigSchema = v.object({
 	KINTONE_DOMAIN: v.pipe(v.string(), v.nonEmpty("KINTONE_DOMAIN is required")),
@@ -2001,7 +2148,8 @@ function resolveConfig(cliValues) {
 		auth,
 		appId: output.KINTONE_APP_ID,
 		guestSpaceId: output.KINTONE_GUEST_SPACE_ID,
-		schemaFilePath: output.SCHEMA_FILE_PATH
+		schemaFilePath: output.SCHEMA_FILE_PATH,
+		stateSchemaFilePath: buildLegacyStateFilePath()
 	};
 }
 function resolveAuth(apiToken, username, password) {
@@ -2254,27 +2402,6 @@ function resolveSingleApp(config, appName) {
 	return { orderedApps: [entry] };
 }
 //#endregion
-//#region src/core/domain/projectConfig/appFilePaths.ts
-function buildAppFilePaths(appName, baseDir) {
-	const prefix = (path) => baseDir ? join(baseDir, path) : path;
-	return {
-		schema: prefix(`${appName}/schema.yaml`),
-		seed: prefix(`${appName}/seed.yaml`),
-		customize: prefix(`${appName}/customize.yaml`),
-		view: prefix(`${appName}/view.yaml`),
-		settings: prefix(`${appName}/settings.yaml`),
-		notification: prefix(`${appName}/notification.yaml`),
-		report: prefix(`${appName}/report.yaml`),
-		action: prefix(`${appName}/action.yaml`),
-		process: prefix(`${appName}/process.yaml`),
-		fieldAcl: prefix(`${appName}/field-acl.yaml`),
-		appAcl: prefix(`${appName}/app-acl.yaml`),
-		recordAcl: prefix(`${appName}/record-acl.yaml`),
-		adminNotes: prefix(`${appName}/admin-notes.yaml`),
-		plugin: prefix(`${appName}/plugin.yaml`)
-	};
-}
-//#endregion
 //#region src/cli/handleError.ts
 /**
 * Log error details without terminating the process.
@@ -2481,6 +2608,27 @@ function printDiffResult(result) {
 	});
 	p.note(lines.join("\n"), "Diff Details", { format: (v) => v });
 }
+function printThreeWayDiffResult(result) {
+	if (result.mode === "two-way") {
+		p.log.info("No base snapshot found (2-way comparison).");
+		printDiffResult(result.diff);
+		return;
+	}
+	if (result.isEmpty) {
+		p.log.info("No changes detected (local, remote, and base are in sync).");
+		return;
+	}
+	const lines = [];
+	for (const e of result.localChanges) lines.push(`${pc.green("L")} ${pc.dim("[")}${pc.green(e.fieldCode)}${pc.dim("]")} ${e.fieldLabel}${pc.dim(":")} local change`);
+	for (const e of result.remoteDrift) lines.push(`${pc.yellow("R")} ${pc.dim("[")}${pc.yellow(e.fieldCode)}${pc.dim("]")} ${e.fieldLabel}${pc.dim(":")} remote drift`);
+	for (const e of result.conflicts) lines.push(`${pc.red("C")} ${pc.dim("[")}${pc.red(e.fieldCode)}${pc.dim("]")} ${e.fieldLabel}${pc.dim(":")} conflict`);
+	if (result.layoutConflict) lines.push(`${pc.red("C")} ${pc.red("layout")}${pc.dim(":")} conflict`);
+	else if (result.layoutLocalChanged && !result.layoutRemoteChanged) lines.push(`${pc.green("L")} ${pc.green("layout")}${pc.dim(":")} local change`);
+	else if (result.layoutRemoteChanged && !result.layoutLocalChanged) lines.push(`${pc.yellow("R")} ${pc.yellow("layout")}${pc.dim(":")} remote drift`);
+	else if (result.layoutLocalChanged && result.layoutRemoteChanged) lines.push(`${pc.green("L")} ${pc.green("layout")}${pc.dim(":")} change`);
+	p.log.info(`${pc.green("L")}=local  ${pc.yellow("R")}=remote drift  ${pc.red("C")}=conflict`);
+	p.note(lines.join("\n"), "3-way Diff Details", { format: (v) => v });
+}
 function printFieldPermissionDiffResult(result) {
 	printGenericDiffResult(result, "Field Permission Diff Details", (entry, colorize, prefix) => `${colorize(prefix)} ${pc.dim("[")}${colorize(entry.fieldCode)}${pc.dim("]:")} ${entry.details}`);
 }
@@ -2603,7 +2751,8 @@ function resolveAppCliConfig(app, projectConfig, cliValues) {
 		auth,
 		appId: app.appId,
 		guestSpaceId,
-		schemaFilePath: cliValues["schema-file"] ?? process.env.SCHEMA_FILE_PATH ?? app.schemaFile ?? buildAppFilePaths(app.name).schema
+		schemaFilePath: cliValues["schema-file"] ?? process.env.SCHEMA_FILE_PATH ?? app.schemaFile ?? buildAppFilePaths(app.name).schema,
+		stateSchemaFilePath: buildStateFilePath(app.name)
 	};
 }
 function resolveAuthForApp(app, projectConfig, cliValues) {
@@ -4072,6 +4221,65 @@ function splitSubtableInnerFields(desired, current) {
 	};
 }
 //#endregion
+//#region src/core/application/formSchema/applySchemaChanges.ts
+function processModifiedEntry(after, before, fieldsToUpdate, innerFieldsToDelete) {
+	if (after.type === "SUBTABLE" && before !== void 0 && before.type === "SUBTABLE") {
+		const { newInnerFields, existingInnerFields, deletedInnerFieldCodes } = splitSubtableInnerFields(after, before);
+		if (newInnerFields.size > 0) throw new ValidationError(ValidationErrorCode.InvalidInput, `kintone REST API does not support adding fields to an existing subtable. Use the schema override command instead. Subtable: ${after.code}`);
+		if (existingInnerFields.size > 0) fieldsToUpdate.push({
+			...after,
+			properties: { fields: existingInnerFields }
+		});
+		for (const code of deletedInnerFieldCodes) innerFieldsToDelete.push(code);
+	} else if (before !== void 0 && before.type !== after.type) throw new ValidationError(ValidationErrorCode.InvalidInput, `Field type change detected for "${after.code}" (${before.type} → ${after.type}). Use the schema override command instead.`);
+	else fieldsToUpdate.push(after);
+}
+/**
+* Applies a {@link Schema} to the remote form (preview).
+*
+* This is the shared application core (ADR-009): it computes the diff against
+* the current form, classifies
+* add/update/delete/layout changes, rejects field type changes and additions
+* to existing subtables with a {@link ValidationError} (AC-13), and applies the
+* changes via the configurator. `migrate` (via local YAML) and `push` (via a
+* merged/local in-memory `Schema`) share this exact implementation.
+*
+* When `expectedRevision` is provided it is passed to every mutation so a
+* concurrent change yields a 409 conflict.
+*/
+async function applySchemaChanges(schema, { container, expectedRevision }) {
+	const [currentFields, currentLayout] = await Promise.all([container.formConfigurator.getFields(), container.formConfigurator.getLayout()]);
+	const diff = DiffDetector.detect(schema, currentFields);
+	const enrichedCurrentLayout = enrichLayoutWithFields(currentLayout, currentFields);
+	const hasLayoutChanges = DiffDetector.detectLayoutChanges(schema.layout, enrichedCurrentLayout);
+	if (diff.isEmpty && !hasLayoutChanges) return;
+	const subtableInnerCodes = collectSubtableInnerFieldCodes(schema.fields);
+	const added = diff.entries.filter((e) => e.type === "added");
+	const modified = diff.entries.filter((e) => e.type === "modified");
+	const deleted = diff.entries.filter((e) => e.type === "deleted");
+	const fieldsToAdd = [];
+	const fieldsToUpdate = [];
+	const innerFieldsToDelete = [];
+	for (const entry of added) {
+		if (entry.after === void 0) continue;
+		if (subtableInnerCodes.has(entry.fieldCode)) continue;
+		fieldsToAdd.push(entry.after);
+	}
+	for (const entry of modified) {
+		if (entry.after === void 0) continue;
+		if (subtableInnerCodes.has(entry.fieldCode)) continue;
+		processModifiedEntry(entry.after, entry.before, fieldsToUpdate, innerFieldsToDelete);
+	}
+	if (fieldsToAdd.length > 0) await container.formConfigurator.addFields(fieldsToAdd, expectedRevision);
+	if (fieldsToUpdate.length > 0) await container.formConfigurator.updateFields(fieldsToUpdate, expectedRevision);
+	if (deleted.length > 0 || innerFieldsToDelete.length > 0) {
+		const currentSubtableInnerCodes = collectSubtableInnerFieldCodes(currentFields);
+		const fieldCodes = [...deleted.filter((e) => !currentSubtableInnerCodes.has(e.fieldCode)).map((e) => e.fieldCode), ...innerFieldsToDelete];
+		if (fieldCodes.length > 0) await container.formConfigurator.deleteFields(fieldCodes, expectedRevision);
+	}
+	if (hasLayoutChanges) await container.formConfigurator.updateLayout(schema.layout, expectedRevision);
+}
+//#endregion
 //#region src/core/domain/formSchema/services/schemaValidator.ts
 const SELECTION_TYPES = new Set([
 	"CHECK_BOX",
@@ -4698,53 +4906,20 @@ function parseSchemaText(codec, rawText) {
 }
 //#endregion
 //#region src/core/application/formSchema/executeMigration.ts
-function processModifiedEntry(after, before, fieldsToUpdate, innerFieldsToDelete) {
-	if (after.type === "SUBTABLE" && before !== void 0 && before.type === "SUBTABLE") {
-		const { newInnerFields, existingInnerFields, deletedInnerFieldCodes } = splitSubtableInnerFields(after, before);
-		if (newInnerFields.size > 0) throw new ValidationError(ValidationErrorCode.InvalidInput, `kintone REST API does not support adding fields to an existing subtable. Use the schema override command instead. Subtable: ${after.code}`);
-		if (existingInnerFields.size > 0) fieldsToUpdate.push({
-			...after,
-			properties: { fields: existingInnerFields }
-		});
-		for (const code of deletedInnerFieldCodes) innerFieldsToDelete.push(code);
-	} else if (before !== void 0 && before.type !== after.type) throw new ValidationError(ValidationErrorCode.InvalidInput, `Field type change detected for "${after.code}" (${before.type} → ${after.type}). Use the schema override command instead.`);
-	else fieldsToUpdate.push(after);
-}
+/**
+* Reads the local schema YAML and applies it to the remote form.
+*
+* Thin wrapper around {@link applySchemaChanges} (ADR-009): it loads/parses the
+* local schema file and validates it, then delegates the application core to
+* the shared function. It does not enforce an expected revision (legacy migrate
+* behaviour) and does not read or write the state file.
+*/
 async function executeMigration({ container }) {
 	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);
 	assertSchemaValid(schema);
-	const [currentFields, currentLayout] = await Promise.all([container.formConfigurator.getFields(), container.formConfigurator.getLayout()]);
-	const diff = DiffDetector.detect(schema, currentFields);
-	const enrichedCurrentLayout = enrichLayoutWithFields(currentLayout, currentFields);
-	const hasLayoutChanges = DiffDetector.detectLayoutChanges(schema.layout, enrichedCurrentLayout);
-	if (diff.isEmpty && !hasLayoutChanges) return;
-	const subtableInnerCodes = collectSubtableInnerFieldCodes(schema.fields);
-	const added = diff.entries.filter((e) => e.type === "added");
-	const modified = diff.entries.filter((e) => e.type === "modified");
-	const deleted = diff.entries.filter((e) => e.type === "deleted");
-	const fieldsToAdd = [];
-	const fieldsToUpdate = [];
-	const innerFieldsToDelete = [];
-	for (const entry of added) {
-		if (entry.after === void 0) continue;
-		if (subtableInnerCodes.has(entry.fieldCode)) continue;
-		fieldsToAdd.push(entry.after);
-	}
-	for (const entry of modified) {
-		if (entry.after === void 0) continue;
-		if (subtableInnerCodes.has(entry.fieldCode)) continue;
-		processModifiedEntry(entry.after, entry.before, fieldsToUpdate, innerFieldsToDelete);
-	}
-	if (fieldsToAdd.length > 0) await container.formConfigurator.addFields(fieldsToAdd);
-	if (fieldsToUpdate.length > 0) await container.formConfigurator.updateFields(fieldsToUpdate);
-	if (deleted.length > 0 || innerFieldsToDelete.length > 0) {
-		const currentSubtableInnerCodes = collectSubtableInnerFieldCodes(currentFields);
-		const fieldCodes = [...deleted.filter((e) => !currentSubtableInnerCodes.has(e.fieldCode)).map((e) => e.fieldCode), ...innerFieldsToDelete];
-		if (fieldCodes.length > 0) await container.formConfigurator.deleteFields(fieldCodes);
-	}
-	if (hasLayoutChanges) await container.formConfigurator.updateLayout(schema.layout);
+	await applySchemaChanges(schema, { container });
 }
 //#endregion
 //#region src/core/domain/generalSettings/services/configParser.ts
@@ -7067,7 +7242,8 @@ function createCliApplyAllContainers(input) {
 	const paths = buildAppFilePaths(input.appName, input.baseDir);
 	const schema = createCliContainer({
 		...base,
-		schemaFilePath: paths.schema
+		schemaFilePath: paths.schema,
+		stateSchemaFilePath: buildStateFilePath(input.appName, input.baseDir)
 	});
 	const seed = createSeedCliContainer({
 		...base,
@@ -8345,7 +8521,12 @@ const applyArgs = {
 	...confirmArgs,
 	...dryRunArgs
 };
-async function runApplyAll(cliConfig, appName, options) {
+/**
+* Diff phase: generate containers, run the diff preview, print results, emit the
+* seed note, and report whether there are changes. Does not print the dry-run
+* note — the caller decides when to surface it.
+*/
+async function runApplyDiffPhase(cliConfig, appName) {
 	const { containers, diffContainers, paths } = createCliApplyAllContainers({
 		...cliConfig,
 		appName
@@ -8362,7 +8543,43 @@ async function runApplyAll(cliConfig, appName, options) {
 	printDiffAllResults(diffResults);
 	const seedExists = (await containers.seed.seedStorage.get()).exists;
 	if (seedExists) p.log.info("Note: Seed data will be upserted (no diff preview available).");
-	const hasChanges = diffResults.some((r) => r.success && !r.result.isEmpty);
+	return {
+		containers,
+		customizeBasePath,
+		seedExists,
+		hasChanges: diffResults.some((r) => r.success && !r.result.isEmpty)
+	};
+}
+/**
+* Apply phase: run apply for one app, print results, and compute the
+* `AppExecutionOutcome`. Deploy stays embedded in `applyAllForApp`, so this
+* preserves per-app dependency-ordered deploy even when called per app from the
+* multi-app flow.
+*/
+async function runApplyExecutePhase({ containers, customizeBasePath, appName }) {
+	const as = p.spinner();
+	as.start(`Applying all domains for ${appName}...`);
+	const output = await applyAllForApp({
+		containers,
+		customizeBasePath
+	});
+	const applyFailCount = output.phases.flatMap((pr) => pr.results).filter((r) => !r.success && r.skipped !== "not-found").length;
+	as.stop(`Apply complete.${applyFailCount > 0 ? ` (${applyFailCount} failed)` : ""}`);
+	printApplyAllResults(output);
+	if (output.phases.flatMap((pr) => pr.results).some((r) => !r.success && r.skipped !== "not-found") || output.deployError) return {
+		ok: false,
+		error: output.deployError ?? new SystemError(SystemErrorCode.ExecutionError, `Apply failed for ${appName}.`)
+	};
+	return { ok: true };
+}
+/**
+* Single-app wrapper that runs the diff and apply phases in sequence, preserving
+* the original single-mode flow (diff → dry-run early return → confirm → apply).
+* Multi-app does not use this wrapper; it inserts a single cross-app confirm
+* between the phases instead.
+*/
+async function runApplyAll(cliConfig, appName, options) {
+	const { containers, customizeBasePath, seedExists, hasChanges } = await runApplyDiffPhase(cliConfig, appName);
 	if (!hasChanges) p.log.success(seedExists ? "No changes detected. Seed data will still be upserted." : "No changes detected.");
 	if (options.dryRun) {
 		p.log.info("Dry run complete. No changes will be applied.");
@@ -8376,20 +8593,11 @@ async function runApplyAll(cliConfig, appName, options) {
 			return { ok: true };
 		}
 	}
-	const as = p.spinner();
-	as.start(`Applying all domains for ${appName}...`);
-	const output = await applyAllForApp({
+	return runApplyExecutePhase({
 		containers,
-		customizeBasePath
+		customizeBasePath,
+		appName
 	});
-	const applyFailCount = output.phases.flatMap((pr) => pr.results).filter((r) => !r.success && r.skipped !== "not-found").length;
-	as.stop(`Apply complete.${applyFailCount > 0 ? ` (${applyFailCount} failed)` : ""}`);
-	printApplyAllResults(output);
-	if (output.phases.flatMap((pr) => pr.results).some((r) => !r.success && r.skipped !== "not-found") || output.deployError) return {
-		ok: false,
-		error: output.deployError ?? new SystemError(SystemErrorCode.ExecutionError, `Apply failed for ${appName}.`)
-	};
-	return { ok: true };
 }
 var apply_default$10 = define({
 	name: "apply",
@@ -8412,12 +8620,42 @@ var apply_default$10 = define({
 					})).ok) process.exitCode = 1;
 				},
 				multiApp: async (plan, projectConfig) => {
-					await runMultiAppWithFailCheck(plan, async (app) => {
+					const appDiffResults = [];
+					for (const app of plan.orderedApps) {
 						const cliConfig = resolveAppCliConfig(app, projectConfig, values);
 						printAppHeader(app.name, app.appId);
-						return runApplyAll(cliConfig, app.name, {
-							skipConfirm,
-							dryRun
+						const diff = await runApplyDiffPhase(cliConfig, app.name);
+						appDiffResults.push({
+							app,
+							...diff
+						});
+					}
+					const hasAnyChanges = appDiffResults.some((a) => a.hasChanges || a.seedExists);
+					if (!hasAnyChanges) p.log.success("No changes detected in any app.");
+					if (dryRun) {
+						p.log.info("Dry run complete. No changes will be applied.");
+						if (appDiffResults.some((a) => !a.hasChanges && a.seedExists)) p.log.info("Note: Seed data would still be upserted when running without --dry-run.");
+						return;
+					}
+					if (!hasAnyChanges) return;
+					if (!skipConfirm) {
+						const shouldContinue = await p.confirm({ message: "Apply these changes to all apps?" });
+						if (p.isCancel(shouldContinue) || !shouldContinue) {
+							p.cancel("Apply cancelled.");
+							return;
+						}
+					}
+					await runMultiAppWithFailCheck(plan, async (app) => {
+						const entry = appDiffResults.find((a) => a.app.name === app.name);
+						if (!entry) throw new SystemError(SystemErrorCode.InternalServerError, `App diff result not found for "${app.name}"`);
+						if (!entry.hasChanges && !entry.seedExists) {
+							p.log.info("No changes. Skipping.");
+							return { ok: true };
+						}
+						return runApplyExecutePhase({
+							containers: entry.containers,
+							customizeBasePath: entry.customizeBasePath,
+							appName: app.name
 						});
 					});
 				}
@@ -8444,7 +8682,8 @@ function createCliCaptureContainers(input) {
 		containers: {
 			schema: createCliContainer({
 				...base,
-				schemaFilePath: paths.schema
+				schemaFilePath: paths.schema,
+				stateSchemaFilePath: buildStateFilePath(input.appName, input.baseDir)
 			}),
 			seed: createSeedCliContainer({
 				...base,
@@ -9726,7 +9965,8 @@ function createCliDiffAllContainers(input) {
 		containers: {
 			schema: createCliContainer({
 				...base,
-				schemaFilePath: paths.schema
+				schemaFilePath: paths.schema,
+				stateSchemaFilePath: buildStateFilePath(input.appName, input.baseDir)
 			}),
 			customization: createCustomizationCliContainer({
 				...base,
@@ -10596,19 +10836,342 @@ var capture_default$3 = define({
 	}
 });
 //#endregion
+//#region src/core/domain/formSchema/services/threeWayMerge.ts
+/**
+* Normalizes a field map so that base/local/remote share the same population
+* before 3-way classification (ADR-007).
+*
+* - Subtable inner fields are removed from the top level: a subtable is treated
+*   as a single entity (its inner Map is compared whole by `isFieldEqual`).
+* - GROUP definitions are removed from the field channel: GROUP structural
+*   changes surface via the layout channel.
+*
+* `getFields()` (remote) already excludes system fields and flattens subtable
+* inner fields to the top level; parsed local/base schemas include GROUP and
+* subtable inner definitions. Running all three through this normalization
+* aligns their populations so classification compares like-with-like.
+*/
+function normalizeForThreeWay(fields) {
+	const innerCodes = collectSubtableInnerFieldCodes(fields);
+	const normalized = /* @__PURE__ */ new Map();
+	for (const [code, def] of fields) {
+		if (def.type === "GROUP") continue;
+		if (innerCodes.has(code)) continue;
+		normalized.set(code, def);
+	}
+	return normalized;
+}
+/**
+* Computes a 3-way merge of two form schemas against a common base.
+*
+* Fields are classified per-entity over the normalized field channel; layout
+* is coarse-grained (single conflict flag, ADR-003). GROUP/subtable-inner are
+* excluded from the field channel and reconstructed from the chosen layout in
+* {@link resolveMerge}.
+*/
+function computeThreeWayMerge(base, local, remote) {
+	const fieldResult = classifyThreeWay(normalizeForThreeWay(base.fields), normalizeForThreeWay(local.fields), normalizeForThreeWay(remote.fields), isFieldEqual);
+	const enrichedBaseLayout = enrichLayoutWithFields(base.layout, base.fields);
+	const enrichedLocalLayout = enrichLayoutWithFields(local.layout, local.fields);
+	const enrichedRemoteLayout = enrichLayoutWithFields(remote.layout, remote.fields);
+	const layoutLocalChanged = !isLayoutEqual(enrichedBaseLayout, enrichedLocalLayout);
+	const layoutRemoteChanged = !isLayoutEqual(enrichedBaseLayout, enrichedRemoteLayout);
+	let layoutConflict = false;
+	let mergedLayout;
+	let layoutAutoSide;
+	if (layoutLocalChanged && layoutRemoteChanged) if (isLayoutEqual(enrichedLocalLayout, enrichedRemoteLayout)) {
+		mergedLayout = enrichedLocalLayout;
+		layoutAutoSide = "local";
+	} else layoutConflict = true;
+	else if (layoutLocalChanged) {
+		mergedLayout = enrichedLocalLayout;
+		layoutAutoSide = "local";
+	} else if (layoutRemoteChanged) {
+		mergedLayout = enrichedRemoteLayout;
+		layoutAutoSide = "remote";
+	} else {
+		mergedLayout = enrichedBaseLayout;
+		layoutAutoSide = "base";
+	}
+	return {
+		fieldEntries: fieldResult.entries,
+		fieldConflicts: fieldResult.conflicts,
+		layoutConflict,
+		baseLayout: enrichedBaseLayout,
+		localLayout: enrichedLocalLayout,
+		remoteLayout: enrichedRemoteLayout,
+		...mergedLayout !== void 0 ? { mergedLayout } : {},
+		...layoutAutoSide !== void 0 ? { layoutAutoSide } : {},
+		hasConflict: fieldResult.hasConflict || layoutConflict,
+		baseFields: base.fields,
+		localFields: local.fields,
+		remoteFields: remote.fields
+	};
+}
+/**
+* Reconstructs the merged {@link Schema} after conflicts have been resolved.
+*
+* The chosen layout (local/remote on conflict, otherwise the auto-merged
+* layout) determines the structure. GROUP/subtable-inner definitions that were
+* excluded from the field channel are reconstructed from the field map that
+* corresponds to the chosen layout, so the result is internally consistent.
+*
+* @throws when `resolution` does not cover every field conflict, or when the
+*   layout resolution is inconsistent with `layoutConflict`.
+*/
+function resolveMerge(merge, resolution) {
+	assertResolutionCovers(merge, resolution);
+	const layoutSide = merge.layoutConflict ? resolution.layout : layoutAutoSide(merge);
+	const chosenLayout = layoutSide === "local" ? merge.localLayout : merge.remoteLayout;
+	const chosenSideFields = layoutSide === "local" ? merge.localFields : merge.remoteFields;
+	const mergedFields = new Map(chosenSideFields);
+	for (const entry of merge.fieldEntries) overlayFieldEntry(mergedFields, entry, resolveFieldEntry(entry, resolution));
+	assertNoOrphanFields(mergedFields, chosenLayout);
+	return Schema.create(mergedFields, chosenLayout);
+}
+/**
+* Rejects merge resolutions whose field channel and layout channel disagree on
+* which fields exist. The two channels are resolved independently
+* (`resolveFieldEntry` vs `layoutSide`), so the merged field map and the chosen
+* layout can diverge in two mirror-image ways, both of which corrupt the
+* layout-driven write-back (`SchemaSerializer.serialize` walks the layout, not
+* the field map):
+*
+* 1. **Orphan field** — a field in `mergedFields` but absent from the chosen
+*    layout. A field added on one side (auto-merged into `mergedFields`) is
+*    placed only in that side's layout; choosing the conflicting layout from
+*    the other side leaves the field unplaced, so it is silently dropped on
+*    write-back (ADR-016).
+* 2. **Resurrected field** — a field placed in the chosen layout but absent
+*    from `mergedFields`. A field deleted on one side (field channel resolves
+*    to `undefined`, removed from `mergedFields`) still appears in the other
+*    side's layout; choosing that layout makes serialization re-emit the
+*    deleted field's full definition from the layout element, silently undoing
+*    the deletion (ADR-017).
+*
+* Detecting both turns a silent correctness loss into an explicit, actionable
+* error: the chosen resolution combination is internally inconsistent and the
+* user must pick the layout side that matches the field-channel decisions.
+*/
+function assertNoOrphanFields(mergedFields, layout) {
+	const { placed, groupCodes } = collectLayoutFieldCodes(layout);
+	const orphans = [];
+	for (const code of mergedFields.keys()) if (!placed.has(code)) orphans.push(code);
+	if (orphans.length > 0) throw new BusinessRuleError(FormSchemaErrorCode.FsOrphanMergedField, `Merge resolution leaves field(s) not placed in the chosen layout: ${orphans.join(", ")}. The adopted field exists on a different side than the chosen layout; choose the layout side that contains the field.`);
+	const resurrected = [];
+	for (const code of placed) {
+		if (groupCodes.has(code)) continue;
+		if (!mergedFields.has(code)) resurrected.push(code);
+	}
+	if (resurrected.length > 0) throw new BusinessRuleError(FormSchemaErrorCode.FsOrphanMergedField, `Merge resolution keeps field(s) placed in the chosen layout that were removed from the field set: ${resurrected.join(", ")}. The field was deleted on one side but the chosen layout still contains it; choose the layout side that omits the deleted field.`);
+}
+function collectLayoutFieldCodes(layout) {
+	const placed = /* @__PURE__ */ new Set();
+	const groupCodes = /* @__PURE__ */ new Set();
+	const collectElements = (elements) => {
+		for (const element of elements) if (element.kind === "field") placed.add(element.field.code);
+	};
+	for (const item of layout) switch (item.type) {
+		case "ROW":
+			collectElements(item.fields);
+			break;
+		case "GROUP":
+			placed.add(item.code);
+			groupCodes.add(item.code);
+			for (const row of item.layout) collectElements(row.fields);
+			break;
+		case "SUBTABLE":
+			placed.add(item.code);
+			collectElements(item.fields);
+			break;
+		case "REFERENCE_TABLE":
+			placed.add(item.code);
+			break;
+	}
+	return {
+		placed,
+		groupCodes
+	};
+}
+function assertResolutionCovers(merge, resolution) {
+	for (const conflict of merge.fieldConflicts) if (!resolution.fields.has(conflict.key)) throw new BusinessRuleError(FormSchemaErrorCode.FsInvalidMergeResolution, `Merge resolution missing field conflict: ${conflict.key}`);
+	if (merge.layoutConflict && resolution.layout !== "local" && resolution.layout !== "remote") throw new BusinessRuleError(FormSchemaErrorCode.FsInvalidMergeResolution, "Merge resolution must choose a layout side for the layout conflict");
+}
+function dropSubtableInner(fields, code) {
+	const existing = fields.get(code);
+	if (existing?.type === "SUBTABLE") for (const innerCode of existing.properties.fields.keys()) fields.delete(innerCode);
+}
+function overlayFieldEntry(mergedFields, entry, resolved) {
+	dropSubtableInner(mergedFields, entry.key);
+	if (resolved === void 0) {
+		mergedFields.delete(entry.key);
+		return;
+	}
+	mergedFields.set(entry.key, resolved);
+	if (resolved.type === "SUBTABLE") for (const [innerCode, innerDef] of resolved.properties.fields) mergedFields.set(innerCode, innerDef);
+}
+function layoutAutoSide(merge) {
+	return merge.layoutAutoSide === "remote" ? "remote" : "local";
+}
+function resolveFieldEntry(entry, resolution) {
+	switch (entry.change.kind) {
+		case "unchanged":
+		case "localOnly":
+		case "bothSame": return entry.merged;
+		case "remoteOnly": return entry.merged;
+		case "conflict": return resolution.fields.get(entry.key) === "remote" ? entry.remote : entry.local;
+	}
+}
+//#endregion
+//#region src/core/domain/formSchema/services/schemaStateParser.ts
+/**
+* Parses pre-parsed (codec-decoded) data into a {@link SchemaState}.
+*
+* The top-level `revision` is extracted and the remainder (the captured
+* `layout`) is parsed via {@link SchemaParser}. This is the inverse of
+* {@link SchemaStateSerializer}. The domain layer does not depend on YAML;
+* the application layer handles codec decoding before calling this.
+*/
+const SchemaStateParser = { parse: (parsed) => {
+	if (!isRecord(parsed)) throw new BusinessRuleError(FormSchemaErrorCode.FsInvalidStateStructure, "Schema state must be an object");
+	const { revision, ...rest } = parsed;
+	if (typeof revision !== "string" || revision.length === 0) throw new BusinessRuleError(FormSchemaErrorCode.FsInvalidStateStructure, "Schema state must have a non-empty \"revision\" string");
+	return {
+		revision,
+		schema: SchemaParser.parse(rest)
+	};
+} };
+//#endregion
+//#region src/core/domain/formSchema/services/schemaStateSerializer.ts
+/**
+* Serializes a {@link SchemaState} to a plain object suitable for YAML
+* stringification (via the codec port in the application layer).
+*
+* The schema portion is serialized through the exact same path as `capture`
+* (`enrichLayoutWithFields` -> `SchemaSerializer.serialize`) so that the state
+* snapshot is round-trip compatible with the captured schema (ADR-007). The
+* top-level `revision` is added alongside the captured `layout`.
+*/
+const SchemaStateSerializer = { serialize: (state) => {
+	const enrichedLayout = enrichLayoutWithFields(state.schema.layout, state.schema.fields);
+	return {
+		revision: state.revision,
+		...SchemaSerializer.serialize(enrichedLayout, state.schema.fields)
+	};
+} };
+//#endregion
+//#region src/core/application/formSchema/schemaStateIo.ts
+/** Loads and parses the schema state, or returns undefined when none exists. */
+async function loadState(storage, codec) {
+	const result = await storage.get();
+	if (!result.exists) return;
+	const parsed = parseConfigText(codec, result.content, "Schema state");
+	return wrapBusinessRuleError(() => SchemaStateParser.parse(parsed));
+}
+/** Serializes and persists the schema state via the codec port. */
+async function saveState(storage, codec, revision, schema) {
+	const text = stringifyConfig(codec, SchemaStateSerializer.serialize({
+		revision,
+		schema
+	}));
+	await storage.update(text);
+}
+//#endregion
+//#region src/core/application/formSchema/loadThreeWayInputs.ts
+/**
+* Loads the three inputs of a 3-way schema sync: the base snapshot (state), the
+* local YAML schema, and the remote schema, plus the current remote revision.
+*
+* The remote schema is reconstructed via the same enrichment path as `capture`
+* so it compares like-with-like against base/local after normalization
+* (ADR-007). `getRevision` is read for the drift signal / expected revision but
+* never short-circuits snapshot fetching (ADR-004).
+*/
+async function loadThreeWayInputs(container) {
+	const [state, localResult, remoteFields, remoteLayout, remoteRevision] = await Promise.all([
+		loadState(container.schemaStateStorage, container.configCodec),
+		container.schemaStorage.get(),
+		container.formConfigurator.getFields(),
+		container.formConfigurator.getLayout(),
+		container.formConfigurator.getRevision()
+	]);
+	const local = localResult.exists ? parseSchemaText(container.configCodec, localResult.content) : void 0;
+	const enrichedRemoteLayout = enrichLayoutWithFields(remoteLayout, remoteFields);
+	return {
+		state,
+		local,
+		remote: Schema.create(remoteFields, enrichedRemoteLayout),
+		remoteRevision
+	};
+}
+//#endregion
+//#region src/core/application/formSchema/detectThreeWayDiff.ts
+function toEntry(entry, kind) {
+	const label = entry.local?.label ?? entry.remote?.label ?? entry.base?.label ?? "";
+	return {
+		fieldCode: entry.key,
+		fieldLabel: label,
+		kind
+	};
+}
+/**
+* Detects differences with 3-way awareness (AC-10, AC-11).
+*
+* When a state (base snapshot) exists, classifies changes into local-only,
+* remote drift, and conflicts. When no state exists, falls back to the existing
+* 2-way `detectDiff`.
+*/
+async function detectThreeWayDiff({ container }) {
+	const { state, local, remote } = await loadThreeWayInputs(container);
+	if (state === void 0 || local === void 0) return {
+		mode: "two-way",
+		diff: await detectDiff({ container })
+	};
+	const merge = computeThreeWayMerge(state.schema, local, remote);
+	const localChanges = [];
+	const remoteDrift = [];
+	const conflicts = [];
+	for (const entry of merge.fieldEntries) switch (entry.change.kind) {
+		case "localOnly":
+			localChanges.push(toEntry(entry, "localOnly"));
+			break;
+		case "remoteOnly":
+			remoteDrift.push(toEntry(entry, "remoteOnly"));
+			break;
+		case "conflict":
+			conflicts.push(toEntry(entry, "conflict"));
+			break;
+		default: break;
+	}
+	const enrichedBaseLayout = enrichLayoutWithFields(state.schema.layout, state.schema.fields);
+	const layoutLocalChanged = !isLayoutEqual(enrichedBaseLayout, merge.localLayout);
+	const layoutRemoteChanged = !isLayoutEqual(enrichedBaseLayout, merge.remoteLayout);
+	const isEmpty = localChanges.length === 0 && remoteDrift.length === 0 && conflicts.length === 0 && !layoutLocalChanged && !layoutRemoteChanged;
+	return {
+		mode: "three-way",
+		localChanges,
+		remoteDrift,
+		conflicts,
+		layoutLocalChanged,
+		layoutRemoteChanged,
+		layoutConflict: merge.layoutConflict,
+		isEmpty
+	};
+}
+//#endregion
 //#region src/cli/commands/schema/diff.ts
 async function runDiff(container) {
 	const s = p.spinner();
 	s.start("Comparing schema...");
 	let result;
 	try {
-		result = await detectDiff({ container });
+		result = await detectThreeWayDiff({ container });
 	} catch (error) {
 		s.stop("Comparison failed.");
 		throw error;
 	}
 	s.stop("Comparison complete.");
-	printDiffResult(result);
+	printThreeWayDiffResult(result);
 }
 var diff_default$2 = define({
 	name: "diff",
@@ -11052,6 +11615,317 @@ var override_default = define({
 	}
 });
 //#endregion
+//#region src/core/application/formSchema/pullSchema.ts
+function serializeSchema(container, schema) {
+	const enrichedLayout = enrichLayoutWithFields(schema.layout, schema.fields);
+	return stringifyConfig(container.configCodec, SchemaSerializer.serialize(enrichedLayout, schema.fields));
+}
+/**
+* First stage of `schema pull` (AC-4, AC-5, AC-6, AC-11).
+*
+* - `force`: returns the remote snapshot for local overwrite (capture-equiv).
+* - first run (no state): returns remote for one-way overwrite.
+* - otherwise: computes the 3-way merge and returns it for conflict resolution
+*   by the CLI. The local YAML / state are NOT written here — that happens in
+*   {@link applyPulledMerge} after resolution, so an aborted resolution leaves
+*   local and state untouched (AC-15).
+*
+* This stage never writes to the remote (pull is read-only against kintone).
+*/
+async function pullSchema({ container, input }) {
+	const { state, local, remote, remoteRevision } = await loadThreeWayInputs(container);
+	if (input.force) {
+		const schemaText = serializeSchema(container, remote);
+		await container.schemaStorage.update(schemaText);
+		await saveState(container.schemaStateStorage, container.configCodec, remoteRevision, remote);
+		return {
+			mode: "force",
+			schemaText
+		};
+	}
+	if (state === void 0 || local === void 0) {
+		const schemaText = serializeSchema(container, remote);
+		await container.schemaStorage.update(schemaText);
+		await saveState(container.schemaStateStorage, container.configCodec, remoteRevision, remote);
+		return {
+			mode: "firstTime",
+			schemaText
+		};
+	}
+	return {
+		mode: "merged",
+		merge: computeThreeWayMerge(state.schema, local, remote),
+		remoteRevision,
+		remoteSchema: remote
+	};
+}
+/**
+* Second stage of `schema pull`: applies a resolved 3-way merge.
+*
+* Writes the merged schema to the local YAML and updates the state to the
+* remote snapshot/revision. Called only after the CLI has fully resolved all
+* conflicts; if the user aborts resolution this is never invoked, so local and
+* state remain unchanged (AC-15).
+*/
+async function applyPulledMerge({ container, input }) {
+	const merged = wrapBusinessRuleError(() => resolveMerge(input.merge, input.resolution));
+	assertSchemaValid(merged);
+	const schemaText = serializeSchema(container, merged);
+	await container.schemaStorage.update(schemaText);
+	await saveState(container.schemaStateStorage, container.configCodec, input.remoteRevision, input.remoteSchema);
+	return { schemaText };
+}
+//#endregion
+//#region src/cli/commands/schema/pull.ts
+async function resolveConflicts(merge, options) {
+	const fields = /* @__PURE__ */ new Map();
+	for (const conflict of merge.fieldConflicts) {
+		let choice;
+		if (options.ours) choice = "local";
+		else if (options.theirs) choice = "remote";
+		else {
+			const selected = await p.select({
+				message: `Conflict on field "${conflict.key}". Keep which side?`,
+				options: [{
+					value: "local",
+					label: "local (ours)"
+				}, {
+					value: "remote",
+					label: "remote (theirs)"
+				}]
+			});
+			if (p.isCancel(selected)) return;
+			choice = selected;
+		}
+		fields.set(conflict.key, choice);
+	}
+	let layout = "noConflict";
+	if (merge.layoutConflict) if (options.ours) layout = "local";
+	else if (options.theirs) layout = "remote";
+	else {
+		const selected = await p.select({
+			message: "Conflict on layout. Keep which side?",
+			options: [{
+				value: "local",
+				label: "local (ours)"
+			}, {
+				value: "remote",
+				label: "remote (theirs)"
+			}]
+		});
+		if (p.isCancel(selected)) return;
+		layout = selected;
+	}
+	return {
+		fields,
+		layout
+	};
+}
+async function runPull(container, schemaFilePath, options) {
+	const s = p.spinner();
+	s.start("Pulling schema from kintone...");
+	const result = await pullSchema({
+		container,
+		input: { force: options.force }
+	});
+	s.stop("Schema pulled.");
+	if (result.mode === "force") {
+		p.log.success(`Local schema overwritten from remote: ${pc.cyan(schemaFilePath)}`);
+		return;
+	}
+	if (result.mode === "firstTime") {
+		p.log.warn("No base snapshot found. Initialized state from remote (one-way pull).");
+		p.log.success(`Local schema written: ${pc.cyan(schemaFilePath)}`);
+		return;
+	}
+	const { merge } = result;
+	if (!merge.hasConflict) {
+		await applyPulledMerge({
+			container,
+			input: {
+				merge,
+				resolution: {
+					fields: /* @__PURE__ */ new Map(),
+					layout: "noConflict"
+				},
+				remoteRevision: result.remoteRevision,
+				remoteSchema: result.remoteSchema
+			}
+		});
+		p.log.success(`Local schema merged and written: ${pc.cyan(schemaFilePath)}`);
+		return;
+	}
+	if (options.ours) p.log.info("Resolving all conflicts in favor of local (--ours).");
+	else if (options.theirs) p.log.info("Resolving all conflicts in favor of remote (--theirs).");
+	const resolution = await resolveConflicts(merge, options);
+	if (resolution === void 0) {
+		p.cancel("Pull cancelled. Local schema and state were left unchanged.");
+		return;
+	}
+	await applyPulledMerge({
+		container,
+		input: {
+			merge,
+			resolution,
+			remoteRevision: result.remoteRevision,
+			remoteSchema: result.remoteSchema
+		}
+	});
+	p.log.success(`Conflicts resolved. Local schema written: ${pc.cyan(schemaFilePath)}`);
+}
+var pull_default = define({
+	name: "pull",
+	description: "Pull remote form schema into the local schema file (3-way merge)",
+	args: {
+		...kintoneArgs,
+		...multiAppArgs,
+		force: {
+			type: "boolean",
+			description: "Overwrite local with remote (capture-equivalent)"
+		},
+		ours: {
+			type: "boolean",
+			description: "Resolve all conflicts in favor of local"
+		},
+		theirs: {
+			type: "boolean",
+			description: "Resolve all conflicts in favor of remote"
+		}
+	},
+	run: async (ctx) => {
+		try {
+			if (ctx.values.all === true) throw new ValidationError(ValidationErrorCode.InvalidInput, "schema pull does not support --all yet. Use --app <name> or a single app.");
+			const options = {
+				force: ctx.values.force === true,
+				ours: ctx.values.ours === true,
+				theirs: ctx.values.theirs === true
+			};
+			if (options.ours && options.theirs) throw new ValidationError(ValidationErrorCode.InvalidInput, "--ours and --theirs cannot be used together");
+			await routeMultiApp(ctx.values, {
+				singleLegacy: async () => {
+					const config = resolveConfig(ctx.values);
+					await runPull(createCliContainer(config), config.schemaFilePath, options);
+				},
+				singleApp: async (app, projectConfig) => {
+					const config = resolveAppCliConfig(app, projectConfig, ctx.values);
+					await runPull(createCliContainer(config), config.schemaFilePath, options);
+				},
+				multiApp: async () => {
+					throw new ValidationError(ValidationErrorCode.InvalidInput, "schema pull does not support --all yet. Use --app <name> or a single app.");
+				}
+			});
+		} catch (error) {
+			handleCliError(error);
+		}
+	}
+});
+//#endregion
+//#region src/core/application/formSchema/pushSchema.ts
+/** Message thrown when the remote drifted from base and `--force` was not set. */
+const PUSH_DRIFT_MESSAGE = "The remote has changed since the base snapshot. Run `schema pull` first.";
+/**
+* Applies the local schema to the remote with drift detection and optimistic
+* concurrency control (AC-7, AC-8, AC-9, AC-11, AC-14).
+*
+* - Reads the current revision (expected-revision source + drift signal) and
+*   the remote snapshot (drift judged by snapshot comparison, never skipped by
+*   revision — ADR-004).
+* - drift && !force → {@link ConflictError} tagged with `SchemaDrift` (drift
+*   distinguished from API optimistic-lock conflicts by error code — ADR-008).
+* - otherwise applies the local schema via the shared {@link applySchemaChanges}
+*   (type changes / subtable additions rejected with ValidationError — AC-13),
+*   sending the observed remote revision as the expected revision (ADR-005).
+* - `--force` skips the drift check and sends no expected revision.
+* - first run (no state): applies with no revision guard and initializes state.
+*
+* Deploy is performed by the CLI (single-path `confirmAndDeploy`). State records
+* the preview revision observed after applying.
+*/
+async function pushSchema({ container, input }) {
+	const { state, local, remote, remoteRevision } = await loadThreeWayInputs(container);
+	if (local === void 0) throw new ValidationError(ValidationErrorCode.InvalidInput, "Schema file not found");
+	assertSchemaValid(local);
+	const firstTime = state === void 0;
+	if (!firstTime && !input.force) {
+		const merge = computeThreeWayMerge(state.schema, local, remote);
+		const hasFieldDrift = merge.fieldEntries.some((e) => e.change.kind === "remoteOnly" || e.change.kind === "conflict");
+		const layoutDrift = !isLayoutEqual(enrichLayoutWithFields(state.schema.layout, state.schema.fields), merge.remoteLayout);
+		if (hasFieldDrift || layoutDrift) throw new ConflictError(ConflictErrorCode.SchemaDrift, PUSH_DRIFT_MESSAGE);
+	}
+	await applySchemaChanges(local, {
+		container,
+		expectedRevision: input.force || firstTime ? SKIP_REVISION_CHECK : remoteRevision
+	});
+	const newRevision = await container.formConfigurator.getRevision();
+	await saveState(container.schemaStateStorage, container.configCodec, newRevision, local);
+	return {
+		mode: firstTime ? "firstTime" : "push",
+		revision: newRevision
+	};
+}
+//#endregion
+//#region src/cli/commands/schema/push.ts
+const PUSH_TOCTOU_MESSAGE = "The remote changed while applying. Run `schema pull` and retry.";
+async function runPush(container, force, skipConfirm) {
+	if (!skipConfirm) {
+		const shouldContinue = await p.confirm({ message: force ? "Force-push local schema to kintone (overwrite remote)?" : "Push local schema to kintone?" });
+		if (p.isCancel(shouldContinue) || !shouldContinue) {
+			p.cancel("Push cancelled.");
+			return;
+		}
+	}
+	const s = p.spinner();
+	s.start("Pushing schema to kintone...");
+	let result;
+	try {
+		result = await pushSchema({
+			container,
+			input: { force }
+		});
+	} catch (error) {
+		s.stop("Push failed.");
+		if (isConflictError(error) && error.code !== ConflictErrorCode.SchemaDrift) throw new ConflictError(ConflictErrorCode.Conflict, PUSH_TOCTOU_MESSAGE, error);
+		throw error;
+	}
+	s.stop("Schema pushed to preview.");
+	if (result.mode === "firstTime") p.log.warn("No base snapshot found. Applied without drift guard and initialized state.");
+	p.log.success("Push completed successfully.");
+	await confirmAndDeploy([container], skipConfirm);
+}
+var push_default = define({
+	name: "push",
+	description: "Push the local schema file to kintone (with drift detection)",
+	args: {
+		...kintoneArgs,
+		...multiAppArgs,
+		...confirmArgs,
+		force: {
+			type: "boolean",
+			description: "Skip drift detection and overwrite remote"
+		}
+	},
+	run: async (ctx) => {
+		try {
+			if (ctx.values.all === true) throw new ValidationError(ValidationErrorCode.InvalidInput, "schema push does not support --all yet. Use --app <name> or a single app.");
+			const force = ctx.values.force === true;
+			const skipConfirm = ctx.values.yes === true;
+			await routeMultiApp(ctx.values, {
+				singleLegacy: async () => {
+					await runPush(createCliContainer(resolveConfig(ctx.values)), force, skipConfirm);
+				},
+				singleApp: async (app, projectConfig) => {
+					await runPush(createCliContainer(resolveAppCliConfig(app, projectConfig, ctx.values)), force, skipConfirm);
+				},
+				multiApp: async () => {
+					throw new ValidationError(ValidationErrorCode.InvalidInput, "schema push does not support --all yet. Use --app <name> or a single app.");
+				}
+			});
+		} catch (error) {
+			handleCliError(error);
+		}
+	}
+});
+//#endregion
 //#region src/core/application/container/validateCli.ts
 function createValidateCliContainer(config) {
 	return {
@@ -11169,7 +12043,9 @@ var schema_default = define({
 				}
 			}
 		}),
-		dump: dump_default
+		dump: dump_default,
+		pull: pull_default,
+		push: push_default
 	},
 	run: () => {}
 });