@aopslabs/aops 0.3.11 → 0.3.13

package/dist/commands/global-update.js

@@ -0,0 +1,623 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { compareCanonicalText } from '@aopslabs/artifact-trust-contracts';
+import { Command } from 'commander';
+const CHECK_CONTRACT = 'aops.global-update-check/v1';
+const PLAN_CONTRACT = 'aops.global-update-plan/v1';
+const RESULT_CONTRACT = 'aops.global-update-result/v1';
+const PUBLIC_REGISTRY = 'https://registry.npmjs.org';
+const EXACT_STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+const PLAN_ID = /^sha256:[a-f0-9]{64}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const SHA512_INTEGRITY = /^sha512-[A-Za-z0-9+/]+={0,2}$/u;
+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}$/iu;
+const PACKAGE_NAMES = ['@aopslabs/aops', '@aopslabs/aops-server'];
+const HEALTH_SAMPLES = 4;
+const HEALTH_INTERVAL_MS = 3_000;
+const HEALTH_STARTUP_ATTEMPTS = 30;
+const HEALTH_STARTUP_INTERVAL_MS = 2_000;
+function cleanEnvironment() {
+    return {
+        ...process.env,
+        NPM_TOKEN: '',
+        NODE_AUTH_TOKEN: '',
+        GH_TOKEN: '',
+        GITHUB_TOKEN: '',
+        NPM_CONFIG_REGISTRY: PUBLIC_REGISTRY,
+        NPM_CONFIG_USERCONFIG: os.devNull,
+        npm_config_registry: PUBLIC_REGISTRY,
+        npm_config_userconfig: os.devNull,
+    };
+}
+function defaultRunner(command, args, cwd = process.cwd()) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: 'utf8',
+        shell: false,
+        windowsHide: true,
+        maxBuffer: 32 * 1024 * 1024,
+        env: cleanEnvironment(),
+    });
+    if (result.error)
+        throw result.error;
+    assert.equal(result.status, 0, `${command} ${args.join(' ')} failed\n${result.stdout}\n${result.stderr}`);
+    return result.stdout;
+}
+export function resolveNpmInvocation(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== 'win32')
+        return { command: 'npm', prefixArgs: [] };
+    const nodeExecutable = path.resolve(options.nodeExecutable ?? process.execPath);
+    const environment = options.environment ?? process.env;
+    const fileExists = options.fileExists ?? existsSync;
+    const candidates = [
+        path.join(path.dirname(nodeExecutable), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    const npmExecPath = environment.npm_execpath?.trim();
+    if (npmExecPath && /^npm-cli\.(?:c?js)$/iu.test(path.basename(npmExecPath))) {
+        candidates.push(path.resolve(npmExecPath));
+    }
+    for (const entry of String(environment.PATH ?? '').split(path.delimiter)) {
+        if (!entry.trim())
+            continue;
+        candidates.push(path.resolve(entry, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+    }
+    const npmCli = [...new Set(candidates)].find((candidate) => fileExists(candidate));
+    assert.ok(npmCli, 'windows_npm_cli_not_found');
+    return { command: nodeExecutable, prefixArgs: [npmCli] };
+}
+function runNpm(run, args, cwd) {
+    const invocation = resolveNpmInvocation();
+    return run(invocation.command, [...invocation.prefixArgs, ...args], cwd);
+}
+export function publicNpmArgs(args) {
+    return [
+        ...args,
+        `--registry=${PUBLIC_REGISTRY}`,
+        `--@aopslabs:registry=${PUBLIC_REGISTRY}`,
+        `--userconfig=${os.devNull}`,
+    ];
+}
+function parseJson(value, label) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${label}_invalid_json`);
+    }
+}
+function exactVersion(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    assert.match(value, EXACT_STABLE_VERSION, `${label} must be an exact stable version`);
+    return value;
+}
+export function compareStableVersions(left, right) {
+    const leftParts = exactVersion(left, 'left version').split('.').map(Number);
+    const rightParts = exactVersion(right, 'right version').split('.').map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return leftParts[index] - rightParts[index];
+    }
+    return 0;
+}
+function sha256(file) {
+    return createHash('sha256').update(readFileSync(file)).digest('hex');
+}
+function plainDirectory(candidate, label) {
+    const absolute = path.resolve(candidate);
+    const stat = lstatSync(absolute);
+    assert.equal(stat.isDirectory() && !stat.isSymbolicLink(), true, `${label} must be a plain directory`);
+    return realpathSync.native(absolute);
+}
+function plainFile(candidate, label) {
+    const absolute = path.resolve(candidate);
+    const stat = lstatSync(absolute);
+    assert.equal(stat.isFile() && !stat.isSymbolicLink(), true, `${label} must be a plain file`);
+    return realpathSync.native(absolute);
+}
+function ensureWithin(parent, candidate, label) {
+    const relative = path.relative(parent, candidate);
+    assert.equal(Boolean(relative) && !relative.startsWith('..') && !path.isAbsolute(relative), true, `${label} must stay inside ${parent}`);
+    return candidate;
+}
+function packageManifest(packageRoot, expectedName) {
+    const manifestPath = plainFile(path.join(packageRoot, 'package.json'), `${expectedName} manifest`);
+    const manifest = parseJson(readFileSync(manifestPath, 'utf8'), `${expectedName}_manifest`);
+    assert.equal(manifest.name, expectedName, `${expectedName} package identity mismatch`);
+    exactVersion(manifest.version, `${expectedName} version`);
+    return manifest;
+}
+function inspectGlobalInstall(run) {
+    const globalPrefix = plainDirectory(runNpm(run, ['prefix', '--global']).trim(), 'global npm prefix');
+    const globalRoot = plainDirectory(runNpm(run, ['root', '--global']).trim(), 'global npm root');
+    ensureWithin(globalPrefix, globalRoot, 'global npm root');
+    const cliRoot = path.join(globalRoot, '@aopslabs', 'aops');
+    const cli = packageManifest(cliRoot, '@aopslabs/aops');
+    const nestedServerRoot = path.join(cliRoot, 'node_modules', '@aopslabs', 'aops-server');
+    const dependencies = cli.dependencies;
+    const exactServerDependency = exactVersion(dependencies?.['@aopslabs/aops-server'], 'installed CLI Server dependency');
+    const topLevelServerRoot = path.join(globalRoot, '@aopslabs', 'aops-server');
+    const nestedServer = existsSync(path.join(nestedServerRoot, 'package.json'));
+    const topLevelServer = existsSync(path.join(topLevelServerRoot, 'package.json'));
+    assert.equal(nestedServer || topLevelServer, true, 'global AOPS Server package was not found');
+    for (const [serverRoot, placement] of [
+        [nestedServerRoot, 'nested'],
+        [topLevelServerRoot, 'top-level'],
+    ]) {
+        if (!existsSync(path.join(serverRoot, 'package.json')))
+            continue;
+        const server = packageManifest(serverRoot, '@aopslabs/aops-server');
+        assert.equal(exactVersion(server.version, `installed ${placement} Server version`), exactServerDependency, `installed ${placement} Server does not match the CLI exact dependency`);
+    }
+    const cliPath = plainFile(path.join(cliRoot, 'dist', 'main.js'), 'global AOPS CLI entrypoint');
+    const serverPath = plainDirectory(nestedServer ? nestedServerRoot : topLevelServerRoot, 'global AOPS Server root');
+    return {
+        globalPrefix,
+        globalRoot,
+        cliPath,
+        serverPath,
+        packages: {
+            cli: exactVersion(cli.version, 'installed CLI version'),
+            server: exactServerDependency,
+        },
+        topology: { nestedServer, topLevelServer },
+    };
+}
+function npmViewString(run, selector, field) {
+    const value = parseJson(runNpm(run, publicNpmArgs(['view', selector, field, '--json'])).trim(), `npm_view_${field}`);
+    if (typeof value !== 'string')
+        throw new Error(`${selector} ${field} must be a string`);
+    return value;
+}
+function availableClosure(run) {
+    const cli = exactVersion(npmViewString(run, '@aopslabs/aops', 'dist-tags.latest'), 'latest CLI version');
+    const server = exactVersion(npmViewString(run, `@aopslabs/aops@${cli}`, 'dependencies.@aopslabs/aops-server'), 'CLI Server dependency');
+    return { cli, server };
+}
+export function inspectGlobalUpdate(run = defaultRunner) {
+    const installation = inspectGlobalInstall(run);
+    const installed = installation.packages;
+    const available = availableClosure(run);
+    assert.equal(compareStableVersions(available.cli, installed.cli) >= 0, true, 'public npm latest must not downgrade the installed CLI');
+    const cliVersionDelta = compareStableVersions(available.cli, installed.cli);
+    const cliUpdateAvailable = cliVersionDelta > 0;
+    const updateAvailable = cliUpdateAvailable ||
+        !installation.topology.nestedServer ||
+        installation.topology.topLevelServer;
+    assert.equal(compareStableVersions(available.server, installed.server) >= 0 || cliUpdateAvailable, true, 'latest CLI closure would unexpectedly downgrade the installed Server without a CLI update');
+    return {
+        schemaVersion: 1,
+        contract: CHECK_CONTRACT,
+        status: updateAvailable ? 'update-available' : 'current',
+        installed,
+        available,
+        updateAvailable,
+        installedTopology: installation.topology,
+        registry: PUBLIC_REGISTRY,
+    };
+}
+function runInstalledJson(run, cliPath, args) {
+    return parseJson(run(process.execPath, [cliPath, ...args]).trim(), args.join('_'));
+}
+function serviceSnapshot(run, cliPath) {
+    return {
+        server: runInstalledJson(run, cliPath, ['server', 'status', '--json']),
+        cockpit: runInstalledJson(run, cliPath, ['cockpit', 'status', '--json']),
+    };
+}
+function assertHealthyServices(services) {
+    assert.equal(services.server.runtimeState, 'running', 'AOPS Server must be running before update');
+    assert.equal(services.server.liveness?.health, 'healthy', 'AOPS Server must be healthy before update');
+    assert.equal(services.cockpit.runtimeState, 'running', 'AOPS Cockpit must be running before update');
+    assert.equal(services.cockpit.health, 'healthy', 'AOPS Cockpit must be healthy before update');
+}
+function packRegistryPackage(run, destination, name, version) {
+    const packed = parseJson(runNpm(run, publicNpmArgs([
+        'pack',
+        `${name}@${version}`,
+        '--ignore-scripts',
+        '--json',
+        '--pack-destination',
+        destination,
+    ])), 'npm_pack');
+    assert.equal(packed.length, 1, `${name}@${version} must produce one tarball`);
+    assert.equal(packed[0].name, name);
+    assert.equal(packed[0].version, version);
+    const registryIntegrity = npmViewString(run, `${name}@${version}`, 'dist.integrity');
+    assert.equal(packed[0].integrity, registryIntegrity, `${name}@${version} integrity mismatch`);
+    const file = plainFile(path.join(destination, packed[0].filename), `${name}@${version} tarball`);
+    return { name, version, path: file, integrity: registryIntegrity, sha256: sha256(file) };
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => canonicalJson(entry));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => compareCanonicalText(left, right))
+            .map(([key, entry]) => [key, canonicalJson(entry)]));
+    }
+    return value;
+}
+function canonicalPlanBody(plan) {
+    return JSON.stringify(canonicalJson(plan));
+}
+export function computeGlobalUpdatePlanId(plan) {
+    return `sha256:${createHash('sha256').update(canonicalPlanBody(plan)).digest('hex')}`;
+}
+function defaultUpdateRoot(configRoot) {
+    const root = configRoot?.trim()
+        ? path.resolve(configRoot)
+        : path.join(os.homedir(), '.aops');
+    if (!existsSync(root))
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+    return plainDirectory(root, 'AOPS config root');
+}
+export function prepareGlobalUpdate(options = {}, run = defaultRunner) {
+    const check = inspectGlobalUpdate(run);
+    assert.equal(check.updateAvailable, true, 'aops_global_update_not_available');
+    const installed = inspectGlobalInstall(run);
+    const services = serviceSnapshot(run, installed.cliPath);
+    assertHealthyServices(services);
+    const configRoot = defaultUpdateRoot(options.configRoot);
+    const updatesRoot = path.join(configRoot, 'global-updates');
+    mkdirSync(updatesRoot, { recursive: true, mode: 0o700 });
+    const operationRoot = path.join(updatesRoot, `${Date.now()}-${process.pid}`);
+    mkdirSync(operationRoot, { recursive: false, mode: 0o700 });
+    const candidateRoot = path.join(operationRoot, 'candidate');
+    const restoreRoot = path.join(operationRoot, 'restore');
+    const cacheRoot = path.join(operationRoot, 'cache');
+    mkdirSync(candidateRoot, { mode: 0o700 });
+    mkdirSync(restoreRoot, { mode: 0o700 });
+    mkdirSync(cacheRoot, { mode: 0o700 });
+    const candidates = [
+        packRegistryPackage(run, candidateRoot, '@aopslabs/aops', check.available.cli),
+        packRegistryPackage(run, candidateRoot, '@aopslabs/aops-server', check.available.server),
+    ];
+    const restorePackages = [
+        packRegistryPackage(run, restoreRoot, '@aopslabs/aops', check.installed.cli),
+        packRegistryPackage(run, restoreRoot, '@aopslabs/aops-server', check.installed.server),
+    ];
+    const body = {
+        schemaVersion: 1,
+        contract: PLAN_CONTRACT,
+        createdAt: new Date().toISOString(),
+        globalPrefix: installed.globalPrefix,
+        globalRoot: installed.globalRoot,
+        cliPath: installed.cliPath,
+        operationRoot,
+        prior: { packages: installed.packages, topology: installed.topology, services },
+        target: {
+            packages: check.available,
+            topology: { nestedServer: true, topLevelServer: false },
+        },
+        candidates,
+        restorePackages,
+        safety: {
+            candidateIntegrity: 'verified-from-public-registry',
+            restoreIntegrity: 'verified-from-public-registry',
+            automaticRollback: true,
+            requiresExactConfirmation: true,
+            healthSamples: HEALTH_SAMPLES,
+            healthIntervalMs: HEALTH_INTERVAL_MS,
+            healthStartupAttempts: HEALTH_STARTUP_ATTEMPTS,
+            healthStartupIntervalMs: HEALTH_STARTUP_INTERVAL_MS,
+        },
+    };
+    const plan = { ...body, planId: computeGlobalUpdatePlanId(body) };
+    const planPath = path.join(operationRoot, 'update-plan.json');
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    return { check, plan, planPath };
+}
+function packageRecordByName(records, name) {
+    const matches = records.filter((record) => record.name === name);
+    assert.equal(matches.length, 1, `update plan must contain exactly one ${name} tarball`);
+    return matches[0];
+}
+function validateRecordSet(records, expected, root, label) {
+    assert.equal(records.length, PACKAGE_NAMES.length, `${label} must contain exactly two packages`);
+    for (const [name, version] of [
+        ['@aopslabs/aops', expected.cli],
+        ['@aopslabs/aops-server', expected.server],
+    ]) {
+        const record = packageRecordByName(records, name);
+        assert.equal(exactVersion(record.version, `${name} ${label} version`), version);
+        assert.match(record.integrity, SHA512_INTEGRITY, `${name} ${label} integrity is invalid`);
+        assert.match(record.sha256, SHA256, `${name} ${label} sha256 is invalid`);
+        const file = plainFile(record.path, `${name} ${label} tarball`);
+        ensureWithin(root, file, `${name} ${label} tarball`);
+        assert.equal(file, record.path, `${name} ${label} tarball must be canonical`);
+        assert.equal(sha256(file), record.sha256, `${name} tarball changed after planning`);
+    }
+}
+export function readGlobalUpdatePlan(planPath) {
+    const resolved = plainFile(planPath, 'global update plan');
+    const plan = parseJson(readFileSync(resolved, 'utf8'), 'global_update_plan');
+    assert.equal(plan.schemaVersion, 1);
+    assert.equal(plan.contract, PLAN_CONTRACT);
+    assert.match(plan.planId, PLAN_ID);
+    const { planId, ...body } = plan;
+    assert.equal(planId, computeGlobalUpdatePlanId(body), 'global update plan identity mismatch');
+    plainDirectory(plan.globalPrefix, 'planned global npm prefix');
+    plainDirectory(plan.globalRoot, 'planned global npm root');
+    ensureWithin(plan.globalPrefix, plan.globalRoot, 'planned global npm root');
+    const operationRoot = plainDirectory(plan.operationRoot, 'global update operation root');
+    assert.equal(operationRoot, path.dirname(resolved), 'global update plan must stay at its operation root');
+    assert.deepEqual(plan.target.topology, { nestedServer: true, topLevelServer: false });
+    exactVersion(plan.prior.packages.cli, 'prior CLI version');
+    exactVersion(plan.prior.packages.server, 'prior Server version');
+    exactVersion(plan.target.packages.cli, 'target CLI version');
+    exactVersion(plan.target.packages.server, 'target Server version');
+    validateRecordSet(plan.candidates, plan.target.packages, operationRoot, 'candidate set');
+    validateRecordSet(plan.restorePackages, plan.prior.packages, operationRoot, 'restore set');
+    assert.equal(plan.safety.candidateIntegrity, 'verified-from-public-registry');
+    assert.equal(plan.safety.restoreIntegrity, 'verified-from-public-registry');
+    assert.equal(plan.safety.automaticRollback, true);
+    assert.equal(plan.safety.requiresExactConfirmation, true);
+    assert.equal(plan.safety.healthSamples, HEALTH_SAMPLES);
+    assert.equal(plan.safety.healthIntervalMs, HEALTH_INTERVAL_MS);
+    assert.equal(plan.safety.healthStartupAttempts, HEALTH_STARTUP_ATTEMPTS);
+    assert.equal(plan.safety.healthStartupIntervalMs, HEALTH_STARTUP_INTERVAL_MS);
+    return plan;
+}
+export function installGlobalUpdateClosure(run, plan, records, topology) {
+    const cli = packageRecordByName(records, '@aopslabs/aops');
+    const server = packageRecordByName(records, '@aopslabs/aops-server');
+    const cacheRoot = path.join(plan.operationRoot, 'cache');
+    mkdirSync(cacheRoot, { recursive: true, mode: 0o700 });
+    runNpm(run, publicNpmArgs(['cache', 'add', server.path, `--cache=${cacheRoot}`]));
+    const topLevelServerRoot = path.join(plan.globalRoot, '@aopslabs', 'aops-server');
+    if (existsSync(path.join(topLevelServerRoot, 'package.json'))) {
+        runNpm(run, publicNpmArgs([
+            '--prefix',
+            plan.globalPrefix,
+            'uninstall',
+            '--global',
+            '--ignore-scripts',
+            '--fund=false',
+            '--audit=false',
+            '@aopslabs/aops-server',
+        ]));
+    }
+    const commonInstallArgs = [
+        '--prefix',
+        plan.globalPrefix,
+        'install',
+        '--global',
+        '--ignore-scripts',
+        '--prefer-offline',
+        `--cache=${cacheRoot}`,
+        '--fund=false',
+        '--audit=false',
+    ];
+    if (topology.topLevelServer && !topology.nestedServer) {
+        runNpm(run, publicNpmArgs([...commonInstallArgs, cli.path, server.path]));
+        return;
+    }
+    runNpm(run, publicNpmArgs([...commonInstallArgs, cli.path]));
+    if (topology.topLevelServer) {
+        runNpm(run, publicNpmArgs([
+            ...commonInstallArgs,
+            server.path,
+        ]));
+    }
+}
+function stopService(run, cliPath, service, bestEffort = false) {
+    try {
+        run(process.execPath, [cliPath, service, 'stop', '--json']);
+    }
+    catch (error) {
+        if (!bestEffort)
+            throw error;
+    }
+}
+function startService(run, cliPath, service) {
+    run(process.execPath, [cliPath, service, 'start', '--json']);
+}
+function updateServerApplication(run, cliPath, expected) {
+    const result = runInstalledJson(run, cliPath, ['server', 'update', '--detach', '--json']);
+    assert.equal(result.status, 'community-native-application-updated');
+    assert.equal(result.priorReleaseVersion, expected.prior);
+    assert.equal(result.releaseVersion, expected.target);
+    assert.equal(typeof result.updateId, 'string');
+    assert.match(result.updateId, UUID);
+    return result.updateId;
+}
+function rollbackServerApplication(run, cliPath, updateId, serverPath, expectedRelease) {
+    const result = runInstalledJson(run, cliPath, [
+        'server',
+        'rollback',
+        'app',
+        '--update-id',
+        updateId,
+        '--source-root',
+        serverPath,
+        '--detach',
+        '--json',
+    ]);
+    assert.equal(result.status, 'community-native-application-rolled-back');
+    assert.equal(result.updateId, updateId);
+    assert.equal(result.releaseVersion, expectedRelease);
+}
+const defaultExecutionDependencies = {
+    fetch: globalThis.fetch.bind(globalThis),
+    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+};
+class StartupHealthPending extends Error {
+    constructor(cause) {
+        super('global_update_health_startup_pending', { cause });
+    }
+}
+async function assertStableHealth(run, plan, execution) {
+    const evidence = [];
+    const collectSample = async (sample, startup) => {
+        const installed = inspectGlobalInstall(run);
+        let services;
+        try {
+            services = serviceSnapshot(run, installed.cliPath);
+            assertHealthyServices(services);
+        }
+        catch (error) {
+            if (startup)
+                throw new StartupHealthPending(error);
+            throw error;
+        }
+        const serverOrigin = validateLoopbackOrigin(services.server.origin, 'AOPS Server origin');
+        const cockpitOrigin = validateLoopbackOrigin(services.cockpit.origin, 'AOPS Cockpit origin');
+        const endpoints = [];
+        for (const [name, url] of [
+            ['server', `${serverOrigin}/api/health`],
+            ['cockpit', cockpitOrigin],
+            ['cockpit-proxy', `${cockpitOrigin}/api/health`],
+        ]) {
+            let response;
+            try {
+                response = await execution.fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(15_000) });
+            }
+            catch (error) {
+                if (startup)
+                    throw new StartupHealthPending(error);
+                throw error;
+            }
+            if (response.status !== 200 && startup) {
+                throw new StartupHealthPending(new Error(`${name} health returned ${response.status}`));
+            }
+            assert.equal(response.status, 200, `${name} health returned ${response.status}`);
+            const body = await response.arrayBuffer();
+            endpoints.push({ name, url, status: response.status, bytes: body.byteLength });
+        }
+        return { sample, observedAt: new Date().toISOString(), endpoints };
+    };
+    let startupError;
+    for (let attempt = 1; attempt <= plan.safety.healthStartupAttempts; attempt += 1) {
+        try {
+            evidence.push(await collectSample(1, true));
+            startupError = undefined;
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof StartupHealthPending))
+                throw error;
+            startupError = error.cause ?? error;
+            if (attempt < plan.safety.healthStartupAttempts) {
+                await execution.sleep(plan.safety.healthStartupIntervalMs);
+            }
+        }
+    }
+    if (startupError)
+        throw startupError;
+    for (let sample = 2; sample <= plan.safety.healthSamples; sample += 1) {
+        await execution.sleep(plan.safety.healthIntervalMs);
+        evidence.push(await collectSample(sample, false));
+    }
+    return evidence;
+}
+export function validateLoopbackOrigin(value, label) {
+    assert.equal(typeof value, 'string', `${label} must be a string`);
+    const url = new URL(value);
+    assert.equal(url.protocol, 'http:', `${label} must use http`);
+    assert.equal(url.username, '', `${label} must not include credentials`);
+    assert.equal(url.password, '', `${label} must not include credentials`);
+    assert.equal(['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname), true, `${label} must be loopback`);
+    assert.equal(url.pathname, '/', `${label} must not include a path`);
+    assert.equal(url.search, '', `${label} must not include a query`);
+    assert.equal(url.hash, '', `${label} must not include a fragment`);
+    return url.origin;
+}
+export async function applyGlobalUpdate(options, run = defaultRunner, execution = defaultExecutionDependencies) {
+    const plan = readGlobalUpdatePlan(options.plan);
+    assert.equal(options.confirm, plan.planId, 'global update confirmation does not match the exact plan');
+    const current = inspectGlobalInstall(run);
+    assert.deepEqual(current.packages, plan.prior.packages, 'global packages changed after update planning');
+    assert.deepEqual(current.topology, plan.prior.topology, 'global package topology changed after update planning');
+    assert.equal(current.globalPrefix, plan.globalPrefix, 'global npm prefix changed after update planning');
+    assertHealthyServices(serviceSnapshot(run, current.cliPath));
+    const events = [];
+    let applicationUpdateId = null;
+    try {
+        stopService(run, current.cliPath, 'cockpit');
+        events.push('stopped:cockpit');
+        stopService(run, current.cliPath, 'server');
+        events.push('stopped:server');
+        installGlobalUpdateClosure(run, plan, plan.candidates, plan.target.topology);
+        events.push('installed:candidate');
+        const updated = inspectGlobalInstall(run);
+        assert.deepEqual(updated.packages, plan.target.packages, 'installed candidate closure is not exact');
+        assert.deepEqual(updated.topology, plan.target.topology, 'installed candidate topology is not canonical');
+        applicationUpdateId = updateServerApplication(run, updated.cliPath, {
+            prior: plan.prior.packages.server,
+            target: plan.target.packages.server,
+        });
+        events.push('updated:server');
+        startService(run, updated.cliPath, 'cockpit');
+        events.push('started:cockpit');
+        const healthEvidence = await assertStableHealth(run, plan, execution);
+        return {
+            schemaVersion: 1,
+            contract: RESULT_CONTRACT,
+            status: 'updated',
+            planId: plan.planId,
+            installed: updated.packages,
+            rollbackPerformed: false,
+            events,
+            healthEvidence,
+            next: 'Exit and reopen the AOPS TUI to run the newly installed binary.',
+        };
+    }
+    catch (updateError) {
+        events.push('rollback:started');
+        try {
+            stopService(run, plan.cliPath, 'cockpit', true);
+            stopService(run, plan.cliPath, 'server', true);
+            installGlobalUpdateClosure(run, plan, plan.restorePackages, plan.prior.topology);
+            events.push('installed:restore');
+            const restored = inspectGlobalInstall(run);
+            assert.deepEqual(restored.packages, plan.prior.packages, 'rollback package closure is not exact');
+            assert.deepEqual(restored.topology, plan.prior.topology, 'rollback package topology is not exact');
+            if (applicationUpdateId) {
+                rollbackServerApplication(run, restored.cliPath, applicationUpdateId, restored.serverPath, plan.prior.packages.server);
+                events.push('rolled-back:server-application');
+            }
+            else {
+                startService(run, restored.cliPath, 'server');
+                events.push('started:server-restore');
+            }
+            startService(run, restored.cliPath, 'cockpit');
+            await assertStableHealth(run, plan, execution);
+            events.push('rollback:healthy');
+        }
+        catch (rollbackError) {
+            throw new AggregateError([updateError, rollbackError], `global update and automatic rollback both failed; recovery artifacts remain at ${plan.operationRoot}`);
+        }
+        throw new Error('global update failed; the prior exact packages were restored and are healthy', { cause: updateError });
+    }
+}
+function output(value, json) {
+    process.stdout.write(`${JSON.stringify(value, null, json ? 0 : 2)}\n`);
+}
+export function makeGlobalUpdateCommand() {
+    const command = new Command('update').description('Check, prepare, and apply a guarded global AOPS npm update');
+    command
+        .command('check')
+        .description('Compare the installed global AOPS closure with the public npm latest tag')
+        .option('--json', 'Output JSON')
+        .action((options) => output(inspectGlobalUpdate(), options.json === true));
+    command
+        .command('prepare')
+        .description('Download and verify exact candidate and rollback tarballs without changing the installation')
+        .option('--config-root <path>', 'AOPS config root for the immutable update plan')
+        .option('--json', 'Output JSON')
+        .action((options) => output(prepareGlobalUpdate(options), options.json === true));
+    command
+        .command('apply')
+        .description('Apply one exact prepared plan with automatic rollback and health verification')
+        .requiredOption('--plan <path>', 'Exact update-plan.json path returned by prepare')
+        .requiredOption('--confirm <plan-id>', 'Exact sha256 plan id returned by prepare')
+        .option('--json', 'Output JSON')
+        .action(async (options) => output(await applyGlobalUpdate(options), options.json === true));
+    return command;
+}

package/dist/lib/agent-assets/native-fs.js

@@ -543,9 +543,9 @@ function defaultNativeRoot() {
     return moduleDirectory.endsWith(`${path.sep}dist`) ? bundled : compiledOrSource;
 }
 function injectedNativeManifestSha256() {
-    return typeof "4667a6c7f4b2f6261035103dbfed6e6117a0aba6b5a7d9cd85750a028b6052d6" === 'undefined'
+    return typeof "9644b89d6936c82a514f32f74d2c65324d45079255cebc642a4af2e36d482964" === 'undefined'
         ? undefined
-        : "4667a6c7f4b2f6261035103dbfed6e6117a0aba6b5a7d9cd85750a028b6052d6";
+        : "9644b89d6936c82a514f32f74d2c65324d45079255cebc642a4af2e36d482964";
 }
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');

package/dist/main.js

@@ -37,6 +37,7 @@ import { makeCommunityCockpitCommand } from './commands/community-cockpit.js';
 import { makeCommunityDoctorCommand } from './commands/community-doctor.js';
 import { makeTargetCommand } from './commands/target.js';
 import { makeVersionCommand } from './commands/version.js';
+import { makeGlobalUpdateCommand } from './commands/global-update.js';
 import { launchBundledTui, shouldLaunchBundledTui } from './lib/tui-launcher.js';
 import { CommunityDiagnosticError, formatCommunityDiagnostic, } from './lib/community-diagnostic.js';
 import { resolveCliApiBaseUrl } from './utils/api.js';
@@ -152,6 +153,7 @@ export function buildCommunityProgram() {
     program.addCommand(makeCommunityDoctorCommand());
     program.addCommand(makeTargetCommand());
     program.addCommand(makeVersionCommand());
+    program.addCommand(makeGlobalUpdateCommand());
     program.addHelpText('after', `
 AOPS Community is a single-user, self-hosted/local-trusted distribution.
 Canonical writes go to the local AOPS server; .aops/** remains a read-only cache.

package/native/manifest.json

@@ -42,7 +42,7 @@
       "capabilityClass": "windows-ntfs-crash-recoverable-v1",
       "qualification": {
         "relativePath": "qualifications/win32-x64.json",
-        "sha256": "3c4edb8aa2e3c74627ca16fe9b42a746f11555d5b137abf560eaceb5e939865d"
+        "sha256": "f589981718dff79e64aa1171acf66abcb86a662b94015592b22217911752ed58"
       }
     }
   ]

package/native/qualifications/win32-x64.json

@@ -7,7 +7,7 @@
   "filesystem": "NTFS",
   "primitiveProfile": "windows-createfile-flush-movefileex-v1",
   "capabilityClass": "windows-ntfs-crash-recoverable-v1",
-  "evidenceSha256": "69bdba89959089af51117f1d2e5398078c1e4ae1bd850efb1ecb557a58b2fb43",
+  "evidenceSha256": "0c390c3a76decbc63fcae8e7d84b56322bf25d2fae728406d8a3dda91f09585e",
   "crashInjectionPoints": [
     "authority-history",
     "authority-current",