@aopslabs/aops 0.2.0

package/dist/commands/community-cockpit.js

@@ -0,0 +1,185 @@
+import { Command } from 'commander';
+import { healthCommunityNativeCockpit, inspectCommunityNativeCockpit, readCommunityCockpitLogs, restartCommunityNativeCockpit, startCommunityNativeCockpit, stopCommunityNativeCockpit, } from '../lib/community-cockpit-lifecycle.js';
+import { inspectCommunityNativeInstall, inspectCommunityNativeRuntime, } from '../lib/community-native-lifecycle.js';
+import { communityCommandAbortRuntime, withCommunityCommandAbortScope, } from '../lib/community-command-abort.js';
+import { openExternalUrl } from '../lib/external-url.js';
+import { runCommunityServerStart } from './community-server.js';
+const defaultDependencies = {
+    inspectInstall: inspectCommunityNativeInstall,
+    inspectServer: inspectCommunityNativeRuntime,
+    startServer: runCommunityServerStart,
+    startCockpit: startCommunityNativeCockpit,
+    openUrl: openExternalUrl,
+};
+function selection(options) {
+    return { instanceName: options.instance, dataRoot: options.dataRoot };
+}
+function commandSelection(options) {
+    return selection(options);
+}
+function writeResult(value, json = false) {
+    if (json)
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    else
+        process.stdout.write(`${String(value)}\n`);
+}
+export async function resolveCommunityCockpit(options, dependencies = defaultDependencies, signal) {
+    const install = dependencies.inspectInstall(selection(options));
+    const requestedInstance = options.instance ?? 'default';
+    if (install.status === 'not-installed') {
+        throw new Error(`AOPS server instance "${requestedInstance}" is not installed. Run "aops setup init" first.`);
+    }
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`AOPS server instance "${requestedInstance}" cannot open Cockpit: ${install.status}` +
+            `${install.error ? ` (${install.error})` : ''}. Run "aops doctor".`);
+    }
+    let server = await dependencies.inspectServer(selection(options));
+    let serverAction = 'already-running';
+    if (server.runtimeState === 'stopped' || server.runtimeState === 'crashed') {
+        await dependencies.startServer({
+            instance: install.state.instanceName,
+            dataRoot: install.paths.dataRoot,
+            detach: true,
+            silent: true,
+        });
+        serverAction = 'started';
+        server = await dependencies.inspectServer({
+            instanceName: install.state.instanceName,
+            dataRoot: install.paths.dataRoot,
+        });
+    }
+    if (server.runtimeState !== 'running' || server.health !== 'healthy') {
+        throw new Error(`AOPS server instance "${install.state.instanceName}" is not ready for Cockpit: ` +
+            `${server.runtimeState}${server.reason ? ` (${server.reason})` : ''}. ` +
+            'Run "aops server status" and "aops server logs".');
+    }
+    const cockpit = await dependencies.startCockpit({ ...selection(options), signal });
+    const shouldOpen = options.open !== false;
+    if (shouldOpen) {
+        try {
+            await dependencies.openUrl(cockpit.origin);
+        }
+        catch (error) {
+            throw new Error(`AOPS Cockpit is ready at ${cockpit.origin}, but the default browser could not be opened: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        status: 'cockpit-ready',
+        instance: install.state.instanceName,
+        origin: cockpit.origin,
+        serverOrigin: cockpit.serverOrigin,
+        serverAction,
+        cockpitAction: cockpit.action,
+        opened: shouldOpen,
+    };
+}
+export async function runCommunityCockpit(options) {
+    const result = await withCommunityCommandAbortScope(communityCommandAbortRuntime, (signal) => resolveCommunityCockpit(options, defaultDependencies, signal));
+    if (options.json) {
+        writeResult(result, true);
+        return;
+    }
+    const started = [
+        result.serverAction === 'started' ? 'AOPS Server started.' : '',
+        result.cockpitAction === 'started' ? 'Cockpit started.' : '',
+    ].filter(Boolean).join(' ');
+    if (started)
+        writeResult(started);
+    writeResult(`AOPS Cockpit: ${result.origin} (API: ${result.serverOrigin})`);
+    writeResult(result.opened ? 'Opened in the default browser.' : 'Browser opening was skipped.');
+}
+export async function runCommunityCockpitStart(options) {
+    const result = await withCommunityCommandAbortScope(communityCommandAbortRuntime, (signal) => startCommunityNativeCockpit({ ...commandSelection(options), signal }));
+    if (options.json)
+        writeResult({ status: 'community-cockpit-running', ...result }, true);
+    else
+        writeResult(result.action === 'started'
+            ? `AOPS Cockpit started at ${result.origin}. API proxy: ${result.serverOrigin}`
+            : `AOPS Cockpit is already running at ${result.origin}.`);
+}
+export async function runCommunityCockpitStop(options) {
+    const result = await withCommunityCommandAbortScope(communityCommandAbortRuntime, (signal) => stopCommunityNativeCockpit({ ...commandSelection(options), signal }));
+    if (options.json)
+        writeResult({
+            status: result.status === 'stopped' ? 'community-cockpit-stopped' : 'community-cockpit-already-stopped',
+            instance: result.state.instanceName,
+            processStatus: result.process?.status ?? null,
+        }, true);
+    else
+        writeResult(result.status === 'stopped' ? 'AOPS Cockpit stopped.' : 'AOPS Cockpit is already stopped.');
+}
+export async function runCommunityCockpitRestart(options) {
+    const result = await withCommunityCommandAbortScope(communityCommandAbortRuntime, (signal) => restartCommunityNativeCockpit({ ...commandSelection(options), signal }));
+    if (options.json)
+        writeResult({ status: 'community-cockpit-restarted', ...result }, true);
+    else
+        writeResult(`AOPS Cockpit restarted at ${result.origin}.`);
+}
+export async function runCommunityCockpitStatus(options) {
+    const result = await inspectCommunityNativeCockpit(commandSelection(options));
+    if (options.json)
+        writeResult({ status: 'community-cockpit-status', ...result }, true);
+    else
+        writeResult(`Cockpit ${result.runtimeState} (${result.health}) at ${result.origin}; API proxy ${result.serverOrigin}.` +
+            `${result.reason ? ` Reason: ${result.reason}` : ''}`);
+    if (['unhealthy', 'identity-conflict', 'orphaned'].includes(result.runtimeState))
+        process.exitCode = 1;
+}
+export async function runCommunityCockpitHealth(options) {
+    const result = await healthCommunityNativeCockpit(commandSelection(options));
+    const hostHealthy = result.runtimeState === 'running' && result.health === 'healthy';
+    const healthy = hostHealthy && result.apiReady;
+    if (options.json)
+        writeResult({ status: healthy ? 'healthy' : 'unhealthy', service: 'cockpit', ...result }, true);
+    else if (healthy)
+        writeResult(`AOPS Cockpit and its API proxy are healthy at ${result.origin}.`);
+    else if (hostHealthy)
+        writeResult(`AOPS Cockpit host is healthy at ${result.origin}, but its API proxy to ${result.serverOrigin} is unavailable.`);
+    else
+        writeResult(`AOPS Cockpit is not healthy: ${result.runtimeState}${result.reason ? ` (${result.reason})` : ''}.`);
+    if (!healthy)
+        process.exitCode = 1;
+}
+export async function runCommunityCockpitLogs(options) {
+    const result = readCommunityCockpitLogs({ ...commandSelection(options), tail: Number(options.tail ?? 100) });
+    if (options.json)
+        writeResult({ status: 'community-cockpit-logs', ...result }, true);
+    else
+        writeResult(result.content || 'No detached Cockpit logs are available.');
+}
+function common(command) {
+    return command
+        .option('--instance <name>', 'Installation instance name', 'default')
+        .option('--data-root <path>', 'Absolute Community data root override')
+        .option('--json', 'Output JSON');
+}
+export function mergeCommunityCockpitOptions(options, command) {
+    return {
+        ...options,
+        ...(typeof command.optsWithGlobals === 'function' ? command.optsWithGlobals() : {}),
+    };
+}
+export function makeCommunityCockpitCommand() {
+    const command = common(new Command('cockpit')
+        .description('Open and independently operate AOPS Cockpit on its own loopback port')
+        .option('--no-open', 'Prepare Cockpit and print its URL without opening a browser'))
+        .action((options, invoked) => runCommunityCockpit(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('open').description('Start stopped local services as needed and open Cockpit'))
+        .option('--no-open', 'Prepare Cockpit and print its URL without opening a browser')
+        .action((options, invoked) => runCommunityCockpit(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('start').description('Start only the Cockpit process; do not start the AOPS Server'))
+        .action((options, invoked) => runCommunityCockpitStart(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('stop').description('Stop only the Cockpit process; do not stop the AOPS Server'))
+        .action((options, invoked) => runCommunityCockpitStop(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('restart').description('Restart only the Cockpit process'))
+        .action((options, invoked) => runCommunityCockpitRestart(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('status').description('Show Cockpit process status without mutation'))
+        .action((options, invoked) => runCommunityCockpitStatus(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('health').description('Check the Cockpit host health without mutation'))
+        .action((options, invoked) => runCommunityCockpitHealth(mergeCommunityCockpitOptions(options, invoked)));
+    common(command.command('logs').description('Show recent Cockpit logs'))
+        .option('--tail <number>', 'Number of log lines', '100')
+        .action((options, invoked) => runCommunityCockpitLogs(mergeCommunityCockpitOptions(options, invoked)));
+    return command;
+}

package/dist/commands/community-console.js

@@ -0,0 +1,109 @@
+import { Command } from 'commander';
+import { logInfo } from '@aopslabs/xf-cli-ui';
+import { promptSelect } from '../utils/prompts.js';
+import { runCommercialLicenseStatus } from './commercial-license.js';
+import { runCommunityDoctor } from './community-doctor.js';
+import { runCommunityCockpit, runCommunityCockpitHealth, runCommunityCockpitLogs, runCommunityCockpitRestart, runCommunityCockpitStart, runCommunityCockpitStatus, runCommunityCockpitStop, } from './community-cockpit.js';
+import { runCommunityServerHealth, runCommunityServerLogs, runCommunityServerRestart, runCommunityServerStart, runCommunityServerStatus, runCommunityServerStop, } from './community-server.js';
+export const COMMUNITY_CONSOLE_CHOICES = Object.freeze([
+    { name: 'Open Cockpit — starts stopped services if needed', value: 'cockpit' },
+    { name: 'Show both service statuses', value: 'status' },
+    { name: 'Start AOPS Server — 5900', value: 'server-start' },
+    { name: 'Start AOPS Server in this terminal — live logs, Ctrl+C to stop', value: 'server-start-foreground' },
+    { name: 'Stop AOPS Server — 5900', value: 'server-stop' },
+    { name: 'Restart AOPS Server — 5900', value: 'server-restart' },
+    { name: 'Check AOPS Server health', value: 'server-health' },
+    { name: 'Show AOPS Server logs', value: 'server-logs' },
+    { name: 'Start Cockpit — 5922', value: 'cockpit-start' },
+    { name: 'Stop Cockpit — 5922', value: 'cockpit-stop' },
+    { name: 'Restart Cockpit — 5922', value: 'cockpit-restart' },
+    { name: 'Check Cockpit health', value: 'cockpit-health' },
+    { name: 'Show Cockpit logs', value: 'cockpit-logs' },
+    { name: 'Show commercial license and domain-admission status', value: 'license-status' },
+    { name: 'Run Doctor (read-only)', value: 'doctor' },
+    { name: 'Back', value: 'back' },
+]);
+export async function runCommunityConsoleAction(action, options, dependencies = {}) {
+    if (action === 'cockpit')
+        return (dependencies.runCockpit ?? runCommunityCockpit)(options);
+    if (action === 'status') {
+        await (dependencies.runServerStatus ?? runCommunityServerStatus)(options);
+        await (dependencies.runCockpitStatus ?? runCommunityCockpitStatus)(options);
+        return;
+    }
+    if (action === 'server-health')
+        return (dependencies.runServerHealth ?? runCommunityServerHealth)(options);
+    if (action === 'server-start')
+        return (dependencies.runServerStart ?? runCommunityServerStart)(options);
+    if (action === 'server-start-foreground')
+        return (dependencies.runServerStart ?? runCommunityServerStart)({
+            ...options,
+            foreground: true,
+        });
+    if (action === 'server-restart')
+        return (dependencies.runServerRestart ?? runCommunityServerRestart)(options);
+    if (action === 'server-stop')
+        return (dependencies.runServerStop ?? runCommunityServerStop)(options);
+    if (action === 'server-logs')
+        return (dependencies.runServerLogs ?? runCommunityServerLogs)(options);
+    if (action === 'cockpit-health')
+        return (dependencies.runCockpitHealth ?? runCommunityCockpitHealth)(options);
+    if (action === 'cockpit-start')
+        return (dependencies.runCockpitStart ?? runCommunityCockpitStart)(options);
+    if (action === 'cockpit-restart')
+        return (dependencies.runCockpitRestart ?? runCommunityCockpitRestart)(options);
+    if (action === 'cockpit-stop')
+        return (dependencies.runCockpitStop ?? runCommunityCockpitStop)(options);
+    if (action === 'cockpit-logs')
+        return (dependencies.runCockpitLogs ?? runCommunityCockpitLogs)(options);
+    if (action === 'license-status') {
+        return (dependencies.runLicenseStatus ?? runCommercialLicenseStatus)({ json: options.json });
+    }
+    return (dependencies.runDoctor ?? runCommunityDoctor)(options);
+}
+export async function runCommunityConsole(options = {}, dependencies = {}) {
+    const interactive = dependencies.isInteractive?.() ??
+        (process.stdin.isTTY === true && process.stdout.isTTY === true);
+    if (!interactive || options.json === true) {
+        console.log(JSON.stringify({
+            status: 'needs-input',
+            mutationPerformed: false,
+            reason: 'community_console_tty_required',
+            next: [
+                'aops server status --json',
+                'aops server start --json',
+                'aops server stop --json',
+                'aops cockpit status --json',
+                'aops cockpit start --json',
+                'aops cockpit stop --json',
+                'aops license status --json',
+            ],
+        }, null, 2));
+        process.exitCode = 2;
+        return;
+    }
+    const select = dependencies.select ?? promptSelect;
+    const info = dependencies.info ?? logInfo;
+    info('AOPS Server and Cockpit use separate processes and ports: 5900 and 5922.');
+    await (dependencies.runServerStatus ?? runCommunityServerStatus)(options);
+    await (dependencies.runCockpitStatus ?? runCommunityCockpitStatus)(options);
+    while (true) {
+        const action = await select({
+            message: 'Server and Cockpit:',
+            type: process.env.AOPS_CLI_MENU_STYLE?.toLowerCase() === 'rawlist' ? 'rawlist' : 'select',
+            pageSize: COMMUNITY_CONSOLE_CHOICES.length,
+            choices: [...COMMUNITY_CONSOLE_CHOICES],
+        });
+        if (action === 'back')
+            return;
+        await runCommunityConsoleAction(action, options, dependencies);
+    }
+}
+export function makeCommunityConsoleCommand() {
+    return new Command('console')
+        .description('Guided server and Cockpit controls; non-TTY returns needs-input without mutation')
+        .option('--instance <name>', 'Installation instance name', 'default')
+        .option('--data-root <path>', 'Absolute Community data root override')
+        .option('--json', 'Return the non-interactive needs-input contract')
+        .action((options) => runCommunityConsole(options));
+}

package/dist/commands/community-doctor.js

@@ -0,0 +1,335 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, statfsSync } from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { Command } from 'commander';
+import { readCommercialIntegrityVerificationSchedule, resolveManagedInstallationLayout, } from '@aopslabs/artifact-trust-contracts';
+import { buildCommunityComposeInvocation, inspectCommunityInstall, readCommunityRuntimePort, } from '../lib/community-lifecycle.js';
+import { buildCommunityInstanceContract } from '../lib/community-instance-contract.js';
+import { resolveCommunityCliIdentity } from '../lib/community-client-contract.js';
+import { communityProcessRuntime } from '../lib/community-docker-adapter.js';
+import { resolveCommunityInstanceLayout } from '../lib/community-instance-layout.js';
+import { inspectCommunityNativeInstall } from '../lib/community-native-lifecycle.js';
+import { inspectCommunityNativePostgres } from '../lib/community-native-postgres.js';
+import { getActiveApiTarget, getApiTarget } from '../utils/config.js';
+import { inspectTargetDoctor } from './target.js';
+function installSelection(options) {
+    if (options.dataRoot)
+        return { instanceName: options.instance, dataRoot: options.dataRoot };
+    const layout = resolveCommunityInstanceLayout({ instanceId: options.instance });
+    return { instanceName: layout.instanceId, dataRoot: layout.dataRoot };
+}
+function existingAncestor(candidate) {
+    let cursor = path.resolve(candidate);
+    while (!existsSync(cursor)) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return cursor;
+        cursor = parent;
+    }
+    return cursor;
+}
+function probePort(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', () => resolve(false));
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => server.close(() => resolve(true)));
+    });
+}
+function inspectCommercialIntegrity() {
+    const layout = resolveManagedInstallationLayout();
+    const activePointer = path.join(layout.storeRoot, 'state', 'active.json');
+    if (!existsSync(activePointer)) {
+        return {
+            id: 'commercial-integrity',
+            status: 'skip',
+            detail: 'state=inactive; no managed commercial artifact is active',
+        };
+    }
+    try {
+        const schedule = readCommercialIntegrityVerificationSchedule(layout.stateRoot);
+        const status = schedule.state === 'waiting'
+            ? 'pass'
+            : schedule.state === 'due'
+                ? 'warn'
+                : 'fail';
+        return {
+            id: 'commercial-integrity',
+            status,
+            detail: `state=${schedule.state}; verifiedAt=${schedule.verifiedAt ?? 'unknown'}; dueAt=${schedule.dueAt ?? 'unknown'}; intervalHours=${schedule.minimumIntervalHours}`,
+        };
+    }
+    catch (error) {
+        return {
+            id: 'commercial-integrity',
+            status: 'fail',
+            detail: `state=invalid; reason=${error instanceof Error ? error.message : 'commercial_integrity_diagnostics_failed'}`,
+        };
+    }
+}
+async function anonymousRegistryCheck(imageDigest, fetchImpl) {
+    try {
+        const tokenResponse = await fetchImpl('https://ghcr.io/token?service=ghcr.io&scope=repository:eeemzs/aops-community:pull', { signal: AbortSignal.timeout(8_000) });
+        if (!tokenResponse.ok)
+            return { id: 'anonymous-registry', status: 'fail', detail: `token HTTP ${tokenResponse.status}` };
+        const token = String((await tokenResponse.json()).token ?? '');
+        if (!token)
+            return { id: 'anonymous-registry', status: 'fail', detail: 'anonymous token missing' };
+        if (!imageDigest)
+            return { id: 'anonymous-registry', status: 'warn', detail: 'anonymous token works; exact release digest unavailable before setup' };
+        const manifestResponse = await fetchImpl(`https://ghcr.io/v2/eeemzs/aops-community/manifests/${imageDigest}`, {
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json',
+            },
+            signal: AbortSignal.timeout(8_000),
+        });
+        const observed = manifestResponse.headers.get('docker-content-digest');
+        return {
+            id: 'anonymous-registry',
+            status: manifestResponse.ok && observed === imageDigest ? 'pass' : 'fail',
+            detail: `manifest HTTP ${manifestResponse.status}; digest=${observed ?? 'missing'}`,
+        };
+    }
+    catch (error) {
+        return { id: 'anonymous-registry', status: 'fail', detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function inspectCommunityDoctor(options = {}, dependencies = {}) {
+    const spawn = dependencies.spawn ?? spawnSync;
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const platform = dependencies.platform ?? process.platform;
+    const arch = dependencies.arch ?? process.arch;
+    const checks = [];
+    const cli = resolveCommunityCliIdentity();
+    if (options.target && options.runtime)
+        throw new Error('community_doctor_selector_conflict:choose_--target_or_--runtime');
+    if (!options.runtime && (options.postgres || options.postgresConfig || options.postgresTls)) {
+        throw new Error('community_doctor_postgres_requires_runtime_native');
+    }
+    const selectedTarget = options.target
+        ? getApiTarget(options.target)
+        : options.runtime
+            ? undefined
+            : getActiveApiTarget();
+    if (options.target && !selectedTarget)
+        throw new Error(`aops_target_not_found:${options.target}`);
+    const selection = installSelection(options);
+    const inspection = inspectCommunityInstall(selection);
+    const nativeInspection = inspectCommunityNativeInstall(selection);
+    const explicitContract = options.runtime
+        ? buildCommunityInstanceContract({ ...options, port: 5900 })
+        : undefined;
+    const profile = selectedTarget
+        ? 'target-only'
+        : explicitContract?.profile
+            ?? (nativeInspection.status === 'installed' ? nativeInspection.state.profile : undefined)
+            ?? (inspection.status === 'installed' ? 'oci-managed-stack' : 'unconfigured');
+    const needsDocker = profile === 'oci-managed-stack' || profile === 'native-container-postgres';
+    const needsCompose = profile === 'oci-managed-stack';
+    checks.push({ id: 'cli-identity', status: 'pass', detail: `${cli.packageName}@${cli.version}; schema=${cli.commandSchemaVersion}; source=${cli.artifactSource}` });
+    checks.push(inspectCommercialIntegrity());
+    const osArchSupported = ['win32', 'darwin', 'linux'].includes(platform) && ['x64', 'arm64'].includes(arch);
+    checks.push({ id: 'os-arch', status: osArchSupported ? 'pass' : 'fail', detail: `${platform}/${arch}` });
+    if (needsDocker) {
+        const docker = spawn('docker', ['--version'], { encoding: 'utf8', windowsHide: true });
+        checks.push({
+            id: 'docker-cli',
+            status: docker.status === 0 ? 'pass' : 'fail',
+            detail: docker.status === 0 ? String(docker.stdout).trim() : String(docker.stderr || docker.error?.message || 'docker unavailable').trim(),
+        });
+    }
+    else
+        checks.push({ id: 'docker-cli', status: 'skip', detail: `${profile} does not require a Docker application runtime.` });
+    if (platform === 'win32' && needsDocker) {
+        const wsl = spawn('wsl.exe', ['--status'], { encoding: 'utf8', windowsHide: true });
+        checks.push({
+            id: 'wsl2',
+            status: wsl.status === 0 ? 'pass' : 'fail',
+            detail: wsl.status === 0 ? String(wsl.stdout).replace(/\0/g, '').trim().slice(-1000) : String(wsl.stderr || wsl.error?.message || 'WSL2 unavailable').replace(/\0/g, '').trim(),
+        });
+    }
+    else
+        checks.push({ id: 'wsl2', status: 'skip', detail: needsDocker ? 'WSL2 check applies only to Windows.' : 'No Docker runtime selected.' });
+    if (needsCompose) {
+        const compose = spawn('docker', ['compose', 'version'], { encoding: 'utf8', windowsHide: true });
+        checks.push({
+            id: 'docker-compose',
+            status: compose.status === 0 ? 'pass' : 'fail',
+            detail: compose.status === 0 ? String(compose.stdout).trim() : String(compose.stderr || compose.error?.message || 'docker compose unavailable').trim(),
+        });
+    }
+    else
+        checks.push({ id: 'docker-compose', status: 'skip', detail: `${profile} does not require the application Compose stack.` });
+    checks.push({
+        id: 'sigstore-verifier',
+        status: needsCompose ? 'pass' : 'skip',
+        detail: needsCompose ? 'bundled sigstore-js verifier; no external cosign installation required' : 'Signed OCI release verification is not used by this profile.',
+    });
+    if (profile === 'target-only') {
+        checks.push({ id: 'disk-space', status: 'skip', detail: 'The selected server is not managed as a local instance.' });
+    }
+    else {
+        const filesystem = dependencies.statfs?.(existingAncestor(inspection.paths.dataRoot))
+            ?? statfsSync(existingAncestor(inspection.paths.dataRoot), { bigint: true });
+        const freeBytes = filesystem.bavail * filesystem.bsize;
+        const minimumBytes = 2n * 1024n * 1024n * 1024n;
+        checks.push({ id: 'disk-space', status: freeBytes >= minimumBytes ? 'pass' : 'fail', detail: `${(Number(freeBytes) / (1024 ** 3)).toFixed(1)} GiB free; 2.0 GiB minimum` });
+    }
+    checks.push({
+        id: 'install-state',
+        status: profile === 'target-only'
+            ? 'skip'
+            : nativeInspection.status === 'installed' && profile !== 'oci-managed-stack'
+                ? 'pass'
+                : nativeInspection.status === 'partial' || nativeInspection.status === 'runtime-conflict'
+                    ? 'fail'
+                    : inspection.status === 'installed' && profile === 'oci-managed-stack'
+                        ? 'pass'
+                        : inspection.status === 'partial'
+                            ? 'fail'
+                            : 'warn',
+        detail: profile === 'target-only'
+            ? 'The selected target is independent of any local installation state.'
+            : nativeInspection.status === 'installed' && profile !== 'oci-managed-stack'
+                ? `installed; profile=${nativeInspection.state.profile}; root=${nativeInspection.paths.instanceRoot}`
+                : nativeInspection.status === 'partial' || nativeInspection.status === 'runtime-conflict'
+                    ? `${nativeInspection.error ?? nativeInspection.status}; missing=${nativeInspection.missingFiles.join(',') || 'none'}`
+                    : inspection.status === 'partial'
+                        ? `${inspection.error ?? 'partial install'}; missing=${inspection.missingFiles.join(',') || 'none'}`
+                        : `${inspection.status}; profile=${profile}; root=${inspection.paths.instanceRoot}`,
+    });
+    if (profile === 'target-only' && selectedTarget) {
+        checks.push({ id: 'release-cache', status: 'skip', detail: 'No local release cache is required for a server target.' });
+        checks.push({ id: 'container-status', status: 'skip', detail: 'The target server lifecycle is not owned by this CLI instance.' });
+        checks.push({ id: 'port', status: 'skip', detail: `Remote/existing endpoint: ${selectedTarget.apiBaseUrl}` });
+        checks.push({ id: 'cockpit-port', status: 'skip', detail: 'The target Cockpit lifecycle is not owned by this CLI instance.' });
+        const targetDoctor = await (dependencies.targetDoctor ?? inspectTargetDoctor)(selectedTarget.name, { timeoutMs: options.timeoutMs, json: true });
+        const compatibility = targetDoctor.compatibility;
+        checks.push({ id: 'server-health', status: targetDoctor.status === 'unavailable' ? 'fail' : 'pass', detail: `target=${selectedTarget.name}; status=${targetDoctor.status}` });
+        checks.push({ id: 'compatibility', status: compatibility.compatible ? (compatibility.status === 'warning' ? 'warn' : 'pass') : 'fail', detail: String(compatibility.reason ?? 'unknown') });
+    }
+    else if (inspection.status === 'installed' && profile === 'oci-managed-stack') {
+        const state = inspection.state;
+        checks.push({ id: 'release-cache', status: 'pass', detail: `${state.activeRelease.releaseVersion} ${state.activeRelease.imageRef}` });
+        const status = await communityProcessRuntime.run(buildCommunityComposeInvocation({ paths: inspection.paths, state, action: 'status' }));
+        checks.push({ id: 'container-status', status: status.exitCode === 0 ? 'pass' : 'fail', detail: (status.stdout || status.stderr || `exit=${status.exitCode}`).trim().slice(-2000) });
+        const port = readCommunityRuntimePort(inspection.paths);
+        checks.push({ id: 'port', status: 'pass', detail: `configured=${port}; installed service is expected to own it` });
+        checks.push({ id: 'cockpit-port', status: 'skip', detail: 'OCI compatibility profile serves Cockpit through its combined edge.' });
+        try {
+            const response = await fetchImpl(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(5_000) });
+            checks.push({ id: 'server-health', status: response.ok ? 'pass' : 'fail', detail: `HTTP ${response.status} on port ${port}` });
+        }
+        catch (error) {
+            checks.push({ id: 'server-health', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    else if (nativeInspection.status === 'installed' && nativeInspection.state && profile !== 'oci-managed-stack') {
+        const state = nativeInspection.state;
+        checks.push({ id: 'release-cache', status: 'skip', detail: `Native source checkout ${state.source.releaseVersion}; no OCI release cache.` });
+        if (state.postgres.mode === 'container') {
+            try {
+                const postgres = await inspectCommunityNativePostgres({
+                    state: state.postgres,
+                    instanceName: state.instanceName,
+                    instanceRoot: nativeInspection.paths.instanceRoot,
+                });
+                checks.push({
+                    id: 'container-status',
+                    status: postgres.container === 'running' && postgres.health === 'healthy' ? 'pass' : 'fail',
+                    detail: `postgres=${postgres.container}; health=${postgres.health}; image=${postgres.imageRef}`,
+                });
+            }
+            catch (error) {
+                checks.push({ id: 'container-status', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        else {
+            checks.push({ id: 'container-status', status: 'skip', detail: 'External PostgreSQL is owned outside this CLI instance.' });
+        }
+        checks.push({ id: 'port', status: 'pass', detail: `configured=${state.server.port}; installed native service is expected to own it` });
+        checks.push({ id: 'cockpit-port', status: 'pass', detail: `configured=${state.cockpit.port}; independent Cockpit service is expected to own it` });
+        try {
+            const response = await fetchImpl(`http://127.0.0.1:${state.server.port}/api/health`, { signal: AbortSignal.timeout(5_000) });
+            checks.push({ id: 'server-health', status: response.ok ? 'pass' : 'fail', detail: `HTTP ${response.status} on port ${state.server.port}` });
+        }
+        catch (error) {
+            checks.push({ id: 'server-health', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+        }
+        try {
+            const cockpitOrigin = `http://127.0.0.1:${state.cockpit.port}`;
+            const [hostResponse, proxyResponse] = await Promise.all([
+                fetchImpl(`${cockpitOrigin}/_aops/cockpit-health`, { signal: AbortSignal.timeout(5_000) }),
+                fetchImpl(`${cockpitOrigin}/api/health`, {
+                    headers: { origin: cockpitOrigin },
+                    signal: AbortSignal.timeout(5_000),
+                }),
+            ]);
+            checks.push({
+                id: 'cockpit-health',
+                status: hostResponse.ok && proxyResponse.ok ? 'pass' : 'fail',
+                detail: `host HTTP ${hostResponse.status}; API proxy HTTP ${proxyResponse.status}; port ${state.cockpit.port}`,
+            });
+        }
+        catch (error) {
+            checks.push({ id: 'cockpit-health', status: 'fail', detail: error instanceof Error ? error.message : String(error) });
+        }
+        checks.push({ id: 'compatibility', status: 'skip', detail: 'Local native runtime uses the installed CLI/server contract.' });
+    }
+    else {
+        const selectedServerPort = explicitContract?.server.port ?? 5900;
+        const selectedCockpitPort = selectedServerPort <= 65_513 ? selectedServerPort + 22 : selectedServerPort - 22;
+        const [available, cockpitAvailable] = await Promise.all([
+            (dependencies.portProbe ?? probePort)(selectedServerPort),
+            (dependencies.portProbe ?? probePort)(selectedCockpitPort),
+        ]);
+        checks.push({ id: 'release-cache', status: 'skip', detail: 'No complete OCI installation to inspect.' });
+        checks.push({ id: 'port', status: available ? 'pass' : 'fail', detail: available ? `${selectedServerPort} is available` : `${selectedServerPort} is already in use` });
+        checks.push({ id: 'cockpit-port', status: cockpitAvailable ? 'pass' : 'fail', detail: cockpitAvailable ? `${selectedCockpitPort} is available` : `${selectedCockpitPort} is already in use` });
+        checks.push({ id: 'container-status', status: 'skip', detail: 'No complete local installation to inspect.' });
+        checks.push({ id: 'server-health', status: 'skip', detail: 'No configured server target or running local instance.' });
+        checks.push({ id: 'cockpit-health', status: 'skip', detail: 'No configured local Cockpit instance.' });
+        checks.push({ id: 'compatibility', status: 'skip', detail: 'Select a target or start a local instance first.' });
+    }
+    if (profile === 'oci-managed-stack') {
+        checks.push(await anonymousRegistryCheck(inspection.status === 'installed' ? inspection.state.activeRelease.imageIndexDigest : undefined, fetchImpl));
+    }
+    else
+        checks.push({ id: 'anonymous-registry', status: 'skip', detail: `${profile} does not pull the AOPS application image.` });
+    return {
+        status: checks.some((check) => check.status === 'fail') ? 'attention-required' : 'healthy',
+        mutationFree: true,
+        profile,
+        cli,
+        selectedTarget: selectedTarget ?? null,
+        checks,
+    };
+}
+export async function runCommunityDoctor(options = {}) {
+    const result = await inspectCommunityDoctor(options);
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        for (const check of result.checks)
+            console.log(`${check.status.toUpperCase().padEnd(4)} ${check.id}: ${check.detail}`);
+        console.log(`Result: ${result.status}`);
+    }
+    if (result.status !== 'healthy')
+        process.exitCode = 1;
+}
+export function makeCommunityDoctorCommand() {
+    return new Command('doctor')
+        .description('Run mutation-free, profile-aware CLI/target/local-instance checks')
+        .option('--instance <name>', 'Local instance name', 'default')
+        .option('--data-root <path>', 'Absolute Community data root override')
+        .option('--runtime <native|oci>', 'Preview checks for an explicit application runtime')
+        .option('--postgres <external|container>', 'PostgreSQL profile for --runtime native')
+        .option('--postgres-config <path>', 'External PostgreSQL config reference')
+        .option('--postgres-tls <disable|require|verify-full>', 'External PostgreSQL TLS policy')
+        .option('--target <name>', 'Named existing server target')
+        .option('--timeout-ms <ms>', 'Target request timeout', (value) => Number.parseInt(value, 10))
+        .option('--json', 'Output JSON')
+        .action(runCommunityDoctor);
+}