@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/update/deviceRecoveryLifecycle.js

@@ -0,0 +1,46 @@
+import { deviceHealthExpectationSchema, deviceHealthMatches, deviceHealthWitnessSchema, queryDeviceHealth, runtimeFilesDigest } from './deviceHealth.js';
+import { deviceRollbackCompleted, readDeviceBootstrapRecovery } from './recoveryPlan.js';
+export function createDeviceRecoveryTick(options) {
+    let running = false, attempts = 0;
+    const binding = options.bootstrap?.transaction;
+    const expectation = binding?.targetEvidence ? deviceHealthExpectationSchema.parse({ transactionId: binding.transactionId, challenge: binding.challenge,
+        initiatingDaemonGeneration: binding.initiatingDaemonGeneration, origin: binding.origin, release: binding.release, resolvedSource: binding.resolvedSource,
+        runtimeDigest: runtimeFilesDigest(binding.targetEvidence.runtimeFiles),
+    }) : undefined;
+    return async () => {
+        if (running || options.signal.aborted || !options.initialized())
+            return;
+        running = true;
+        try {
+            const original = options.lease();
+            if (original && options.bootstrap?.transaction.installedRollback) {
+                if (await deviceRollbackCompleted(options.root, options.startup, options.bootstrap.transaction.transactionId)) {
+                    await original.release(async () => {
+                        if (!await deviceRollbackCompleted(options.root, options.startup, options.bootstrap.transaction.transactionId))
+                            throw Error('Original rollback completion changed during admission restoration');
+                    });
+                    options.released(original);
+                }
+                return;
+            }
+            if (original) {
+                if (!binding || !expectation || binding.origin.kind !== 'local' || options.bootstrap?.plan || binding.lifecycle === 'provision-and-arm' || binding.initiatingDaemonGeneration === options.generation || original.transactionId !== binding.transactionId || attempts >= 5)
+                    return;
+                attempts += 1;
+                const current = await readDeviceBootstrapRecovery(options.root, options.startup);
+                if (!current || current.plan || current.transaction.installedRollback || current.transaction.transactionId !== binding.transactionId || current.transaction.challenge !== binding.challenge || JSON.stringify(current.transaction.origin) !== JSON.stringify(binding.origin) || JSON.stringify(current.transaction.release) !== JSON.stringify(binding.release) || current.transaction.resolvedSource !== binding.resolvedSource || current.transaction.initiatingDaemonGeneration !== binding.initiatingDaemonGeneration)
+                    throw Error('Original local successor recovery binding changed');
+                if (options.signal.aborted || !options.initialized() || options.lease() !== original)
+                    return;
+                const witness = deviceHealthWitnessSchema.parse(await queryDeviceHealth(options.root, expectation));
+                if (!deviceHealthMatches(expectation, witness) || witness.daemonGeneration !== options.generation)
+                    throw Error('Private control did not confirm the exact original successor');
+                return;
+            }
+            await options.reconcile();
+        }
+        finally {
+            running = false;
+        }
+    };
+}

package/dist/workstation/update/deviceRollback.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { deviceHealthExpectationSchema, deviceInstalledRollbackSchema, deviceRollbackReceiptSchema, runtimeFilesDigest } from './deviceHealthProtocol.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
+import { readPrivateUpdateBytes, updateTransactionKey } from './recoveryPlan.js';
+import { runtimeRequest } from '../control/runtimeClient.js';
+import { LocalControlError } from '../control/protocol.js';
+import { writeDurablePrivateUpdate } from './privateDurability.js';
+export { deviceRollbackReceiptSchema } from './deviceHealthProtocol.js';
+export function rollbackHandoffPath(root, transactionId) { return path.join(root, 'update', `rollback-handoff-${updateTransactionKey(transactionId)}.json`); }
+export async function writePrivateDeviceEvidence(file, value) {
+    await writeDurablePrivateUpdate(file, JSON.stringify(value) + '\n');
+}
+function receiptMatches(expected, raw) {
+    const receipt = deviceRollbackReceiptSchema.parse(raw);
+    const { schemaVersion: _schemaVersion, prepared: _prepared, daemonGeneration: _generation, ...binding } = receipt;
+    if (receipt.daemonGeneration === expected.initiatingDaemonGeneration || JSON.stringify(deviceHealthExpectationSchema.parse(binding)) !== JSON.stringify(expected))
+        throw Error('Original target cleanup receipt changed its private recovery binding');
+    return receipt;
+}
+export async function assertDeviceRollbackReceipt(root, expected, raw) {
+    const receipt = receiptMatches(expected, raw);
+    const durable = receiptMatches(expected, JSON.parse((await readPrivateUpdateBytes(rollbackHandoffPath(root, expected.transactionId), 65536)).toString('utf8')));
+    if (JSON.stringify(receipt) !== JSON.stringify(durable))
+        throw Error('Original target cleanup receipt was not durably confirmed');
+}
+export async function queryDeviceRollbackHandoff(root, expected) {
+    return runtimeRequest(root, 'prepare-update-rollback', undefined, { request: expected }, 20_000);
+}
+export async function prepareDeviceRollbackHandoff(options, raw) {
+    const expected = deviceHealthExpectationSchema.parse(raw);
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(options.root, 'update/device-transaction.json'), 33_554_432)).toString('utf8')));
+    const actual = deviceHealthExpectationSchema.parse({ transactionId: transaction.transactionId, challenge: transaction.challenge, initiatingDaemonGeneration: transaction.initiatingDaemonGeneration, origin: transaction.origin, release: transaction.release, resolvedSource: transaction.resolvedSource, runtimeDigest: transaction.targetEvidence ? runtimeFilesDigest(transaction.targetEvidence.runtimeFiles) : '' });
+    if (JSON.stringify(expected) !== JSON.stringify(actual) || options.generation === expected.initiatingDaemonGeneration || options.startup.version !== expected.release.version || options.startup.runtimeDigest !== expected.runtimeDigest || !['RESTARTING', 'SUCCEEDED', 'FAILED'].includes(transaction.phase))
+        throw new LocalControlError('BINDING_CONFLICT', 'Only the exact original target daemon can prepare this rollback');
+    try {
+        const receipt = receiptMatches(expected, JSON.parse((await readPrivateUpdateBytes(rollbackHandoffPath(options.root, expected.transactionId), 65536)).toString('utf8')));
+        if (receipt.daemonGeneration !== options.generation)
+            throw Error('A replacement daemon cannot reuse another original cleanup receipt');
+        await writePrivateDeviceEvidence(rollbackHandoffPath(options.root, expected.transactionId), receipt);
+        return receipt;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lease = options.lease();
+    if (lease.transactionId !== transaction.transactionId)
+        throw new LocalControlError('BINDING_CONFLICT', 'Original maintenance transaction changed');
+    await lease.ready;
+    if ((await lease.observe()).status !== 'candidate')
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original target work or unknown obligations prevent automatic rollback');
+    await lease.handoff();
+    const receipt = deviceRollbackReceiptSchema.parse({ ...actual, schemaVersion: 1, prepared: true, daemonGeneration: options.generation });
+    await writePrivateDeviceEvidence(rollbackHandoffPath(options.root, expected.transactionId), receipt);
+    return receipt;
+}
+export async function persistDeviceRollbackPhase(root, expected, phase) {
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const file = path.join(root, 'update/device-transaction.json');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(file, 33_554_432)).toString('utf8')));
+    if (transaction.transactionId !== expected.transactionId || transaction.challenge !== expected.challenge || transaction.release.sha512 !== expected.release.sha512 || transaction.resolvedSource !== expected.resolvedSource)
+        throw Error('Original private rollback transaction changed');
+    await writePrivateDeviceEvidence(file, deviceTransactionSchema.parse({ ...transaction, phase, recoveryRequired: phase === 'FAILED' }));
+}
+export async function persistDeviceInstalledRollback(recovery, rawHandoff) {
+    await assertDeviceRollbackReceipt(recovery.root, recovery.expectation, rawHandoff);
+    const archive = await readArchiveEvidence(recovery.rollback.archive);
+    if (archive.sha512 !== recovery.rollback.sha512 || archive.size !== recovery.rollback.size || archive.version !== recovery.rollback.version)
+        throw Error('Frozen rollback package changed before installed evidence persistence');
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const file = path.join(recovery.root, 'update/device-transaction.json');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(file, 33_554_432)).toString('utf8')));
+    if (transaction.transactionId !== recovery.expectation.transactionId || transaction.challenge !== recovery.expectation.challenge || transaction.resolvedSource !== recovery.expectation.resolvedSource)
+        throw Error('Original installed rollback transaction changed');
+    const installedRollback = deviceInstalledRollbackSchema.parse({ schemaVersion: 1, transactionId: transaction.transactionId, archive, handoff: rawHandoff });
+    await writePrivateDeviceEvidence(file, deviceTransactionSchema.parse({ ...transaction, phase: 'RESTARTING', recoveryRequired: true, installedRollback }));
+}

package/dist/workstation/update/globalInstall.js

@@ -0,0 +1,186 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * `npm install --global <archive>` reinstalls an already-present package by renaming the old
+ * install directory aside ("retire") and extracting the new one in its place. On at least one
+ * observed host (a container whose target directory sits on the image's read-only layers, backed
+ * by `fuse-overlayfs`) that retire-then-extract sequence is unreliable: `npm`'s own tar/arborist
+ * step intermittently reports `TAR_ENTRY_ERROR EEXIST` on the package's top-level `package.json`,
+ * immediately followed by `ENOENT` when npm reads the same path back — on the *same* path, even
+ * starting from an empty directory, and reproducibly across repeated attempts. A plain `tar`
+ * extraction of the identical archive onto the identical path, and a non-global `npm install` run
+ * inside an already-extracted directory, both succeed every time: the bug is specific to npm's
+ * own global-package retire/link machinery, not to the archive, the dependencies, or the
+ * filesystem's ability to write there at all.
+ *
+ * This is therefore a fallback, not the primary path: it only runs after a real `npm install
+ * --global` attempt has already failed, and it reimplements only what that attempt was observably
+ * unable to do reliably --- replace the target directory's contents and its `bin` entry --- using
+ * the two operations proven to work. It intentionally does not run on Windows, where npm's global
+ * `bin` entries are shim files (`.cmd`/`.ps1`), not symlinks, and this path has no evidence either
+ * way.
+ */
+export async function attemptGlobalInstallFallback(npmPath, npmPrefix, archive, env, spawn = nodeSpawn) {
+    if (process.platform === 'win32')
+        throw new Error('No tested fallback for a global npm install on Windows');
+    const manifest = await readArchivePackageJson(archive, spawn);
+    const name = manifest.name;
+    if (typeof name !== 'string' || name.length === 0)
+        throw new Error('Archive package.json has no usable "name"');
+    const bin = manifest.bin;
+    const target = path.join(npmPrefix, 'lib/node_modules', name);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    // Finish extraction and dependency resolution before changing the installed package. Keep the
+    // previous tree and command entries until every replacement succeeds, including bin linking.
+    const staging = await fs.mkdtemp(path.join(path.dirname(target), '.axom-install-'));
+    const candidate = path.join(staging, 'candidate');
+    const previous = path.join(staging, 'previous');
+    let retired = false;
+    let replaced = false;
+    let retainRecovery = false;
+    const commands = [];
+    try {
+        await fs.mkdir(candidate);
+        await run(spawn, 'tar', ['-xzf', archive, '-C', candidate, '--strip-components=1'], {});
+        const installEnv = { ...process.env, ...env };
+        delete installEnv.NPM_CONFIG_PREFIX;
+        delete installEnv.npm_config_prefix;
+        await run(spawn, npmPath, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: candidate, env: installEnv });
+        try {
+            await fs.rename(target, previous);
+            retired = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await fs.rename(candidate, target);
+        replaced = true;
+        await relinkBinaries(npmPrefix, target, name, bin, staging, commands);
+    }
+    catch (error) {
+        const restoreErrors = [];
+        for (const { link, backup } of commands.reverse()) {
+            try {
+                await fs.rm(link, { force: true });
+                if (backup)
+                    await fs.rename(backup, link);
+            }
+            catch (restoreError) {
+                restoreErrors.push(restoreError);
+            }
+        }
+        // A command restoration failure must not prevent restoring the package itself.
+        try {
+            if (replaced)
+                await fs.rm(target, { recursive: true, force: true });
+        }
+        catch (restoreError) {
+            restoreErrors.push(restoreError);
+        }
+        try {
+            if (retired)
+                await fs.rename(previous, target);
+        }
+        catch (restoreError) {
+            restoreErrors.push(restoreError);
+        }
+        if (restoreErrors.length) {
+            retainRecovery = true;
+            throw new AggregateError([error, ...restoreErrors], `Global install fallback failed and its previous installation could not be restored; recovery files retained at ${staging}`);
+        }
+        throw error;
+    }
+    finally {
+        if (!retainRecovery)
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function readArchivePackageJson(archive, spawn) {
+    const raw = await capture(spawn, 'tar', ['-xzf', archive, '-O', 'package/package.json'], {});
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Archive package.json is not valid JSON');
+    }
+}
+/** Reproduces npm's own `bin` linking: a relative symlink from `<prefix>/bin/<name>` to the script. */
+async function relinkBinaries(npmPrefix, target, packageName, bin, staging, commands) {
+    const entries = binEntries(packageName, bin);
+    if (entries.length === 0)
+        return;
+    const binDir = path.join(npmPrefix, 'bin');
+    await fs.mkdir(binDir, { recursive: true });
+    for (const [command, relativeScript] of entries) {
+        const script = path.join(target, relativeScript);
+        const link = path.join(binDir, command);
+        let backup;
+        try {
+            const existing = await fs.lstat(link);
+            if (existing.isDirectory())
+                throw new Error('Refusing to replace a directory with an npm command');
+            backup = path.join(staging, `bin-${commands.length}`);
+            await fs.rename(link, backup);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        commands.push({ link, backup });
+        await fs.symlink(path.relative(binDir, script), link);
+        await fs.chmod(script, 0o755).catch(() => undefined);
+    }
+}
+/** Exported for direct unit testing; same resolution npm itself applies to a package.json `bin` field. */
+export function binEntries(packageName, bin) {
+    if (typeof bin === 'string') {
+        const short = packageName.startsWith('@') ? packageName.split('/')[1] ?? packageName : packageName;
+        return [[short, bin]];
+    }
+    if (bin && typeof bin === 'object') {
+        return Object.entries(bin).filter((entry) => typeof entry[1] === 'string');
+    }
+    return [];
+}
+function run(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}
+function capture(spawn, command, args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(command, args, { ...options, shell: false, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`${command} failed: exit ${code ?? signal ?? 'unknown'}`));
+        });
+    });
+}