@aopslabs/aops 0.3.23 → 0.3.25

package/dist/commands/community-server.js

@@ -1,9 +1,12 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
 import { abandonInterruptedCommunityRecovery, assertCommunityLedgerHasNoNonterminalOperation, assertNoCommunityRecoveryCommitJournal, assertCommunityRecoveryMutationFence, buildCommunityComposeInvocation, inspectCommunityInstall, readCommunityBackupReceipt, reconcileCommunityRecoveryCommit, recoverCommunityUpdate, resolveCommunityInstallPaths, restoreCommunitySourceRuntime, restoreCommunityBackup, rollbackCommunityInstall, setupCommunityInstall, stageCommunityRelease, updateCommunityInstall, verifyStagedCommunityRelease, verifyCommunityBackupRecord, writeCommunityBackupReceipt, } from '../lib/community-lifecycle.js';
 import { communityProcessRuntime, createCommunityDockerAdapter } from '../lib/community-docker-adapter.js';
 import { communityCommandAbortRuntime, throwIfCommunityCommandAborted, withCommunityCommandAbortScope, } from '../lib/community-command-abort.js';
+import { compareCanonicalText } from '@aopslabs/artifact-trust-contracts';
+import { createCommunityNativeBackupV1, restoreCommunityNativeBackupV1, verifyCommunityNativeBackupV1, } from '../lib/community-native-backup.js';
 import { resolveCommunityInstanceLayout } from '../lib/community-instance-layout.js';
 import { assertCommunityOperationJournalFence, captureCommunityOperationDigests, createCommunityOperationJournal, digestsEqual, finishCommunityOperationJournal, inspectCommunityOperationJournalFile, openCommunityOperationJournalForReconciliation, runCommunityJournaledPromotion, runCommunityJournaledSideEffect, } from '../lib/community-operation-journal.js';
 import { COMMUNITY_OPERATION_LOCK_DIRECTORY_NAME, inspectCommunityOperationLock, recoverStaleCommunityOperationLock, withCommunityOperationLock, } from '../lib/community-operation-lock.js';
@@ -1479,6 +1482,30 @@ export async function runCommunityServerRollback(options, dependencies = {}) {
     });
 }
 export async function runCommunityServerBackup(options, dependencies = {}) {
+    const native = inspectNativeFrom(options);
+    if (native.status !== 'not-installed' && native.state?.postgres.mode === 'external') {
+        const paths = resolveCommunityNativePaths(installSelection(options));
+        const repoUrl = loadExternalPostgresUrl(native.state.postgres.configRef, native.state.postgres.tlsPolicy);
+        const { record, receiptPath } = await createCommunityNativeBackupV1({
+            backupRoot: paths.backupRoot,
+            repoUrl,
+            instanceName: native.state.instanceName,
+            releaseVersion: native.state.source.releaseVersion ?? null,
+            pgBinDir: options.pgBinDir,
+        });
+        writeResult({
+            status: 'community-backup-created',
+            profile: native.state.profile,
+            backup: {
+                path: record.path,
+                receiptPath,
+                sha256: record.sha256,
+                byteLength: record.byteLength,
+                kind: record.kind,
+            },
+        }, options.json);
+        return;
+    }
     await withMutatingCommandScope(dependencies, async (runtime, signal) => {
         const output = await withInstalledOperation(options, 'backup', runtime, signal, async ({ paths, state }, { journal, lifecycle }) => {
             const record = await lifecycle.createBackup({ paths, state });
@@ -1501,12 +1528,181 @@ export async function runCommunityServerBackup(options, dependencies = {}) {
         writeResult(output, options.json);
     });
 }
+function restoreGateForInstall(options) {
+    try {
+        const native = inspectNativeFrom(options);
+        return native.status !== 'not-installed' && native.state?.postgres.mode === 'external'
+            ? 'native'
+            : 'oci';
+    }
+    catch {
+        return 'either';
+    }
+}
+async function scanCommunityBackups(options) {
+    const restoreGate = options.restoreGate ?? restoreGateForInstall(options);
+    const paths = pathsFrom(options);
+    const updatesRoot = options.updatesRoot
+        ? path.resolve(options.updatesRoot)
+        : path.join(os.homedir(), '.aops', 'global-updates');
+    const entries = [];
+    const candidates = [];
+    const collect = (directory, origin) => {
+        if (!existsSync(directory))
+            return;
+        let names;
+        try {
+            names = readdirSync(directory);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.dump'))
+                continue;
+            candidates.push({ dumpPath: path.join(directory, name), origin });
+        }
+    };
+    collect(paths.backupRoot, 'instance-backup');
+    if (existsSync(updatesRoot)) {
+        let updateDirs;
+        try {
+            updateDirs = readdirSync(updatesRoot);
+        }
+        catch {
+            updateDirs = [];
+        }
+        for (const updateDir of updateDirs) {
+            collect(path.join(updatesRoot, updateDir, 'database-backup'), 'update-backup');
+        }
+    }
+    for (const candidate of candidates) {
+        let stats;
+        try {
+            stats = lstatSync(candidate.dumpPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stats.isFile())
+            continue;
+        const receiptPresent = existsSync(`${candidate.dumpPath}.json`);
+        let eligible = false;
+        let reason = null;
+        let verifiedBy = null;
+        let nativeRefusal = null;
+        if (restoreGate !== 'oci') {
+            try {
+                const record = await verifyCommunityNativeBackupV1({ backupPath: candidate.dumpPath });
+                eligible = true;
+                verifiedBy = record.verifiedBy ?? null;
+            }
+            catch (nativeError) {
+                nativeRefusal = nativeError instanceof Error ? nativeError.message : String(nativeError);
+            }
+        }
+        if (!eligible && restoreGate !== 'native') {
+            try {
+                await readCommunityBackupReceipt(paths, candidate.dumpPath);
+                eligible = true;
+            }
+            catch (ociError) {
+                const ociRefusal = ociError instanceof Error ? ociError.message : String(ociError);
+                reason = nativeRefusal === null ? ociRefusal : `native: ${nativeRefusal}; oci: ${ociRefusal}`;
+            }
+        }
+        else if (!eligible) {
+            reason = nativeRefusal;
+        }
+        entries.push({
+            path: candidate.dumpPath,
+            origin: candidate.origin,
+            byteLength: stats.size,
+            modifiedAt: new Date(stats.mtimeMs).toISOString(),
+            receiptPresent,
+            eligible,
+            reason,
+            verifiedBy,
+        });
+    }
+    entries.sort((left, right) => compareCanonicalText(right.modifiedAt, left.modifiedAt));
+    return { paths, updatesRoot, entries };
+}
+export async function runCommunityServerBackupList(options, dependencies = {}) {
+    const { paths, updatesRoot, entries } = await scanCommunityBackups(options);
+    writeResult({
+        status: 'community-backup-list',
+        mutationFree: true,
+        instance: options.instance ?? 'default',
+        searched: [paths.backupRoot, updatesRoot],
+        count: entries.length,
+        restoreGate: options.restoreGate ?? restoreGateForInstall(options),
+        eligibleCount: entries.filter((entry) => entry.eligible).length,
+        backups: entries,
+    }, options.json);
+}
+export async function resolveCommunityRestoreSource(options) {
+    const explicit = typeof options.backup === 'string' && options.backup.trim() !== '';
+    if (explicit && options.latest === true) {
+        throw new Error('community_restore_source_ambiguous:pass_either_--latest_or_--backup_not_both');
+    }
+    if (!explicit && options.latest !== true) {
+        throw new Error('community_restore_backup_path_required:pass_--backup_<path>_or_--latest');
+    }
+    if (explicit) {
+        return { backupPath: path.resolve(options.backup), selection: 'explicit', candidate: null };
+    }
+    const { entries } = await scanCommunityBackups(options);
+    const eligible = entries.filter((entry) => entry.eligible);
+    if (eligible.length === 0) {
+        const refusals = entries
+            .slice(0, 5)
+            .map((entry) => `${entry.path}: ${entry.reason ?? 'unknown'}`)
+            .join('; ');
+        throw new Error(entries.length === 0
+            ? 'community_restore_no_backup_found: no backup files were found to restore from'
+            : `community_restore_no_eligible_backup: found ${entries.length} backup file(s), none restorable (${refusals})`);
+    }
+    return { backupPath: eligible[0].path, selection: 'latest', candidate: eligible[0] };
+}
 export async function runCommunityServerRestore(options, dependencies = {}) {
-    if (!options.backup)
-        throw new Error('community_restore_backup_path_required');
+    const gate = restoreGateForInstall(options);
+    const source = await resolveCommunityRestoreSource({ ...options, restoreGate: gate });
+    if (gate === 'native') {
+        const native = inspectNativeFrom(options);
+        const postgres = native.state?.postgres;
+        if (postgres?.mode !== 'external') {
+            throw new Error('community_server_restore_native_profile_lost');
+        }
+        const paths = resolveCommunityNativePaths(installSelection(options));
+        const repoUrl = loadExternalPostgresUrl(postgres.configRef, postgres.tlsPolicy);
+        const result = await restoreCommunityNativeBackupV1({
+            backupPath: source.backupPath,
+            repoUrl,
+            backupRoot: paths.backupRoot,
+            instanceName: native.state.instanceName,
+            releaseVersion: native.state.source.releaseVersion ?? null,
+            confirmDataRewind: options.confirmDataRewind === true,
+            confirmNoUndo: options.confirmNoUndo === true,
+            skipPreRestoreBackup: options.preRestoreBackup === false,
+            pgBinDir: options.pgBinDir,
+        });
+        writeResult({
+            status: 'community-backup-restored',
+            profile: native.state.profile,
+            selection: source.selection,
+            backup: {
+                path: result.restored.path,
+                sha256: result.restored.sha256,
+                byteLength: result.restored.byteLength,
+            },
+            preRestoreBackup: result.preRestoreBackup,
+        }, options.json);
+        return;
+    }
     await withMutatingCommandScope(dependencies, async (runtime, signal) => {
         const output = await withInstalledOperation(options, 'restore', runtime, signal, async ({ paths }, { journal, receipt, lifecycle }) => {
-            const backup = await readCommunityBackupReceipt(paths, path.resolve(options.backup));
+            const backup = await readCommunityBackupReceipt(paths, source.backupPath);
             throwIfCommunityCommandAborted(signal);
             const result = await restoreCommunityBackup({
                 paths,
@@ -1520,6 +1716,7 @@ export async function runCommunityServerRestore(options, dependencies = {}) {
             throwIfCommunityCommandAborted(signal);
             return {
                 status: 'community-backup-restored',
+                selection: source.selection,
                 backup: { path: backup.path, sha256: backup.sha256, byteLength: backup.byteLength },
                 replacementVolumeName: result.replacementVolumeName,
             };
@@ -1947,7 +2144,7 @@ export async function runCommunityServerReset(options, dependencies = {}) {
 }
 function common(command) {
     return command
-        .option('--instance <name>', 'Installation instance name', 'default')
+        .option('--instance <name>', 'Installation instance name (default: "default")')
         .option('--data-root <path>', 'Absolute Community data root override')
         .option('--json', 'Output JSON');
 }
@@ -2042,11 +2239,20 @@ export function makeCommunityServerCommand(identity = {}) {
         .option('--detach', 'Start the rolled-back native server in the background (default)')
         .option('--ready-timeout-ms <milliseconds>', 'Native Server readiness budget from 1000 to 900000 ms; default 120000')
         .action((options, child) => runCommunityServerRollbackApplication(mergeCommunityCommandOptions(options, child), dependencies));
-    common(command.command('backup').description('Create and verify a custom-format PostgreSQL backup plus receipt'))
+    const backup = common(command.command('backup').description('Create and verify a custom-format PostgreSQL backup plus receipt'))
+        .option('--pg-bin-dir <path>', 'Directory containing pg_dump / pg_restore, when they are not on PATH')
         .action((options) => runCommunityServerBackup(options, dependencies));
-    const restore = common(command.command('restore').description('Restore database data; legacy flat form remains OCI-only until P4'))
+    common(backup.command('list').description('List existing backups and say which ones restore will accept'))
+        .option('--updates-root <path>', 'Global update root to scan for updater-written dumps')
+        .action((options, child) => runCommunityServerBackupList(mergeCommunityCommandOptions(options, child), dependencies));
+    const restore = common(command.command('restore').description('Restore database data; dispatches on the install profile'))
         .option('--backup <path>', 'Backup dump path; its JSON receipt must exist beside it')
+        .option('--latest', 'Restore the newest backup that restore will accept; mutually exclusive with --backup')
+        .option('--updates-root <path>', 'Global update root to scan when resolving --latest')
         .option('--confirm-data-rewind', 'Confirm that data will be rewound to the selected backup')
+        .option('--no-pre-restore-backup', 'Skip the automatic backup of the current state (native profile)')
+        .option('--confirm-no-undo', 'Required alongside --no-pre-restore-backup: there will be nothing to go back to')
+        .option('--pg-bin-dir <path>', 'Directory containing pg_restore / psql, when they are not on PATH')
         .action((options) => runCommunityServerRestore(options, dependencies));
     common(restore.command('db').description('Restore only PostgreSQL for one exact native application update'))
         .requiredOption('--update-id <id>', 'Exact native application update ID whose snapshot evidence will be used')

package/dist/commands/db.js

@@ -0,0 +1,145 @@
+import { Command } from 'commander';
+import path from 'node:path';
+import { createCommunityNativeBackupV1, restoreCommunityNativeBackupV1, } from '../lib/community-native-backup.js';
+import { inspectCommunityNativeInstall, loadExternalPostgresUrl, resolveCommunityNativePaths, } from '../lib/community-native-lifecycle.js';
+import { reportCommunityNativePendingMigrations } from '../lib/community-native-migration.js';
+import { resolveCommunityRestoreSource, runCommunityServerBackupList, } from './community-server.js';
+function selection(command) {
+    return command.optsWithGlobals();
+}
+function withCommonOptions(command) {
+    return command
+        .option('--instance <name>', 'Installation instance name')
+        .option('--data-root <path>', 'Absolute Community data root override')
+        .option('--json', 'Output JSON');
+}
+export async function runDbBackup(options) {
+    const selectionInput = { instanceName: options.instance, dataRoot: options.dataRoot };
+    const native = inspectCommunityNativeInstall(selectionInput);
+    if (native.status === 'not-installed' || !native.state) {
+        throw new Error('community_db_backup_requires_installed_native_server');
+    }
+    if (native.state.postgres.mode !== 'external') {
+        throw new Error('community_db_backup_external_postgres_only:use_aops_server_backup_for_managed_postgres');
+    }
+    const paths = resolveCommunityNativePaths(selectionInput);
+    const repoUrl = loadExternalPostgresUrl(native.state.postgres.configRef, native.state.postgres.tlsPolicy);
+    const { record, receiptPath } = await createCommunityNativeBackupV1({
+        backupRoot: paths.backupRoot,
+        repoUrl,
+        instanceName: native.state.instanceName,
+        releaseVersion: native.state.source.releaseVersion ?? null,
+        pgBinDir: options.pgBinDir,
+    });
+    const payload = {
+        status: 'community-db-backup-created',
+        instance: native.state.instanceName,
+        backup: {
+            path: record.path,
+            receiptPath,
+            sha256: record.sha256,
+            byteLength: record.byteLength,
+            kind: record.kind,
+            createdAt: record.createdAt,
+        },
+    };
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Backup written and verified.\n  ${record.path}\n  ${record.byteLength} bytes  ${record.sha256}\n`);
+}
+export async function runDbRestore(options) {
+    const selectionInput = { instanceName: options.instance, dataRoot: options.dataRoot };
+    const native = inspectCommunityNativeInstall(selectionInput);
+    if (native.status === 'not-installed' || !native.state) {
+        throw new Error('community_db_restore_requires_installed_native_server');
+    }
+    if (native.state.postgres.mode !== 'external') {
+        throw new Error('community_db_restore_external_postgres_only');
+    }
+    const source = await resolveCommunityRestoreSource({ ...options, restoreGate: 'native' });
+    const paths = resolveCommunityNativePaths(selectionInput);
+    const repoUrl = loadExternalPostgresUrl(native.state.postgres.configRef, native.state.postgres.tlsPolicy);
+    const result = await restoreCommunityNativeBackupV1({
+        backupPath: source.backupPath,
+        repoUrl,
+        backupRoot: paths.backupRoot,
+        instanceName: native.state.instanceName,
+        releaseVersion: native.state.source.releaseVersion ?? null,
+        confirmDataRewind: options.confirmDataRewind === true,
+        pgBinDir: options.pgBinDir,
+        skipPreRestoreBackup: options.preRestoreBackup === false,
+        confirmNoUndo: options.confirmNoUndo === true,
+    });
+    const reportRoot = options.sourceRoot
+        ? path.resolve(options.sourceRoot)
+        : native.state.source.root;
+    const schema = reportRoot
+        ? await reportCommunityNativePendingMigrations({ repoUrl, sourceRoot: reportRoot })
+        : { status: 'unavailable', reason: 'no source root is known, so the migration policy could not be read' };
+    const payload = {
+        status: 'community-db-restored',
+        schema,
+        instance: native.state.instanceName,
+        selection: source.selection,
+        restored: {
+            path: result.restored.path,
+            sha256: result.restored.sha256,
+            byteLength: result.restored.byteLength,
+        },
+        preRestoreBackup: result.preRestoreBackup,
+    };
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Restored ${result.restored.path}\n` +
+        (result.preRestoreBackup
+            ? `  previous state saved to ${result.preRestoreBackup.path}\n`
+            : '  no pre-restore backup was taken\n'));
+}
+export function makeDbCommand() {
+    const command = new Command('db').description('Operator database surface: full PostgreSQL backup, listing and restore');
+    withCommonOptions(command.command('backup').description('Take one full PostgreSQL backup with pg_dump and verify it'))
+        .option('--pg-bin-dir <path>', 'Directory containing pg_dump / pg_restore, when they are not on PATH')
+        .action(async (_options, child) => {
+        await runDbBackup(selection(child));
+    });
+    withCommonOptions(command.command('list').description('List backups and say which ones a restore will accept'))
+        .option('--updates-root <path>', 'Global update root to scan for updater-written dumps')
+        .action(async (_options, child) => {
+        await runCommunityServerBackupList({ ...selection(child), restoreGate: 'native' });
+    });
+    withCommonOptions(command.command('restore').description('Restore one full backup: --latest or --backup <path>'))
+        .option('--backup <path>', 'Exact backup dump to restore')
+        .option('--latest', 'Restore the newest backup a restore will accept')
+        .option('--updates-root <path>', 'Global update root to scan when resolving --latest')
+        .option('--confirm-data-rewind', 'Confirm that data will be rewound to the selected backup')
+        .option('--pg-bin-dir <path>', 'Directory containing pg_dump / pg_restore, when they are not on PATH')
+        .option('--no-pre-restore-backup', 'Skip the automatic backup of the current state; requires --confirm-no-undo')
+        .option('--confirm-no-undo', 'Acknowledge that skipping the pre-restore backup removes the ability to undo')
+        .option('--source-root <path>', 'Repository root holding the migration policy; enables the post-restore schema report')
+        .action(async (_options, child) => {
+        await runDbRestore(selection(child));
+    });
+    withCommonOptions(command.command('which').description('Print the backup that --latest would choose, without restoring'))
+        .option('--updates-root <path>', 'Global update root to scan')
+        .action(async (_options, child) => {
+        const options = selection(child);
+        const source = await resolveCommunityRestoreSource({ ...options, latest: true, restoreGate: 'native' });
+        const payload = {
+            status: 'community-db-restore-source',
+            mutationFree: true,
+            selection: source.selection,
+            backup: source.backupPath,
+            candidate: source.candidate,
+        };
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            return;
+        }
+        process.stdout.write(`--latest would restore:\n  ${source.backupPath}\n`);
+    });
+    return command;
+}

package/dist/commands/experience.js

@@ -161,7 +161,6 @@ function parseSourceRefs(values) {
 function buildExperienceMeta(options) {
     const sessionContext = compactPayload({
         sessionId: normalizeNonEmpty(options.sessionId),
-        missionId: normalizeNonEmpty(options.missionId),
         chatv3Seq: normalizeNonEmpty(options.chatv3Seq),
         pmRefs: toStringArray(options.pmRef),
         discussRefs: toStringArray(options.discussRef),
@@ -832,7 +831,6 @@ Promote a hosted experience into a durable memory item, or a playbook:
         .option('--tag <tag>', 'General tag; repeatable', collectRepeatedOption, [])
         .option('--source-ref <json-or-ref>', 'Source reference JSON or string; repeatable', collectRepeatedOption, [])
         .option('--session-id <id>', 'Session id for session-scoped experience context')
-        .option('--mission-id <id>', 'Mission id for session-scoped experience context')
         .option('--chatv3-seq <seq>', 'ChatV3 sequence anchor for session-scoped experience context')
         .option('--pm-ref <ref>', 'Projectman reference for session-scoped experience context; repeatable', collectRepeatedOption, [])
         .option('--discuss-ref <ref>', 'Discuss topic/turn reference for session-scoped experience context; repeatable', collectRepeatedOption, [])