Skip to content

Commit b198f91

Browse files
fix(cli): os dev's in-place organization-ownership upgrade names what stopped it, and the command that carries on (#26785)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XQ5pdkuCpFo7HHTQm6TUo9U)_ Fixes #26615 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:`os dev` 遇到旧开发库被启动保护拒绝、就地升级又没跑完时,不再只说「The upgrade did not run to a report」。它会打印仪式自己的拒绝原文(终端强制彩色时也读得到),或者仪式是怎么结束的(退出码、信号)加日志末尾;最后给出一条能直接接着跑的完整命令(带数据库和它写好的计划文件)。 - **为什么改**:卡片里开发者拉了一周 main 后启动失败,只拿到一句没有原因的话。这里在五种旧库形态上都复现不出那次具体的停止(包括 10 月 16 日的 HotCRM 真实旧库 + 已发布的 18.2.0,都升级成功),但找到了三处会把原因吞掉的代码路径,现在都会说出原因。 - **风险与回滚**:只动 `os dev` 的就地升级读结果和打印的那一层;生产 `os migrate … --apply` 仪式本身一行没改,升级前的备份照旧保留。回滚即还原 `packages/cli/src/utils/dev-organization-ownership-upgrade.ts`。 - **先看**:`packages/cli/src/utils/dev-organization-ownership-upgrade.ts`(`stopCause` 与 `readApplyOutcome`)、`packages/cli/test/dev-organization-ownership-stale-column.integration.test.ts`、`scripts/check-cli-test-child-env.mjs`(名单加一行)。 - **两分钟验证**:`pnpm --filter @objectstack/cli exec vitest run src/utils/dev-organization-ownership-upgrade.test.ts`,应见 13 条全绿,其中「a refusal printed in colour is read in the ceremony's own words」。 - **需要你做的**:无,席位落地。 ## What changes `os dev`'s in-place upgrade of a development database the organization-ownership boot guard refused (`upgradeDevelopmentDatabase`, ADR-0131 D10 development exception) now never ends without its cause: - **The ceremony's refusal, in its own words, also in colour.** The refusal lines are read from the ceremony log with colour stripped (`stripVTControlCharacters`). Before, a terminal that forces colour (`FORCE_COLOR`) made chalk write `ESC[31m ✗ Refused: …` into the log, the reader's `startsWith('✗')` matched nothing, and the stop printed no cause. Measured: `FORCE_COLOR=1 os migrate organization-ownership --dev --apply …` writes exactly that byte shape to a file. The `✗` glyph is now the printer's alone, no longer doubled (`✗ ✗ Refused`). - **A stop with no refusal of its own names how it ended.** The apply's exit used to be ignored. An uncaught error (printed by oclif as `Error: …`), a crash or a signal printed no `✗` line, so nothing was shown. Now the upgrade prints `` `os migrate organization-ownership --dev --apply` exited with code N `` (or `was ended by SIGNAL`, or `could not be started`), then the end of that run's own part of the log, without the kernel's timestamped INFO/DEBUG narration and without the plan run's output. - **A report file that is not a report is read as none.** The apply reserves its `--out` file before it boots, holding a reservation text. A run that stopped between the reservation and the report left that text, which the upgrade parsed as a report with no verdict and printed 「The upgrade stopped at a blocker (above)」 with nothing above. A file that did not parse threw out of `os dev`. Both are now "no report", with the cause. A blocked report that names no blocker prints the log's cause too. - **No silent drop (seat ruling C, 6446501014).** A stale `organization_id` the plan gives the column-drop fate is a column the plan accounts for, so the upgrade proceeds, but before the apply runs `os dev` prints one line per column-drop table whose retired column held non-null stamps: the table, how many stamped values the drop discards (the plan's `fateCounts.rowsLosingTheirStamp`), and that the copy keeps them. A table with no stamps is not named. A column the plan gives no fate still refuses the plan. - **The exact command that carries on.** Every failed upgrade ends on `os migrate organization-ownership --dev --database-url URL --apply --plan-file PLAN --backup-taken`, with the database the boot opened and the plan the upgrade wrote. The apply resumes from its checkpoint and prints the stop on the developer's terminal. The copy taken before the upgrade is kept exactly as before. The production ceremony (`os migrate organization-ownership --apply` without `--dev`) is unchanged: no file under `packages/cli/src/commands/migrate/` or `packages/runtime` is touched. ## Tests - `packages/cli/src/utils/dev-organization-ownership-upgrade.test.ts`: six new cases (a coloured refusal, an uncaught error with kernel narration around it, a signal, the reservation text left behind, an unparseable report file, a blocked report with no blocker), and the existing cases read the un-doubled refusal and the exact command; a seventh (ruling C) pins that a `sys_secret` column drop discarding 3 stamps is announced exactly once before the apply, a drop with 0 stamps is not, and the upgrade completes. 13/13 (ablating the `rows > 0` filter turns the C pin red: 1 failed | 12 passed). - `packages/cli/test/dev-organization-ownership-stale-column.integration.test.ts` (new, integration tier, the card's third target): a fresh `os dev` creates the database, the staging step gives `sys_flow_credential` and `sys_secret` the injected `organization_id` column and its `idx_TABLE_organization_id` index with unstamped rows, and deletes the marker (the 18.0 pre-release shape). A plain `os dev` on it is refused, upgraded in place and starts (「server started on the upgraded database」). Both columns are gone, the marker is verified, the rows are kept, and the copy still has both columns. The `sys_secret` row is stamped with a real `sys_organization` id, and `os dev` prints its stamped-count line before "Upgraded the development database" and does not name the unstamped `sys_flow_credential`. 5/5. It joins the built-entrypoint census of `scripts/check-cli-test-child-env.mjs` (seventeen → eighteen, with its reason). <details><summary>Red first: the new cases against the base source</summary> The base `dev-organization-ownership-upgrade.ts` (`5cc31c7885`), restored from `HEAD` afterwards (`git diff HEAD` empty), driven by a copy of the test whose fake answers the base seam's `number`: ``` × a refused plan changes nothing and boots nothing: its refusal is printed, with the copy's location × a blocked step boots nothing: each blocker is printed, and how to resume × ⭐ a refusal printed in colour is read in the ceremony's own words × an apply that stopped with no refusal of its own (an uncaught error) names how it ended and the end of its log × an apply ended by a signal says so × a report file still holding the apply's reservation text is no report: the cause is printed, not "a blocker (above)" × a report file that does not parse is named, never thrown × a blocked report that names no blocker prints the log's cause instead of an empty "above" Tests 8 failed | 4 passed (12) ``` The first two are the un-doubled glyph and the exact command; the other six are the swallowed causes. </details> ## Acceptance notes - **The reported stop did not reproduce in this container.** The reporter's database (`.objectstack/data/backups/organization-ownership-2026-10-27T10-08-08-349Z`) is on the reporter's machine. Five shapes were measured, and each completed the upgrade and started: (1) a one-object fixture on `main`, both columns added, no marker; (2) the same with a shape-generation-0 birth marker; (3) HotCRM `afdf9a0` on `main` with the columns, the indexes, and stamped rows in both tables; (4) the same on the **published 18.2.0** install; (5) an **authentic** HotCRM database written by HotCRM `4f82b81` (2026-10-16, platform `18.0.0-next.2`), then started by HotCRM on the published 18.2.0. Its plan carried exactly `sys_flow_credential` and `sys_secret` as column-drop tables with the column, `column-drops done {"dropped":2}`. The test fixture stands in for the reporter's backup. With this change, running `os dev` on that backup prints the cause the ceremony hit. The `ceremony.log` beside the backup already holds it. - **Target 2 measured: already handled.** `sys_flow_credential` and `sys_secret` carry inventory fate `column-drop` (`organization-ownership-inventory.ts`), and the dev-mode ceremony drops both columns through the drift door, index included. The new test pins it. No ceremony change was needed. - **The ruling's data line** was decided by the seat (ruling C, 6446501014): proceed, and print what each column drop discards. A blanket refusal would refuse every 17.x dev database, because `sys_audit_log` and the `sys_metadata` family are column-drop tables and always stamped. - Open PRs on the file surface, read at start and before this PR: only #26337 touches `organization-ownership-inventory.ts` (not touched here). Card #26687 has no PR yet. ## Verification <details><summary>Local subset at the head named in the report</summary> - `pnpm --filter @objectstack/cli exec vitest run --project unit`: Test Files 339 passed (339), Tests 4932 passed (4932), at `74e75e381c`. - `pnpm --filter @objectstack/cli typecheck`: exit 0 (`check:test-typecheck: OK`). - `vitest run --project integration test/dev-organization-ownership-stale-column.integration.test.ts`: 5 passed. - The derived gate list (`dispatch-gates.mjs --commands`) was re-run at `74e75e381c` after a full `pnpm build` and reconciled with `--ran`: 80 derived, 80 run, 0 NOT-MEASURED. `check:dual-build-cjs-loads` and `check:i18n-coverage` both exit 0. The full table is in the os-dev-report on the card (round 2: 6447810905). </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; scoped eslint passes on the touched files. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: not touched. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the maintainer summary is in Chinese by the fleet's rule). --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5pVM4YkXVkL6VgUUhP)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent cee4b16 commit b198f91

6 files changed

Lines changed: 576 additions & 34 deletions
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): `os dev`'s in-place organization-ownership upgrade names what stopped it, and the exact command that carries on
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
When the organization-ownership boot guard refuses a development database, `os dev` copies it and runs the ceremony on it in place. When that upgrade did not finish, it could exit with 「The upgrade did not run to a report」 and no cause.
11+
12+
What changes:
13+
14+
- The ceremony's own refusal is printed in its own words, also when the terminal forces colour (`FORCE_COLOR`): the refusal lines are read with colour stripped, and the `✗` glyph is no longer printed twice.
15+
- An apply that stopped with no refusal of its own (an uncaught error, a crash, a signal) says how it ended and prints the end of its log, without the kernel's boot narration.
16+
- A report file still holding the apply's reservation text, or one that does not parse, is read as "no report", with the cause, never as "a blocker (above)" with nothing above. A blocked report that names no blocker prints the log's cause too.
17+
- A stale `organization_id` the plan gives the column-drop fate is upgraded as before, but no longer silently: before the apply runs, `os dev` prints per table how many stamped values the drop discards, and names the copy that keeps them.
18+
- Each failed upgrade ends on the exact command that carries on: `os migrate organization-ownership --dev --database-url URL --apply --plan-file PLAN --backup-taken`, with the database and the plan the upgrade wrote.
19+
20+
The copy taken before the upgrade is kept, as before. A development database with a stale `organization_id` column on `sys_flow_credential` and `sys_secret` (objects that no longer declare it) is upgraded and starts under `os dev`, now pinned by a test. The production ceremony is unchanged.
21+
22+
What to do: nothing.

‎packages/cli/src/commands/dev.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -941,6 +941,7 @@ export default class Dev extends Command {
941941
sqliteFile,
942942
env: localEnv,
943943
cwd: process.cwd(),
944+
announce: (line) => console.log(chalk.yellow(` ⚠ ${line}`)),
944945
});
945946
},
946947
});

‎packages/cli/src/utils/dev-organization-ownership-upgrade.test.ts‎

Lines changed: 115 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
isOrganizationOwnershipRequiredMessage,
1919
ORGANIZATION_OWNERSHIP_REQUIRED_MESSAGE,
2020
upgradeDevelopmentDatabase,
21+
type CeremonyRunEnd,
2122
type DevelopmentUpgradeInput,
2223
} from './dev-organization-ownership-upgrade.js';
2324

@@ -29,20 +30,37 @@ const NOW = new Date('2026-10-16T10:00:00.000Z');
2930
const BACKUP = (): string => join(dir, 'backups', 'organization-ownership-2026-10-16T10-00-00-000Z');
3031

3132
/** A fake CLI: answers `planCode`, and writes the files a real run writes. */
32-
function fakeRun(opts: { planCode?: number; report?: Record<string, unknown> | null }): DevelopmentUpgradeInput['run'] {
33+
function fakeRun(opts: {
34+
planCode?: number;
35+
report?: Record<string, unknown> | null;
36+
/** What the apply prints to its log, verbatim. */
37+
applyLog?: string;
38+
/** How the apply ends, when not by its report's verdict. */
39+
applyEnd?: CeremonyRunEnd;
40+
/** What the apply leaves at its `--out` path instead of a report. */
41+
applyFile?: string;
42+
/** The plan file the plan run writes. */
43+
plan?: Record<string, unknown>;
44+
}): DevelopmentUpgradeInput['run'] {
3345
return (args, logFile) => {
3446
calls.push([...args]);
3547
const out = args[args.indexOf('--out') + 1]!;
3648
if (!args.includes('--apply')) {
3749
writeFileSync(logFile, opts.planCode ? ' ✗ Refused (sys_mystery): sys_mystery carries organization_id …\n' : 'planned\n', { flag: 'a' });
38-
if (!opts.planCode) writeFileSync(out, '{}');
39-
return opts.planCode ?? 0;
50+
if (!opts.planCode) writeFileSync(out, JSON.stringify(opts.plan ?? {}));
51+
return { status: opts.planCode ?? 0 };
4052
}
53+
if (opts.applyLog) writeFileSync(logFile, opts.applyLog, { flag: 'a' });
4154
if (opts.report) writeFileSync(out, JSON.stringify(opts.report));
42-
return opts.report?.complete ? 0 : 1;
55+
if (opts.applyFile !== undefined) writeFileSync(out, opts.applyFile);
56+
return opts.applyEnd ?? { status: opts.report?.complete ? 0 : 1 };
4357
};
4458
}
4559

60+
/** The exact command every failed apply ends on: the plan this upgrade wrote, the database it opened. */
61+
const AGAIN = (): string =>
62+
`os migrate organization-ownership --dev --database-url file:${primary} --apply --plan-file ${join(BACKUP(), 'plan.json')} --backup-taken`;
63+
4664
const input = (run: DevelopmentUpgradeInput['run'], over: Partial<DevelopmentUpgradeInput> = {}): DevelopmentUpgradeInput => ({
4765
binPath: '/cli/bin/run.js',
4866
databaseUrl: `file:${primary}`,
@@ -83,7 +101,8 @@ describe('os dev — the in-place upgrade of a v17-shape development database',
83101
const result = upgradeDevelopmentDatabase(input(fakeRun({ planCode: 1 })));
84102
expect(result.ok).toBe(false);
85103
expect(calls).toHaveLength(1);
86-
expect(result.lines[0]).toContain('✗ Refused (sys_mystery)');
104+
// The ceremony's own words; the `✗` glyph is the printer's, never doubled.
105+
expect(result.lines[0]).toBe('Refused (sys_mystery): sys_mystery carries organization_id …');
87106
expect(result.lines.at(-1)).toContain('nothing was changed');
88107
expect(result.lines.at(-1)).toContain(BACKUP());
89108
// The ceremony is open (18.x step 6): the way on is running it by hand.
@@ -97,7 +116,7 @@ describe('os dev — the in-place upgrade of a v17-shape development database',
97116
})));
98117
expect(result.ok).toBe(false);
99118
expect(result.lines[0]).toBe('authored-conversion: The authored permission x differs …');
100-
expect(result.lines.at(-1)).toContain(`--apply --plan-file ${join(BACKUP(), 'plan.json')} --backup-taken`);
119+
expect(result.lines.at(-1)).toContain(AGAIN());
101120
});
102121

103122
it('every step finished but the post-check holds an unattributable row: boots nothing, names the table, count and remedy', () => {
@@ -130,6 +149,96 @@ describe('os dev — the in-place upgrade of a v17-shape development database',
130149
expect(result.lines[0]).not.toContain('17.x');
131150
});
132151

152+
it('⭐ a column drop that discards stamped values is said, per table, before the apply runs, and the upgrade completes', () => {
153+
const announced: Array<{ line: string; callsSoFar: number }> = [];
154+
const stamps = (rowsLosingTheirStamp: number) => ({ columnPresent: true, rowsLosingTheirStamp, rowsWithNullOrganization: 0 });
155+
const result = upgradeDevelopmentDatabase(input(
156+
fakeRun({
157+
plan: {
158+
tables: [
159+
{ object: 'sys_flow_credential', fate: 'column-drop', fateCounts: stamps(0) },
160+
{ object: 'sys_secret', fate: 'column-drop', fateCounts: stamps(3) },
161+
// Attribution keeps every stamp: nothing is discarded there.
162+
{ object: 'sys_job', fate: 'attribution', fateCounts: stamps(9) },
163+
],
164+
},
165+
report: { complete: true, blocking: 0, warnings: [], steps: [] },
166+
}),
167+
{ announce: (line) => announced.push({ line, callsSoFar: calls.length }) },
168+
));
169+
expect(result.ok).toBe(true);
170+
expect(announced.map((a) => a.line)).toEqual([
171+
`sys_secret: the plan drops its retired organization_id column, discarding 3 stamped value(s); the copy in ${BACKUP()} keeps them.`,
172+
]);
173+
// Said after the plan and before the apply.
174+
expect(announced[0]!.callsSoFar).toBe(1);
175+
expect(calls).toHaveLength(2);
176+
});
177+
178+
describe('an apply that writes no report still names its cause, and the exact command that carries on', () => {
179+
// A `FORCE_COLOR` terminal: chalk colours the refusal even into the log file.
180+
const COLOURED = '\u001b[31m ✗ Refused: The plan file … was computed for the database A, and this run opened B.\u001b[39m\n';
181+
182+
it('⭐ a refusal printed in colour is read in the ceremony\'s own words', () => {
183+
const result = upgradeDevelopmentDatabase(input(fakeRun({ applyLog: COLOURED, applyEnd: { status: 1 } })));
184+
expect(result.ok).toBe(false);
185+
expect(result.lines[0]).toBe('Refused: The plan file … was computed for the database A, and this run opened B.');
186+
expect(result.lines.at(-1)).toContain('The upgrade did not run to a report.');
187+
expect(result.lines.at(-1)).toContain(AGAIN());
188+
expect(result.lines.at(-1)).toContain(BACKUP());
189+
});
190+
191+
it('an apply that stopped with no refusal of its own (an uncaught error) names how it ended and the end of its log', () => {
192+
const log =
193+
'2026-10-27T10:08:09.000Z INFO Bootstrap complete\n' +
194+
' → step column-drops…\n' +
195+
'2026-10-27T10:08:10.000Z INFO Graceful shutdown started\n' +
196+
' Error: SQLITE_ERROR: error in index idx_sys_secret_organization_id after drop column\n';
197+
const result = upgradeDevelopmentDatabase(input(fakeRun({ applyLog: log, applyEnd: { status: 1 } })));
198+
expect(result.ok).toBe(false);
199+
expect(result.lines[0]).toContain('exited with code 1 without a refusal of its own');
200+
expect(result.lines).toContain(' Error: SQLITE_ERROR: error in index idx_sys_secret_organization_id after drop column');
201+
expect(result.lines).toContain(' → step column-drops…');
202+
// The kernel's INFO narration is not the cause.
203+
expect(result.lines.some((l) => l.includes('Bootstrap complete'))).toBe(false);
204+
expect(result.lines.at(-1)).toContain(AGAIN());
205+
});
206+
207+
it('an apply ended by a signal says so', () => {
208+
const result = upgradeDevelopmentDatabase(input(fakeRun({ applyEnd: { status: null, signal: 'SIGKILL' } })));
209+
expect(result.lines[0]).toContain('was ended by SIGKILL without a refusal of its own, and its log');
210+
expect(result.lines.at(-1)).toContain('The upgrade did not run to a report.');
211+
});
212+
213+
it('a report file still holding the apply\'s reservation text is no report: the cause is printed, not "a blocker (above)"', () => {
214+
const reservation = JSON.stringify({ kind: 'organization-ownership-apply-reservation', reservedAt: '2026-10-27T10:08:09.000Z', note: '…' });
215+
const result = upgradeDevelopmentDatabase(input(fakeRun({
216+
applyLog: ' Error: the stack shut down mid-step\n',
217+
applyEnd: { status: 1 },
218+
applyFile: reservation,
219+
})));
220+
expect(result.ok).toBe(false);
221+
expect(result.lines).toContain(' Error: the stack shut down mid-step');
222+
expect(result.lines.at(-1)).toContain('The upgrade did not run to a report.');
223+
expect(result.lines.join('\n')).not.toContain('a blocker (above)');
224+
});
225+
226+
it('a report file that does not parse is named, never thrown', () => {
227+
const result = upgradeDevelopmentDatabase(input(fakeRun({ applyEnd: { status: 1 }, applyFile: '{"kind":"organization-own' })));
228+
expect(result.ok).toBe(false);
229+
expect(result.lines.some((l) => l.startsWith(`Its report file ${join(BACKUP(), 'apply.json')} could not be read`))).toBe(true);
230+
});
231+
232+
it('a blocked report that names no blocker prints the log\'s cause instead of an empty "above"', () => {
233+
const result = upgradeDevelopmentDatabase(input(fakeRun({
234+
report: { complete: false, warnings: [], steps: [{ step: 'column-drops', status: 'blocked', blockers: [] }] },
235+
applyLog: ' ✗ The ceremony stopped at a blocker (above). Resolve it and re-run --apply; finished steps are not repeated. Report: …\n',
236+
})));
237+
expect(result.lines[0]).toContain('The ceremony stopped at a blocker');
238+
expect(result.lines.at(-1)).toContain(AGAIN());
239+
});
240+
});
241+
133242
it('the IPC message is recognised by its type alone', () => {
134243
expect(isOrganizationOwnershipRequiredMessage({ type: ORGANIZATION_OWNERSHIP_REQUIRED_MESSAGE, tables: ['sys_job'] })).toBe(true);
135244
expect(isOrganizationOwnershipRequiredMessage({ type: 'objectstack:listening', port: 3000 })).toBe(false);

0 commit comments

Comments
 (0)