@aopslabs/aops 0.2.0

package/dist/lib/setup-readiness.js

@@ -0,0 +1,888 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { readAopsServerEnvConfig, resolveAopsServerEnvPath, } from '@aopslabs/aops-runtime-config';
+import { inspectCommunityInstall } from './community-lifecycle.js';
+import { buildCommunityPnpmInvocation, isCommunityNativeNpmPackageSource, inspectCommunityNativeInstall, inspectCommunityNativeSource, loadExternalPostgresUrl, loadExternalServerAuthConfig, resolveCommunityNativeCockpitPort, resolveCommunityNativeDefaultSourceRoot, } from './community-native-lifecycle.js';
+import { buildCommunityInstanceContract, } from './community-instance-contract.js';
+import { createCliApiClientFromOptions, fetchCliBootstrapHealth } from '../utils/api.js';
+import { findApiTargetByBaseUrlReadOnly, getActiveApiTargetReadOnly, getApiTargetReadOnly, } from '../utils/config.js';
+import { inspectSetupAgentAssets, } from './setup-agent-assets-bridge.js';
+import { inspectLocalPostgres, } from './setup-local-postgres.js';
+import { createCommunityDiagnostic } from './community-diagnostic.js';
+export const SETUP_PATHS = [
+    {
+        id: 'native-external',
+        number: '1',
+        title: 'Npm server with your existing PostgreSQL',
+    },
+    {
+        id: 'native-container',
+        number: '2',
+        title: 'Npm server with automatic Docker PostgreSQL',
+    },
+    {
+        id: 'native-local',
+        number: '3',
+        title: 'Npm server with PostgreSQL installed on this computer',
+    },
+    {
+        id: 'cli-existing',
+        number: '4',
+        title: 'CLI connected to an existing AOPS server',
+    },
+];
+export function normalizeBootstrapAuthContract(bootstrap) {
+    const auth = bootstrap.auth && typeof bootstrap.auth === 'object'
+        ? bootstrap.auth
+        : null;
+    const providerValue = bootstrap.authProvider ?? auth?.provider;
+    const authProvider = providerValue === 'trusted-local'
+        ? 'trusted-local'
+        : providerValue === 'remote-session' || providerValue === 'authv2-jwt-session'
+            ? 'remote-session'
+            : null;
+    const explicitAuthRequired = typeof bootstrap.authRequired === 'boolean' ? bootstrap.authRequired : null;
+    const authRequired = explicitAuthRequired !== null
+        ? explicitAuthRequired === (authProvider === 'remote-session')
+            ? explicitAuthRequired
+            : null
+        : authProvider !== null
+            ? authProvider === 'remote-session'
+            : null;
+    const firstAdminState = auth && typeof auth.firstAdminState === 'string'
+        ? auth.firstAdminState
+        : null;
+    return {
+        authProvider,
+        authRequired,
+        firstAdminState: firstAdminState === 'not-applicable' || firstAdminState === 'required' ||
+            firstAdminState === 'ready' || firstAdminState === 'blocked' || firstAdminState === 'unknown'
+            ? firstAdminState
+            : null,
+    };
+}
+function normalizeNonEmpty(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized || undefined;
+}
+function normalizeSafeApiBaseUrl(value) {
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        return undefined;
+    try {
+        const parsed = new URL(normalized);
+        if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password ||
+            parsed.search || parsed.hash || parsed.pathname !== '/') {
+            throw new Error('setup_api_base_url_invalid');
+        }
+        return parsed.origin;
+    }
+    catch {
+        throw new Error('setup_api_base_url_invalid');
+    }
+}
+function normalizePort(value) {
+    const port = Number(value ?? 5900);
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+        throw new Error('setup_port_invalid');
+    }
+    return port;
+}
+export function parseSetupPath(value) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    if (!normalized)
+        return undefined;
+    return SETUP_PATHS.find((entry) => entry.id === normalized || entry.number === normalized)?.id;
+}
+function pathDescriptor(id) {
+    return id ? SETUP_PATHS.find((entry) => entry.id === id) : undefined;
+}
+function isLoopbackUrl(value) {
+    try {
+        const host = new URL(value).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host);
+    }
+    catch {
+        return false;
+    }
+}
+function isLoopbackPostgresAtPort(value, port) {
+    try {
+        const parsed = new URL(value);
+        return isLoopbackUrl(value) && Number(parsed.port || 5432) === port;
+    }
+    catch {
+        return false;
+    }
+}
+function commandAvailable(command) {
+    const locator = process.platform === 'win32' ? 'where.exe' : 'which';
+    const result = spawnSync(locator, [command], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 1_000,
+        stdio: 'ignore',
+    });
+    return result.status === 0;
+}
+function dockerRuntimeAvailable(compose) {
+    const info = spawnSync('docker', ['info', '--format', '{{json .ServerVersion}}'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 2_000,
+        stdio: 'ignore',
+    });
+    if (info.status !== 0)
+        return false;
+    if (!compose)
+        return true;
+    const composeVersion = spawnSync('docker', ['compose', 'version'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 2_000,
+        stdio: 'ignore',
+    });
+    return composeVersion.status === 0;
+}
+function safeReason(error, fallback) {
+    const message = error instanceof Error ? error.message : '';
+    return /^[a-z0-9_:-]+$/i.test(message) ? message : fallback;
+}
+function inferInstalledPath(native, oci) {
+    if (native.status === 'installed' && native.state?.profile === 'native-external-postgres') {
+        return 'native-external';
+    }
+    if (native.status === 'installed' && native.state?.profile === 'native-container-postgres') {
+        return 'native-container';
+    }
+    return undefined;
+}
+function installationStateCheck(selected, native, oci, desiredSecurity) {
+    if (!selected) {
+        return {
+            id: 'installation-state',
+            state: 'unknown',
+            required: false,
+            summary: 'Installation state will be evaluated after a path is selected.',
+        };
+    }
+    if (selected === 'cli-existing') {
+        return {
+            id: 'installation-state',
+            state: 'not-applicable',
+            required: false,
+            summary: 'The CLI-only path does not install a local server runtime.',
+        };
+    }
+    if (oci.status !== 'not-installed') {
+        return {
+            id: 'installation-state',
+            state: 'action-required',
+            required: true,
+            summary: 'A legacy application-image installation owns this local instance.',
+            next: 'Use the explicit server lifecycle to inspect or remove that installation before selecting an npm-server setup path.',
+            data: { blocking: true, legacyProfile: 'oci-managed-stack' },
+        };
+    }
+    const installedPath = inferInstalledPath(native, oci);
+    const compatibleInstalledPath = selected === 'native-local' && installedPath === 'native-external'
+        ? selected
+        : installedPath;
+    if (compatibleInstalledPath && compatibleInstalledPath !== selected) {
+        return {
+            id: 'installation-state',
+            state: 'action-required',
+            required: true,
+            summary: 'A different local installation profile already owns this instance.',
+            next: 'Use the installed path, or run the explicit migration/reset workflow before switching paths.',
+            data: { blocking: true, selectedPath: selected, installedPath },
+        };
+    }
+    if (native.status === 'runtime-conflict' || (native.status !== 'not-installed' && oci.status !== 'not-installed')) {
+        const diagnostic = createCommunityDiagnostic(new Error(native.error ?? 'community_instance_runtime_conflict'), {
+            code: 'setup_install_runtime_conflict',
+            phase: 'readiness',
+            summary: 'Conflicting local runtime state requires repair before setup can continue.',
+            nextActions: ['Run `aops doctor --json` and resolve the reported runtime conflict.'],
+        });
+        return {
+            id: 'installation-state',
+            state: 'action-required',
+            required: true,
+            summary: diagnostic.summary,
+            next: diagnostic.nextActions[0],
+            data: {
+                blocking: true,
+                reasonCode: diagnostic.cause.code,
+                phase: diagnostic.phase,
+                diagnostic,
+            },
+        };
+    }
+    const expected = selected === 'native-external' || selected === 'native-local'
+        ? native.status === 'installed' && native.state?.profile === 'native-external-postgres'
+        : selected === 'native-container'
+            ? native.status === 'installed' && native.state?.profile === 'native-container-postgres'
+            : false;
+    const partial = native.status === 'partial';
+    if (partial) {
+        const diagnostic = createCommunityDiagnostic(new Error(native.error ?? 'community_native_install_partial'), {
+            code: 'setup_install_state_incomplete',
+            phase: 'readiness',
+        });
+        return {
+            id: 'installation-state',
+            state: 'action-required',
+            required: true,
+            summary: diagnostic.summary,
+            next: diagnostic.nextActions[0] ?? 'Run `aops doctor --json` before resuming setup.',
+            data: {
+                blocking: true,
+                reasonCode: diagnostic.cause.code,
+                phase: diagnostic.phase,
+                diagnostic,
+            },
+        };
+    }
+    if (expected) {
+        const authProvider = native.state?.server?.authProvider;
+        const exposure = native.state?.server?.exposure;
+        const securityMatches = !desiredSecurity ||
+            (authProvider === desiredSecurity.authProvider &&
+                exposure === desiredSecurity.exposure);
+        if (!securityMatches) {
+            return {
+                id: 'installation-state',
+                state: 'action-required',
+                required: true,
+                summary: 'The installed server security mode differs from the selected mode.',
+                next: 'Apply the selected setup path to reconfigure server authentication and exposure.',
+                data: {
+                    installed: true,
+                    securityMatches: false,
+                    authProvider: authProvider ?? null,
+                    exposure: exposure ?? null,
+                    desiredAuthProvider: desiredSecurity.authProvider,
+                    desiredExposure: desiredSecurity.exposure,
+                },
+            };
+        }
+        return {
+            id: 'installation-state',
+            state: 'ready',
+            required: true,
+            summary: 'The selected local installation profile is present.',
+            data: {
+                installed: true,
+                securityMatches,
+                authProvider: authProvider ?? null,
+                exposure: exposure ?? null,
+            },
+        };
+    }
+    return {
+        id: 'installation-state',
+        state: 'action-required',
+        required: true,
+        summary: 'The selected local installation profile is not installed yet.',
+        next: 'Run `aops setup init --apply` to continue the selected setup path.',
+    };
+}
+async function probeEndpoint(options) {
+    try {
+        const api = await createCliApiClientFromOptions({
+            apiBaseUrl: options.apiBaseUrl,
+            targetName: options.targetName,
+            timeoutMs: options.timeoutMs,
+            readOnly: true,
+        });
+        const bootstrap = await fetchCliBootstrapHealth(api, {
+            timeoutMs: options.timeoutMs,
+        });
+        const { authProvider, authRequired, firstAdminState } = normalizeBootstrapAuthContract(bootstrap);
+        let authenticated = authRequired === false ? true : authRequired === true ? false : null;
+        let principalUserId = null;
+        if (authRequired === true) {
+            try {
+                const me = await api.client.requestXfJson('/api/auth/me', { method: 'GET' }, { retry401: false, timeoutMs: options.timeoutMs });
+                const userId = me.result?.data?.principal?.userId;
+                principalUserId = typeof userId === 'string' && userId.trim() ? userId.trim() : null;
+                authenticated =
+                    me.status === 200 &&
+                        me.result?.ok === true &&
+                        Boolean(principalUserId) &&
+                        me.result?.data?.authProvider === authProvider &&
+                        me.result?.data?.authRequired === authRequired;
+            }
+            catch {
+                authenticated = false;
+            }
+        }
+        return {
+            reachable: true,
+            authRequired,
+            authProvider,
+            authenticated,
+            principalUserId,
+            firstAdminState,
+        };
+    }
+    catch {
+        return {
+            reachable: false,
+            authRequired: null,
+            authProvider: null,
+            authenticated: null,
+            principalUserId: null,
+            firstAdminState: null,
+        };
+    }
+}
+async function probeCockpit(origin, timeoutMs) {
+    const request = async (pathname) => {
+        try {
+            const response = await fetch(`${origin}${pathname}`, {
+                headers: pathname.startsWith('/api') ? { origin } : undefined,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    const [reachable, apiReachable] = await Promise.all([
+        request('/_aops/cockpit-health'),
+        request('/api/health'),
+    ]);
+    return { reachable, apiReachable, origin };
+}
+function agentAssetCheck(status) {
+    if (status.availability === 'task-136-pending') {
+        return {
+            id: 'agent-assets',
+            state: 'action-required',
+            required: false,
+            summary: status.summary,
+            next: status.nextActions[0],
+            data: status.data,
+        };
+    }
+    return status.state === 'ready'
+        ? {
+            id: 'agent-assets',
+            state: 'ready',
+            required: true,
+            summary: status.summary,
+            data: status.data,
+        }
+        : {
+            id: 'agent-assets',
+            state: 'action-required',
+            required: true,
+            summary: status.summary,
+            next: status.nextActions[0],
+            data: status.data,
+        };
+}
+export async function inspectSetupReadiness(options = {}) {
+    const processEnv = options.processEnv ?? process.env;
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const probes = options.probes ?? {};
+    const explicitApiBaseUrl = normalizeSafeApiBaseUrl(options.apiBaseUrl);
+    const localPort = normalizePort(options.port);
+    const native = probes.nativeInspection ?? inspectCommunityNativeInstall({
+        instanceName: options.instance,
+        dataRoot: options.dataRoot,
+    });
+    const oci = probes.ociInspection ?? inspectCommunityInstall({
+        instanceName: options.instance,
+        dataRoot: options.dataRoot,
+    });
+    let activeTarget = probes.activeTarget ?? null;
+    if (probes.activeTarget === undefined) {
+        try {
+            activeTarget = getActiveApiTargetReadOnly() ?? null;
+        }
+        catch {
+            activeTarget = null;
+        }
+    }
+    const requestedTargetName = normalizeNonEmpty(options.targetName);
+    let selectedTarget = probes.selectedTarget ?? null;
+    if (probes.selectedTarget === undefined) {
+        try {
+            if (requestedTargetName) {
+                selectedTarget =
+                    getApiTargetReadOnly(requestedTargetName) ?? null;
+            }
+            else if (explicitApiBaseUrl) {
+                selectedTarget =
+                    findApiTargetByBaseUrlReadOnly(explicitApiBaseUrl) ?? null;
+            }
+            else {
+                selectedTarget = activeTarget;
+            }
+        }
+        catch {
+            selectedTarget = null;
+        }
+    }
+    if (selectedTarget &&
+        explicitApiBaseUrl &&
+        selectedTarget.apiBaseUrl !== explicitApiBaseUrl) {
+        selectedTarget = null;
+    }
+    if (probes.selectedTarget === undefined &&
+        probes.activeTarget !== undefined &&
+        !requestedTargetName &&
+        explicitApiBaseUrl) {
+        selectedTarget = activeTarget?.apiBaseUrl === explicitApiBaseUrl ? activeTarget : null;
+    }
+    const explicitPath = parseSetupPath(options.path);
+    const installedPath = inferInstalledPath(native, oci);
+    const activeTargetPath = selectedTarget && !isLoopbackUrl(selectedTarget.apiBaseUrl) ? 'cli-existing' : undefined;
+    const selected = explicitPath ?? installedPath ?? activeTargetPath;
+    const descriptor = pathDescriptor(selected);
+    const desiredSecurity = options.auth && options.exposure
+        ? Object.freeze({
+            authProvider: options.auth,
+            exposure: options.exposure,
+        })
+        : undefined;
+    const source = explicitPath
+        ? 'explicit'
+        : installedPath
+            ? 'installed-state'
+            : activeTargetPath
+                ? 'active-target'
+                : 'unselected';
+    const checks = [
+        descriptor
+            ? {
+                id: 'installation-path',
+                state: 'ready',
+                required: true,
+                summary: `Path ${descriptor.number} selected: ${descriptor.title}.`,
+                data: {
+                    id: descriptor.id,
+                    number: descriptor.number,
+                    ...(desiredSecurity
+                        ? {
+                            authProvider: desiredSecurity.authProvider,
+                            exposure: desiredSecurity.exposure,
+                            desiredAuthProvider: desiredSecurity.authProvider,
+                            desiredExposure: desiredSecurity.exposure,
+                        }
+                        : {}),
+                },
+            }
+            : {
+                id: 'installation-path',
+                state: 'action-required',
+                required: true,
+                summary: 'No installation path has been selected or inferred.',
+                next: 'Choose path 1, 2, 3, or 4.',
+                data: { choices: SETUP_PATHS },
+            },
+    ];
+    checks.push(installationStateCheck(selected, native, oci, desiredSecurity));
+    const explicitPostgresConfig = normalizeNonEmpty(options.postgresConfig);
+    const safePostgresConfig = explicitPostgresConfig
+        ? buildCommunityInstanceContract({
+            runtime: 'native',
+            postgres: 'external',
+            postgresConfig: explicitPostgresConfig,
+            postgresTls: options.postgresTls ?? 'require',
+            processEnv,
+        }).postgres.configRef
+        : undefined;
+    const envResolution = resolveAopsServerEnvPath({ explicitPath: safePostgresConfig }, processEnv);
+    let envSnapshot;
+    let envError;
+    try {
+        envSnapshot = readAopsServerEnvConfig(processEnv, envResolution.path);
+    }
+    catch (error) {
+        envError = safeReason(error, 'aops_server_env_invalid');
+    }
+    if (selected === 'native-external' || selected === 'native-local') {
+        const postgresEnvReady = Boolean(envSnapshot?.exists && envSnapshot.repoDialect === 'pg' && envSnapshot.repoUrl);
+        let envAuthProvider = null;
+        let envAuthError = null;
+        if (envSnapshot?.exists) {
+            const configuredProvider = String(envSnapshot.assignments.AOPS_AUTH_PROVIDER ?? 'trusted-local')
+                .trim()
+                .toLowerCase();
+            try {
+                if (configuredProvider !== 'trusted-local') {
+                    throw new Error('community_local_auth_provider_retired:repair_with_trusted-local');
+                }
+                envAuthProvider = loadExternalServerAuthConfig(envResolution.path, 'trusted-local').authProvider;
+            }
+            catch (error) {
+                envAuthError = safeReason(error, 'aops_server_env_auth_invalid');
+            }
+        }
+        const authEnvReady = envAuthProvider !== null;
+        const authProviderMatches = !desiredSecurity || envAuthProvider === desiredSecurity.authProvider;
+        const selectedLocalPostgresPort = Number(options.localPostgresPort ?? 5432);
+        const localPostgresTargetMatches = selected !== 'native-local' || isLoopbackPostgresAtPort(String(envSnapshot?.repoUrl ?? ''), selectedLocalPostgresPort);
+        const postgresReady = postgresEnvReady && localPostgresTargetMatches;
+        const envReady = postgresReady && authEnvReady && authProviderMatches;
+        checks.push({
+            id: 'global-server-env',
+            state: envReady ? 'ready' : 'action-required',
+            required: true,
+            summary: envReady
+                ? 'The selected server env contains a PostgreSQL repository target.'
+                : postgresEnvReady && authEnvReady && !authProviderMatches
+                    ? 'The selected server env authentication provider does not match the selected server mode.'
+                    : postgresEnvReady && !authEnvReady
+                        ? 'The selected server env has an invalid authentication provider or AuthV2 secret closure.'
+                        : selected === 'native-local' && postgresEnvReady
+                            ? 'The selected server env points to a non-local PostgreSQL target or a different local port.'
+                            : 'The selected server env is missing, unsafe, or does not contain a PostgreSQL target.',
+            next: envReady
+                ? undefined
+                : postgresEnvReady && authEnvReady && !authProviderMatches
+                    ? `Run \`aops setup server-env --auth ${desiredSecurity.authProvider}\` for the selected private env.`
+                    : selected === 'native-local'
+                        ? 'Path 3 creates a private local server env during apply; use `--postgres-config <private-path>` to preserve an existing remote env, or use path 1 for that remote target.'
+                        : 'Run `aops setup server-env` or provide a safe `--postgres-config` file path.',
+            data: {
+                path: envResolution.path,
+                source: envResolution.source,
+                exists: envSnapshot?.exists ?? false,
+                repoDialect: envSnapshot?.repoDialect ?? null,
+                redactedRepoUrl: envSnapshot?.redactedRepoUrl ?? null,
+                postgresReady,
+                localPostgresTargetMatches,
+                authProvider: envAuthProvider,
+                desiredAuthProvider: desiredSecurity?.authProvider ?? null,
+                authProviderMatches,
+                authError: envAuthError,
+                error: envError ?? null,
+                blocking: selected === 'native-local' &&
+                    postgresEnvReady &&
+                    !localPostgresTargetMatches,
+            },
+        });
+        const installedPostgresTls = source === 'installed-state' &&
+            native.status === 'installed' &&
+            native.state?.profile === 'native-external-postgres'
+            ? native.state.postgres.tlsPolicy
+            : undefined;
+        const tlsPolicy = selected === 'native-local'
+            ? 'disable'
+            : options.postgresTls ?? installedPostgresTls;
+        if (!tlsPolicy) {
+            checks.push({
+                id: 'postgresql-tls',
+                state: 'action-required',
+                required: true,
+                summary: 'A PostgreSQL TLS policy has not been selected.',
+                next: 'Choose require (default), verify-full, or an explicit disable policy.',
+            });
+        }
+        else if (!envReady) {
+            checks.push({
+                id: 'postgresql-tls',
+                state: 'action-required',
+                required: true,
+                summary: 'PostgreSQL TLS readiness cannot be validated until the server env is ready.',
+                data: { policy: tlsPolicy },
+            });
+        }
+        else {
+            try {
+                loadExternalPostgresUrl(envResolution.path, tlsPolicy);
+                checks.push({
+                    id: 'postgresql-tls',
+                    state: 'ready',
+                    required: true,
+                    summary: `PostgreSQL configuration satisfies the ${tlsPolicy} TLS policy.`,
+                    data: { policy: tlsPolicy },
+                });
+            }
+            catch (error) {
+                checks.push({
+                    id: 'postgresql-tls',
+                    state: 'action-required',
+                    required: true,
+                    summary: 'PostgreSQL or TLS configuration is not ready.',
+                    next: 'Repair the selected server env and TLS root certificate reference.',
+                    data: { policy: tlsPolicy, error: safeReason(error, 'postgresql_tls_config_invalid') },
+                });
+            }
+        }
+    }
+    else {
+        checks.push({
+            id: 'global-server-env',
+            state: 'not-applicable',
+            required: false,
+            summary: 'This path does not require an external PostgreSQL server env.',
+            data: { path: envResolution.path, source: envResolution.source },
+        });
+        checks.push({
+            id: 'postgresql-tls',
+            state: 'not-applicable',
+            required: false,
+            summary: 'External PostgreSQL TLS configuration is not used by this path.',
+        });
+    }
+    if (selected === 'native-local') {
+        const local = probes.localPostgres ?? await inspectLocalPostgres({
+            host: options.localPostgresHost,
+            port: options.localPostgresPort,
+            timeoutMs: options.timeoutMs,
+        });
+        const next = local.reachable
+            ? undefined
+            : [local.guidance.summary, ...local.guidance.commands, local.guidance.url].join(' ');
+        checks.push({
+            id: 'local-postgresql',
+            state: local.reachable ? 'ready' : 'action-required',
+            required: true,
+            summary: local.reachable
+                ? `A local PostgreSQL endpoint is reachable at ${local.host}:${local.port}.`
+                : local.status === 'installed-not-running'
+                    ? `PostgreSQL tools were found, but no server is reachable at ${local.host}:${local.port}.`
+                    : `PostgreSQL was not detected at ${local.host}:${local.port}.`,
+            next,
+            data: {
+                host: local.host,
+                port: local.port,
+                status: local.status,
+                psqlAvailable: local.psqlAvailable,
+                psqlVersion: local.psqlVersion,
+                install: local.reachable ? null : local.guidance,
+            },
+        });
+    }
+    else {
+        checks.push({
+            id: 'local-postgresql',
+            state: 'not-applicable',
+            required: false,
+            summary: 'Local PostgreSQL discovery and provisioning are not used by this path.',
+        });
+    }
+    const hasCommand = probes.commandAvailable ?? commandAvailable;
+    if (selected === 'native-external' || selected === 'native-container' || selected === 'native-local') {
+        const selectedSourceRoot = path.resolve(options.sourceRoot ?? resolveCommunityNativeDefaultSourceRoot(cwd));
+        let nativeSourceReady = false;
+        let npmPackage = false;
+        let nativeSourceError = null;
+        if (probes.commandAvailable) {
+            nativeSourceReady = options.sourceRoot ? hasCommand('pnpm') : true;
+        }
+        else {
+            try {
+                inspectCommunityNativeSource(selectedSourceRoot);
+                npmPackage = isCommunityNativeNpmPackageSource(selectedSourceRoot);
+                if (!npmPackage)
+                    buildCommunityPnpmInvocation(selectedSourceRoot, ['--version'], processEnv);
+                nativeSourceReady = true;
+            }
+            catch (error) {
+                nativeSourceError = safeReason(error, 'community_native_source_runtime_invalid');
+            }
+        }
+        const needsDocker = selected === 'native-container';
+        const dockerReady = !needsDocker
+            ? true
+            : probes.commandAvailable
+                ? hasCommand('docker')
+                : hasCommand('docker') && dockerRuntimeAvailable(false);
+        const runtimeReady = nativeSourceReady && dockerReady;
+        checks.push({
+            id: 'runtime',
+            state: runtimeReady ? 'ready' : 'action-required',
+            required: true,
+            summary: runtimeReady
+                ? npmPackage
+                    ? 'The installed npm server runtime is ready; no source build is required.'
+                    : 'Native source runtime requirements are available.'
+                : needsDocker
+                    ? 'The installed npm server runtime (or an explicit source checkout) and a running Docker daemon are required.'
+                    : 'Install the matching @aopslabs/aops-server package separately, or provide a valid development checkout with pnpm 11.',
+            next: runtimeReady
+                ? undefined
+                : needsDocker
+                    ? 'Install and start Docker Desktop/Engine, then retry the npm-server setup.'
+                    : 'Install the matching npm server package or provide a valid Community source checkout.',
+            data: {
+                node: process.version,
+                sourceRoot: selectedSourceRoot,
+                sourceKind: npmPackage ? 'npm-package' : 'source-checkout',
+                nativeSource: nativeSourceReady,
+                docker: needsDocker ? dockerReady : null,
+                error: nativeSourceError,
+            },
+        });
+    }
+    else if (selected === 'cli-existing') {
+        checks.push({
+            id: 'runtime',
+            state: 'not-applicable',
+            required: false,
+            summary: 'The CLI-only path does not require a local server or container runtime.',
+        });
+    }
+    else {
+        checks.push({
+            id: 'runtime',
+            state: 'unknown',
+            required: false,
+            summary: 'Runtime requirements depend on the selected installation path.',
+        });
+    }
+    const endpointUrl = selected === 'cli-existing'
+        ? explicitApiBaseUrl ?? selectedTarget?.apiBaseUrl
+        : explicitApiBaseUrl ?? `http://127.0.0.1:${localPort}`;
+    const endpoint = probes.endpoint ?? (endpointUrl
+        ? await probeEndpoint({
+            apiBaseUrl: endpointUrl,
+            targetName: selected === 'cli-existing' ? selectedTarget?.name : undefined,
+            timeoutMs: options.timeoutMs ?? 1_500,
+        })
+        : {
+            reachable: false,
+            authRequired: null,
+            authProvider: null,
+            authenticated: null,
+            principalUserId: null,
+            firstAdminState: null,
+        });
+    checks.push({
+        id: 'host',
+        state: endpoint.reachable ? 'ready' : 'action-required',
+        required: true,
+        summary: endpoint.reachable
+            ? `${selected === 'cli-existing' ? 'Remote' : 'Local'} AOPS host is reachable.`
+            : `${selected === 'cli-existing' ? 'Remote' : 'Local'} AOPS host is not reachable yet.`,
+        next: endpoint.reachable
+            ? undefined
+            : selected === 'cli-existing'
+                ? 'Configure a reachable target or pass `--api-base-url`.'
+                : 'Install or start the selected local runtime.',
+        data: { apiBaseUrl: endpointUrl ?? null },
+    });
+    const localPath = selected === 'native-external' || selected === 'native-container' || selected === 'native-local';
+    if (localPath) {
+        const cockpitPort = native.state?.cockpit?.port ?? resolveCommunityNativeCockpitPort(localPort);
+        const cockpitOrigin = `http://127.0.0.1:${cockpitPort}`;
+        const cockpit = probes.cockpit ?? (native.status === 'installed'
+            ? await probeCockpit(cockpitOrigin, options.timeoutMs ?? 1_500)
+            : { reachable: false, apiReachable: false, origin: cockpitOrigin });
+        const ready = cockpit.reachable && cockpit.apiReachable;
+        checks.push({
+            id: 'cockpit',
+            state: ready ? 'ready' : 'action-required',
+            required: true,
+            summary: ready
+                ? `AOPS Cockpit is reachable at ${cockpit.origin} and its API proxy is healthy.`
+                : cockpit.reachable
+                    ? `AOPS Cockpit is reachable at ${cockpit.origin}, but its AOPS Server proxy is unavailable.`
+                    : `AOPS Cockpit is not reachable at ${cockpit.origin}.`,
+            next: ready ? undefined : cockpit.reachable
+                ? 'Run `aops server start`, then verify with `aops cockpit health`.'
+                : 'Run `aops cockpit start`, then verify with `aops cockpit health`.',
+            data: cockpit,
+        });
+    }
+    else {
+        checks.push({
+            id: 'cockpit',
+            state: 'not-applicable',
+            required: false,
+            summary: 'The CLI-only path does not manage a local Cockpit process.',
+        });
+    }
+    const targetRequired = selected === 'cli-existing';
+    const targetSelected = selectedTarget?.active === true ||
+        (selectedTarget !== null && activeTarget?.name === selectedTarget.name);
+    const targetProviderMatches = !selectedTarget || endpoint.authProvider === selectedTarget.authProvider;
+    const loginReady = targetProviderMatches &&
+        (endpoint.authRequired === false ||
+            (endpoint.authRequired === true && endpoint.authenticated === true));
+    checks.push({
+        id: 'target-login',
+        state: !targetRequired
+            ? 'not-applicable'
+            : !selectedTarget
+                ? 'action-required'
+                : !targetSelected
+                    ? 'action-required'
+                    : loginReady
+                        ? 'ready'
+                        : 'action-required',
+        required: targetRequired,
+        summary: !targetRequired
+            ? 'A remote target is not required for this local installation path.'
+            : !selectedTarget
+                ? explicitApiBaseUrl
+                    ? 'The endpoint was probed, but no persistent existing-server target is selected.'
+                    : 'No existing-server target is configured.'
+                : !targetSelected
+                    ? 'The matching existing-server target is saved but is not selected.'
+                    : loginReady
+                        ? 'The selected target and authenticated session are ready.'
+                        : endpoint.authRequired === null
+                            ? 'The selected target is reachable, but its authentication contract could not be verified.'
+                            : !targetProviderMatches
+                                ? 'The selected target authentication provider does not match the server contract.'
+                                : selectedTarget.hasCredentials
+                                    ? 'The selected target has stored credentials, but `/api/auth/me` did not verify them.'
+                                    : 'The selected target requires login credentials.',
+        next: targetRequired && !selectedTarget
+            ? 'Add and select an AOPS target.'
+            : targetRequired && !targetSelected
+                ? `Run \`aops target use ${selectedTarget?.name ?? '<name>'} --apply\`.`
+                : targetRequired && endpoint.authRequired === null
+                    ? `Run \`aops target doctor${selectedTarget?.name ? ` ${selectedTarget.name}` : ''} --json\` and repair the server auth contract.`
+                    : targetRequired && !targetProviderMatches
+                        ? `Run \`aops target doctor${selectedTarget?.name ? ` ${selectedTarget.name}` : ''} --json\` and repair the provider mismatch.`
+                        : targetRequired && !loginReady
+                            ? `Run \`aops auth login${selectedTarget?.name ? ` --target ${selectedTarget.name}` : ''}\`.`
+                            : undefined,
+        data: selectedTarget
+            ? {
+                name: selectedTarget.name,
+                apiBaseUrl: selectedTarget.apiBaseUrl,
+                authProvider: endpoint.authProvider ?? selectedTarget.authProvider,
+                tlsPolicy: selectedTarget.tlsPolicy ?? null,
+                active: targetSelected,
+                providerMatches: targetProviderMatches,
+                hasCredentials: selectedTarget.hasCredentials,
+                authenticated: endpoint.authenticated === true,
+                principalUserId: endpoint.principalUserId ?? null,
+            }
+            : {
+                apiBaseUrl: endpointUrl ?? null,
+                authProvider: endpoint.authProvider ?? null,
+                authenticated: false,
+            },
+    });
+    const assets = probes.agentAssets ?? await inspectSetupAgentAssets(options.agentAssetsProvider);
+    checks.push(agentAssetCheck(assets));
+    const requiredAction = checks.some((check) => check.required && check.state !== 'ready' && check.state !== 'not-applicable');
+    const nextActions = [...new Set(checks.map((check) => check.next).filter((value) => Boolean(value)))];
+    return Object.freeze({
+        schemaVersion: 1,
+        mutationFree: true,
+        status: requiredAction ? 'action-required' : 'ready',
+        path: Object.freeze({
+            id: descriptor?.id ?? null,
+            number: descriptor?.number ?? null,
+            title: descriptor?.title ?? null,
+            source,
+        }),
+        checks: Object.freeze(checks),
+        nextActions: Object.freeze(nextActions),
+    });
+}