|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +import { Command, Flags } from '@oclif/core'; |
| 4 | +import chalk from 'chalk'; |
| 5 | +import { createInterface } from 'node:readline'; |
| 6 | +import { |
| 7 | + printHeader, |
| 8 | + printSuccess, |
| 9 | + printWarning, |
| 10 | + printError, |
| 11 | + printInfo, |
| 12 | + printStep, |
| 13 | + createTimer, |
| 14 | + emitJson, |
| 15 | +} from '../../utils/format.js'; |
| 16 | +import { bootSchemaStack } from '../../utils/schema-migrate.js'; |
| 17 | +import { buildDataMigrationPlugins } from '../../utils/data-migration-plugins.js'; |
| 18 | + |
| 19 | +async function confirm(question: string): Promise<boolean> { |
| 20 | + if (!process.stdin.isTTY) return false; // non-interactive → require --yes |
| 21 | + const rl = createInterface({ input: process.stdin, output: process.stdout }); |
| 22 | + try { |
| 23 | + const answer: string = await new Promise((resolve) => rl.question(question, resolve)); |
| 24 | + return /^y(es)?$/i.test(answer.trim()); |
| 25 | + } finally { |
| 26 | + rl.close(); |
| 27 | + } |
| 28 | +} |
| 29 | + |
| 30 | +/** |
| 31 | + * `os migrate value-shapes` — the ADR-0104 D1 non-media value-shape gate |
| 32 | + * (#3438), the sibling of `os migrate files-to-references` (#3617). |
| 33 | + * |
| 34 | + * Scans every stored reference (`lookup` / `master_detail` / `user` / `tree`) |
| 35 | + * and structured-JSON (`location` / `address` / `composite` / `repeater` / |
| 36 | + * `record` / `vector`) value against the contract the write path enforces, and |
| 37 | + * — on an `--apply` run finding zero violations — records the deployment-level |
| 38 | + * `adr-0104-value-shapes` flag. That flag, never the platform version, is what |
| 39 | + * turns strict enforcement of those classes on for THIS deployment. |
| 40 | + * |
| 41 | + * ## No backfill, deliberately |
| 42 | + * |
| 43 | + * Unlike its sibling this run rewrites nothing. The file migration converts |
| 44 | + * legacy values because the platform narrowed that storage form and therefore |
| 45 | + * owes the conversion; a malformed `location` is application data whose correct |
| 46 | + * value only its author knows. So this reports and prescribes, and the operator |
| 47 | + * fixes and re-runs until it is green. |
| 48 | + * |
| 49 | + * The happy consequence: with nothing to convert, `--apply`'s only write is the |
| 50 | + * flag row, so #3617's invariant is trivially preserved — a dry run changes |
| 51 | + * nothing, and whether a run changed this deployment's posture never depends on |
| 52 | + * what the run found. |
| 53 | + * |
| 54 | + * ## Why it is not gated on the file migration's flag |
| 55 | + * |
| 56 | + * That flag attests that file values were migrated and their ownership |
| 57 | + * reconciled. It says nothing about whether a `lookup` id or a `location` |
| 58 | + * payload is well formed. Reusing it here would be borrowing evidence for a |
| 59 | + * fact it does not cover — see the ADR's 2026-07-27 amendment. |
| 60 | + */ |
| 61 | +export default class MigrateValueShapes extends Command { |
| 62 | + static override description = |
| 63 | + 'Scan stored reference and structured-JSON field values against the ADR-0104 value contract. ' + |
| 64 | + 'Read-only; --apply records the deployment-level migration flag when the scan finds zero violations.'; |
| 65 | + |
| 66 | + static override examples = [ |
| 67 | + '$ os migrate value-shapes', |
| 68 | + '$ os migrate value-shapes --apply', |
| 69 | + '$ os migrate value-shapes --apply --yes --json', |
| 70 | + '$ os migrate value-shapes --object contact --object account', |
| 71 | + ]; |
| 72 | + |
| 73 | + static override flags = { |
| 74 | + 'database-url': Flags.string({ |
| 75 | + description: 'Database URL to scan (defaults to $OS_DATABASE_URL / the project DB)', |
| 76 | + env: 'OS_DATABASE_URL', |
| 77 | + }), |
| 78 | + apply: Flags.boolean({ |
| 79 | + description: |
| 80 | + 'Record the deployment migration flag when the scan passes (the scan itself is always read-only)', |
| 81 | + default: false, |
| 82 | + }), |
| 83 | + yes: Flags.boolean({ char: 'y', description: 'Skip the --apply confirmation prompt', default: false }), |
| 84 | + object: Flags.string({ |
| 85 | + description: 'Restrict to this object (repeatable; default: every object with a covered field)', |
| 86 | + multiple: true, |
| 87 | + }), |
| 88 | + 'max-records': Flags.integer({ |
| 89 | + description: |
| 90 | + 'Safety bound on records scanned per object — exceeding it truncates the scan and fails the gate', |
| 91 | + }), |
| 92 | + json: Flags.boolean({ description: 'Output as JSON (implies non-interactive; requires --yes to apply)' }), |
| 93 | + }; |
| 94 | + |
| 95 | + async run(): Promise<void> { |
| 96 | + const { flags } = await this.parse(MigrateValueShapes); |
| 97 | + const timer = createTimer(); |
| 98 | + const apply = flags.apply; |
| 99 | + |
| 100 | + if (!flags.json) printHeader('Migrate · value-shapes'); |
| 101 | + |
| 102 | + // No occupancy gate, unlike the file migration: that command rewrites rows, |
| 103 | + // so a second writer on the same SQLite file is a real hazard. This one only |
| 104 | + // reads. A concurrent writer can still move the counts under us, which the |
| 105 | + // scan reports honestly rather than pretending to have frozen the database. |
| 106 | + |
| 107 | + if (apply && !flags.yes) { |
| 108 | + if (flags.json || !process.stdin.isTTY) { |
| 109 | + if (flags.json) { |
| 110 | + await emitJson({ error: 'confirmation_required', hint: 'pass --yes' }, 0, { compact: true }); |
| 111 | + this.exit(1); |
| 112 | + return; |
| 113 | + } |
| 114 | + printWarning( |
| 115 | + 'Apply mode records this deployment\'s migration flag, which turns on strict value-shape ' + |
| 116 | + 'enforcement. Re-run with --yes to confirm, or run without --apply to preview.', |
| 117 | + ); |
| 118 | + this.exit(1); |
| 119 | + return; |
| 120 | + } |
| 121 | + const ok = await confirm( |
| 122 | + chalk.bold('\nRecord the value-shape migration flag on this database if the scan passes? [y/N] '), |
| 123 | + ); |
| 124 | + if (!ok) { |
| 125 | + printInfo('Aborted — nothing recorded.'); |
| 126 | + return; |
| 127 | + } |
| 128 | + } |
| 129 | + |
| 130 | + if (!flags.json) { |
| 131 | + printStep(apply ? 'Booting data stack (APPLY mode)…' : 'Booting data stack (scan only)…'); |
| 132 | + } |
| 133 | + |
| 134 | + let stack; |
| 135 | + try { |
| 136 | + stack = await bootSchemaStack({ |
| 137 | + databaseUrl: flags['database-url'], |
| 138 | + extraPlugins: await buildDataMigrationPlugins(), |
| 139 | + }); |
| 140 | + } catch (error: any) { |
| 141 | + if (flags.json) { await emitJson({ error: error.message }, 0, { compact: true }); this.exit(1); } |
| 142 | + printError(error.message || String(error)); |
| 143 | + this.exit(1); |
| 144 | + return; |
| 145 | + } |
| 146 | + |
| 147 | + try { |
| 148 | + const engine: any = stack.kernel.getService('objectql'); |
| 149 | + if (typeof engine?.getObject !== 'function') { |
| 150 | + throw new Error('No ObjectQL engine on this stack — cannot scan.'); |
| 151 | + } |
| 152 | + // An empty scan is indistinguishable from a clean one, and this command's |
| 153 | + // verdict is what authorises strict enforcement — so refuse to run when no |
| 154 | + // app metadata is loaded (missing artifact / wrong directory) rather than |
| 155 | + // "verify" a database the scan never actually looked at. |
| 156 | + const loadedObjects: string[] = |
| 157 | + typeof engine.getConfigs === 'function' ? Object.keys(engine.getConfigs()) : []; |
| 158 | + if (!loadedObjects.some((name) => !name.startsWith('sys_'))) { |
| 159 | + throw new Error( |
| 160 | + 'No app objects are loaded, so the scan would examine nothing. ' + |
| 161 | + 'Run "os build" in your project root first (the migration reads dist/objectstack.json), then re-run.', |
| 162 | + ); |
| 163 | + } |
| 164 | + |
| 165 | + const { scanValueShapes, valueShapeScanPassed, formatValueShapeScanReport } = |
| 166 | + await import('@objectstack/objectql'); |
| 167 | + |
| 168 | + // In JSON mode keep stdout parseable — route scan warnings to stderr. |
| 169 | + const logger = flags.json |
| 170 | + ? { info: (m: string) => console.error(m), warn: (m: string) => console.error(m) } |
| 171 | + : { info: (m: string) => printInfo(m), warn: (m: string) => printWarning(m) }; |
| 172 | + |
| 173 | + const report = await scanValueShapes(engine, logger, { |
| 174 | + objects: flags.object, |
| 175 | + maxRecordsPerObject: flags['max-records'], |
| 176 | + }); |
| 177 | + const passed = valueShapeScanPassed(report); |
| 178 | + |
| 179 | + // The flag write is the ONLY write this command makes, and only on an |
| 180 | + // apply run that passed. A failing apply run still records — deliberately: |
| 181 | + // it stamps `blocking` and clears `verified_at`, so a deployment whose data |
| 182 | + // has regressed closes its own gate rather than coasting on an old pass. |
| 183 | + let flag: unknown = null; |
| 184 | + if (apply) { |
| 185 | + const { recordDataMigrationRun } = await import('@objectstack/platform-objects/system'); |
| 186 | + const { VALUE_SHAPES_MIGRATION_ID } = await import('@objectstack/spec/system'); |
| 187 | + flag = await recordDataMigrationRun(engine, { |
| 188 | + migrationId: VALUE_SHAPES_MIGRATION_ID, |
| 189 | + passed, |
| 190 | + blocking: report.blocking, |
| 191 | + advisory: 0, |
| 192 | + applied: true, |
| 193 | + // Passed as an OBJECT — `recordDataMigrationRun` serialises it. |
| 194 | + details: { |
| 195 | + scannedObjects: report.scannedObjects.length, |
| 196 | + scannedRecords: report.scannedRecords, |
| 197 | + fields: report.findings.length, |
| 198 | + truncated: report.truncated, |
| 199 | + unreadableObjects: report.unreadableObjects, |
| 200 | + }, |
| 201 | + }); |
| 202 | + if (typeof engine.invalidateDataMigrationFlags === 'function') { |
| 203 | + engine.invalidateDataMigrationFlags(); |
| 204 | + } |
| 205 | + } |
| 206 | + |
| 207 | + if (flags.json) { |
| 208 | + await emitJson({ |
| 209 | + database: stack.dbLabel, |
| 210 | + apply, |
| 211 | + scan: report, |
| 212 | + gatePassed: passed, |
| 213 | + flag, |
| 214 | + duration: timer.elapsed(), |
| 215 | + }); |
| 216 | + if (!passed) this.exit(1); |
| 217 | + return; |
| 218 | + } |
| 219 | + |
| 220 | + printInfo(`Database: ${chalk.white(stack.dbLabel)}`); |
| 221 | + console.log(''); |
| 222 | + console.log(formatValueShapeScanReport(report).join('\n')); |
| 223 | + console.log(''); |
| 224 | + |
| 225 | + if (passed && apply) { |
| 226 | + printSuccess( |
| 227 | + `Scan clean — recorded the deployment flag. Reference and structured-JSON value shapes ` + |
| 228 | + `are now enforced on this deployment (${timer.elapsed()}).`, |
| 229 | + ); |
| 230 | + } else if (passed) { |
| 231 | + printSuccess(`Scan clean (${timer.elapsed()}). Re-run with --apply to record the flag and enforce.`); |
| 232 | + } else if (apply) { |
| 233 | + printError('Scan found violations — the flag records the failure and the gate stays closed.'); |
| 234 | + printInfo('Fix the values named above and re-run; nothing is converted for you.'); |
| 235 | + this.exit(1); |
| 236 | + } else { |
| 237 | + printError('Scan found violations — fix them, then re-run with --apply.'); |
| 238 | + this.exit(1); |
| 239 | + } |
| 240 | + } catch (error: any) { |
| 241 | + if (flags.json) { await emitJson({ error: error.message }, 0, { compact: true }); this.exit(1); } |
| 242 | + printError(error.message || String(error)); |
| 243 | + this.exit(1); |
| 244 | + } finally { |
| 245 | + await stack.shutdown(); |
| 246 | + } |
| 247 | + } |
| 248 | +} |
0 commit comments