@datarails-ai/dr-appspace-cli 0.12.82 → 0.12.83

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 +38 -1
  2. package/dist/cli.js +2599 -1836
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -55,7 +55,7 @@ dr-appspace app-space whoami -s DEV
55
55
  - **`app-space` commands** (ported from `dr-dev-cli app-space`, re-based onto
56
56
  this auth): `whoami`, `list`, `get`, `logs`, `try`, `push`, `publish`,
57
57
  `unpublish` — plus `scaffold`, `preview`, `test`, `contract`, `compile`,
58
- `eject` and `migrate`.
58
+ `eject`, `migrate` and `compare`.
59
59
 
60
60
  ### Moving an app to the new `ctx` names
61
61
 
@@ -71,6 +71,43 @@ additions go into your own text and layout.
71
71
  `--to-runtime 2` is refused: runtime 2 is proposed (DR-58160). Rules:
72
72
  `docs/appspace/ctx-migrate.md`.
73
73
 
74
+ ### Checking a migrated app
75
+
76
+ `compare [dir]` proves that the migrated folder answers as the published app
77
+ does. For each read handler it runs the published code, then the folder's code,
78
+ through the dry run that `try` uses: back to back, with the same payload, as
79
+ the same role. Then it compares the two JSON answers.
80
+
81
+ ```
82
+ dr-appspace app-space push ./my-app # as a draft: the published version stays live
83
+ dr-appspace app-space compare ./my-app --payloads @./payloads.json --ignore '$.meta.generated_at'
84
+ ```
85
+
86
+ Push the folder as a draft first. A dry run takes its grants from the stored
87
+ app, not from the folder, so migrated code that calls `ctx.dr` fails before the
88
+ push. The published code comes from `GET /apps/<id>/package?version=published`.
89
+ The command stops when the answer does not say `"served": "published"` (a
90
+ server too old for the selector: deploy it first), when its version is not the
91
+ published one in `GET /apps/<id>/versions`, and when the published version is
92
+ also the working one (nothing to compare: push the draft first). It warns when
93
+ the folder's handlers or lib differ from the stored draft.
94
+
95
+ Every dry run is read-only (`read_only: true`): the server stops each write
96
+ before it does anything and counts it, also when the handler catches the
97
+ error. The command refuses a server that does not echo the flag and the count. Each handler is `equal`, `differ`, `error`, `unchanged` (same text,
98
+ same lib), `writes` (stopped by the read-only run), `skipped` (a static write
99
+ hint, a new handler, a role the gate refuses) or `not checked (metric
100
+ unbound)`. The output shows paths, the kind of each difference (`missing`,
101
+ `extra`, `type`, `value`) and a salted hash of each value and of each object
102
+ key, never the values: the answers hold customer data. `--show-values` prints
103
+ them to the terminal. `--out <file>` writes the report without values.
104
+ `--ignore <path>` masks a volatile value (`rows[*].updated_at`, `$.*.id`; a
105
+ pattern of only wildcards is refused) and the report counts what each mask
106
+ hid. `--strict` fails on any skipped or not-checked handler. `--handler`,
107
+ `--as`, `--max-diffs` and `--json` work as their names say. Exit 0 pass, 1
108
+ fail, 2 refused. Full rules and the check order:
109
+ `docs/appspace/ctx-migrate.md`, "Check a migrated app".
110
+
74
111
  ### A handler that takes a file
75
112
 
76
113
  `try` and `test` can put a file in front of a handler, the way the page does: