@collective-intelligence/cli 0.1.30 → 0.1.32

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 +54 -6
  2. package/dist/cli.js +12 -9
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -284,13 +284,14 @@ ci transfer export --domain documents --out ./acme.zip
284
284
  ci transfer export --run <export-run-id> --out ./acme --format folder
285
285
 
286
286
  # Import in two steps: upload and plan, read the Plan, then apply it.
287
- ci transfer import --plan --archive ./acme.zip --policy update
288
- ci transfer import --apply --plan-run <plan-run-id> --policy update
287
+ ci transfer import --plan --archive ./acme.zip --portability ./portability.json --save-plan ./plan.json
288
+ ci transfer import --apply --plan-file ./plan.json
289
289
 
290
290
  # Undo an applied import, and manage runs.
291
291
  ci transfer rollback --source-run <import-run-id>
292
292
  ci transfer runs
293
293
  ci transfer runs --run <run-id> --report
294
+ ci transfer runs --run <run-id> --mappings --out ./mappings.json
294
295
  ```
295
296
 
296
297
  **Export.** `--domain` (repeatable: `knowledge`, `documents`, `datasets`) or
@@ -301,13 +302,50 @@ Relation Boundary. `--out <path>` saves the archive after the run completes,
301
302
  as a zip (`--format zip`, the default) or a folder (`--format folder`). `--run
302
303
  <export-run-id>` skips the export and saves the archive of a finished run.
303
304
 
305
+ **Portability configuration.** Export (including preview) and import Plan accept
306
+ `--portability <file>`. This is the same versioned JSON configuration used by the
307
+ Dashboard and API. The backend validates it before export, upload or Plan starts.
308
+ It describes explicit JSON paths, entity references, base-user mappings, managed
309
+ files in configured Organization storage, and declarative transformations. No
310
+ external-application user identity is used. For example:
311
+
312
+ ```json
313
+ {
314
+ "version": 1,
315
+ "userMatch": "email",
316
+ "units": [
317
+ {
318
+ "domain": "knowledge",
319
+ "unit": "people",
320
+ "portablePaths": [[{ "key": "name" }]],
321
+ "references": [
322
+ { "path": [{ "key": "owner" }], "target": { "kind": "user" } }
323
+ ]
324
+ }
325
+ ]
326
+ }
327
+ ```
328
+
329
+ Paths start at business data and use `key`, `index`, or `each` segments. Ordinary
330
+ JSON needs explicit portable-as-is or rule coverage. Files declare
331
+ `stored_file_id`, `storage_key`, `file_object`, or `external_url`; external URLs
332
+ stay external. Transformations support `remove`, `set`, and `template` rules.
333
+ New archives use version 2; legacy archives remain usable where supported, with
334
+ unverified coverage clearly reported. Unsupported capabilities block Apply.
335
+
304
336
  **Import.** `--plan` takes `--archive <folder|zip>` and uploads it file by file
305
337
  with signed URLs, then runs the Plan. `--archive-id <id>` names the archive in
306
338
  the target Organization: pass the id that an interrupted upload printed to
307
339
  resume it (files that are already there are skipped), or pass it alone to plan
308
- an archive that is already uploaded. `--apply` needs `--plan-run <id>`; it takes
309
- the archive of that Plan run. Send the same import options on both steps; the
310
- backend refuses an apply whose options differ from the Plan. `--confirm-replace`
340
+ an archive that is already uploaded. Use `--save-plan <file>` to save the exact
341
+ request options, including the validated configuration, archive, run and target.
342
+ Apply with `--plan-file <file>`; it does not reread the original configuration
343
+ file and refuses option, archive or run overrides. The file contains no login
344
+ credentials, but can contain business values from the configuration.
345
+
346
+ The existing `--apply --plan-run <id>` form remains available: send the same
347
+ import options on both steps. The backend refuses an apply whose options differ
348
+ from the Plan, including edited saved-file options. `--confirm-replace`
311
349
  belongs to `--apply` and is required when the Plan removes Dataset rows.
312
350
 
313
351
  | Option | Values |
@@ -334,12 +372,22 @@ name the unit as `--unit` does.
334
372
  After a Plan, the CLI writes one line on stderr for each unit that is blocked
335
373
  (`write_permission_denied`, `unit_incomplete`, `unit_ambiguous`) and for each
336
374
  warning (`no_match_key_or_origin`, `forced_duplicates`, `earlier_run_committed`,
337
- `already_imported`). The Plan itself stays in the JSON result on stdout.
375
+ `already_imported`). It also prints per-unit counts, entity/user coverage,
376
+ missing/ambiguous references, file actions, transformation paths and values,
377
+ and portability blockers. The Plan itself stays in the JSON result on stdout.
378
+ Apply checks the live completed Plan; any selected unit or portability blocker
379
+ requires fixing or reselecting and creating a new Plan. Imports default to
380
+ skip-existing with events off; updating existing data requires `--policy update`.
338
381
 
339
382
  **Runs.** `ci transfer runs` lists the latest runs (`--limit <n>` sets how many).
340
383
  `--run <id>` reads that run directly, however old it is, and with `--report`,
341
384
  `--cancel`, `--resume` or `--purge` it reads the Run Report, cancels, resumes
342
385
  (and follows) or purges the files of that run. `--limit` with `--run` is refused.
386
+ `--mappings` downloads all protected mapping pages as a JSON result, including
387
+ mapping validity and Dataset target revision locators. Optional `--out <file>`
388
+ also saves the complete mapping object atomically. Authorization errors preserve
389
+ an existing output file. Resume and rollback use the same run commands; inspect
390
+ mapping validity after rollback before using target IDs.
343
391
 
344
392
  **Output.** Every line on stdout is one JSON object. Commands that start a run
345
393
  print one `{"kind":"progress","step":"run",...}` line per run event, and upload