@aopslabs/aops 0.2.0

package/dist/lib/community-cockpit-lifecycle.js

@@ -0,0 +1,601 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { COMMUNITY_NATIVE_CHILD_PROTOCOL, COMMUNITY_NATIVE_CONTROL_PROTOCOL, } from './community-native-child.js';
+import { communityNativeRuntime, inspectCommunityNativeInstall, resolveCommunityNativeChildEntry, resolveCommunityNativePaths, } from './community-native-lifecycle.js';
+import { withCommunityOperationLock } from './community-operation-lock.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const READY_TIMEOUT_MS = 15_000;
+const STOP_TIMEOUT_MS = 15_000;
+const POLL_MS = 100;
+const MAX_LOG_TAIL_BYTES = 4 * 1024 * 1024;
+function validPort(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65_535;
+}
+function samePath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === '' &&
+        path.relative(path.resolve(right), path.resolve(left)) === '';
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new Error('community_operation_aborted');
+}
+function exactKeys(input, required, optional = []) {
+    const keys = Object.keys(input);
+    if (required.some((key) => !keys.includes(key)) ||
+        keys.some((key) => !required.includes(key) && !optional.includes(key)))
+        throw new Error('community_cockpit_process_schema_invalid');
+}
+function assertPlainDirectory(candidate, code) {
+    const stats = lstatSync(candidate);
+    if (!stats.isDirectory() || stats.isSymbolicLink() || !samePath(realpathSync.native(candidate), candidate)) {
+        throw new Error(code);
+    }
+}
+function assertPlainFile(candidate, parent, code) {
+    const stats = lstatSync(candidate);
+    if (!stats.isFile() || stats.isSymbolicLink() ||
+        !samePath(realpathSync.native(candidate), candidate) || !samePath(path.dirname(candidate), parent))
+        throw new Error(code);
+}
+function assertPaths(paths) {
+    assertPlainDirectory(paths.instanceRoot, 'community_cockpit_instance_root_unsafe');
+    assertPlainDirectory(paths.runtimeRoot, 'community_cockpit_runtime_root_unsafe');
+    if (existsSync(paths.logRoot))
+        assertPlainDirectory(paths.logRoot, 'community_cockpit_log_root_unsafe');
+    for (const candidate of [paths.processPath, paths.identityPath, paths.controlPath]) {
+        if (existsSync(candidate))
+            assertPlainFile(candidate, paths.runtimeRoot, 'community_cockpit_runtime_file_unsafe');
+    }
+    if (existsSync(paths.logPath))
+        assertPlainFile(paths.logPath, paths.logRoot, 'community_cockpit_log_file_unsafe');
+}
+function atomicJsonWrite(targetPath, value) {
+    const parent = path.dirname(targetPath);
+    assertPlainDirectory(parent, 'community_cockpit_runtime_root_unsafe');
+    if (existsSync(targetPath))
+        assertPlainFile(targetPath, parent, 'community_cockpit_runtime_file_unsafe');
+    const temporary = path.join(parent, `.${path.basename(targetPath)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: 'utf8', flag: 'wx', mode: 0o600,
+        });
+        renameSync(temporary, targetPath);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function readJson(targetPath, code) {
+    try {
+        return JSON.parse(readFileSync(targetPath, 'utf8'));
+    }
+    catch {
+        throw new Error(code);
+    }
+}
+export function resolveCommunityCockpitPaths(input = {}) {
+    const native = resolveCommunityNativePaths(input);
+    return {
+        dataRoot: native.dataRoot,
+        instanceRoot: native.instanceRoot,
+        runtimeRoot: native.runtimeRoot,
+        processPath: path.join(native.runtimeRoot, 'native-cockpit-process.json'),
+        identityPath: path.join(native.runtimeRoot, 'native-cockpit-identity.json'),
+        controlPath: path.join(native.runtimeRoot, 'native-cockpit-control.json'),
+        logRoot: native.logRoot,
+        logPath: path.join(native.logRoot, 'native-cockpit.log'),
+    };
+}
+function parseProcess(value, paths) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('community_cockpit_process_invalid');
+    }
+    const input = value;
+    exactKeys(input, [
+        'schemaVersion', 'protocol', 'service', 'instanceName', 'launchId', 'pid', 'status',
+        'startedAt', 'updatedAt', 'sourceFingerprint', 'hostEntry', 'port', 'serverPort',
+        'identityPath', 'controlPath', 'logPath',
+    ], ['hostPid', 'exitCode', 'signal', 'failure']);
+    if (input.schemaVersion !== 1 || input.protocol !== COMMUNITY_NATIVE_CHILD_PROTOCOL || input.service !== 'cockpit' ||
+        !UUID.test(String(input.launchId)) || !Number.isSafeInteger(input.pid) || input.pid < 1 ||
+        (input.hostPid !== undefined && (!Number.isSafeInteger(input.hostPid) || input.hostPid < 1)) ||
+        !['starting', 'running', 'exited', 'failed'].includes(input.status) ||
+        Number.isNaN(Date.parse(String(input.startedAt))) || Number.isNaN(Date.parse(String(input.updatedAt))) ||
+        !SHA256.test(String(input.sourceFingerprint)) || !path.isAbsolute(String(input.hostEntry)) ||
+        !validPort(input.port) || !validPort(input.serverPort) || input.port === input.serverPort ||
+        !samePath(String(input.identityPath), paths.identityPath) ||
+        !samePath(String(input.controlPath), paths.controlPath) || !samePath(String(input.logPath), paths.logPath))
+        throw new Error('community_cockpit_process_schema_invalid');
+    return input;
+}
+function readProcess(paths) {
+    assertPaths(paths);
+    if (!existsSync(paths.processPath))
+        return null;
+    return parseProcess(readJson(paths.processPath, 'community_cockpit_process_json_invalid'), paths);
+}
+function writeProcess(paths, record) {
+    assertPaths(paths);
+    atomicJsonWrite(paths.processPath, record);
+}
+function parseIdentity(paths, record) {
+    const value = readJson(paths.identityPath, 'community_cockpit_identity_json_invalid');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('community_cockpit_identity_invalid');
+    }
+    const input = value;
+    const keys = Object.keys(input).sort().join(',');
+    if (keys !== 'controlPath,hostEntry,hostPid,launchId,pid,port,protocol,schemaVersion,sourceFingerprint,startedAt') {
+        throw new Error('community_cockpit_identity_schema_invalid');
+    }
+    if (input.schemaVersion !== 1 || input.protocol !== COMMUNITY_NATIVE_CHILD_PROTOCOL ||
+        input.launchId !== record.launchId || input.pid !== record.pid ||
+        !Number.isSafeInteger(input.hostPid) || input.hostPid < 1 || input.startedAt !== record.startedAt ||
+        input.sourceFingerprint !== record.sourceFingerprint || !samePath(input.hostEntry, record.hostEntry) ||
+        !samePath(input.controlPath, paths.controlPath) || input.port !== record.port)
+        throw new Error('community_cockpit_identity_mismatch');
+    return input;
+}
+function parseControl(paths) {
+    const value = readJson(paths.controlPath, 'community_cockpit_control_json_invalid');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('community_cockpit_control_invalid');
+    }
+    const input = value;
+    if (Object.keys(input).sort().join(',') !== 'command,launchId,protocol,requestedAt,schemaVersion' ||
+        input.schemaVersion !== 1 || input.protocol !== COMMUNITY_NATIVE_CONTROL_PROTOCOL ||
+        !UUID.test(String(input.launchId)) || input.command !== 'stop' ||
+        Number.isNaN(Date.parse(String(input.requestedAt))))
+        throw new Error('community_cockpit_control_schema_invalid');
+    return input;
+}
+function removeControlIfOwned(paths, launchId) {
+    if (!existsSync(paths.controlPath))
+        return;
+    const control = parseControl(paths);
+    if (control.launchId !== launchId)
+        throw new Error('community_cockpit_control_launch_mismatch');
+    rmSync(paths.controlPath, { force: true });
+}
+function removeIdentityIfOwned(paths, record) {
+    if (!existsSync(paths.identityPath))
+        return;
+    parseIdentity(paths, record);
+    rmSync(paths.identityPath, { force: true });
+}
+function writeStopRequest(paths, launchId, now) {
+    if (existsSync(paths.controlPath)) {
+        const existing = parseControl(paths);
+        if (existing.launchId === launchId)
+            return;
+        throw new Error('community_cockpit_control_launch_mismatch');
+    }
+    atomicJsonWrite(paths.controlPath, {
+        schemaVersion: 1,
+        protocol: COMMUNITY_NATIVE_CONTROL_PROTOCOL,
+        launchId,
+        command: 'stop',
+        requestedAt: now().toISOString(),
+    });
+}
+function statusBase(state, port, serverPort = state.server.publicPort) {
+    return {
+        origin: `http://127.0.0.1:${port}`,
+        serverOrigin: `http://127.0.0.1:${serverPort}`,
+        port,
+    };
+}
+async function observeCockpit(params) {
+    const record = params.processRecord;
+    const identityPresent = existsSync(params.paths.identityPath);
+    const port = record?.port ?? params.state.cockpit.port;
+    const base = statusBase(params.state, port, record?.serverPort);
+    if (!record) {
+        return {
+            ...base,
+            runtimeState: identityPresent ? 'identity-conflict' : 'stopped',
+            recoverable: !identityPresent,
+            process: null,
+            identity: null,
+            supervisorAlive: false,
+            hostAlive: false,
+            health: 'not-checked',
+            reason: identityPresent ? 'community_cockpit_identity_without_process_record' : null,
+        };
+    }
+    const supervisorAlive = params.runtime.processExists(record.pid);
+    let identity = null;
+    if (identityPresent) {
+        try {
+            identity = parseIdentity(params.paths, record);
+        }
+        catch (error) {
+            return {
+                ...base,
+                runtimeState: 'identity-conflict', recoverable: false, process: record, identity: null,
+                supervisorAlive, hostAlive: record.hostPid ? params.runtime.processExists(record.hostPid) : false,
+                health: 'not-checked',
+                reason: error instanceof Error ? error.message : 'community_cockpit_identity_invalid',
+            };
+        }
+    }
+    const hostPid = identity?.hostPid ?? record.hostPid;
+    const hostAlive = hostPid ? params.runtime.processExists(hostPid) : false;
+    const active = record.status === 'starting' || record.status === 'running';
+    if (!active) {
+        if (!supervisorAlive && !hostAlive) {
+            return {
+                ...base,
+                runtimeState: 'stopped', recoverable: true, process: record, identity,
+                supervisorAlive: false, hostAlive: false, health: 'not-checked',
+                reason: identity ? 'community_cockpit_terminal_identity_stale' : null,
+            };
+        }
+        return {
+            ...base,
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_cockpit_terminal_record_with_live_or_unowned_process',
+        };
+    }
+    if (!supervisorAlive && !hostAlive) {
+        return {
+            ...base,
+            runtimeState: 'crashed', recoverable: true, process: record, identity,
+            supervisorAlive: false, hostAlive: false, health: 'not-checked',
+            reason: 'community_cockpit_process_disappeared',
+        };
+    }
+    if (record.instanceName !== params.state.instanceName) {
+        return {
+            ...base,
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_cockpit_process_instance_mismatch',
+        };
+    }
+    if (!identity) {
+        return {
+            ...base,
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity: null,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_cockpit_live_process_without_matching_identity',
+        };
+    }
+    if (!supervisorAlive && hostAlive) {
+        return {
+            ...base,
+            runtimeState: 'orphaned', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked', reason: 'community_cockpit_host_orphaned',
+        };
+    }
+    if (supervisorAlive && !hostAlive) {
+        return {
+            ...base,
+            runtimeState: 'unhealthy', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'unhealthy', reason: 'community_cockpit_host_process_missing',
+        };
+    }
+    const healthy = await params.runtime.health(`${base.origin}/_aops/cockpit-health`);
+    return {
+        ...base,
+        runtimeState: healthy ? 'running' : record.status === 'starting' ? 'starting' : 'unhealthy',
+        recoverable: false,
+        process: record,
+        identity,
+        supervisorAlive,
+        hostAlive,
+        health: healthy ? 'healthy' : 'unhealthy',
+        reason: healthy ? null : 'community_cockpit_health_failed',
+    };
+}
+export async function inspectCommunityNativeCockpit(params = {}) {
+    const install = inspectCommunityNativeInstall(params);
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`community_native_not_installed:${install.status}:${install.error ?? 'run_setup_init'}`);
+    }
+    const paths = resolveCommunityCockpitPaths(params);
+    return observeCockpit({
+        state: install.state,
+        paths,
+        processRecord: readProcess(paths),
+        runtime: params.runtime ?? communityNativeRuntime,
+    });
+}
+function cockpitEnvironment(params) {
+    const env = { ...(params.env ?? process.env) };
+    for (const key of Object.keys(env)) {
+        const upper = key.toUpperCase();
+        if (/^PG[A-Z0-9_]+$/i.test(key) || /^(?:AOPS|PROJECTMAN|DOCMAN|AGENTSPACE|CHATV3|AUTHV2|KANBAN|SPRINT|TASKER|FILEMAN|SYS)_/i.test(key) ||
+            /(?:^|_)(?:AUTH|COOKIE|DATABASE|ENCRYPT|JWT|PASSWORD|PG|POSTGRES|SECRET|SESSION|SQLITE|TOKEN)(?:_|$)/i.test(key) ||
+            /_(?:REPO|PG|SQLITE)_URL$/i.test(key) || /^NODE_/i.test(key) || /^DYLD_/i.test(key) ||
+            ['DATABASE_URL', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'SSLKEYLOGFILE', 'HTTP_PROXY', 'HTTPS_PROXY',
+                'ALL_PROXY', 'NO_PROXY', 'ADDRESS_HEADER', 'XFF_DEPTH', 'PROTOCOL_HEADER', 'HOST_HEADER'].includes(upper))
+            delete env[key];
+    }
+    return {
+        ...env,
+        NODE_ENV: 'production',
+        AOPS_NATIVE_LAUNCH_ID: params.launchId,
+        AOPS_NATIVE_STARTED_AT: params.startedAt,
+        AOPS_NATIVE_SOURCE_FINGERPRINT: params.state.source.sourceFingerprint,
+        AOPS_NATIVE_HOST_ENTRY: params.state.build.hostEntry,
+        AOPS_NATIVE_IDENTITY_PATH: params.paths.identityPath,
+        AOPS_NATIVE_CONTROL_PATH: params.paths.controlPath,
+        AOPS_NATIVE_PORT: String(params.state.cockpit.port),
+        COMMUNITY_PORT: String(params.state.cockpit.port),
+        AOPS_COMMUNITY_HOST_MODE: 'cockpit',
+        AOPS_COMMUNITY_SERVER_PORT: String(params.state.server.publicPort),
+    };
+}
+async function stopSpawnedCockpit(params) {
+    writeStopRequest(params.paths, params.processRecord.launchId, params.now);
+    let identity = null;
+    const pollCount = Math.max(1, Math.ceil(params.timeoutMs / POLL_MS));
+    for (let attempt = 0; attempt < pollCount; attempt += 1) {
+        if (existsSync(params.paths.identityPath)) {
+            identity = parseIdentity(params.paths, params.processRecord);
+        }
+        const supervisorAlive = params.runtime.processExists(params.processRecord.pid);
+        const hostAlive = identity ? params.runtime.processExists(identity.hostPid) : false;
+        if (!supervisorAlive && !hostAlive) {
+            if (existsSync(params.paths.identityPath))
+                removeIdentityIfOwned(params.paths, params.processRecord);
+            removeControlIfOwned(params.paths, params.processRecord.launchId);
+            return;
+        }
+        await params.runtime.sleep(POLL_MS);
+    }
+    const supervisorAlive = params.runtime.processExists(params.processRecord.pid);
+    const hostAlive = identity ? params.runtime.processExists(identity.hostPid) : false;
+    if (!supervisorAlive && !hostAlive) {
+        if (existsSync(params.paths.identityPath))
+            removeIdentityIfOwned(params.paths, params.processRecord);
+        removeControlIfOwned(params.paths, params.processRecord.launchId);
+        return;
+    }
+    if (identity) {
+        throw new Error('community_cockpit_child_cleanup_timeout:verified_processes_left_running');
+    }
+    await params.handle.terminate();
+    if (params.runtime.processExists(params.processRecord.pid)) {
+        throw new Error('community_cockpit_child_cleanup_timeout:supervisor_still_running');
+    }
+    removeControlIfOwned(params.paths, params.processRecord.launchId);
+}
+async function waitUntilReady(params) {
+    const deadline = Date.now() + params.timeoutMs;
+    const child = {};
+    void params.handle.wait.then((value) => { child.exit = value; }, (error) => { child.failure = error; });
+    try {
+        while (Date.now() < deadline) {
+            throwIfAborted(params.signal);
+            if (child.failure)
+                throw new Error('community_cockpit_child_launch_failed');
+            if (child.exit) {
+                throw new Error(`community_cockpit_child_exited_before_ready:${child.exit.exitCode ?? child.exit.signal ?? 'unknown'}`);
+            }
+            if (existsSync(params.paths.identityPath)) {
+                const identity = parseIdentity(params.paths, params.processRecord);
+                if (await params.runtime.health(`http://127.0.0.1:${params.state.cockpit.port}/_aops/cockpit-health`, params.signal)) {
+                    return identity;
+                }
+            }
+            await params.runtime.sleep(POLL_MS, params.signal);
+        }
+        throw new Error('community_cockpit_child_ready_timeout');
+    }
+    catch (error) {
+        await stopSpawnedCockpit(params);
+        throw error;
+    }
+}
+async function withCockpitLifecycleLock(params, operation, callback) {
+    const install = inspectCommunityNativeInstall(params);
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`community_native_not_installed:${install.status}:${install.error ?? 'run_setup_init'}`);
+    }
+    const paths = resolveCommunityCockpitPaths(params);
+    return (params.withOperationLock ?? withCommunityOperationLock)({ instanceDirectory: paths.runtimeRoot, operation, signal: params.signal }, callback);
+}
+async function startCommunityNativeCockpitUnlocked(params = {}) {
+    throwIfAborted(params.signal);
+    const install = inspectCommunityNativeInstall(params);
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`community_native_not_installed:${install.status}:${install.error ?? 'run_setup_init'}`);
+    }
+    const state = install.state;
+    const paths = resolveCommunityCockpitPaths(params);
+    const runtime = params.runtime ?? communityNativeRuntime;
+    const prior = readProcess(paths);
+    const observed = await observeCockpit({ state, paths, processRecord: prior, runtime });
+    if (observed.runtimeState === 'running') {
+        return {
+            action: 'already-running', state, paths, process: observed.process,
+            origin: observed.origin, serverOrigin: observed.serverOrigin,
+        };
+    }
+    if (observed.runtimeState !== 'stopped' && observed.runtimeState !== 'crashed') {
+        throw new Error(`community_cockpit_process_active:${observed.runtimeState}:${observed.reason ?? 'run_cockpit_status'}`);
+    }
+    if (prior)
+        removeIdentityIfOwned(paths, prior);
+    if (prior)
+        removeControlIfOwned(paths, prior.launchId);
+    mkdirSync(paths.logRoot, { recursive: true, mode: 0o700 });
+    assertPaths(paths);
+    const now = params.now ?? (() => new Date());
+    const launchId = (params.createId ?? randomUUID)();
+    const startedAt = now().toISOString();
+    const handle = await runtime.spawnChild({
+        childEntry: resolveCommunityNativeChildEntry(),
+        cwd: state.source.root,
+        env: cockpitEnvironment({ state, paths, launchId, startedAt, env: params.env }),
+        mode: 'detached',
+        logPath: paths.logPath,
+    });
+    let record = {
+        schemaVersion: 1,
+        protocol: COMMUNITY_NATIVE_CHILD_PROTOCOL,
+        service: 'cockpit',
+        instanceName: state.instanceName,
+        launchId,
+        pid: handle.pid,
+        status: 'starting',
+        startedAt,
+        updatedAt: startedAt,
+        sourceFingerprint: state.source.sourceFingerprint,
+        hostEntry: state.build.hostEntry,
+        port: state.cockpit.port,
+        serverPort: state.server.publicPort,
+        identityPath: paths.identityPath,
+        controlPath: paths.controlPath,
+        logPath: paths.logPath,
+    };
+    writeProcess(paths, record);
+    try {
+        const identity = await waitUntilReady({
+            state, paths, processRecord: record, handle, runtime,
+            timeoutMs: params.readyTimeoutMs ?? READY_TIMEOUT_MS,
+            now,
+            signal: params.signal,
+        });
+        record = { ...record, hostPid: identity.hostPid, status: 'running', updatedAt: now().toISOString() };
+        writeProcess(paths, record);
+    }
+    catch (error) {
+        const liveAfterFailure = runtime.processExists(record.pid) || (() => {
+            try {
+                return existsSync(paths.identityPath) && runtime.processExists(parseIdentity(paths, record).hostPid);
+            }
+            catch {
+                return false;
+            }
+        })();
+        record = {
+            ...record,
+            status: liveAfterFailure ? 'starting' : 'failed',
+            updatedAt: now().toISOString(),
+            failure: error instanceof Error ? error.message.slice(0, 300) : 'community_cockpit_launch_failed',
+        };
+        writeProcess(paths, record);
+        throw error;
+    }
+    handle.detach();
+    return {
+        action: 'started', state, paths, process: record,
+        origin: `http://127.0.0.1:${state.cockpit.port}`,
+        serverOrigin: `http://127.0.0.1:${state.server.publicPort}`,
+    };
+}
+export async function startCommunityNativeCockpit(params = {}) {
+    return withCockpitLifecycleLock(params, 'start', () => startCommunityNativeCockpitUnlocked(params));
+}
+async function stopCommunityNativeCockpitUnlocked(params = {}) {
+    throwIfAborted(params.signal);
+    const install = inspectCommunityNativeInstall(params);
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`community_native_not_installed:${install.status}:${install.error ?? 'run_setup_init'}`);
+    }
+    const paths = resolveCommunityCockpitPaths(params);
+    const runtime = params.runtime ?? communityNativeRuntime;
+    const now = params.now ?? (() => new Date());
+    const observed = await observeCockpit({
+        state: install.state,
+        paths,
+        processRecord: readProcess(paths),
+        runtime,
+    });
+    if (observed.runtimeState === 'stopped' || observed.runtimeState === 'crashed') {
+        return { status: 'already-stopped', state: install.state, process: observed.process };
+    }
+    if (!observed.process || !observed.identity || !observed.supervisorAlive ||
+        !['starting', 'running', 'unhealthy'].includes(observed.runtimeState)) {
+        throw new Error(`community_cockpit_stop_refused:${observed.runtimeState}:${observed.reason ?? 'identity_not_verified'}`);
+    }
+    writeStopRequest(paths, observed.process.launchId, now);
+    const deadline = Date.now() + (params.timeoutMs ?? STOP_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+        throwIfAborted(params.signal);
+        if (existsSync(paths.identityPath))
+            parseIdentity(paths, observed.process);
+        const supervisorAlive = runtime.processExists(observed.process.pid);
+        const hostAlive = runtime.processExists(observed.identity.hostPid);
+        if (!supervisorAlive && !hostAlive && !existsSync(paths.identityPath)) {
+            removeControlIfOwned(paths, observed.process.launchId);
+            const stopped = {
+                ...observed.process,
+                status: 'exited',
+                updatedAt: now().toISOString(),
+                exitCode: 0,
+                signal: null,
+            };
+            delete stopped.failure;
+            writeProcess(paths, stopped);
+            return { status: 'stopped', state: install.state, process: stopped };
+        }
+        await runtime.sleep(POLL_MS, params.signal);
+    }
+    throw new Error('community_cockpit_stop_timeout:no_unverified_pid_kill');
+}
+export async function stopCommunityNativeCockpit(params = {}) {
+    return withCockpitLifecycleLock(params, 'stop', () => stopCommunityNativeCockpitUnlocked(params));
+}
+export async function restartCommunityNativeCockpit(params = {}) {
+    return withCockpitLifecycleLock(params, 'restart', async () => {
+        await stopCommunityNativeCockpitUnlocked(params);
+        return startCommunityNativeCockpitUnlocked(params);
+    });
+}
+export async function healthCommunityNativeCockpit(params = {}) {
+    const runtime = params.runtime ?? communityNativeRuntime;
+    const status = await inspectCommunityNativeCockpit(params);
+    if (status.runtimeState !== 'running' || status.health !== 'healthy') {
+        return { ...status, apiHealth: 'not-checked', apiReady: false };
+    }
+    const apiReady = await runtime.health(`${status.origin}/api/health`, params.signal);
+    return {
+        ...status,
+        apiHealth: apiReady ? 'healthy' : 'unhealthy',
+        apiReady,
+    };
+}
+export function readCommunityCockpitLogs(params = {}) {
+    const install = inspectCommunityNativeInstall(params);
+    if (install.status !== 'installed' || !install.state) {
+        throw new Error(`community_native_not_installed:${install.status}:${install.error ?? 'run_setup_init'}`);
+    }
+    const paths = resolveCommunityCockpitPaths(params);
+    assertPaths(paths);
+    const tail = Number(params.tail ?? 100);
+    if (!Number.isSafeInteger(tail) || tail < 1 || tail > 10_000)
+        throw new Error('community_logs_tail_invalid');
+    if (!existsSync(paths.logPath))
+        return { content: '', lineCount: 0, truncated: false, logPath: paths.logPath };
+    const stats = lstatSync(paths.logPath);
+    const byteLength = Math.min(stats.size, MAX_LOG_TAIL_BYTES);
+    const start = stats.size - byteLength;
+    const buffer = Buffer.alloc(byteLength);
+    const fd = openSync(paths.logPath, 'r');
+    try {
+        if (byteLength > 0)
+            readSync(fd, buffer, 0, byteLength, start);
+    }
+    finally {
+        closeSync(fd);
+    }
+    let content = buffer.toString('utf8');
+    let truncated = start > 0;
+    if (truncated) {
+        const firstNewline = content.indexOf('\n');
+        content = firstNewline >= 0 ? content.slice(firstNewline + 1) : '';
+    }
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    const selected = lines.slice(-tail);
+    truncated ||= selected.length < lines.length;
+    return { content: selected.join('\n'), lineCount: selected.length, truncated, logPath: paths.logPath };
+}

package/dist/lib/community-command-abort.js

@@ -0,0 +1,59 @@
+export const COMMUNITY_COMMAND_ABORT_MESSAGE = 'community_operation_aborted';
+export class CommunityCommandAbortedError extends Error {
+    code = 'COMMUNITY_OPERATION_ABORTED';
+    constructor() {
+        super(COMMUNITY_COMMAND_ABORT_MESSAGE);
+        this.name = 'CommunityCommandAbortedError';
+    }
+}
+export const communityCommandAbortRuntime = Object.freeze({
+    createController: () => new AbortController(),
+    addSignalListener: (signal, listener) => process.on(signal, listener),
+    removeSignalListener: (signal, listener) => process.off(signal, listener),
+});
+export function throwIfCommunityCommandAborted(signal) {
+    if (signal?.aborted)
+        throw new CommunityCommandAbortedError();
+}
+export async function withCommunityCommandAbortScope(runtime, callback) {
+    const controller = runtime.createController();
+    const registrations = [];
+    const abort = () => {
+        if (!controller.signal.aborted)
+            controller.abort(new CommunityCommandAbortedError());
+    };
+    let failed = false;
+    let failure;
+    let result;
+    try {
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            registrations.push(signal);
+            runtime.addSignalListener(signal, abort);
+        }
+        throwIfCommunityCommandAborted(controller.signal);
+        result = await callback(controller.signal);
+        throwIfCommunityCommandAborted(controller.signal);
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+    }
+    let cleanupFailed = false;
+    let cleanupFailure;
+    for (const signal of registrations) {
+        try {
+            runtime.removeSignalListener(signal, abort);
+        }
+        catch (error) {
+            if (!cleanupFailed) {
+                cleanupFailed = true;
+                cleanupFailure = error;
+            }
+        }
+    }
+    if (failed)
+        throw failure;
+    if (cleanupFailed)
+        throw cleanupFailure;
+    return result;
+}