@hivemagnus/magnus-server 1.0.3 → 1.1.1

package/.env.example

@@ -179,3 +179,23 @@ CORS_ORIGIN=https://magnus.example.com:3000
 # HEALTH_SNAPSHOT_RETENTION_DAYS=7
 # NOTIFICATION_READ_RETENTION_DAYS=30
 # NOTIFICATION_MAX_RETENTION_DAYS=90
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Upgrades (optional). Each automatic behaviour has its own switch; set them
+# false if you run your own release process. See UPGRADING.md.
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Back up (pg_dump) and apply pending migrations at startup, under an advisory lock.
+# MAGNUS_AUTO_MIGRATE=false
+# MAGNUS_AUTO_MIGRATE_BACKUP=true
+# MAGNUS_AUTO_MIGRATE_ALLOW_SLOW=false
+# MAGNUS_BACKUP_DIR=$MAGNUS_HOME/backups
+# MAGNUS_PG_DUMP=pg_dump
+# Daily npm registry check for new releases (console notice and `magnus-server check`).
+# MAGNUS_UPDATE_CHECK=true
+# MAGNUS_UPDATE_REGISTRY=https://registry.npmjs.org
+# Server-driven agent upgrades (console "Upgrade agents", `magnus-server agents upgrade`).
+# MAGNUS_AGENT_UPGRADES=true
+# MAGNUS_AGENT_UPGRADE_CONCURRENCY=5
+# The retired git-checkout self-update endpoints (source installs only).
+# MAGNUS_LEGACY_GIT_SELF_UPDATE=false

package/README.md

@@ -59,14 +59,18 @@ under `MAGNUS_HOME`, default `~/.magnus`.
 ```bash
 magnus-server check   --env-file ~/.magnus/server.env   # validate env, reach PostgreSQL and Redis, list integrations
 magnus-server migrate --env-file ~/.magnus/server.env   # apply migrations and base data
-magnus-server start   --env-file ~/.magnus/server.env   # or: start --migrate
+magnus-server start   --env-file ~/.magnus/server.env   # MAGNUS_AUTO_MIGRATE=true: back up and migrate first
 ```
 
 | Command | Purpose |
 | --- | --- |
-| `start` (default) | Start the API server. `--migrate` applies pending migrations first. |
-| `check` | Validate configuration, connect to PostgreSQL and Redis, report pending migrations and enabled integrations. Exits non-zero on a problem. |
+| `start` (default) | Start the API server. With `MAGNUS_AUTO_MIGRATE=true` it first dumps the database and applies pending migrations under an advisory lock. `--migrate` applies them without a dump. |
+| `check` | Validate configuration, connect to PostgreSQL and Redis, report pending migrations, available updates and enabled integrations (`--format json` for tooling). Exits non-zero on a problem. |
 | `migrate` | Run `prisma migrate deploy` with the packaged schema and migrations, then create the base rows (system actor, sentinel nodes, starter library). Idempotent. |
+| `migrations` | List applied and pending migrations with their impact (`fast`, `slow`, `one-way`). |
+| `backup` | Dump PostgreSQL (`pg_dump -Fc`) into `MAGNUS_BACKUP_DIR` and print the restore command. |
+| `upgrade`, `rollback` | Upgrade or roll back the `magnus init` project this server was installed into (runs `magnus upgrade`; see [UPGRADING.md](../../UPGRADING.md)). |
+| `agents upgrade` | Upgrade agents to the version this server ships (`--to`, `--nodes`, `--dry-run`). |
 | `env-schema` | Print the documented environment variables (`--format json` or `table`). |
 | `version`, `help` | Print the version or usage. |
 

package/agent-version.json

@@ -1 +1,3 @@
-{"version":"1.0.3"}
+{
+  "version": "1.1.1"
+}

package/dist/cli/agents.js

@@ -0,0 +1,111 @@
+/** `magnus-server agents upgrade`: the console's "Upgrade agents" action from a shell. */
+import { UsageError } from './args.js';
+export const AGENTS_USAGE = `Usage: magnus-server agents upgrade [options] [--env-file FILE]
+
+Upgrades agents to the version this server ships with (or --to), one canary
+first, then MAGNUS_AGENT_UPGRADE_CONCURRENCY at a time. Each agent installs the
+exact version beside the running one and switches back by itself if the new
+version does not report a heartbeat in time. Stops at the first failure.
+
+Options:
+  --to X.Y.Z            Agent version (default: the one bundled with this server)
+  --integrity sha512-…  npm integrity of that version (default: read from the registry)
+  --nodes a,b           Only these nodes (names, host names or ids)
+  --dry-run             Show which agents would be upgraded, and why others would not
+
+Agents are called over TLS. NODE_EXTRA_CA_CERTS from --env-file is honoured, so
+the command trusts the same CA as the service.`;
+export function parseAgentsArgs(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help')
+        return 'help';
+    if (sub !== 'upgrade')
+        throw new UsageError(`unknown agents subcommand "${sub}"`);
+    const options = { dryRun: false };
+    for (let index = 0; index < rest.length; index++) {
+        const arg = rest[index];
+        const [name, inline] = arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+        const value = () => {
+            const next = inline ?? rest[++index];
+            if (!next || next.startsWith('--'))
+                throw new UsageError(`${name} requires a value`);
+            return next;
+        };
+        if (name === '--to')
+            options.to = value();
+        else if (name === '--integrity')
+            options.integrity = value();
+        else if (name === '--nodes')
+            options.nodes = value().split(',').map(node => node.trim()).filter(Boolean);
+        else if (name === '--dry-run')
+            options.dryRun = true;
+        else if (name === '--help' || name === '-h')
+            return 'help';
+        else
+            throw new UsageError(`unknown option ${name}`);
+    }
+    return options;
+}
+export async function commandAgents(args) {
+    const options = parseAgentsArgs(args);
+    if (options === 'help') {
+        console.log(AGENTS_USAGE);
+        return 0;
+    }
+    const { getDb, disconnectDb } = await import('../db/client.js');
+    const { disconnectRedis } = await import('../queue/redis.js');
+    const service = await import('../services/agent-upgrade-service.js');
+    try {
+        let nodeIds;
+        if (options.nodes) {
+            const rows = await getDb().node.findMany({
+                where: { OR: [{ id: { in: options.nodes } }, { name: { in: options.nodes } }, { hostname: { in: options.nodes } }] },
+                select: { id: true, name: true, hostname: true },
+            });
+            const unknown = options.nodes.filter(node => !rows.some(row => row.id === node || row.name === node || row.hostname === node));
+            if (unknown.length) {
+                console.error(`Unknown node(s): ${unknown.join(', ')}`);
+                return 1;
+            }
+            nodeIds = rows.map(row => row.id);
+        }
+        const release = await service.resolveAgentRelease({ version: options.to, integrity: options.integrity });
+        const candidates = await service.listUpgradeCandidates(release.version, nodeIds);
+        console.log(`magnus-agent ${release.version} (${release.integrity.slice(0, 19)}…)`);
+        for (const candidate of candidates) {
+            console.log(`  ${candidate.eligible ? '→' : '·'} ${candidate.name.padEnd(28)} ${candidate.version.padEnd(12)} ${candidate.eligible ? 'will upgrade' : candidate.reason}`);
+        }
+        const eligible = candidates.filter(candidate => candidate.eligible);
+        if (options.dryRun) {
+            console.log(`Dry run: ${eligible.length} of ${candidates.length} agent(s) would be upgraded.`);
+            return 0;
+        }
+        if (eligible.length === 0) {
+            console.log('Nothing to upgrade.');
+            return candidates.some(candidate => candidate.reason !== 'already on this version') ? 1 : 0;
+        }
+        const deps = service.defaultDeps();
+        const seen = new Map();
+        const save = deps.save;
+        deps.save = async (run) => {
+            for (const node of run.nodes) {
+                if (seen.get(node.nodeId) === node.state)
+                    continue;
+                seen.set(node.nodeId, node.state);
+                if (node.state !== 'pending')
+                    console.log(`  ${node.name}: ${node.state}${node.detail ? ` (${node.detail})` : ''}`);
+            }
+            await save(run);
+        };
+        const { done } = await service.startUpgradeRun({ version: release.version, integrity: release.integrity, nodeIds: eligible.map(node => node.nodeId),
+            actorId: 'system:magnus-server-cli', deps });
+        const run = await done;
+        console.log(`${run.status === 'succeeded' ? 'Done' : 'Stopped'}: ${run.message ?? run.status}`);
+        return run.status === 'succeeded' ? 0 : 1;
+    }
+    finally {
+        await disconnectDb().catch(() => undefined);
+        await disconnectRedis().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/cli/args.js

@@ -6,20 +6,28 @@ Commands:
   start         Start the API server (default)
   check         Validate configuration and reach PostgreSQL and Redis; list enabled integrations
   migrate       Apply pending migrations (prisma migrate deploy) and base data
+  migrations    Show applied and pending migrations with their impact notes
+  backup        Dump PostgreSQL (pg_dump -Fc) into MAGNUS_BACKUP_DIR and print the restore command
+  upgrade       Upgrade a \`magnus init\` project (runs \`magnus upgrade\`; see --help there)
+  rollback      Switch a \`magnus init\` project back to the previous version
+  agents        Agent fleet commands: \`agents upgrade [--to X.Y.Z] [--nodes a,b] [--dry-run]\`
   env-schema    Print the documented environment variables
   help          Show this help
   version       Print the version
 
 Options:
   --env-file <path>   Load variables from an env file (repeatable; existing variables win)
-  --migrate           start: apply pending migrations before listening
-  --format <fmt>      env-schema: json (default) or table
+  --migrate           start: apply pending migrations before listening (MAGNUS_AUTO_MIGRATE adds a backup and lock)
+  --format <fmt>      env-schema (default json), check and migrations (default table): json or table
+  --label <text>      backup: label in the dump file name
   -h, --help          Show this help
   -v, --version       Print the version
 `;
-const COMMANDS = new Set(['start', 'check', 'migrate', 'env-schema', 'help', 'version']);
+const COMMANDS = new Set(['start', 'check', 'migrate', 'migrations', 'backup', 'upgrade', 'rollback', 'agents', 'env-schema', 'help', 'version']);
+/** Commands whose remaining arguments belong to another tool. */
+const PASSTHROUGH = new Set(['upgrade', 'rollback', 'agents']);
 export function parseArgs(argv) {
-    const options = { command: 'start', envFiles: [], migrate: false, format: 'json' };
+    const options = { command: 'start', envFiles: [], migrate: false, format: 'json', formatGiven: false, passthrough: [] };
     let commandSeen = false;
     for (let index = 0; index < argv.length; index++) {
         const arg = argv[index];
@@ -33,6 +41,10 @@ export function parseArgs(argv) {
             index++;
             return next;
         };
+        if (commandSeen && PASSTHROUGH.has(options.command) && arg !== '--env-file' && !arg.startsWith('--env-file=')) {
+            options.passthrough.push(arg);
+            continue;
+        }
         if (arg === '-h' || arg === '--help')
             options.command = 'help';
         else if (arg === '-v' || arg === '--version')
@@ -46,7 +58,10 @@ export function parseArgs(argv) {
             if (format !== 'json' && format !== 'table')
                 throw new UsageError(`unknown format "${format}" (use json or table)`);
             options.format = format;
+            options.formatGiven = true;
         }
+        else if (arg === '--label' || arg.startsWith('--label='))
+            options.label = value('--label');
         else if (arg.startsWith('-'))
             throw new UsageError(`unknown option ${arg}`);
         else if (!commandSeen && COMMANDS.has(arg)) {

package/dist/cli/auto-migrate.js

@@ -0,0 +1,85 @@
+/**
+ * Startup auto-migrate (`MAGNUS_AUTO_MIGRATE=true`).
+ *
+ * Runs before the server listens. A session advisory lock serializes every
+ * instance sharing the database, so only one dumps and migrates while the
+ * others wait and then find nothing pending. A failed backup stops startup:
+ * migrations never run without a dump unless the operator turned the dump off.
+ */
+import { join } from 'node:path';
+import pg from 'pg';
+import { backupDatabase, describeMigration, migrationsNeedingAttention, readMigrationState, } from './migrations.js';
+/** Key for `pg_advisory_lock(hashtextextended(key, 0))`; distinct from Prisma's own migrate lock. */
+export const MIGRATE_LOCK_KEY = 'magnus:migrate';
+/** Pure decision, separated for tests. */
+export function decideAutoMigrate(state, settings) {
+    if (state.pending.length === 0)
+        return { action: 'skip', reason: `${state.packaged.length} migration(s) already applied` };
+    const attention = migrationsNeedingAttention(state.pending);
+    if (attention.length > 0 && !settings.autoMigrateAllowSlow) {
+        return {
+            action: 'refuse',
+            reason: `pending migration(s) need an operator: ${attention.map(describeMigration).join('; ')}. `
+                + 'Run `magnus upgrade` (or `magnus-server migrate` after a backup), or set MAGNUS_AUTO_MIGRATE_ALLOW_SLOW=true.',
+        };
+    }
+    // A fresh database has nothing to back up.
+    return { action: 'migrate', backup: settings.autoMigrateBackup && !state.fresh };
+}
+export async function autoMigrate(options) {
+    const log = options.log ?? ((line) => console.log(line));
+    const client = new pg.Client({ connectionString: options.databaseUrl, connectionTimeoutMillis: 10_000 });
+    await client.connect();
+    let locked = false;
+    try {
+        const tried = await client.query('SELECT pg_try_advisory_lock(hashtextextended($1, 0)) AS locked', [MIGRATE_LOCK_KEY]);
+        if (!tried.rows[0]?.locked) {
+            log('[auto-migrate] another instance is migrating; waiting for it to finish');
+            await client.query('SELECT pg_advisory_lock(hashtextextended($1, 0))', [MIGRATE_LOCK_KEY]);
+        }
+        locked = true;
+        const state = await readMigrationState(client, options.migrationsDir);
+        const decision = decideAutoMigrate(state, options.settings);
+        if (decision.action === 'skip') {
+            log(`[auto-migrate] nothing to do: ${decision.reason}`);
+            return { decision };
+        }
+        if (decision.action === 'refuse')
+            throw new Error(`Auto-migrate refused: ${decision.reason}`);
+        log(`[auto-migrate] ${state.pending.length} pending: ${state.pending.map(describeMigration).join(', ')}`);
+        let backup;
+        if (decision.backup) {
+            backup = await backupDatabase({
+                databaseUrl: options.databaseUrl,
+                backupDir: options.backupDir,
+                label: `pre-migrate-${options.version}`,
+                client,
+                pgDump: options.pgDump,
+            }).catch((error) => {
+                throw new Error(`Auto-migrate stopped before migrating: the backup failed. ${error instanceof Error ? error.message : String(error)}`);
+            });
+            log(`[auto-migrate] backup written to ${backup.file}`);
+        }
+        else if (!state.fresh) {
+            log('[auto-migrate] MAGNUS_AUTO_MIGRATE_BACKUP=false: migrating without a dump');
+        }
+        try {
+            await options.migrate();
+        }
+        catch (error) {
+            const restore = backup ? ` To restore the pre-migration state: ${backup.restoreCommand}` : '';
+            throw new Error(`${error instanceof Error ? error.message : String(error)}${restore}`);
+        }
+        log('[auto-migrate] migrations applied');
+        return { decision, backup };
+    }
+    finally {
+        if (locked)
+            await client.query('SELECT pg_advisory_unlock(hashtextextended($1, 0))', [MIGRATE_LOCK_KEY]).catch(() => undefined);
+        await client.end().catch(() => undefined);
+    }
+}
+export function defaultBackupDir(env, home) {
+    return env['MAGNUS_BACKUP_DIR']?.trim() || join(home, 'backups');
+}
+//# sourceMappingURL=auto-migrate.js.map

package/dist/cli/env-catalog.js

@@ -97,6 +97,20 @@ export const ENV_CATALOG = [
     { name: 'OPENAI_API_KEY', group: 'ai', secret: true, description: 'Optional OpenAI provider key.' },
     { name: 'OPENROUTER_API_KEY', group: 'ai', secret: true, description: 'Optional OpenRouter provider key.' },
     { name: 'ANTHROPIC_API_KEY', group: 'ai', secret: true, description: 'Optional Anthropic provider key.' },
+    // ── Upgrades ── (every automatic behaviour has its own switch; set them false to run your own release process)
+    { name: 'MAGNUS_AUTO_MIGRATE', group: 'upgrades', default: 'false', description: 'true: apply pending migrations at startup, before listening, under an advisory lock and after a pg_dump. `magnus init` projects and the container images set it to true.' },
+    { name: 'MAGNUS_AUTO_MIGRATE_BACKUP', group: 'upgrades', default: 'true', description: 'Dump the database (pg_dump -Fc into MAGNUS_BACKUP_DIR) before an automatic migration. A failed dump stops startup. Set false only if you back up another way.' },
+    { name: 'MAGNUS_AUTO_MIGRATE_ALLOW_SLOW', group: 'upgrades', default: 'false', description: 'Let auto-migrate apply migrations marked slow or one-way; otherwise startup stops and asks for `magnus upgrade`.' },
+    { name: 'MAGNUS_BACKUP_DIR', group: 'upgrades', default: '$MAGNUS_HOME/backups', description: 'Directory for pre-migration database dumps (0700; dumps are 0600).' },
+    { name: 'MAGNUS_PG_DUMP', group: 'upgrades', default: 'pg_dump', description: 'pg_dump binary used for pre-migration backups. Its major version must be at least the server\'s.' },
+    { name: 'MAGNUS_RUNTIME_FILE', group: 'upgrades', default: '$MAGNUS_HOME/run/server-runtime.json', description: 'File the server writes after it starts listening ({version, pid, port}); upgrade tooling reads it to confirm the new version is serving.' },
+    { name: 'MAGNUS_UPDATE_CHECK', group: 'upgrades', default: 'true', description: 'Daily check of the npm registry for newer Magnus releases, shown in the console and `magnus-server check`. Sends no data beyond a registry GET. Set false to opt out.' },
+    { name: 'MAGNUS_UPDATE_REGISTRY', group: 'upgrades', default: 'https://registry.npmjs.org', description: 'npm registry used by the update check.' },
+    { name: 'MAGNUS_AGENT_UPGRADES', group: 'upgrades', default: 'true', description: 'Allow server-driven agent upgrades (console action, API and `magnus-server agents upgrade`). Agents must also allow it (MAGNUS_AGENT_SELF_UPGRADE).' },
+    { name: 'MAGNUS_AGENT_UPGRADE_CONCURRENCY', group: 'upgrades', default: '5', description: 'Agents upgraded in parallel after the first (canary) agent confirms. Maximum 50.' },
+    { name: 'MAGNUS_LEGACY_GIT_SELF_UPDATE', group: 'upgrades', default: 'false', description: 'true: keep the retired git-checkout self-update endpoints (/api/v1/self-update/apply and /restart) for source installs. npm installs use `magnus upgrade`.' },
+    { name: 'NODE_EXTRA_CA_CERTS', group: 'upgrades', description: 'Extra CA bundle (PEM) trusted when the server calls agents, for agent certificates from a private CA. Node reads it at process start: set it in the unit; `magnus-server agents` also honours it from --env-file.' },
+    { name: 'MAGNUS_PROJECT_DIR', group: 'upgrades', description: 'Managed project created by `magnus init` (holds magnus-project.json). `magnus-server upgrade` finds it from the install path when unset.' },
     // ── Retention ──
     { name: 'LOG_RETENTION_DAYS', group: 'retention', default: '30', description: 'Days to keep ingested node logs.' },
     { name: 'HEALTH_SNAPSHOT_RETENTION_DAYS', group: 'retention', default: '7', description: 'Days to keep health snapshots.' },

package/dist/cli/migrations.js

@@ -0,0 +1,117 @@
+/**
+ * Migration state, impact notes and pre-migration backups, shared by
+ * `magnus-server migrate`, `check` and startup auto-migrate.
+ */
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/** Packaged migration directory names, in apply order. */
+export function packagedMigrations(migrationsDir) {
+    if (!existsSync(migrationsDir))
+        return [];
+    return readdirSync(migrationsDir, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && existsSync(join(migrationsDir, entry.name, 'migration.sql')))
+        .map(entry => entry.name)
+        .sort();
+}
+/**
+ * Each migration may carry `magnus-impact.json` (`{"impact":"slow","note":"…"}`).
+ * A migration without one is treated as fast and reversible by rollback.
+ */
+export function readMigrationImpact(migrationsDir, name) {
+    const path = join(migrationsDir, name, 'magnus-impact.json');
+    if (!existsSync(path))
+        return { impact: 'fast', note: '' };
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    const impact = raw.impact === 'slow' || raw.impact === 'one-way' ? raw.impact : 'fast';
+    return { impact, note: typeof raw.note === 'string' ? raw.note : '' };
+}
+export async function readMigrationState(client, migrationsDir) {
+    const packaged = packagedMigrations(migrationsDir);
+    const table = await client.query(`SELECT to_regclass('public._prisma_migrations') IS NOT NULL AS exists`);
+    const applied = table.rows[0]?.exists
+        ? new Set((await client.query('SELECT migration_name FROM _prisma_migrations WHERE finished_at IS NOT NULL AND rolled_back_at IS NULL')).rows
+            .map(row => row.migration_name))
+        : new Set();
+    const pending = packaged.filter(name => !applied.has(name))
+        .map(name => ({ name, ...readMigrationImpact(migrationsDir, name) }));
+    return { packaged, applied, pending, fresh: applied.size === 0 };
+}
+/** Pending migrations an operator must confirm: slow ones, or ones only a restore can undo. */
+export function migrationsNeedingAttention(pending) {
+    return pending.filter(migration => migration.impact !== 'fast');
+}
+export function describeMigration(migration) {
+    return `${migration.name} (${migration.impact}${migration.note ? `: ${migration.note}` : ''})`;
+}
+export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'inherit', 'inherit'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', chunk => { stdout += String(chunk); });
+    child.stderr?.on('data', chunk => { stderr += String(chunk); });
+    child.on('error', reject);
+    child.on('close', code => resolve({ code: code ?? 1, stdout, stderr }));
+});
+/** Absolute path of the prisma CLI installed next to magnus-server. */
+export function prismaCliPath() {
+    const require = createRequire(import.meta.url);
+    return join(dirname(require.resolve('prisma/package.json')), 'build', 'index.js');
+}
+export function majorOf(versionText) {
+    const match = /(\d+)(?:\.\d+)?/.exec(versionText);
+    return match ? Number(match[1]) : null;
+}
+/** A restore command that never contains the connection password. */
+export function restoreCommand(file) {
+    return `pg_restore --clean --if-exists --no-owner -d "$DATABASE_URL" '${file.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * `pg_dump -Fc` into the backup directory (0700 directory, 0600 dump).
+ * Refuses when pg_dump is older than the server, which would produce an
+ * unusable or partial dump.
+ */
+export async function backupDatabase(options) {
+    const run = options.run ?? runCommand;
+    const pgDump = options.pgDump ?? 'pg_dump';
+    const serverVersion = (await options.client.query('SHOW server_version_num')).rows[0]?.server_version_num ?? '';
+    const serverMajor = serverVersion ? Math.floor(Number(serverVersion) / 10_000) : null;
+    let client;
+    try {
+        client = await run(pgDump, ['--version'], { capture: true });
+    }
+    catch {
+        throw new Error(`${pgDump} is not installed. Install the PostgreSQL ${serverMajor ?? ''} client tools (or set MAGNUS_PG_DUMP), or set MAGNUS_AUTO_MIGRATE_BACKUP=false if you back up the database another way.`.replace('  ', ' '));
+    }
+    const clientMajor = majorOf(client.stdout);
+    if (client.code !== 0 || clientMajor === null)
+        throw new Error(`${pgDump} --version failed: ${client.stderr.trim() || client.stdout.trim()}`);
+    if (serverMajor !== null && clientMajor < serverMajor) {
+        throw new Error(`${pgDump} is PostgreSQL ${clientMajor} but the server is PostgreSQL ${serverMajor}; install the PostgreSQL ${serverMajor} client and set MAGNUS_PG_DUMP to it (on Debian and Ubuntu: /usr/lib/postgresql/${serverMajor}/bin/pg_dump).`);
+    }
+    mkdirSync(options.backupDir, { recursive: true, mode: 0o700 });
+    const stamp = (options.now ?? new Date()).toISOString().replace(/[:.]/g, '-');
+    const file = join(options.backupDir, `${stamp}-${options.label.replace(/[^A-Za-z0-9._-]+/g, '_')}.dump`);
+    const result = await run(pgDump, ['--format=custom', '--no-owner', '--file', file, '--dbname', options.databaseUrl], { capture: true });
+    if (result.code !== 0)
+        throw new Error(`pg_dump failed (exit ${result.code}): ${result.stderr.trim().split('\n').slice(-3).join(' ')}`);
+    if (!existsSync(file) || statSync(file).size === 0)
+        throw new Error(`pg_dump wrote no data to ${file}`);
+    chmodSync(file, 0o600);
+    const metadataFile = `${file}.json`;
+    const restore = restoreCommand(file);
+    writeFileSync(metadataFile, `${JSON.stringify({
+        createdAt: (options.now ?? new Date()).toISOString(),
+        label: options.label,
+        postgresMajor: serverMajor,
+        pgDumpMajor: clientMajor,
+        restoreCommand: restore,
+    }, null, 2)}\n`, { mode: 0o600 });
+    return { file, metadataFile, restoreCommand: restore };
+}
+//# sourceMappingURL=migrations.js.map

package/dist/cli/preflight.js

@@ -1,8 +1,8 @@
 /** Reachability and configuration checks behind `magnus-server check`. */
-import { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import pg from 'pg';
 import { Redis } from 'ioredis';
+import { describeMigration, migrationsNeedingAttention, readMigrationState } from './migrations.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -31,20 +31,11 @@ export async function checkDatabase(url, migrationsDir) {
     }
     const results = [{ name: 'database', status: 'pass', message: `connected to ${redactUrl(url)}` }];
     try {
-        const packaged = existsSync(migrationsDir)
-            ? readdirSync(migrationsDir, { withFileTypes: true })
-                .filter(entry => entry.isDirectory() && existsSync(join(migrationsDir, entry.name, 'migration.sql')))
-                .map(entry => entry.name)
-            : [];
-        const table = await client.query(`SELECT to_regclass('public._prisma_migrations') IS NOT NULL AS exists`);
-        const applied = table.rows[0]?.exists
-            ? new Set((await client.query('SELECT migration_name FROM _prisma_migrations WHERE finished_at IS NOT NULL AND rolled_back_at IS NULL')).rows
-                .map(row => row.migration_name))
-            : new Set();
-        const pending = packaged.filter(name => !applied.has(name));
+        const { packaged, pending } = await readMigrationState(client, migrationsDir);
+        const attention = migrationsNeedingAttention(pending);
         results.push(pending.length === 0
             ? { name: 'migrations', status: 'pass', message: `${packaged.length} applied` }
-            : { name: 'migrations', status: 'warn', message: `${pending.length} pending; run \`magnus-server migrate\`` });
+            : { name: 'migrations', status: 'warn', message: `${pending.length} pending${attention.length ? ` (needs attention: ${attention.map(describeMigration).join('; ')})` : ''}; run \`magnus-server migrate\`` });
     }
     catch (error) {
         results.push({ name: 'migrations', status: 'warn', message: `cannot read migration state: ${errorMessage(error)}` });

package/dist/cli/upgrade.js

@@ -0,0 +1,55 @@
+/**
+ * `magnus-server upgrade|rollback`: the upgrade engine lives in
+ * @hivemagnus/magnus. Find the managed project this server was installed
+ * into and hand the command to the engine installed alongside it.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export const PROJECT_FILE = 'magnus-project.json';
+export function findProjectDir(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, PROJECT_FILE)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function locateProject(packageRoot, env = process.env) {
+    const configured = env['MAGNUS_PROJECT_DIR']?.trim();
+    if (configured)
+        return existsSync(join(configured, PROJECT_FILE)) ? resolve(configured) : null;
+    let real = packageRoot;
+    try {
+        real = realpathSync(packageRoot);
+    }
+    catch { /* keep the unresolved path */ }
+    return findProjectDir(real);
+}
+export async function delegateToProject(command, args, packageRoot) {
+    const dir = locateProject(packageRoot);
+    if (!dir) {
+        console.error([
+            'This magnus-server was not installed by `magnus init`, so there is no managed project to upgrade.',
+            'Either turn this install into a managed project once:',
+            '  npx @hivemagnus/magnus adopt --server-env-file <path to your server env file> [--ui-env-file <path>]',
+            'or upgrade by hand: see UPGRADING.md (https://github.com/ChefTaco/magnus/blob/main/UPGRADING.md).',
+            'Set MAGNUS_PROJECT_DIR if the project lives somewhere else.',
+        ].join('\n'));
+        return 1;
+    }
+    const engine = join(dir, 'current', 'node_modules', '@hivemagnus', 'magnus', 'dist', 'cli.js');
+    if (!existsSync(engine)) {
+        console.error(`The project at ${dir} has no upgrade engine in ./current. Run: npx @hivemagnus/magnus@latest ${command} --dir ${dir}`);
+        return 1;
+    }
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(process.execPath, [engine, command, '--dir', dir, ...args], { stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('close', code => resolvePromise(code ?? 1));
+    });
+}
+//# sourceMappingURL=upgrade.js.map