kintone-migrator 0.12.2 → 0.12.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +183 -378
  2. package/dist/index.mjs +973 -902
  3. package/package.json +37 -11
package/README.md CHANGED
@@ -1,269 +1,270 @@
1
1
  # kintone-migrator
2
2
 
3
- A CLI tool for migrating kintone form schemas, seed data, JS/CSS customizations, and field access permissions.
3
+ A CLI tool for managing kintone apps as code -- form schemas, seed data, JS/CSS customizations, and field access permissions.
4
4
 
5
- Compares a YAML-defined schema file against an actual kintone app form, providing diff detection, migration, schema capture, seed data management, JS/CSS customization, field ACL management, and more.
6
-
7
- ## Installation
5
+ ## Quick Start
8
6
 
9
7
  ```bash
8
+ # Install
10
9
  npm install -g kintone-migrator
10
+
11
+ # Set up environment
12
+ export KINTONE_DOMAIN=example.cybozu.com
13
+ export KINTONE_USERNAME=your_username
14
+ export KINTONE_PASSWORD=your_password
15
+ export KINTONE_APP_ID=123
16
+
17
+ # Capture current form schema
18
+ kintone-migrator schema capture -f schema.yaml
19
+
20
+ # Edit schema.yaml, then check diff
21
+ kintone-migrator schema diff
22
+
23
+ # Apply changes
24
+ kintone-migrator schema migrate
11
25
  ```
12
26
 
13
27
  Requires Node.js 22 or later.
14
28
 
15
29
  ## Configuration
16
30
 
17
- Connection details for kintone can be specified via CLI arguments or environment variables. CLI arguments take precedence.
31
+ ### Authentication
32
+
33
+ Two methods are supported (API Token takes priority if both are set):
18
34
 
19
- ### kintone Connection
35
+ - **API Token** (`KINTONE_API_TOKEN`): Recommended. Multiple tokens can be comma-separated (e.g., `token1,token2`).
36
+ - **Username/Password** (`KINTONE_USERNAME` / `KINTONE_PASSWORD`): Basic authentication.
37
+
38
+ ### Connection Options
20
39
 
21
40
  | CLI Argument | Environment Variable | Description |
22
- |---------|----------|------|
41
+ |---|---|---|
23
42
  | `--domain`, `-d` | `KINTONE_DOMAIN` | kintone domain (e.g., `example.cybozu.com`) |
24
- | `--api-token`, `-t` | `KINTONE_API_TOKEN` | kintone API token |
25
- | `--username`, `-u` | `KINTONE_USERNAME` | kintone username |
26
- | `--password`, `-p` | `KINTONE_PASSWORD` | kintone password |
27
- | `--app-id`, `-a` | `KINTONE_APP_ID` | kintone app ID |
28
- | `--guest-space-id`, `-g` | `KINTONE_GUEST_SPACE_ID` | kintone guest space ID |
43
+ | `--api-token`, `-t` | `KINTONE_API_TOKEN` | API token |
44
+ | `--username`, `-u` | `KINTONE_USERNAME` | Username |
45
+ | `--password`, `-p` | `KINTONE_PASSWORD` | Password |
46
+ | `--app-id`, `-a` | `KINTONE_APP_ID` | App ID |
47
+ | `--guest-space-id`, `-g` | `KINTONE_GUEST_SPACE_ID` | Guest space ID |
29
48
  | `--schema-file`, `-f` | `SCHEMA_FILE_PATH` | Schema file path (default: `schema.yaml`) |
30
49
 
31
- ### Multi-App Options
50
+ CLI arguments take precedence over environment variables.
32
51
 
33
- These options are available on **all commands** (diff, migrate, override, capture, dump, validate, seed, customize, field-acl, capture-field-acl) and enable multi-app mode via a project config file.
52
+ ### .env File
34
53
 
35
- | CLI Argument | Description |
36
- |---------|------|
37
- | `--app <name>` | Target a specific app by name (from project config) |
38
- | `--all` | Run all apps in dependency order |
39
- | `--config`, `-c` | Project config file path (default: `kintone-migrator.yaml`) |
54
+ Environment variables can be defined in a `.env` file and loaded with `dotenv-cli` or similar tools.
40
55
 
41
- **Mutual exclusion rules:**
56
+ ```env
57
+ KINTONE_DOMAIN=example.cybozu.com
58
+ KINTONE_USERNAME=your_username
59
+ KINTONE_PASSWORD=your_password
60
+ KINTONE_APP_ID=123
61
+ SCHEMA_FILE_PATH=schema.yaml
62
+ ```
42
63
 
43
- - `--app` and `--all` cannot be used together
44
- - `--app-id` and `--app` cannot be used together
45
- - `--app-id` and `--all` cannot be used together
64
+ ### Multi-App Project Config
46
65
 
47
- ### Authentication
66
+ For managing multiple apps, create a project config file (`kintone-migrator.yaml`):
48
67
 
49
- Two authentication methods are supported:
68
+ ```yaml
69
+ domain: example.cybozu.com
70
+ auth:
71
+ apiToken: "shared-token"
50
72
 
51
- - **API Token** (`KINTONE_API_TOKEN`): Recommended. Scoped per app for better security. Multiple tokens can be specified as a comma-separated string (e.g., `token1,token2`).
52
- - **Username/Password** (`KINTONE_USERNAME` / `KINTONE_PASSWORD`): Basic authentication with user credentials.
73
+ apps:
74
+ customer:
75
+ appId: "10"
76
+ schemaFile: schemas/customer.yaml
77
+ seedFile: seeds/customer.yaml
78
+ order:
79
+ appId: "20"
80
+ schemaFile: schemas/order.yaml
81
+ dependsOn:
82
+ - customer
83
+ ```
53
84
 
54
- If both are provided, API Token takes priority. At least one method must be configured.
85
+ | Field | Required | Description |
86
+ |---|---|---|
87
+ | `appId` | Yes | kintone app ID |
88
+ | `schemaFile` | No | Schema file path (default: `schemas/<appName>.yaml`) |
89
+ | `seedFile` | No | Seed file path (default: `seeds/<appName>.yaml`) |
90
+ | `domain` | No | Override top-level domain |
91
+ | `auth` | No | Override top-level authentication |
92
+ | `guestSpaceId` | No | Guest space ID |
93
+ | `dependsOn` | No | List of app names this app depends on |
55
94
 
56
- ### .env File
95
+ Multi-app CLI options (available on all commands):
57
96
 
58
- Environment variables can also be defined in a `.env` file and loaded with `dotenv-cli` or similar tools.
97
+ | CLI Argument | Description |
98
+ |---|---|
99
+ | `--app <name>` | Target a specific app by name |
100
+ | `--all` | Run all apps in dependency order |
101
+ | `--config`, `-c` | Config file path (default: `kintone-migrator.yaml`) |
59
102
 
60
- ```env
61
- KINTONE_DOMAIN=example.cybozu.com
103
+ Apps are executed in topological order based on `dependsOn`. Circular dependencies are detected and reported as errors. `--all` stops on first failure (fail-fast).
62
104
 
63
- # Authentication: Use either API Token or Username/Password (API Token takes priority)
64
- # KINTONE_API_TOKEN=your_api_token
65
- KINTONE_USERNAME=your_username
66
- KINTONE_PASSWORD=your_password
105
+ Configuration merge priority (high to low): CLI arguments > environment variables > app-level settings > top-level settings.
67
106
 
68
- KINTONE_APP_ID=123
69
- # KINTONE_GUEST_SPACE_ID=456
70
- SCHEMA_FILE_PATH=schema.yaml
71
- ```
107
+ For details, see [Project Config Specification](./spec/projectConfig.md).
72
108
 
73
109
  ## Commands
74
110
 
75
- ### `diff`
111
+ Commands are organized into domain groups:
76
112
 
77
- Detects differences between the schema file and the current kintone form.
113
+ | Group | Subcommand | Description |
114
+ |---|---|---|
115
+ | `schema` | `diff` | Show differences between schema file and kintone form |
116
+ | `schema` | `migrate` | Apply schema changes (incremental) |
117
+ | `schema` | `override` | Overwrite entire form from schema |
118
+ | `schema` | `capture` | Save current form schema to file |
119
+ | `schema` | `validate` | Validate schema file locally |
120
+ | `schema` | `dump` | Dump raw field/layout JSON (for debugging) |
121
+ | `seed` | `apply` | Apply seed data records |
122
+ | `seed` | `capture` | Capture records from kintone app |
123
+ | `customize` | `apply` | Apply JS/CSS customizations |
124
+ | `field-acl` | `apply` | Apply field access permissions |
125
+ | `field-acl` | `capture` | Save current field permissions to file |
78
126
 
79
- ```bash
80
- kintone-migrator diff
81
- kintone-migrator diff -d example.cybozu.com -a 123
127
+ All commands support `--app <name>` and `--all` for [multi-app mode](#multi-app-project-config). Commands that modify data (`schema migrate`, `schema override`, `seed apply --clean`, `customize apply`) support `--yes` / `-y` to skip confirmation prompts.
82
128
 
83
- # Multi-app mode
84
- kintone-migrator diff --app customer
85
- kintone-migrator diff --all
86
- ```
129
+ ### `schema` -- Form Schema Management
87
130
 
88
- ### `migrate`
131
+ #### `schema diff`
89
132
 
90
- Applies schema file changes to the kintone form. Displays the diff and prompts for confirmation before execution. Only detected differences are applied (add, update, delete).
133
+ Detects differences between the schema file and the current kintone form.
91
134
 
92
135
  ```bash
93
- kintone-migrator migrate
94
-
95
- # Skip confirmation prompts (for CI/CD)
96
- kintone-migrator migrate --yes
97
- kintone-migrator migrate -y
98
-
99
- # Multi-app mode
100
- kintone-migrator migrate --app customer
101
- kintone-migrator migrate --all
102
- kintone-migrator migrate --all --yes
136
+ kintone-migrator schema diff
137
+ kintone-migrator schema diff --app customer
103
138
  ```
104
139
 
105
- ### `override`
140
+ #### `schema migrate`
106
141
 
107
- Overwrites the entire kintone form with the schema file contents. Fields not defined in the schema will be deleted.
142
+ Applies only the detected differences (add, update, delete) to the kintone form.
108
143
 
109
144
  ```bash
110
- kintone-migrator override
145
+ kintone-migrator schema migrate
146
+ kintone-migrator schema migrate --yes # Skip confirmation (for CI/CD)
147
+ kintone-migrator schema migrate --all --yes # All apps
148
+ ```
111
149
 
112
- # Skip confirmation prompts (for CI/CD)
113
- kintone-migrator override --yes
114
- kintone-migrator override -y
150
+ #### `schema override`
115
151
 
116
- # Reset form: delete all custom fields (no schema file needed)
117
- kintone-migrator override --reset
152
+ Overwrites the entire kintone form with the schema file. Fields not in the schema are deleted.
118
153
 
119
- # Multi-app mode
120
- kintone-migrator override --all
121
- kintone-migrator override --reset --all
122
- kintone-migrator override --all --yes
154
+ ```bash
155
+ kintone-migrator schema override
156
+ kintone-migrator schema override --reset # Delete all custom fields (no schema needed)
157
+ kintone-migrator schema override --all --yes
123
158
  ```
124
159
 
125
- #### Override-specific arguments
160
+ | Option | Description |
161
+ |---|---|
162
+ | `--reset` | Delete all custom fields. In multi-app mode, apps are reset in reverse dependency order. |
163
+ | `--yes`, `-y` | Skip confirmation prompts. |
126
164
 
127
- | CLI Argument | Description |
128
- |---------|------|
129
- | `--reset` | Reset form by deleting all custom fields. Cannot be used with `--schema-file`. In multi-app mode (`--all`), apps are reset in reverse dependency order. |
130
- | `--yes`, `-y` | Skip confirmation prompts. Also available on `migrate`. |
131
-
132
- ### `capture`
165
+ #### `schema capture`
133
166
 
134
- Saves the current kintone form schema to a file.
167
+ Saves the current kintone form schema to a YAML file.
135
168
 
136
169
  ```bash
137
- kintone-migrator capture
138
- kintone-migrator capture -f my-schema.yaml
139
-
140
- # Multi-app mode
141
- kintone-migrator capture --app customer
142
- kintone-migrator capture --all
170
+ kintone-migrator schema capture
171
+ kintone-migrator schema capture -f my-schema.yaml
143
172
  ```
144
173
 
145
- ### `dump`
174
+ #### `schema validate`
146
175
 
147
- Dumps kintone form field definitions and layout in JSON format. For debugging purposes.
176
+ Validates the schema file locally without connecting to kintone.
148
177
 
149
178
  ```bash
150
- kintone-migrator dump
151
-
152
- # Multi-app mode
153
- kintone-migrator dump --app customer
154
- kintone-migrator dump --all
179
+ kintone-migrator schema validate
180
+ kintone-migrator schema validate -f my-schema.yaml
155
181
  ```
156
182
 
157
- `fields.json` and `layout.json` will be output to the current directory. In multi-app mode, files are prefixed with the app name (e.g., `customer_fields.json`).
183
+ #### `schema dump`
158
184
 
159
- ### `validate`
160
-
161
- Validates the schema file locally without connecting to kintone. Checks for structural issues such as empty labels, missing selection options, invalid lookup configurations, and more.
185
+ Dumps raw kintone field definitions and layout as JSON. Outputs `fields.json` and `layout.json` (prefixed with app name in multi-app mode).
162
186
 
163
187
  ```bash
164
- kintone-migrator validate
165
- kintone-migrator validate -f my-schema.yaml
166
-
167
- # Multi-app mode
168
- kintone-migrator validate --app customer
169
- kintone-migrator validate --all
188
+ kintone-migrator schema dump
170
189
  ```
171
190
 
172
- ### `seed`
191
+ ### `seed` -- Seed Data Management
173
192
 
174
- Applies seed data (records) to a kintone app using upsert (insert or update based on a key field). Can also capture existing records from an app to a seed file.
193
+ #### `seed apply`
194
+
195
+ Upserts seed data records into a kintone app.
175
196
 
176
197
  ```bash
177
- # Apply seed data to a single app
178
- kintone-migrator seed
179
- kintone-migrator seed -s my-seed.yaml
180
-
181
- # Clean apply: delete all existing records, then apply seed data
182
- kintone-migrator seed --clean
183
- kintone-migrator seed --clean --yes
184
-
185
- # Capture records from a kintone app
186
- kintone-migrator seed --capture --key-field customer_code
187
- kintone-migrator seed --capture --key-field customer_code -s seeds/customer.yaml
188
-
189
- # Multi-app mode
190
- kintone-migrator seed --all
191
- kintone-migrator seed --clean --all --yes
192
- kintone-migrator seed --capture --key-field code --all
193
- kintone-migrator seed --app customer
198
+ kintone-migrator seed apply # Apply seed data
199
+ kintone-migrator seed apply --clean --yes # Delete all records first
194
200
  ```
195
201
 
196
- #### Seed-specific arguments
197
-
198
- | CLI Argument | Description |
199
- |---------|------|
200
- | `--capture` | Capture mode: fetch records from kintone and save to seed file |
201
- | `--clean` | Delete all existing records before applying seed data. Cannot be used with `--capture`. Prompts for confirmation unless `--yes` is specified. |
202
- | `--key-field`, `-k` | Key field code for upsert (required for `--capture`) |
202
+ | Option | Description |
203
+ |---|---|
203
204
  | `--seed-file`, `-s` | Seed file path (default: `seed.yaml`) |
204
- | `--yes`, `-y` | Skip confirmation prompts (for `--clean` mode) |
205
+ | `--key-field`, `-k` | Key field code for upsert |
206
+ | `--clean` | Delete all records before applying. |
207
+ | `--yes`, `-y` | Skip confirmation prompts (for `--clean` mode). |
205
208
 
206
- ### `customize`
209
+ #### `seed capture`
207
210
 
208
- Applies JS/CSS customization to a kintone app from a YAML config file. Local files are uploaded and merged with existing customization settings. Files not in the config are preserved. After applying, prompts for deployment to production.
211
+ Captures existing records from a kintone app and saves them to a seed file.
209
212
 
210
213
  ```bash
211
- kintone-migrator customize
212
- kintone-migrator customize --customize-file my-customize.yaml
214
+ kintone-migrator seed capture --key-field customer_code
215
+ ```
216
+
217
+ | Option | Description |
218
+ |---|---|
219
+ | `--seed-file`, `-s` | Seed file path (default: `seed.yaml`) |
220
+ | `--key-field`, `-k` | Key field code (required) |
213
221
 
214
- # Skip confirmation prompts (for CI/CD)
215
- kintone-migrator customize --yes
222
+ ### `customize` -- JS/CSS Customization
216
223
 
217
- # Multi-app mode
218
- kintone-migrator customize --app customer
219
- kintone-migrator customize --all
220
- kintone-migrator customize --all --yes
224
+ #### `customize apply`
225
+
226
+ Applies JS/CSS customizations from a YAML config file. Local files are uploaded and merged with existing settings.
227
+
228
+ ```bash
229
+ kintone-migrator customize apply
230
+ kintone-migrator customize apply --customize-file my-customize.yaml
231
+ kintone-migrator customize apply --all --yes
221
232
  ```
222
233
 
223
- #### Customize-specific arguments
234
+ | Option | Environment Variable | Description |
235
+ |---|---|---|
236
+ | `--customize-file` | `CUSTOMIZE_FILE_PATH` | Config file path (default: `customize.yaml`, multi-app: `customize/<appName>.yaml`) |
237
+ | `--yes`, `-y` | -- | Skip confirmation prompts. |
224
238
 
225
- | CLI Argument | Environment Variable | Description |
226
- |---------|----------|------|
227
- | `--customize-file` | `CUSTOMIZE_FILE_PATH` | Customization config file path (default: `customize.yaml`, multi-app: `customize/<appName>.yaml`) |
228
- | `--yes`, `-y` | — | Skip confirmation prompts |
239
+ ### `field-acl` -- Field Access Permissions
229
240
 
230
- ### `field-acl`
241
+ #### `field-acl apply`
231
242
 
232
- Applies field access permissions from a YAML config file to a kintone app. Uses full replacement — the YAML file defines the complete desired state.
243
+ Applies field access permissions from a YAML config file. Uses full replacement -- the file defines the complete desired state.
233
244
 
234
245
  ```bash
235
- kintone-migrator field-acl
236
- kintone-migrator field-acl --field-acl-file my-field-acl.yaml
237
-
238
- # Multi-app mode
239
- kintone-migrator field-acl --app customer
240
- kintone-migrator field-acl --all
246
+ kintone-migrator field-acl apply
247
+ kintone-migrator field-acl apply --field-acl-file my-field-acl.yaml
241
248
  ```
242
249
 
243
- #### Field ACL-specific arguments
244
-
245
- | CLI Argument | Environment Variable | Description |
246
- |---------|----------|------|
250
+ | Option | Environment Variable | Description |
251
+ |---|---|---|
247
252
  | `--field-acl-file` | `FIELD_ACL_FILE_PATH` | Field ACL file path (default: `field-acl.yaml`, multi-app: `field-acl/<appName>.yaml`) |
248
253
 
249
- ### `capture-field-acl`
254
+ #### `field-acl capture`
250
255
 
251
- Captures the current field access permissions from a kintone app and saves them to a YAML file.
256
+ Captures the current field access permissions and saves them to a YAML file. Uses the same `--field-acl-file` option as `field-acl apply`.
252
257
 
253
258
  ```bash
254
- kintone-migrator capture-field-acl
255
- kintone-migrator capture-field-acl --field-acl-file my-field-acl.yaml
256
-
257
- # Multi-app mode
258
- kintone-migrator capture-field-acl --app customer
259
- kintone-migrator capture-field-acl --all
259
+ kintone-migrator field-acl capture
260
+ kintone-migrator field-acl capture --field-acl-file my-field-acl.yaml
260
261
  ```
261
262
 
262
- Uses the same `--field-acl-file` argument as `field-acl`.
263
+ ## File Formats
263
264
 
264
- ## Schema File
265
+ ### Schema File
265
266
 
266
- Schema files define the desired kintone form configuration in YAML format. The `layout` key at the root describes form rows, groups, subtables, and field definitions.
267
+ Defines the desired kintone form configuration. The `layout` key describes form rows, groups, subtables, and fields.
267
268
 
268
269
  ```yaml
269
270
  layout:
@@ -278,7 +279,6 @@ layout:
278
279
  - type: GROUP
279
280
  code: detail_group
280
281
  label: 詳細情報
281
- openGroup: true
282
282
  layout:
283
283
  - type: ROW
284
284
  fields:
@@ -288,78 +288,16 @@ layout:
288
288
  size: { width: "400" }
289
289
  ```
290
290
 
291
- ### Lookup Fields
291
+ Supported field types: `SINGLE_LINE_TEXT`, `MULTI_LINE_TEXT`, `RICH_TEXT`, `NUMBER`, `CALC`, `CHECK_BOX`, `RADIO_BUTTON`, `MULTI_SELECT`, `DROP_DOWN`, `DATE`, `TIME`, `DATETIME`, `LINK`, `USER_SELECT`, `ORGANIZATION_SELECT`, `GROUP_SELECT`, `FILE`, `GROUP`, `SUBTABLE`, `REFERENCE_TABLE`
292
292
 
293
- `SINGLE_LINE_TEXT`, `NUMBER`, and `LINK` fields can be configured as lookup fields by adding a `lookup` property. Lookups are not a separate field type in kintone; they are a property of these field types.
293
+ Lookup fields and reference tables are also supported. For details, see:
294
294
 
295
- ```yaml
296
- - code: customer_code
297
- type: SINGLE_LINE_TEXT
298
- label: 顧客コード
299
- size: { width: "200" }
300
- lookup:
301
- relatedApp: { app: "10" }
302
- relatedKeyField: code
303
- fieldMappings:
304
- - { field: customer_name, relatedField: name }
305
- - { field: email, relatedField: contact_email }
306
- lookupPickerFields: [code, name, contact_email]
307
- filterCond: 'status in ("active")'
308
- sort: "code asc"
309
- ```
310
-
311
- ### Reference Tables
295
+ - [Schema Specification](./spec/schema.md) -- format reference, all field types, and validation rules
296
+ - [Sample Schema (YAML)](./spec/sample_schema.yaml) / [JSON](./spec/sample_schema.json) -- comprehensive examples
312
297
 
313
- `REFERENCE_TABLE` fields display related records from another app.
314
-
315
- ```yaml
316
- - code: related_orders
317
- type: REFERENCE_TABLE
318
- label: 関連注文
319
- size: { width: "600" }
320
- referenceTable:
321
- relatedApp: { app: "42" }
322
- condition: { field: customer_name, relatedField: name }
323
- filterCond: 'status in ("active")'
324
- displayFields: [name, email, phone]
325
- sort: "name asc"
326
- size: "5"
327
- ```
298
+ ### Seed Data File
328
299
 
329
- ### Supported Field Types
330
-
331
- | Type | Description |
332
- |------|-------------|
333
- | `SINGLE_LINE_TEXT` | Single-line text |
334
- | `MULTI_LINE_TEXT` | Multi-line text |
335
- | `RICH_TEXT` | Rich text editor |
336
- | `NUMBER` | Number |
337
- | `CALC` | Calculated field |
338
- | `CHECK_BOX` | Checkbox (multi-select) |
339
- | `RADIO_BUTTON` | Radio button (single-select) |
340
- | `MULTI_SELECT` | Multi-select |
341
- | `DROP_DOWN` | Dropdown (single-select) |
342
- | `DATE` | Date |
343
- | `TIME` | Time |
344
- | `DATETIME` | Date and time |
345
- | `LINK` | Link (URL, phone, email) |
346
- | `USER_SELECT` | User selection |
347
- | `ORGANIZATION_SELECT` | Organization selection |
348
- | `GROUP_SELECT` | Group selection |
349
- | `FILE` | File attachment |
350
- | `GROUP` | Field group (collapsible) |
351
- | `SUBTABLE` | Subtable |
352
- | `REFERENCE_TABLE` | Reference table |
353
-
354
- For the full specification and all supported field types, see:
355
-
356
- - [Schema Specification](./spec/schema.md) — format reference for all field types, layout items, decoration elements, and validation rules
357
- - [Sample Schema (YAML)](./spec/sample_schema.yaml) — comprehensive example covering all field types
358
- - [Sample Schema (JSON)](./spec/sample_schema.json) — equivalent example in JSON format
359
-
360
- ## Seed Data File
361
-
362
- Seed data files define records to be upserted into a kintone app. The `key` field specifies which field to use for matching existing records (must have the "Prohibit duplicate values" setting enabled in kintone).
300
+ Defines records to upsert into a kintone app. The `key` field specifies which field to match on (must have "Prohibit duplicate values" enabled).
363
301
 
364
302
  ```yaml
365
303
  key: customer_code
@@ -370,37 +308,13 @@ records:
370
308
  tags:
371
309
  - "VIP"
372
310
  - "long-term"
373
- assignee:
374
- - code: "user1"
375
- start_date: "2025-01-15"
376
- order_items:
377
- - product_name: "Product A"
378
- quantity: "1"
379
- price: "1000"
380
311
  ```
381
312
 
382
- ### Seed Field Value Types
383
-
384
- | kintone Field Type | YAML Representation | Example |
385
- |------|-------------|---------|
386
- | `SINGLE_LINE_TEXT`, `MULTI_LINE_TEXT`, `RICH_TEXT` | string | `"text"` |
387
- | `NUMBER` | string | `"1000"` |
388
- | `RADIO_BUTTON`, `DROP_DOWN` | string | `"high"` |
389
- | `CHECK_BOX`, `MULTI_SELECT` | string[] | `["VIP", "long-term"]` |
390
- | `DATE` | string (YYYY-MM-DD) | `"2025-01-15"` |
391
- | `TIME` | string (HH:mm) | `"09:00"` |
392
- | `DATETIME` | string (ISO 8601) | `"2025-01-15T09:00:00Z"` |
393
- | `LINK` | string | `"https://example.com"` |
394
- | `USER_SELECT`, `ORGANIZATION_SELECT`, `GROUP_SELECT` | object[] with `code` | `[{code: "user1"}]` |
395
- | `SUBTABLE` | object[] | `[{field1: "val1"}]` |
396
-
397
- For the full specification, see:
398
-
399
- - [Seed Data Specification](./spec/seed.md) — format reference, field type mappings, and validation rules
313
+ For field type mappings and details, see [Seed Data Specification](./spec/seed.md).
400
314
 
401
- ## Customization Config File
315
+ ### Customization Config File
402
316
 
403
- Customization config files define JS/CSS resources to apply to a kintone app. Resources can be local files or external URLs. The merge strategy preserves existing resources not defined in the config.
317
+ Defines JS/CSS resources to apply to a kintone app. Existing resources not in the config are preserved.
404
318
 
405
319
  ```yaml
406
320
  scope: ALL
@@ -417,32 +331,13 @@ mobile:
417
331
  js:
418
332
  - type: FILE
419
333
  path: ./dist/mobile.js
420
- css: []
421
334
  ```
422
335
 
423
- | Field | Required | Description |
424
- |-------|----------|-------------|
425
- | `scope` | No | Customization scope: `ALL` (all users), `ADMIN` (admins only), `NONE` (disabled). Omit to keep current scope. |
426
- | `desktop` | Yes | Desktop platform JS/CSS configuration |
427
- | `mobile` | No | Mobile platform JS/CSS configuration (defaults to empty if omitted) |
428
-
429
- Each resource in `js` / `css` arrays has:
430
-
431
- | Field | Description |
432
- |-------|-------------|
433
- | `type: FILE` + `path` | Local file to upload (relative to config file directory) |
434
- | `type: URL` + `url` | External URL resource |
435
-
436
- Each category (desktop.js, desktop.css, mobile.js, mobile.css) supports up to 30 resources.
437
-
438
- For the full specification, see:
336
+ For details, see [Customization Specification](./spec/domains/customization.md).
439
337
 
440
- - [Customization Domain Specification](./spec/domains/customization.md) — domain model, config format, and merge strategy
441
- - [Customization Use Case Specification](./spec/usecases/customization.md) — use case details and test cases
338
+ ### Field ACL File
442
339
 
443
- ## Field ACL File
444
-
445
- Field ACL files define field-level access permissions in YAML format. The file represents the complete desired state — all permissions are replaced on apply.
340
+ Defines field-level access permissions. The file represents the complete desired state -- all permissions are replaced on apply.
446
341
 
447
342
  ```yaml
448
343
  rights:
@@ -463,97 +358,7 @@ rights:
463
358
  code: general_staff
464
359
  ```
465
360
 
466
- | Field | Description |
467
- |-------|-------------|
468
- | `rights` | List of field permission rules |
469
- | `rights[].code` | Field code to set permissions for |
470
- | `rights[].entities` | List of permission entries for this field |
471
- | `entities[].accessibility` | Access level: `READ`, `WRITE`, or `NONE` |
472
- | `entities[].entity.type` | Entity type: `USER`, `GROUP`, `ORGANIZATION`, or `FIELD_ENTITY` |
473
- | `entities[].entity.code` | Entity identifier (username, group code, etc.) |
474
- | `entities[].includeSubs` | Include sub-organizations/sub-groups (optional) |
475
-
476
- For the full specification, see:
477
-
478
- - [FieldPermission Domain Specification](./spec/domains/fieldPermission.md) — domain model, config format, and serialization
479
- - [FieldPermission Use Case Specification](./spec/usecases/fieldPermission.md) — use case details and test cases
480
-
481
- ## Multi-App Project Config
482
-
483
- A project config file (`kintone-migrator.yaml`) enables managing multiple kintone apps with dependency ordering. All commands (diff, migrate, override, capture, dump, validate, seed, customize, field-acl, capture-field-acl) support multi-app mode.
484
-
485
- ```yaml
486
- # Shared connection settings (can be overridden per app)
487
- # domain can also be set via KINTONE_DOMAIN env var or --domain CLI arg
488
- domain: example.cybozu.com
489
- auth:
490
- apiToken: "shared-token"
491
- # guestSpaceId: "456"
492
-
493
- # App definitions
494
- apps:
495
- customer:
496
- appId: "10"
497
- schemaFile: schemas/customer.yaml
498
- seedFile: seeds/customer.yaml
499
- order:
500
- appId: "20"
501
- schemaFile: schemas/order.yaml
502
- seedFile: seeds/order.yaml
503
- dependsOn:
504
- - customer
505
- invoice:
506
- appId: "30"
507
- dependsOn:
508
- - order
509
- - customer
510
- ```
511
-
512
- ### App Configuration Fields
513
-
514
- | Field | Required | Description |
515
- |-------|----------|-------------|
516
- | `appId` | Yes | kintone app ID |
517
- | `schemaFile` | No | Schema file path (default: `schemas/<appName>.yaml`) |
518
- | `seedFile` | No | Seed file path (default: `seeds/<appName>.yaml`) |
519
- | `domain` | No | App-specific kintone domain (overrides top-level) |
520
- | `auth` | No | App-specific authentication (overrides top-level) |
521
- | `guestSpaceId` | No | App-specific guest space ID |
522
- | `dependsOn` | No | List of app names this app depends on |
523
-
524
- ### Configuration Merge Priority (high to low)
525
-
526
- 1. CLI arguments (`--domain`, `--api-token`, etc.)
527
- 2. Environment variables (`KINTONE_DOMAIN`, `KINTONE_API_TOKEN`, etc.)
528
- 3. App-level settings (per `apps.<name>`)
529
- 4. Top-level settings
530
-
531
- ### Authentication in Config File
532
-
533
- ```yaml
534
- # API Token authentication
535
- auth:
536
- apiToken: "your-token"
537
-
538
- # Username/Password authentication
539
- auth:
540
- username: "your-username"
541
- password: "your-password"
542
- ```
543
-
544
- ### Dependency Resolution
545
-
546
- Apps are executed in topological order based on `dependsOn` declarations. Same-level apps are sorted alphabetically for deterministic ordering. Circular dependencies are detected and reported as errors.
547
-
548
- ### Execution Behavior
549
-
550
- - **`--all`**: Executes all apps in dependency order. Stops on first failure (fail-fast). Remaining apps are skipped.
551
- - **`--app <name>`**: Executes only the specified app.
552
- - **`--reset --all`**: Resets apps in **reverse** dependency order (dependent apps first) to avoid reference integrity issues.
553
-
554
- For the full specification, see:
555
-
556
- - [Project Config Specification](./spec/projectConfig.md) — format reference, validation rules, and dependency resolution
361
+ For details, see [Field Permission Specification](./spec/domains/fieldPermission.md).
557
362
 
558
363
  ## License
559
364