@aopslabs/aops 0.2.0

package/dist/lib/community-docker-adapter.js

@@ -0,0 +1,498 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, writeSync, } from 'node:fs';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { buildCommunityComposeBaseInvocation, buildCommunityComposeInvocation, assertCommunityPostgresVolumeName, readCommunityRuntimePort, } from './community-lifecycle.js';
+export class CommunityProcessAbortedError extends Error {
+    code = 'COMMUNITY_OPERATION_ABORTED';
+    constructor() {
+        super('community_operation_aborted');
+        this.name = 'CommunityProcessAbortedError';
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new CommunityProcessAbortedError();
+}
+function appendBounded(current, chunk, maxBytes = 1_048_576) {
+    const next = current + chunk.toString('utf8');
+    return next.length > maxBytes ? next.slice(-maxBytes) : next;
+}
+export const communityProcessRuntime = {
+    run(invocation) {
+        return new Promise((resolve, reject) => {
+            let preparedInputFd;
+            let preparedOutputFd;
+            let ownsInputFd = false;
+            let ownsOutputFd = false;
+            try {
+                if (invocation.inputPath && invocation.inputFd !== undefined)
+                    throw new Error('community_process_multiple_inputs_refused');
+                if (invocation.outputPath && invocation.outputFd !== undefined)
+                    throw new Error('community_process_multiple_outputs_refused');
+                throwIfAborted(invocation.signal);
+                if (invocation.inputFd !== undefined) {
+                    if (!Number.isInteger(invocation.inputFd) || invocation.inputFd < 0)
+                        throw new Error('community_process_input_fd_invalid');
+                    const stat = fstatSync(invocation.inputFd, { bigint: true });
+                    if (!stat.isFile() || stat.nlink !== 1n)
+                        throw new Error('community_process_input_fd_unsafe');
+                    preparedInputFd = invocation.inputFd;
+                }
+                else if (invocation.inputPath) {
+                    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+                    preparedInputFd = openSync(invocation.inputPath, constants.O_RDONLY | noFollow);
+                    ownsInputFd = true;
+                    const stat = fstatSync(preparedInputFd, { bigint: true });
+                    if (!stat.isFile() || stat.nlink !== 1n)
+                        throw new Error('community_process_input_path_unsafe');
+                }
+                if (invocation.outputFd !== undefined) {
+                    if (!Number.isInteger(invocation.outputFd) || invocation.outputFd < 0)
+                        throw new Error('community_process_output_fd_invalid');
+                    const stat = fstatSync(invocation.outputFd, { bigint: true });
+                    if (!stat.isFile() || stat.nlink !== 1n || stat.size !== 0n)
+                        throw new Error('community_process_output_fd_unsafe');
+                    preparedOutputFd = invocation.outputFd;
+                }
+                else if (invocation.outputPath) {
+                    if (existsSync(invocation.outputPath))
+                        throw new Error('community_process_output_already_exists');
+                    mkdirSync(path.dirname(invocation.outputPath), { recursive: true });
+                    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+                    preparedOutputFd = openSync(invocation.outputPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow, 0o600);
+                    ownsOutputFd = true;
+                }
+            }
+            catch (error) {
+                if (ownsInputFd && preparedInputFd !== undefined)
+                    closeSync(preparedInputFd);
+                if (ownsOutputFd && preparedOutputFd !== undefined)
+                    closeSync(preparedOutputFd);
+                reject(error);
+                return;
+            }
+            let child;
+            try {
+                child = spawn(invocation.command, invocation.args, {
+                    env: { ...process.env, ...invocation.env },
+                    shell: false,
+                    windowsHide: true,
+                    stdio: [preparedInputFd ?? 'pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch (error) {
+                if (ownsInputFd && preparedInputFd !== undefined)
+                    closeSync(preparedInputFd);
+                if (ownsOutputFd && preparedOutputFd !== undefined)
+                    closeSync(preparedOutputFd);
+                reject(error);
+                return;
+            }
+            if (ownsInputFd && preparedInputFd !== undefined) {
+                closeSync(preparedInputFd);
+                ownsInputFd = false;
+            }
+            let stdout = '';
+            let stderr = '';
+            let outputOffset = 0;
+            let settled = false;
+            let childClosed = false;
+            let terminalError;
+            let hardKillTimer;
+            let finalKillTimer;
+            let exitCode = null;
+            let exitSignal = null;
+            const cleanup = () => {
+                invocation.signal?.removeEventListener('abort', onAbort);
+                if (hardKillTimer)
+                    clearTimeout(hardKillTimer);
+                if (finalKillTimer)
+                    clearTimeout(finalKillTimer);
+                if (ownsOutputFd && preparedOutputFd !== undefined) {
+                    closeSync(preparedOutputFd);
+                    ownsOutputFd = false;
+                }
+            };
+            const finish = () => {
+                if (settled || !childClosed)
+                    return;
+                settled = true;
+                cleanup();
+                if (terminalError)
+                    reject(terminalError);
+                else
+                    resolve({ exitCode, signal: exitSignal, stdout, stderr });
+            };
+            const safeKill = (signal) => {
+                try {
+                    return child.kill(signal);
+                }
+                catch {
+                    return false;
+                }
+            };
+            const terminate = (error) => {
+                if (settled)
+                    return;
+                terminalError ??= error;
+                child.stdin?.destroy();
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                if (!childClosed) {
+                    safeKill('SIGTERM');
+                    hardKillTimer ??= setTimeout(() => {
+                        if (!childClosed)
+                            safeKill('SIGKILL');
+                    }, 500);
+                    hardKillTimer.unref();
+                    finalKillTimer ??= setTimeout(() => {
+                        if (!childClosed && !settled) {
+                            safeKill('SIGKILL');
+                            settled = true;
+                            cleanup();
+                            reject(new Error('community_process_termination_unconfirmed:child_may_still_run=true'));
+                        }
+                    }, 3_000);
+                    finalKillTimer.unref();
+                }
+                finish();
+            };
+            const onAbort = () => terminate(new CommunityProcessAbortedError());
+            child.once('error', (error) => {
+                terminalError ??= error;
+                if (!child.pid) {
+                    childClosed = true;
+                    finish();
+                }
+            });
+            child.stderr?.on('data', (chunk) => { stderr = appendBounded(stderr, chunk); });
+            child.stdout?.on('data', (chunk) => {
+                if (settled)
+                    return;
+                if (preparedOutputFd === undefined) {
+                    stdout = appendBounded(stdout, chunk);
+                    return;
+                }
+                try {
+                    let written = 0;
+                    while (written < chunk.byteLength) {
+                        const count = writeSync(preparedOutputFd, chunk, written, chunk.byteLength - written, outputOffset + written);
+                        if (count <= 0)
+                            throw new Error('community_process_output_short_write');
+                        written += count;
+                    }
+                    outputOffset += written;
+                }
+                catch (error) {
+                    terminate(error);
+                }
+            });
+            if (preparedInputFd === undefined) {
+                child.stdin?.on('error', (error) => {
+                    if (error.code !== 'EPIPE')
+                        terminate(error);
+                });
+                child.stdin?.end();
+            }
+            child.once('close', (code, signal) => {
+                childClosed = true;
+                exitCode = code;
+                exitSignal = signal;
+                finish();
+            });
+            invocation.signal?.addEventListener('abort', onAbort, { once: true });
+            if (invocation.signal?.aborted)
+                onAbort();
+        });
+    },
+};
+function composePrefix(params) {
+    return buildCommunityComposeBaseInvocation(params);
+}
+async function runChecked(runtime, invocation) {
+    let result;
+    try {
+        throwIfAborted(invocation.signal);
+        result = await runtime.run(invocation);
+        throwIfAborted(invocation.signal);
+    }
+    catch (error) {
+        if (error instanceof CommunityProcessAbortedError || invocation.signal?.aborted) {
+            throw new CommunityProcessAbortedError();
+        }
+        throw new Error(`community_process_execution_failed:${redactDiagnostic(error instanceof Error ? error.message : String(error))}`);
+    }
+    if (result.exitCode !== 0) {
+        throw new Error(`community_process_failed:${redactDiagnostic(invocation.args.at(-1) ?? 'unknown')}:${result.exitCode}:${redactDiagnostic(result.stderr)}`);
+    }
+    return result;
+}
+function redactDiagnostic(value) {
+    return value
+        .replace(/(postgres(?:ql)?:\/\/[^:\s/@]+:)[^@\s/]+@/gi, '$1[REDACTED]@')
+        .replace(/((?:password|passwd|secret|token|api[_-]?key|authorization)\s*[=:]\s*)[^\s,;]+/gi, '$1[REDACTED]')
+        .replace(/(--(?:password|passwd|secret|token|api[_-]?key)\s+)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/(\bBearer\s+)[A-Za-z0-9._~+/-]+/gi, '$1[REDACTED]')
+        .replace(/("(?:password|passwd|secret|token|apiKey|authorization)"\s*:\s*")[^"]*(")/gi, '$1[REDACTED]$2')
+        .trim()
+        .slice(-1000);
+}
+const VOLUME_LABELS = {
+    managed: 'com.aops.community.managed',
+    installId: 'com.aops.community.install-id',
+    operationId: 'com.aops.community.operation-id',
+    claimTokenSha256: 'com.aops.community.claim-token-sha256',
+};
+function expectedVolumeLabels(claim) {
+    return {
+        [VOLUME_LABELS.managed]: 'true',
+        [VOLUME_LABELS.installId]: claim.installId,
+        [VOLUME_LABELS.operationId]: claim.operationId,
+        [VOLUME_LABELS.claimTokenSha256]: claim.claimTokenSha256,
+    };
+}
+function assertClaim(state, claim) {
+    if (claim.schemaVersion !== 1 || claim.installId !== state.installId ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(claim.operationId) ||
+        !/^sha256:[a-f0-9]{64}$/.test(claim.claimTokenSha256)) {
+        throw new Error('community_postgres_volume_claim_invalid');
+    }
+    assertCommunityPostgresVolumeName(state, claim.name);
+}
+async function inspectClaimedVolume(runtime, state, claim, signal) {
+    assertClaim(state, claim);
+    const result = await runChecked(runtime, {
+        command: 'docker',
+        args: ['volume', 'inspect', '--format', '{{json .}}', claim.name],
+        env: {},
+        signal,
+    });
+    let inspected;
+    try {
+        inspected = JSON.parse(result.stdout.trim());
+    }
+    catch (error) {
+        throw new Error('community_postgres_volume_inspect_invalid', { cause: error });
+    }
+    const labels = inspected.Labels;
+    const expected = expectedVolumeLabels(claim);
+    if (inspected.Name !== claim.name || inspected.Driver !== 'local' ||
+        !labels || typeof labels !== 'object' || Array.isArray(labels) ||
+        JSON.stringify(Object.keys(labels).sort()) !== JSON.stringify(Object.keys(expected).sort()) ||
+        Object.entries(expected).some(([key, value]) => labels[key] !== value)) {
+        throw new Error('community_postgres_volume_ownership_mismatch');
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function assertHeldBackupIdentity(backupPath, backupRoot, fd, original, rootOriginal) {
+    const root = path.resolve(backupRoot);
+    const rootStat = lstatSync(root, { bigint: true });
+    const visible = lstatSync(backupPath, { bigint: true });
+    const held = fstatSync(fd, { bigint: true });
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory() || !sameIdentity(rootStat, rootOriginal) ||
+        realpathSync.native(root) !== root ||
+        path.dirname(path.resolve(backupPath)) !== root || visible.isSymbolicLink() || !visible.isFile() || visible.nlink !== 1n ||
+        !held.isFile() || held.nlink !== 1n || !sameIdentity(held, original) || !sameIdentity(visible, original) ||
+        realpathSync.native(backupPath) !== path.resolve(backupPath)) {
+        throw new Error('community_backup_output_identity_changed');
+    }
+    return held;
+}
+function assertHeldBackupStable(fd, expected) {
+    const held = fstatSync(fd, { bigint: true });
+    if (!held.isFile() || held.nlink !== 1n || !sameIdentity(held, expected) || held.size !== expected.size ||
+        held.mtimeNs !== expected.mtimeNs || held.ctimeNs !== expected.ctimeNs) {
+        throw new Error('community_backup_output_changed_during_verification');
+    }
+    return held;
+}
+async function hashFileDescriptor(fd, expected, signal) {
+    const hash = createHash('sha256');
+    const expectedSize = Number(expected.size);
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 1)
+        throw new Error('community_backup_file_invalid');
+    const buffer = Buffer.alloc(64 * 1024);
+    let offset = 0;
+    while (offset < expectedSize) {
+        throwIfAborted(signal);
+        const count = readSync(fd, buffer, 0, Math.min(buffer.byteLength, expectedSize - offset), offset);
+        if (count <= 0)
+            throw new Error('community_backup_output_short_read');
+        hash.update(buffer.subarray(0, count));
+        offset += count;
+    }
+    throwIfAborted(signal);
+    const final = fstatSync(fd, { bigint: true });
+    if (!sameIdentity(final, expected) || final.size !== expected.size ||
+        final.mtimeNs !== expected.mtimeNs || final.ctimeNs !== expected.ctimeNs) {
+        throw new Error('community_backup_output_changed_during_hash');
+    }
+    return `sha256:${hash.digest('hex')}`;
+}
+export function createCommunityDockerAdapter(options) {
+    const runtime = options.runtime ?? communityProcessRuntime;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? (() => new Date());
+    const createId = options.createId ?? randomUUID;
+    const signal = options.signal;
+    return {
+        verifyRelease: options.verifyRelease,
+        async createBackup({ paths, state }) {
+            const backupPath = path.join(paths.backupRoot, `${now().toISOString().replace(/[:.]/g, '-')}-${createId()}.dump`);
+            const prefix = composePrefix({ paths, state });
+            const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+            const canonicalBackupRoot = realpathSync.native(paths.backupRoot);
+            const rootOriginal = lstatSync(paths.backupRoot, { bigint: true });
+            if (rootOriginal.isSymbolicLink() || !rootOriginal.isDirectory() || canonicalBackupRoot !== path.resolve(paths.backupRoot)) {
+                throw new Error('community_backup_root_unsafe');
+            }
+            const outputFd = openSync(backupPath, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | noFollow, 0o600);
+            try {
+                const original = fstatSync(outputFd, { bigint: true });
+                const rootAfterOpen = lstatSync(paths.backupRoot, { bigint: true });
+                if (!sameIdentity(rootAfterOpen, rootOriginal) || realpathSync.native(paths.backupRoot) !== canonicalBackupRoot) {
+                    throw new Error('community_backup_root_identity_changed');
+                }
+                await runChecked(runtime, {
+                    ...prefix,
+                    args: [...prefix.args, 'exec', '-T', 'postgres', 'pg_dump',
+                        '-U', 'aops', '-d', 'aops', '--format=custom', '--no-owner', '--no-privileges'],
+                    outputFd,
+                    signal,
+                });
+                fsyncSync(outputFd);
+                const dumped = assertHeldBackupIdentity(backupPath, paths.backupRoot, outputFd, original, rootOriginal);
+                if (dumped.size <= 0n)
+                    throw new Error('community_backup_file_invalid');
+                options.afterBackupDump?.(backupPath);
+                const verificationBaseline = assertHeldBackupStable(outputFd, dumped);
+                options.afterBackupVerificationBaseline?.(backupPath, outputFd);
+                assertHeldBackupStable(outputFd, verificationBaseline);
+                await runChecked(runtime, {
+                    ...prefix,
+                    args: [...prefix.args, 'exec', '-T', 'postgres', 'pg_restore', '--list'],
+                    inputFd: outputFd,
+                    signal,
+                });
+                const verified = assertHeldBackupStable(outputFd, verificationBaseline);
+                const sha256 = await hashFileDescriptor(outputFd, verified, signal);
+                const final = assertHeldBackupIdentity(backupPath, paths.backupRoot, outputFd, original, rootOriginal);
+                if (final.size !== verified.size || final.mtimeNs !== verified.mtimeNs || final.ctimeNs !== verified.ctimeNs) {
+                    throw new Error('community_backup_output_changed_after_verification');
+                }
+                return {
+                    path: backupPath,
+                    sha256,
+                    byteLength: Number(final.size),
+                    verified: true,
+                    createdAt: now().toISOString(),
+                    sourceRelease: state.activeRelease,
+                };
+            }
+            finally {
+                closeSync(outputFd);
+            }
+        },
+        async stop({ paths, state }) {
+            await runChecked(runtime, { ...buildCommunityComposeInvocation({ paths, state, action: 'down' }), signal });
+        },
+        async pull({ paths, state, release }) {
+            await runChecked(runtime, { ...buildCommunityComposeInvocation({ paths, state, release, action: 'pull' }), signal });
+        },
+        async start({ paths, state, release, postgresVolumeName }) {
+            await runChecked(runtime, { ...buildCommunityComposeInvocation({
+                    paths,
+                    state,
+                    release,
+                    postgresVolumeName,
+                    action: 'up',
+                }), signal });
+        },
+        async health({ paths }) {
+            const port = readCommunityRuntimePort(paths);
+            throwIfAborted(signal);
+            const timeoutSignal = AbortSignal.timeout(10_000);
+            const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+            let response;
+            try {
+                response = await fetchImpl(options.healthUrl ?? `http://127.0.0.1:${port}/api/health`, {
+                    signal: combinedSignal,
+                });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw new CommunityProcessAbortedError();
+                throw error;
+            }
+            try {
+                await response.body?.cancel();
+            }
+            catch {
+            }
+            throwIfAborted(signal);
+            if (!response.ok)
+                throw new Error(`community_health_failed:${response.status}`);
+        },
+        async dataSmoke({ paths, state }) {
+            const prefix = composePrefix({ paths, state });
+            const result = await runChecked(runtime, {
+                ...prefix,
+                args: [...prefix.args, 'exec', '-T', 'postgres', 'psql', '-U', 'aops', '-d', 'aops',
+                    '--tuples-only', '--no-align', '--command', 'SELECT 1'],
+                signal,
+            });
+            if (result.stdout.trim() !== '1')
+                throw new Error('community_data_smoke_failed');
+        },
+        async claimFreshPostgresVolume({ state, claim }) {
+            assertClaim(state, claim);
+            const listed = await runChecked(runtime, {
+                command: 'docker',
+                args: ['volume', 'ls', '--quiet'],
+                env: {},
+                signal,
+            });
+            const exactNames = listed.stdout.split(/\r?\n/).map((name) => name.trim()).filter(Boolean);
+            if (exactNames.includes(claim.name)) {
+                throw new Error('community_postgres_volume_already_exists');
+            }
+            const labels = expectedVolumeLabels(claim);
+            await runChecked(runtime, {
+                command: 'docker',
+                args: [
+                    'volume', 'create', '--driver', 'local',
+                    ...Object.entries(labels).flatMap(([key, value]) => ['--label', `${key}=${value}`]),
+                    claim.name,
+                ],
+                env: {},
+                signal,
+            });
+            await inspectClaimedVolume(runtime, state, claim, signal);
+        },
+        async restoreBackup({ paths, state, backup, snapshot, volumeClaim }) {
+            assertClaim(state, volumeClaim);
+            if (snapshot.sourcePath !== backup.path || snapshot.sha256 !== backup.sha256 ||
+                snapshot.byteLength !== backup.byteLength || !Number.isInteger(snapshot.fd) || snapshot.fd < 0) {
+                throw new Error('community_backup_snapshot_invalid');
+            }
+            await inspectClaimedVolume(runtime, state, volumeClaim, signal);
+            const prefix = composePrefix({ paths, state, postgresVolumeName: volumeClaim.name });
+            await runChecked(runtime, {
+                ...prefix,
+                args: [...prefix.args, 'up', '--no-build', '--detach', '--wait', 'postgres'],
+                signal,
+            });
+            await inspectClaimedVolume(runtime, state, volumeClaim, signal);
+            await runChecked(runtime, {
+                ...prefix,
+                args: [...prefix.args, 'exec', '-T', 'postgres', 'pg_restore',
+                    '-U', 'aops', '-d', 'aops', '--no-owner', '--no-privileges', '--exit-on-error'],
+                inputFd: snapshot.fd,
+                signal,
+            });
+        },
+    };
+}

package/dist/lib/community-home.js

@@ -0,0 +1,31 @@
+import { inspectCommunityInstall } from './community-lifecycle.js';
+import { inspectCommunityNativeInstall } from './community-native-lifecycle.js';
+import { getActiveApiTarget } from '../utils/config.js';
+function isRemoteTarget(apiBaseUrl) {
+    try {
+        const host = new URL(apiBaseUrl).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        return host !== 'localhost' && host !== '::1' && !/^127(?:\.\d{1,3}){3}$/.test(host);
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveCommunityHomeMode(dependencies = {}) {
+    try {
+        const native = (dependencies.inspectNative ?? inspectCommunityNativeInstall)();
+        if (native.status === 'installed')
+            return 'operate';
+        if (native.status !== 'not-installed')
+            return 'setup';
+        const oci = (dependencies.inspectOci ?? inspectCommunityInstall)();
+        if (oci.status === 'installed')
+            return 'operate';
+        if (oci.status !== 'not-installed')
+            return 'setup';
+        const activeTarget = (dependencies.getActiveTarget ?? getActiveApiTarget)();
+        return activeTarget && isRemoteTarget(activeTarget.apiBaseUrl) ? 'operate' : 'setup';
+    }
+    catch {
+        return 'setup';
+    }
+}

package/dist/lib/community-instance-contract.js

@@ -0,0 +1,148 @@
+import { resolveAopsServerEnvPath } from '@aopslabs/aops-runtime-config';
+const INSTANCE_ID = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+function instanceId(value) {
+    const normalized = (value ?? 'default').trim().toLowerCase();
+    if (!INSTANCE_ID.test(normalized))
+        throw new Error('community_instance_name_invalid');
+    return normalized;
+}
+function portNumber(value) {
+    const port = Number(value ?? 5900);
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535)
+        throw new Error('community_port_invalid');
+    return port;
+}
+function authProvider(value) {
+    const normalized = (value ?? 'trusted-local').trim().toLowerCase();
+    if (normalized === 'trusted-local')
+        return normalized;
+    if (normalized === 'authv2-jwt-session' || normalized === 'remote-session') {
+        throw new Error('community_setup_local_auth_retired:use_--auth_trusted-local_or_a_remote-session_target');
+    }
+    throw new Error('community_setup_auth_invalid:use_--auth_trusted-local');
+}
+export function buildCommunityInstanceContract(input) {
+    if (input.runtime !== 'native' && input.runtime !== 'oci') {
+        throw new Error('community_setup_runtime_required:use_--runtime_native_or_oci');
+    }
+    const runtime = input.runtime;
+    const exposure = input.exposure ?? 'loopback';
+    if (exposure !== 'loopback' && exposure !== 'authenticated-network' && exposure !== 'container') {
+        throw new Error('community_setup_exposure_invalid:use_--exposure_loopback_or_container');
+    }
+    const selectedAuthProvider = authProvider(input.auth);
+    const port = portNumber(input.port);
+    const publicPort = portNumber(input.publicPort ?? port);
+    if (exposure === 'loopback' && input.publicPort !== undefined && publicPort !== port) {
+        throw new Error('community_setup_public_port_requires_container_exposure');
+    }
+    if (exposure === 'authenticated-network' && input.publicPort !== undefined && publicPort !== port) {
+        throw new Error('community_setup_public_port_requires_container_exposure');
+    }
+    if (exposure === 'container' && port !== 5900) {
+        throw new Error('community_setup_container_exposure_port_required:5900');
+    }
+    if (exposure === 'authenticated-network') {
+        throw new Error('community_setup_authenticated_network_retired:use_a_remote-session_target');
+    }
+    if (exposure === 'container' && selectedAuthProvider !== 'trusted-local') {
+        throw new Error('community_setup_container_requires_trusted-local');
+    }
+    const host = '127.0.0.1';
+    const server = Object.freeze({
+        host,
+        port,
+        exposure,
+        publicPort,
+        authProvider: selectedAuthProvider,
+    });
+    const base = {
+        schemaVersion: 1,
+        instanceId: instanceId(input.instance),
+        runtime,
+        server,
+        lifecycleAuthority: 'local-instance',
+    };
+    if (runtime === 'oci') {
+        if (input.postgres || input.postgresConfig || input.postgresTls ||
+            input.exposure !== undefined || input.auth !== undefined || input.publicPort !== undefined) {
+            throw new Error('community_setup_oci_native_options_refused');
+        }
+        return Object.freeze({
+            ...base,
+            profile: 'oci-managed-stack',
+            postgres: Object.freeze({ mode: 'managed-stack' }),
+            implementation: 'oci-v1-adapter',
+        });
+    }
+    if (input.postgres !== 'external' && input.postgres !== 'container') {
+        throw new Error('community_setup_native_postgres_required:use_--postgres_external_or_container');
+    }
+    if (input.postgres === 'container') {
+        if (input.postgresConfig || input.postgresTls) {
+            throw new Error('community_setup_container_postgres_external_options_refused');
+        }
+        if (exposure !== 'loopback') {
+            throw new Error('community_setup_managed_postgres_requires_loopback_exposure');
+        }
+        return Object.freeze({
+            ...base,
+            profile: 'native-container-postgres',
+            postgres: Object.freeze({ mode: 'container' }),
+            implementation: 'native-v1-supervisor',
+        });
+    }
+    if (!['disable', 'require', 'verify-full'].includes(String(input.postgresTls))) {
+        throw new Error('community_setup_external_postgres_tls_required:use_--postgres-tls');
+    }
+    const configInput = input.postgresConfig?.trim();
+    if (configInput) {
+        const isWindowsPath = /^[A-Za-z]:[\\/]/.test(configInput);
+        if (/[\0\r\n]/.test(configInput) ||
+            (!isWindowsPath && /^[A-Za-z][A-Za-z0-9+.-]*:/.test(configInput)) ||
+            /[=@;]/.test(configInput) ||
+            /(?:^|\s)(?:host|user|password|pwd|dbname|server|data\s+source|user\s+id|uid|database|initial\s+catalog|pghost|pgport|pgdatabase|pguser|pgpassword|pgservice|pgsslmode)\s*=/i.test(configInput)) {
+            throw new Error('community_setup_external_postgres_config_must_be_file_reference');
+        }
+    }
+    const configRef = resolveAopsServerEnvPath({ explicitPath: configInput }, input.processEnv ?? process.env).path;
+    return Object.freeze({
+        ...base,
+        profile: 'native-external-postgres',
+        postgres: Object.freeze({
+            mode: 'external',
+            configRef,
+            tlsPolicy: input.postgresTls,
+        }),
+        implementation: 'native-v1-supervisor',
+    });
+}
+export function parseCommunityInstanceContract(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('community_instance_contract_invalid');
+    }
+    const input = value;
+    const ociRuntime = input.runtime === 'oci';
+    if (ociRuntime &&
+        ((input.server?.exposure !== undefined && input.server.exposure !== 'loopback') ||
+            (input.server?.authProvider !== undefined && input.server.authProvider !== 'trusted-local') ||
+            (input.server?.host !== undefined && input.server.host !== '127.0.0.1') ||
+            (input.server?.publicPort !== undefined && input.server.publicPort !== input.server?.port)))
+        throw new Error('community_instance_contract_oci_server_invalid');
+    const rebuilt = buildCommunityInstanceContract({
+        runtime: input.runtime,
+        postgres: input.postgres?.mode === 'managed-stack' ? undefined : input.postgres?.mode,
+        postgresConfig: input.postgres?.configRef,
+        postgresTls: input.postgres?.tlsPolicy,
+        exposure: ociRuntime ? undefined : input.server?.exposure,
+        auth: ociRuntime ? undefined : input.server?.authProvider,
+        publicPort: ociRuntime ? undefined : input.server?.publicPort,
+        instance: input.instanceId,
+        port: input.server?.port,
+    });
+    if (input.schemaVersion !== 1 || input.profile !== rebuilt.profile ||
+        input.lifecycleAuthority !== 'local-instance' || input.implementation !== rebuilt.implementation) {
+        throw new Error('community_instance_contract_schema_invalid');
+    }
+    return rebuilt;
+}