From bdae1cb3f28fd85b2dd59f08b69417b207ef29f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 13:10:53 +0000 Subject: [PATCH 1/2] docs(cli): `os migrate meta --from` lists the edits, it does not rewrite (#10831) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four hand-written docs-site pages and one docblock inside the command's own source told authors that `os migrate meta --from N` rewrites their files. It rewrites none. The `--from` arm replays the ADR-0087 chain over the loaded stack in memory and reports the diff; both `writeFileSync` calls in `packages/cli/src/commands/migrate/meta.ts` are guarded by `if (flags.out)`, so the only file it ever writes is the `--out` JSON snapshot, and the command header at :155-157 explicitly declines the AST rewrite as "unsafe and lossy". The in-place codemod is separate and unbuilt. Two of the four were wrong twice over: they attached a *stored*-arm behaviour ("stored flows are rewritten", "rewrite stored metadata automatically") to `--from`, which is declared `exclusive: ['stored']` at :195-198 and therefore cannot be combined with `--stored` at all. Both errors are fixed, not just the verb, and "automatically" — the word the class-wide reword existed to remove — is gone. All four now carry the already-blessed sentence the generated reference carriers use: run the command to LIST the mechanical edits for existing sources, then apply them by hand. The `pendingDataMigrations` docblock at :81 rides along per triage: the contrast it draws (metadata migration's subject is the author's source, the data migrations' subject is a deployment's rows) is correct and is preserved; only the false verb on the first half changed. Split on the ARM, not on the verb: `os migrate meta --stored --apply` genuinely does rewrite `sys_metadata` rows, so no `--stored` wording was touched anywhere, and `content/docs/releases/**` was not edited. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- .changeset/migrate-meta-lists-not-rewrites.md | 23 +++++++++++++++++++ content/docs/automation/flows.mdx | 5 ++-- content/docs/data-modeling/queries.mdx | 4 ++-- .../docs/protocol/objectql/query-syntax.mdx | 3 ++- .../protocol/objectui/widget-contract.mdx | 3 ++- packages/cli/src/commands/migrate/meta.ts | 12 +++++----- 6 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 .changeset/migrate-meta-lists-not-rewrites.md diff --git a/.changeset/migrate-meta-lists-not-rewrites.md b/.changeset/migrate-meta-lists-not-rewrites.md new file mode 100644 index 0000000000..2e0bd68692 --- /dev/null +++ b/.changeset/migrate-meta-lists-not-rewrites.md @@ -0,0 +1,23 @@ +--- +"@objectstack/cli": patch +--- + +Correct a false verb in `os migrate meta`'s own source comments: the `--from` +arm **lists** the mechanical edits an author's source needs; it rewrites no file +(#10831). + +The `pendingDataMigrations` docblock in +`packages/cli/src/commands/migrate/meta.ts` opened with "this command rewrites an +author's source" — 74 lines above the command header that says the opposite +("The command does not silently rewrite TS config source (that AST rewrite is +unsafe and lossy)"). Both `writeFileSync` calls in the file are guarded by +`if (flags.out)`, so the only file the `--from` arm ever writes is the `--out` +JSON snapshot. The in-place codemod is a separate, unbuilt piece of work. + +The contrast the docblock was drawing — metadata migration's subject is the +author's *source*, the two data migrations' subject is a deployment's *rows* — +is correct and is preserved; only the verb on the first half changed. The +`--stored` arm genuinely does rewrite `sys_metadata` rows and its wording is +untouched. + +No runtime behaviour changes: comment-only. diff --git a/content/docs/automation/flows.mdx b/content/docs/automation/flows.mdx index 3ae6dba6de..27cedf8b1d 100644 --- a/content/docs/automation/flows.mdx +++ b/content/docs/automation/flows.mdx @@ -242,8 +242,9 @@ Replace them per branch — they are different mechanisms, not one rename: | `actionType: 'my_fn'` (shorthand) | `function: 'my_fn'` — the conversion moves it for you | | inline `config.script` | move the logic into a registered function and call it via `config.function` | -Stored flows are rewritten by `os migrate meta --from 16`; authoring one of -these keys in TypeScript is now a compile error carrying the same prescription. +Run `os migrate meta --from 16` to list the mechanical edits for existing flow +sources; apply them by hand. Authoring one of these keys in TypeScript is now a +compile error carrying the same prescription. [#4343]: https://github.com/objectstack-ai/objectstack/issues/4343 diff --git a/content/docs/data-modeling/queries.mdx b/content/docs/data-modeling/queries.mdx index 1b7c034d99..d8c92eea56 100644 --- a/content/docs/data-modeling/queries.mdx +++ b/content/docs/data-modeling/queries.mdx @@ -385,8 +385,8 @@ backend, which left "what can this backend actually compute" unpredictable to th Both were retired (#6188, ADR-0049 enforce-or-remove): a query carrying either is now refused at parse with a prescription. There is no replacement in the query vocabulary — read the rows with an ordinary `fields` query and shape them in the caller, or materialise -the roll-up as a stored field. `os migrate meta --from 16` rewrites affected dataset -measures. +the roll-up as a stored field. Run `os migrate meta --from 16` to list the mechanical +edits for the affected dataset measures; apply them by hand. diff --git a/content/docs/protocol/objectql/query-syntax.mdx b/content/docs/protocol/objectql/query-syntax.mdx index 742e05acbf..fb586b1d77 100644 --- a/content/docs/protocol/objectql/query-syntax.mdx +++ b/content/docs/protocol/objectql/query-syntax.mdx @@ -857,7 +857,8 @@ by no SQL backend, so which backend could compute them was unpredictable to the Both were retired (#6188, ADR-0049 enforce-or-remove) and are now refused at parse with a prescription. There is no replacement in the query vocabulary — read the rows with an ordinary `fields` query and shape them in the caller, or materialise the roll-up as a -stored field. `os migrate meta --from 16` rewrites affected dataset measures. +stored field. Run `os migrate meta --from 16` to list the mechanical edits for the +affected dataset measures; apply them by hand. ### Group By Multiple Fields diff --git a/content/docs/protocol/objectui/widget-contract.mdx b/content/docs/protocol/objectui/widget-contract.mdx index c083846ffd..417462721d 100644 --- a/content/docs/protocol/objectui/widget-contract.mdx +++ b/content/docs/protocol/objectui/widget-contract.mdx @@ -313,7 +313,8 @@ customVars: The prescription in both waves is `customVars`, and it is a byte-for-byte replacement — `customVars` carrying `font-size-lg: 1.125rem` puts exactly the same `--font-size-lg` on the document the retired scale did. Run - `os migrate meta --from 16` to rewrite stored metadata automatically. + `os migrate meta --from 16` to list the mechanical edits for existing sources; + apply them by hand. Widgets inherit the active theme automatically; they do not each carry their own copy of the palette or the font stack. diff --git a/packages/cli/src/commands/migrate/meta.ts b/packages/cli/src/commands/migrate/meta.ts index 529ab0ff39..aa3dbea298 100644 --- a/packages/cli/src/commands/migrate/meta.ts +++ b/packages/cli/src/commands/migrate/meta.ts @@ -78,12 +78,12 @@ interface PendingDataMigration { * leaves for the operator (ADR-0104's 2026-07-30 addendum, #3438). * * Metadata migration and data migration are different jobs with different - * subjects: this command rewrites an author's source, while these two rewrite - * (or vouch for) a deployment's rows, one deployment at a time. Nothing here - * can run them, and — with no database in reach — nothing here can say whether - * they have run; the booting server reports that. What this can do is make - * sure the upgrade never *ends* without naming them, because a gate nobody is - * told about is served by nobody. + * subjects: this command reports the edits an author's source needs, while + * these two rewrite (or vouch for) a deployment's rows, one deployment at a + * time. Nothing here can run them, and — with no database in reach — nothing + * here can say whether they have run; the booting server reports that. What + * this can do is make sure the upgrade never *ends* without naming them, + * because a gate nobody is told about is served by nobody. * * Listed only when the author's own metadata declares the field classes each * gate is about, so the advice is never noise. From d986096107c2f9e45141e62b791a361d950675b6 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 13:31:28 +0000 Subject: [PATCH 2/2] docs(deployment): the `--from` half of cli.mdx's division-of-labour sentence lists, it does not rewrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `content/docs/deployment/cli.mdx:921-924` is a fifth carrier of the same false verb this PR exists to remove, and the card's table did not reach it: `os migrate meta --from N` rewrites an **author's source** and reads no database; `--stored` rewrites **one deployment's rows** and reads no config. The `--from` half is false for the same reason as the other four — the arm replays the chain in memory and prints the mechanical edits; both `writeFileSync` calls in `packages/cli/src/commands/migrate/meta.ts` are guarded by `if (flags.out)`, so the only file it writes is the `--out` JSON snapshot. This is the same source-vs-rows contrast shape as the `meta.ts:81` docblock, so it gets the same treatment triage ruled for that one: the contrast is correct and is preserved verbatim — both bold subjects, "reads no database" / "reads no config", and the mutual-exclusion note (which restates `exclusive: ['stored']`) are untouched. Only the verb on the `--from` half changed. Split on the ARM, not on the verb: the `--stored` half of this very sentence is correct and is left exactly as it was, as are every other `--stored` mention on the page (:624, :679, :850, :864-867). Line :838 already said "reports what is left to do" and needed nothing. Committed separately from the four dispatched pages so it can be dropped on its own if review judges it out of scope. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- content/docs/deployment/cli.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index 4211f924ad..b2db97142e 100644 --- a/content/docs/deployment/cli.mdx +++ b/content/docs/deployment/cli.mdx @@ -919,9 +919,9 @@ an old dialect exits `1`. So "my metadata is on protocol N" becomes a check rather than a belief. Note the division of labour with the default mode: `os migrate meta --from N` -rewrites an **author's source** and reads no database; `--stored` rewrites **one -deployment's rows** and reads no config. Same chain, opposite ends of the -contract — which is why the two modes are mutually exclusive. +lists the edits **an author's source** needs and reads no database; `--stored` +rewrites **one deployment's rows** and reads no config. Same chain, opposite +ends of the contract — which is why the two modes are mutually exclusive. **Without shell access, use the route.** This command needs to reach the deployment's database directly, which a hosted operator cannot do. The same pass