kintone-migrator 0.34.6 → 0.35.0

package/README.md

@@ -131,16 +131,23 @@ apps:
 | `guestSpaceId` | No | Guest space ID |
 | `dependsOn` | No | List of app names this app depends on |
 
-Multi-app CLI options (available on all commands):
+Multi-app CLI options (available on every command except `init`):
 
 | CLI Argument | Description |
 |---|---|
 | `--app <name>` | Target a specific app by name |
-| `--all` | Run all apps in dependency order |
+| `--all` | Run all apps in dependency order (not supported by `<domain> push` / `<domain> pull` — see below) |
 | `--config`, `-c` | Config file path (default: `kintone-migrator.yaml`) |
 
 Apps are executed in topological order based on `dependsOn`. Circular dependencies are detected and reported as errors. `--all` stops on first failure (fail-fast).
 
+The per-domain `push` / `pull` commands (`schema push`, `customize push`, `customize pull`, `view pull`, ...) only run one app at a time: they accept `--app <name>` but reject `--all` with a validation error. To run every app, use the top-level aggregate `push` / `pull` commands, which cover every domain across every app in dependency order:
+
+```bash
+kintone-migrator push --all --yes    # every domain, every app
+kintone-migrator pull --all          # every domain, every app
+```
+
 Configuration merge priority (high to low): CLI arguments > environment variables > app-level settings > top-level settings.
 
 #### File Path Resolution in Multi-App Mode
@@ -183,7 +190,7 @@ Commands are organized into domain groups:
 | `schema` | `override` | Overwrite entire form from schema |
 | `schema` | `capture` | _Deprecated — use `schema pull`._ Save current form schema to file |
 | `schema` | `validate` | Validate schema file locally |
-| `schema` | `dump` | Dump raw field/layout JSON (for debugging) |
+| `schema` | `dump` | Dump raw field/layout JSON (debugging / preview-vs-published check) |
 | `seed` | `push` | Upsert seed data records (plain upsert; no 3-way merge) |
 | `seed` | `apply` | _Deprecated alias for `seed push`._ |
 | `seed` | `capture` | Capture records from kintone app |
@@ -214,7 +221,9 @@ Commands are organized into domain groups:
 
 > **Deprecation notice:** the `apply`/`capture`/`migrate` commands above are deprecated in favor of their per-domain `push`/`pull` successors and will be removed in a future major version. The top-level `apply`/`capture` aggregate commands are likewise superseded by the top-level `push`/`pull` aggregate commands (which run every domain at once), not by any single `<domain> push`/`<domain> pull`. `push` writes to kintone (with a drift guard; use `--force` for the legacy overwrite behavior) and `pull` reads from kintone (with 3-way merge; `--force` for legacy overwrite). `seed` is out of scope for 3-way merge, so it has `seed push` but no `seed pull` — keep using `seed capture` to read records.
 
-All commands support `--app <name>` and `--all` for [multi-app mode](#multi-app-project-config). Commands that modify data (`schema push`, `schema override`, `seed push --clean`, `customize push`) support `--yes` / `-y` to skip confirmation prompts.
+Every command except `init` supports `--app <name>` for [multi-app mode](#multi-app-project-config). `--all` is supported by the `apply` / `capture` / `diff` / `migrate` commands, `seed push`, and the top-level aggregate `push` / `pull`, but **not** by the per-domain `push` / `pull` commands (`schema push`, `schema pull`, `customize push`, `customize pull`, `view push`, ...) — those reject `--all` with a validation error. Run the top-level `push` / `pull` with `--all` to cover every app instead.
+
+Commands that modify data (`schema push`, `schema override`, `seed push --clean`, `customize push`) support `--yes` / `-y` to skip confirmation prompts.
 
 ### `init` -- Project Initialization
 
@@ -249,13 +258,28 @@ Authentication settings are intentionally omitted from the generated config to a
 
 #### `schema diff`
 
-Detects differences between the schema file and the current kintone form.
+Detects differences between the schema file and the current kintone form. The output states which form generation the comparison used.
 
 ```bash
 kintone-migrator schema diff
 kintone-migrator schema diff --app customer
+kintone-migrator schema diff --published
 ```
 
+| Option | Description |
+|---|---|
+| `--published` | Compare against the published (deployed) form instead of the preview (unpublished) one. |
+
+Without `--published` the comparison is 3-way against the preview form: with a base snapshot it distinguishes local changes, remote drift, and conflicts.
+
+With `--published` the comparison is 2-way against the deployed form. The base snapshot is not used, so drift and conflicts are not detected -- "no changes" means only that the schema file matches what is currently published.
+
+This is the check to run after a deploy: if `schema diff --published` reports no changes, the schema file's contents are live on the published form.
+
+`--published` requires the app to have been deployed at least once. On an app that has never been deployed, the read fails with an error that identifies it as a published read and points at the likely cause. With `--all`, a single failing app stops the whole run (fail-fast) and the remaining apps are skipped.
+
+`--published` is accepted only by `schema dump` and `schema diff`. `schema pull`, `schema push`, `schema capture`, `schema migrate`, and `schema override` always target the preview generation, and passing `--published` to them is silently ignored.
+
 #### `schema migrate`
 
 > **Deprecated.** Use `schema push` (drift-guarded) or `schema push --force` (legacy overwrite) instead. `schema migrate` keeps working but will be removed in a future major version.
@@ -305,12 +329,53 @@ kintone-migrator schema validate -f my-schema.yaml
 
 #### `schema dump`
 
-Dumps raw kintone field definitions and layout as JSON. Outputs `fields.json` and `layout.json` (prefixed with app name in multi-app mode).
+Dumps raw kintone field definitions and layout as JSON. Outputs `fields.json` and `layout.json` (prefixed with app name in multi-app mode), or their `published-` counterparts with `--published`, so both generations can be dumped side by side and compared.
 
 ```bash
 kintone-migrator schema dump
+kintone-migrator schema dump --published
 ```
 
+| Option | Description |
+|---|---|
+| `--published` | Dump the published (deployed) form instead of the preview (unpublished) one. |
+
+With `--published` the output file names are prefixed with `published-`, so the two generations never overwrite each other: `published-fields.json` / `published-layout.json` (in multi-app mode, `<appName>-published-fields.json` / `<appName>-published-layout.json`).
+
+`--published` requires the app to have been deployed at least once. On an app that has never been deployed, the dump fails with an error that identifies it as a published read and points at the likely cause, and no file is written. With `--all`, a single failing app stops the whole run (fail-fast) and the remaining apps are skipped.
+
+`--published` is accepted only by `schema dump` and `schema diff`. `schema pull`, `schema push`, `schema capture`, `schema migrate`, and `schema override` always target the preview generation, and passing `--published` to them is silently ignored.
+
+Because the two dumps sit side by side, you can compare the preview form definition with the published one before pushing your own changes:
+
+```bash
+kintone-migrator schema dump              # fields.json / layout.json (preview)
+kintone-migrator schema dump --published  # published-fields.json / published-layout.json
+
+# revision can differ between generations, so exclude it from the comparison
+diff -I '"revision"' fields.json published-fields.json
+diff -I '"revision"' layout.json published-layout.json
+```
+
+In a multi-app project (a `kintone-migrator.yaml` is present), add `--app <name>` to both dumps -- with none of `--app`, `--all`, or `--app-id` the command only lists the available apps and writes no files. With `--app <name>` the output file names are prefixed with the app name (`--app-id` bypasses the project config and keeps the unprefixed names):
+
+```bash
+kintone-migrator schema dump --app customer              # customer-fields.json / customer-layout.json
+kintone-migrator schema dump --app customer --published  # customer-published-fields.json / customer-published-layout.json
+
+diff -I '"revision"' customer-fields.json customer-published-fields.json
+diff -I '"revision"' customer-layout.json customer-published-layout.json
+```
+
+The `-I '"revision"'` exclusion is needed because `dump` saves the kintone response as-is: both `fields.json` and `layout.json` carry a top-level `revision`, and its value can differ between the preview and published generations even when the form contents are identical. If the comparison reports differences other than `revision` -- for example the same fields serialized in a different key order -- normalize both files before comparing:
+
+```bash
+diff <(jq -S 'del(.revision)' fields.json) <(jq -S 'del(.revision)' published-fields.json)
+diff <(jq -S 'del(.revision)' layout.json) <(jq -S 'del(.revision)' published-layout.json)
+```
+
+No differences means the form definition in preview matches the one that is published. It does not mean that a deploy is safe in general: deploying publishes **all** pending preview settings for the app -- views, notifications, process management, the various permission settings, plugins, general settings -- while this check covers the form definition only. Someone else's undeployed work in those other areas would still go live.
+
 ### `seed` -- Seed Data Management
 
 #### `seed push`
@@ -344,6 +409,8 @@ kintone-migrator seed capture --key-field customer_code
 
 ### `customize` -- JS/CSS Customization
 
+> **Note:** `customize push` / `customize pull` handle one app per run — they accept `--app <name>` but reject `--all`. To apply customizations to every app at once, use the top-level aggregate `push` / `pull` (`kintone-migrator push --all --yes`), which runs every domain for every app in dependency order. The deprecated `customize apply` / `customize capture` still accept `--all`.
+
 #### `customize apply`
 
 > **Deprecated.** Use `customize push` instead (and `customize pull` in place of `customize capture`). The legacy commands keep working but will be removed in a future major version.

package/dist/index.mjs

@@ -1324,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) {
@@ -1677,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) {
@@ -1684,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;
@@ -1701,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() {
@@ -1764,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) {
@@ -2706,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.");
@@ -9172,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);
@@ -17736,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.");
 				}
 			});
@@ -17781,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]);
 		}
 	}
 };
@@ -17844,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);
@@ -17874,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);
@@ -17884,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) => {
@@ -17896,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.");
 				}
 			});