@objectstack/cli 10.0.0 → 10.3.0

package/dist/commands/migrate/plan.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { printHeader, printSuccess, printWarning, printError, printInfo, printStep, createTimer, } from '../../utils/format.js';
+import { bootSchemaStack, renderPlan, summarize } from '../../utils/schema-migrate.js';
+/**
+ * `os migrate plan` — dry-run diff of metadata vs the physical database,
+ * categorised safe / needs-confirm / destructive (issue #2186). Never mutates
+ * the schema.
+ */
+export default class MigratePlan extends Command {
+    static description = 'Show how the physical database has drifted from metadata (dry run; no changes applied)';
+    static examples = [
+        '$ os migrate plan',
+        '$ os migrate plan --json',
+        '$ os migrate plan --database-url postgres://localhost/app',
+    ];
+    static flags = {
+        'database-url': Flags.string({
+            description: 'Database URL to inspect (defaults to $OS_DATABASE_URL / the project DB)',
+            env: 'OS_DATABASE_URL',
+        }),
+        json: Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        const { flags } = await this.parse(MigratePlan);
+        const timer = createTimer();
+        if (!flags.json) {
+            printHeader('Migrate · plan');
+            printStep('Booting schema stack…');
+        }
+        let stack;
+        try {
+            stack = await bootSchemaStack({ databaseUrl: flags['database-url'] });
+        }
+        catch (error) {
+            if (flags.json) {
+                console.log(JSON.stringify({ error: error.message }));
+                this.exit(1);
+            }
+            printError(error.message || String(error));
+            this.exit(1);
+            return;
+        }
+        try {
+            if (!stack.driver) {
+                if (flags.json) {
+                    console.log(JSON.stringify({ error: 'no_sql_driver', changes: [] }));
+                    return;
+                }
+                printWarning('Schema migration is only supported on SQL drivers (SQLite / Postgres). No SQL driver is active.');
+                return;
+            }
+            const drift = await stack.driver.detectManagedDrift();
+            if (flags.json) {
+                console.log(JSON.stringify({
+                    database: stack.dbLabel,
+                    managedTables: stack.managedTableCount,
+                    total: drift.length,
+                    changes: drift,
+                    duration: timer.elapsed(),
+                }, null, 2));
+                return;
+            }
+            printInfo(`Database: ${chalk.white(stack.dbLabel)}`);
+            printInfo(`Examined ${chalk.white(String(stack.managedTableCount))} managed table(s).`);
+            console.log('');
+            if (drift.length === 0) {
+                printSuccess('Physical schema is in sync with metadata — nothing to migrate.');
+                console.log('');
+                return;
+            }
+            renderPlan(drift);
+            printInfo(summarize(drift));
+            console.log(chalk.dim('  Apply with: ') + chalk.white('os migrate apply') +
+                chalk.dim(' (add --allow-destructive for drops / tightenings)'));
+            console.log(chalk.dim(`  ${timer.display()}`));
+            console.log('');
+        }
+        catch (error) {
+            if (flags.json) {
+                console.log(JSON.stringify({ error: error.message }));
+                this.exit(1);
+            }
+            printError(error.message || String(error));
+            this.exit(1);
+        }
+        finally {
+            await stack.shutdown();
+        }
+    }
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/migrate/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/commands/migrate/plan.ts"],"names":[],"mappings":"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"}

package/dist/commands/package/publish.js

@@ -11,10 +11,10 @@
  *      into sys_package_version.manifest_json (status=published).
  *   3. (optional) auto-install into a target environment via --env.
  *
- * This is the "upload my local code to my org" path. It does NOT write
- * sys_environment_revision (that's the legacy `objectstack publish` path,
- * which still exists for backward compatibility while ADR-0006 v4 Phase B
- * transitions complete).
+ * This is the "upload my local code to my org" path — the single supported
+ * way to publish. (The legacy direct-to-environment `os publish` / `os
+ * rollback` commands, which wrote sys_environment_revision, have been
+ * removed.)
  */
 import { readFile } from 'node:fs/promises';
 import { resolve as resolvePath, basename, dirname, isAbsolute } from 'node:path';

package/dist/commands/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,OAAO,EAAS,MAAM,aAAa,CAAC;AAyInD,MAAM,CAAC,OAAO,OAAO,KAAM,SAAQ,OAAO;IACxC,OAAgB,WAAW,SAAkM;IAE7N,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;;;;;;;;MAoBnB;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAQtD;IAEH;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAIpD;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAi2D3B"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAQ,OAAO,EAAS,MAAM,aAAa,CAAC;AAyInD,MAAM,CAAC,OAAO,OAAO,KAAM,SAAQ,OAAO;IACxC,OAAgB,WAAW,SAAkM;IAE7N,OAAgB,IAAI;;MAElB;IAEF,OAAgB,KAAK;;;;;;;;;;MAoBnB;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAQtD;IAEH;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAIpD;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA80D3B"}

package/dist/commands/serve.js

@@ -412,7 +412,7 @@ export default class Serve extends Command {
                     // "missing artifact" error and assemble a bare kernel that
                     // can later install marketplace apps at runtime.
                     const { createDefaultHostConfig } = await import('@objectstack/runtime');
-                    const bootResult = await createDefaultHostConfig({ requireArtifact: !useEmptyBoot });
+                    const bootResult = await createDefaultHostConfig({ requireArtifact: !useEmptyBoot, dev: isDev });
                     config = { ...originalConfig, ...bootResult };
                 }
                 else if (resolvedMode === 'standalone') {
@@ -423,6 +423,9 @@ export default class Serve extends Command {
                     const standaloneInput = {
                         ...(config.standalone ?? {}),
                         projectRoot: (config.standalone?.projectRoot ?? path.dirname(absolutePath)),
+                        // #2229: dev enables the native-better-sqlite3 → wasm → in-memory
+                        // step-down in the shared datasource factory; prod fails loudly.
+                        dev: isDev,
                     };
                     const bootResult = await createStandaloneStack(standaloneInput);
                     config = { ...originalConfig, ...bootResult };
@@ -516,10 +519,39 @@ export default class Serve extends Command {
                     envLevel: readLogLevelEnv(),
                 }),
             };
+            // Cluster wiring: env-driven driver selection (mirrors OS_DATABASE_URL).
+            // The remote driver self-registers on import; import it dynamically so it
+            // works in BOTH config-boot and compiled-artifact mode. Open-core ships
+            // only the in-memory driver — remote drivers (e.g. redis) come from the EE
+            // distribution; if absent we fall back to the in-memory cluster.
+            let clusterConfig;
+            const __clusterDriver = process.env.OS_CLUSTER_DRIVER?.trim();
+            if (__clusterDriver && __clusterDriver !== 'memory') {
+                // Multi-node authorization gate (open mechanism): a distribution (e.g.
+                // an EE license) may deny multi-node. On denial, downgrade to
+                // single-node rather than fail — multi-node is an add-on, never brick.
+                // Dynamic, non-literal specifier so the CLI does not statically depend
+                // on the cluster package (mirrors the remote-driver import below).
+                const __clusterPkg = '@objectstack/service-cluster';
+                const { checkMultiNodeAllowed } = (await import(__clusterPkg));
+                const __gate = checkMultiNodeAllowed();
+                if (!__gate.allowed) {
+                    console.warn(`[cluster] multi-node not authorized (${__gate.reason ?? 'denied'}) — ` +
+                        `downgrading to single-node (in-memory cluster). Remove OS_CLUSTER_DRIVER to silence.`);
+                }
+                else {
+                    try {
+                        await import(`@objectstack/service-cluster-${__clusterDriver}`);
+                    }
+                    catch { /* may already be registered by the loaded config */ }
+                    clusterConfig = { driver: __clusterDriver, url: process.env.OS_REDIS_URL };
+                }
+            }
             const runtime = new Runtime({
                 kernel: {
                     logger: loggerConfig
-                }
+                },
+                cluster: clusterConfig,
             });
             const kernel = runtime.getKernel();
             // Load plugins from configuration
@@ -587,16 +619,25 @@ export default class Serve extends Command {
                         resolvedDatabaseUrl = databaseUrl ?? 'mongodb://localhost:27017/objectstack';
                     }
                     else if (driverType === 'sqlite' || driverType === 'sql') {
-                        const { SqlDriver } = await import('@objectstack/driver-sql');
                         const filePath = (databaseUrl ?? ':memory:').replace(/^file:/, '').replace(/^sqlite:/, '').replace(/^sql:\/\//, '');
-                        await kernel.use(new DriverPlugin(new SqlDriver({
-                            client: 'better-sqlite3',
-                            connection: { filename: filePath },
-                            useNullAsDefault: true,
-                        })));
-                        trackPlugin('SqlDriver');
-                        resolvedDriverLabel = 'SqlDriver(sqlite)';
-                        resolvedDatabaseUrl = databaseUrl ?? ':memory:';
+                        // Probe-by-connect with a dev-only native → wasm → in-memory
+                        // step-down (#2229). better-sqlite3 loads its native addon lazily
+                        // (first query), so an ABI mismatch is invisible here and would
+                        // otherwise surface much later as a runtime crash. resolveSqliteDriver
+                        // forces the load and degrades gracefully in dev / fails loudly in prod.
+                        const { resolveSqliteDriver } = await import('@objectstack/service-datasource');
+                        const resolved = await resolveSqliteDriver({
+                            filename: filePath,
+                            dev: isDev,
+                            // #2186: in dev, self-heal a persisted DB when a metadata change
+                            // relaxes a constraint (loosen-only; never destructive / never in prod).
+                            autoMigrate: isDev ? 'safe' : undefined,
+                            warn: (m) => console.warn(chalk.yellow(m)),
+                        });
+                        await kernel.use(new DriverPlugin(resolved.driver));
+                        trackPlugin(resolved.engine === 'memory' ? 'MemoryDriver' : resolved.engine === 'sqlite-wasm' ? 'SqliteWasmDriver' : 'SqlDriver');
+                        resolvedDriverLabel = resolved.label;
+                        resolvedDatabaseUrl = resolved.engine === 'memory' ? '(in-memory)' : (databaseUrl ?? ':memory:');
                     }
                     else if (driverType === 'sqlite-wasm' || driverType === 'wasm-sqlite' || driverType === 'wasm') {
                         const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');
@@ -615,6 +656,7 @@ export default class Serve extends Command {
                             client: 'pg',
                             connection: databaseUrl,
                             pool: { min: 0, max: 5 },
+                            autoMigrate: isDev ? 'safe' : undefined, // #2186 dev loosen-only self-heal
                         })));
                         trackPlugin('PostgresDriver');
                         resolvedDriverLabel = 'SqlDriver(pg)';
@@ -626,99 +668,33 @@ export default class Serve extends Command {
                             client: 'mysql2',
                             connection: databaseUrl,
                             pool: { min: 0, max: 5 },
+                            autoMigrate: isDev ? 'safe' : undefined, // #2186 dev loosen-only self-heal
                         })));
                         trackPlugin('MySQLDriver');
                         resolvedDriverLabel = 'SqlDriver(mysql2)';
                         resolvedDatabaseUrl = databaseUrl;
                     }
                     else if (isDev) {
-                        // Default in dev: prefer native SQLite for production-like SQL
-                        // semantics at native speed. When the native `better-sqlite3`
-                        // binary is unavailable — not built, ABI mismatch after a Node
-                        // upgrade (e.g. Node 25 → NODE_MODULE_VERSION mismatch), or a
-                        // blocked prebuild download — fall back to the pure-JS wasm SQLite
-                        // driver, which keeps *real* SQL semantics (and on-disk
-                        // persistence) without any native build step. Only if wasm also
-                        // fails to load do we drop to the in-memory driver (mingo), which
-                        // is neither real SQL nor persistent.
-                        //
-                        // knex loads its client lazily (at first query, not at construction),
-                        // so the only reliable signal inside this registration window is to
-                        // actually open a connection: connect() runs `SELECT 1`, which forces
-                        // better-sqlite3 to load. If that throws we step down the chain here
-                        // instead of letting the failure surface much later — as a
-                        // missing-module crash on the first real query — or be swallowed by
-                        // the silent catch below, leaving the kernel with no driver at all.
-                        let sqliteDriver;
-                        let sqliteOk = false;
-                        try {
-                            const { SqlDriver } = await import('@objectstack/driver-sql');
-                            sqliteDriver = new SqlDriver({
-                                client: 'better-sqlite3',
-                                connection: { filename: ':memory:' },
-                                useNullAsDefault: true,
-                            });
-                            await sqliteDriver.connect();
-                            sqliteOk = true;
-                        }
-                        catch {
-                            sqliteOk = false;
-                            if (sqliteDriver?.disconnect) {
-                                try {
-                                    await sqliteDriver.disconnect();
-                                }
-                                catch { /* ignore */ }
-                            }
-                        }
-                        if (sqliteOk) {
-                            await kernel.use(new DriverPlugin(sqliteDriver));
-                            trackPlugin('SqlDriver');
-                            resolvedDriverLabel = 'SqlDriver(sqlite)';
-                            resolvedDatabaseUrl = ':memory:';
-                        }
-                        else {
-                            // Native unavailable → try the pure-JS wasm SQLite driver before
-                            // giving up on SQL fidelity entirely. Same probe-by-connect
-                            // approach: actually open the connection so a load failure is
-                            // caught here rather than on the first real query.
-                            let wasmDriver;
-                            let wasmOk = false;
-                            try {
-                                const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');
-                                wasmDriver = new SqliteWasmDriver({
-                                    filename: ':memory:',
-                                    persist: 'on-disconnect',
-                                });
-                                await wasmDriver.connect();
-                                wasmOk = true;
-                            }
-                            catch {
-                                wasmOk = false;
-                                if (wasmDriver?.disconnect) {
-                                    try {
-                                        await wasmDriver.disconnect();
-                                    }
-                                    catch { /* ignore */ }
-                                }
-                            }
-                            if (wasmOk) {
-                                await kernel.use(new DriverPlugin(wasmDriver));
-                                trackPlugin('SqliteWasmDriver');
-                                resolvedDriverLabel = 'SqliteWasmDriver';
-                                resolvedDatabaseUrl = ':memory:';
-                                console.warn(chalk.yellow('  ⚠ native better-sqlite3 unavailable (ABI mismatch or not built) — dev using wasm SQLite (real SQL, slower).\n' +
-                                    '    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.'));
-                            }
-                            else {
-                                const { InMemoryDriver } = await import('@objectstack/driver-memory');
-                                await kernel.use(new DriverPlugin(new InMemoryDriver()));
-                                trackPlugin('MemoryDriver');
-                                resolvedDriverLabel = 'InMemoryDriver';
-                                resolvedDatabaseUrl = '(in-memory)';
-                                console.warn(chalk.yellow('  ⚠ neither native nor wasm SQLite available — dev falling back to InMemoryDriver (mingo, not real SQL).\n' +
-                                    '    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.'));
-                            }
-                        }
+                        // Default in dev (no DB configured): prefer native SQLite for
+                        // production-like SQL at native speed, with a graceful step-down to
+                        // wasm SQLite (real SQL + on-disk persistence) then in-memory when the
+                        // native better-sqlite3 binary is unavailable — not built, ABI mismatch
+                        // after a Node upgrade (e.g. NODE_MODULE_VERSION change), or a blocked
+                        // prebuild download. Shared with the explicit-file branch and the
+                        // datasource factory via resolveSqliteDriver (#2229), which probes by
+                        // actually opening a connection + running SELECT 1 (better-sqlite3 loads
+                        // its native addon lazily at first query, not at construction).
+                        const { resolveSqliteDriver } = await import('@objectstack/service-datasource');
+                        const resolved = await resolveSqliteDriver({
+                            filename: ':memory:',
+                            dev: true,
+                            autoMigrate: 'safe', // #2186 dev loosen-only self-heal
+                            warn: (m) => console.warn(chalk.yellow(m)),
+                        });
+                        await kernel.use(new DriverPlugin(resolved.driver));
+                        trackPlugin(resolved.engine === 'memory' ? 'MemoryDriver' : resolved.engine === 'sqlite-wasm' ? 'SqliteWasmDriver' : 'SqlDriver');
+                        resolvedDriverLabel = resolved.label;
+                        resolvedDatabaseUrl = resolved.engine === 'memory' ? '(in-memory)' : ':memory:';
                     }
                 }
                 catch (e) {