@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/control/inspect.js

@@ -0,0 +1,71 @@
+import os from 'node:os';
+import { createServiceManager } from '../service/installer.js';
+import { serviceContext } from '../daemonctl.js';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BindingStore } from './bindingStore.js';
+import { inspectRuntime } from './runtimeClient.js';
+import { localInspectionSchema, operationRecordSchema } from './protocol.js';
+import { readControlFile } from './runtimeHost.js';
+import { updateServiceContext } from '../config.js';
+import { CLIENT_VERSION } from '../version.js';
+import { readPidManifest, manifestProcessLive } from '../keepers/kit/lock.js';
+export async function inspectKeepers(directory) {
+    try {
+        let running = false;
+        for (const kind of ['acp', 'terminal']) {
+            const root = path.join(directory, 'keepers', kind, 'run');
+            let entries;
+            try {
+                entries = await fs.readdir(root);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    continue;
+                throw e;
+            }
+            for (const entry of entries) {
+                const manifest = await readPidManifest(path.join(root, entry, 'keeper.pid.json'));
+                if (manifest && await manifestProcessLive(manifest))
+                    running = true;
+            }
+        }
+        return running ? 'running' : 'stopped';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export async function inspectWorkstation(directory, deps = {}) {
+    const identity = await new BindingStore(directory).inspect();
+    let pending = null;
+    try {
+        const operation = operationRecordSchema.parse(JSON.parse(await readControlFile(path.join(directory, 'operation.json'))));
+        if (operation.outcome !== 'succeeded')
+            pending = operation;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const cliPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../cli.js');
+    const context = updateServiceContext(directory);
+    let runtime = await inspectRuntime(directory);
+    const standardHome = os.userInfo().homedir;
+    const standardDirectory = path.join(standardHome, '.axom/workstation');
+    const probeLegacy = deps.legacyServiceRunning ?? (process.platform === 'darwin' && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? async () => (await createServiceManager(serviceContext()).status()).running : undefined);
+    if (runtime.state === 'stopped' && probeLegacy) {
+        try {
+            if (await probeLegacy())
+                runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+        catch {
+            runtime = { ...runtime, state: 'unknown', connection: 'unknown' };
+        }
+    }
+    const service = (process.platform === 'darwin' || process.platform === 'linux') && path.resolve(directory) === standardDirectory && os.homedir() === standardHome
+        ? await createServiceManager(serviceContext()).enablement() : undefined;
+    return localInspectionSchema.parse({ schemaVersion: 1, ...identity, installation: { source: context.managed ? 'managed' : 'existing', version: CLIENT_VERSION, nodeVersion: process.versions.node, nodePath: context.nodePath, cliPath, npmPath: context.npmPath, npmPrefix: context.npmPrefix }, runtime, ...(service ? { service } : {}), keepers: await inspectKeepers(directory), pending });
+}

package/dist/workstation/control/locks.js

@@ -0,0 +1,110 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import lockfile from 'proper-lockfile';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { pidAlive, processCommand } from '../keepers/kit/lock.js';
+import { LocalControlError } from './protocol.js';
+const ownership = new AsyncLocalStorage();
+export function assertLockOwnership() {
+    let lease = ownership.getStore();
+    while (lease) {
+        if (!lease.valid || !lease.active)
+            throw new LocalControlError('BUSY', 'Workstation lock ownership was lost or released');
+        lease = lease.parent;
+    }
+}
+function operationLease(directory) {
+    const expected = path.join(path.resolve(directory), 'control/operation');
+    let lease = ownership.getStore();
+    let held;
+    while (lease) {
+        if (!lease.valid || !lease.active)
+            throw new LocalControlError('BUSY', 'Workstation operation lock ownership was lost or released');
+        if (lease.stem === expected)
+            held = lease;
+        lease = lease.parent;
+    }
+    if (!held)
+        throw new LocalControlError('BUSY', 'The workstation operation lock is required');
+    return held;
+}
+export function assertWorkstationOperationLock(directory) { return operationLease(directory); }
+export function assertOutsideOperationLease() {
+    let lease = ownership.getStore();
+    while (lease) {
+        if (path.basename(lease.stem) === 'operation')
+            throw new LocalControlError('BUSY', 'Owner control requires an outside-operation context');
+        lease = lease.parent;
+    }
+}
+export function registerOperationLeaseFinalizer(directory, finalizer) {
+    operationLease(directory).finalizers.add(finalizer);
+}
+function finalize(lease) {
+    lease.active = false;
+    const callbacks = [...lease.finalizers];
+    lease.finalizers.clear();
+    for (const callback of callbacks) {
+        try {
+            callback();
+        }
+        catch (error) {
+            lease.finalizerErrors.push(error);
+        }
+    }
+}
+export async function withPrivateLock(stem, work) {
+    await privateDirectory(path.dirname(stem));
+    const ownerFile = stem + '.owner.json';
+    // proper-lockfile's time lease alone is insufficient: a suspended live app still owns its operation.
+    let lockPresent = false;
+    try {
+        const stat = await fs.lstat(stem + '.lock');
+        lockPresent = true;
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw Error('Unsafe lock');
+        if (Date.now() - stat.mtimeMs > 30_000) {
+            const owner = JSON.parse(await fs.readFile(ownerFile, 'utf8'));
+            if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || typeof owner.command !== 'string')
+                throw Error('Unknown owner');
+            if (pidAlive(owner.pid))
+                throw Error('Live or unverifiable owner');
+        }
+    }
+    catch (error) {
+        if (lockPresent || error.code !== 'ENOENT')
+            throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    const lease = { valid: true, active: true, stem: path.resolve(stem), parent: ownership.getStore(), finalizers: new Set(), finalizerErrors: [] };
+    const nonce = randomUUID();
+    let release;
+    try {
+        release = await lockfile.lock(stem, { realpath: false, stale: 30_000, update: 2_000, retries: 0, onCompromised: () => { lease.valid = false; finalize(lease); } });
+    }
+    catch {
+        throw new LocalControlError('BUSY', 'Another workstation operation is active');
+    }
+    try {
+        await fs.writeFile(ownerFile, JSON.stringify({ schemaVersion: 1, pid: process.pid, command: await processCommand(process.pid), nonce }), { mode: 0o600 });
+        return await ownership.run(lease, async () => { const result = await work(); assertLockOwnership(); return result; });
+    }
+    finally {
+        finalize(lease);
+        if (lease.valid) {
+            try {
+                if (JSON.parse(await fs.readFile(ownerFile, 'utf8')).nonce === nonce)
+                    await fs.rm(ownerFile);
+            }
+            catch { /* release still required */ }
+            await release();
+        }
+        if (lease.finalizerErrors.length)
+            throw new AggregateError(lease.finalizerErrors, 'Workstation lease finalizers failed');
+    }
+}
+export function withWorkstationLock(directory, name, work) {
+    return withPrivateLock(name === 'operation' ? path.join(directory, 'control/operation') : path.join(os.homedir(), '.axom/locks/cli-install'), work);
+}

package/dist/workstation/control/protocol.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export const bindingSchema = z.object({ server: z.string().min(1), workstationId: z.string().min(1), ownerUserId: z.string().min(1).optional() });
+export const bindingGuardSchema = z.object({ revision: z.string().min(1), runtimeGeneration: z.string().nullable() });
+const activitySchema = z.object({ commands: z.number().int().nonnegative(), terminals: z.number().int().nonnegative(), agents: z.number().int().nonnegative(), transfers: z.number().int().nonnegative() });
+export const runtimeSnapshotSchema = z.object({
+    state: z.enum(['stopped', 'running', 'unknown']), binding: bindingSchema.nullable(), generation: z.string().nullable(),
+    mode: z.enum(['launchd', 'foreground', 'unknown']), connection: z.enum(['offline', 'connecting', 'online', 'reconnecting', 'rejected', 'unknown']), activity: activitySchema.nullable(),
+});
+export const cliInstallationSchema = z.object({
+    source: z.enum(['managed', 'existing']), version: z.string(), nodeVersion: z.string(),
+    nodePath: z.string(), cliPath: z.string(), npmPath: z.string(), npmPrefix: z.string(),
+});
+export const operationRecordSchema = z.object({
+    id: z.string().min(1), kind: z.enum(['register', 'switch', 'start', 'stop', 'remove', 'update']), phase: z.string().min(1).max(80),
+    target: z.object({ server: z.string().min(1), ownerUserId: z.string().min(1).nullable() }).strict(),
+    workstationId: z.string().min(1).optional(), outcome: z.enum(['pending', 'succeeded', 'failed', 'unknown']),
+}).strict();
+export const serviceSnapshotSchema = z.object({ installed: z.boolean(), enabled: z.boolean().nullable(), loaded: z.boolean(), running: z.boolean(), reason: z.string().optional() });
+export const localInspectionSchema = z.object({
+    schemaVersion: z.literal(1), installation: cliInstallationSchema, binding: bindingSchema.nullable(), revision: z.string().min(1),
+    identityState: z.enum(['absent', 'ready', 'incomplete', 'corrupt']), runtime: runtimeSnapshotSchema,
+    service: serviceSnapshotSchema.optional(),
+    keepers: z.enum(['stopped', 'running', 'unknown']), pending: operationRecordSchema.nullable(),
+});
+export const localErrorCodeSchema = z.enum(['UNSUPPORTED_INSTALLATION', 'UNSUPPORTED_PROTOCOL', 'BINDING_CONFLICT', 'INSTANCE_OCCUPIED', 'AUTHORIZATION_REQUIRED', 'OWNER_MISMATCH', 'NETWORK_FAILED', 'CORRUPT_IDENTITY', 'SERVICE_FAILED', 'BUSY', 'OUTCOME_UNKNOWN']);
+export const cliResultSchema = z.object({
+    status: z.enum(['succeeded', 'busy', 'pending', 'failed', 'conflict']), inspection: localInspectionSchema.nullable(),
+    error: z.object({ code: localErrorCodeSchema, message: z.string().max(1024) }).optional(),
+}).refine(value => value.status !== 'succeeded' || value.inspection !== null, 'Successful operations require inspection');
+export class LocalControlError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalControlError';
+    }
+}
+export function stoppedRuntime() {
+    return { state: 'stopped', binding: null, generation: null, mode: 'unknown', connection: 'offline', activity: null };
+}

package/dist/workstation/control/restartGuard.js

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { promisify } from 'node:util';
+import { LocalControlError } from './protocol.js';
+import { readControlFile, runtimeOwnerLive, runtimePaths } from './runtimeHost.js';
+const run = promisify(execFile);
+async function parentPid(pid) {
+    let value;
+    if (process.platform === 'linux') {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8');
+        value = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/)[1];
+    }
+    else
+        value = (await run('ps', ['-o', 'ppid=', '-p', String(pid)], { timeout: 1000 })).stdout.trim();
+    const parent = Number(value);
+    if (!value || !Number.isSafeInteger(parent) || parent < 0)
+        throw new Error('Unknown process parent');
+    return parent;
+}
+export async function assertRuntimeRestartSafe(directory, generation, overrides = {}) {
+    const deps = { owner: async () => JSON.parse(await readControlFile(runtimePaths(directory).ownerFile)),
+        live: runtimeOwnerLive, parent: parentPid, pid: process.pid, ...overrides };
+    try {
+        const owner = await deps.owner();
+        if (owner.generation !== generation)
+            throw new LocalControlError('BINDING_CONFLICT', 'Workstation changed before restart');
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1 || !await deps.live(owner))
+            throw new Error('Unknown runtime process');
+        const seen = new Set();
+        const deadline = Date.now() + 3000;
+        let current = deps.pid;
+        while (current > 1 && !seen.has(current) && seen.size < 128 && Date.now() < deadline) {
+            if (current === owner.pid)
+                throw new LocalControlError('BUSY', 'This command is running inside the workstation daemon. Restarting it would terminate the current agent or command. Finish the session or move it to an independent keeper before restarting.');
+            seen.add(current);
+            current = await deps.parent(current);
+        }
+        if (current > 1)
+            throw new Error('Unknown process ancestry');
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Cannot verify that workstation restart will preserve the calling session');
+    }
+}

package/dist/workstation/control/rootFormat.js

@@ -0,0 +1,16 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { LocalControlError } from './protocol.js';
+export async function assertLegacyRoot(directory) {
+    for (const name of ['device.json', 'legacy-migration.json']) {
+        try {
+            await fs.lstat(path.join(directory, name));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        throw new LocalControlError('CORRUPT_IDENTITY', 'This workstation uses registrations; legacy identity writes and startup are unsupported');
+    }
+}

package/dist/workstation/control/runtimeClient.js

@@ -0,0 +1,152 @@
+import net from 'node:net';
+import { runtimePaths, readControlFile, runtimeOwnerLive } from './runtimeHost.js';
+import { runtimeSnapshotSchema, stoppedRuntime, LocalControlError, localErrorCodeSchema } from './protocol.js';
+import { pidAlive } from '../keepers/kit/lock.js';
+import { parseDeviceInspection, deviceResultSchema, deviceRuntimeUpdateRequestSchema, removeRegistrationRequestSchema } from './deviceProtocol.js';
+export async function removeDeviceRuntimeRegistration(directory, value) {
+    const request = removeRegistrationRequestSchema.parse(value);
+    let response;
+    try {
+        response = await runtimeRequest(directory, 'remove-registration', request.guard.runtimeGeneration, { request }, 15_000);
+    }
+    catch (error) {
+        if (error instanceof LocalControlError)
+            throw error;
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original running owner could not confirm removal');
+    }
+    const result = deviceResultSchema.parse(response);
+    if (result.operationId !== request.operationId || result.registrationId !== request.guard.registrationId)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original removal reply does not match');
+    return result;
+}
+export async function inspectDeviceRuntime(directory) {
+    return parseDeviceInspection(await runtimeRequest(directory, 'inspect'));
+}
+export async function prepareDeviceRuntimeStop(directory, generation, stopMode, operationId) {
+    const receipt = await runtimeRequest(directory, 'prepare-stop', generation, { stopMode, operationId }, 15_000);
+    if (receipt.prepared !== true || receipt.generation !== generation || receipt.stopMode !== stopMode)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Device shutdown preparation was not confirmed');
+}
+export async function stopDeviceRuntime(directory, generation, stopMode) {
+    await runtimeRequest(directory, 'stop', generation, { stopMode });
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        try {
+            const current = await inspectDeviceRuntime(directory);
+            if (current.runtime.generation !== generation)
+                throw new LocalControlError('BINDING_CONFLICT', 'A new device daemon started');
+        }
+        catch (error) {
+            if (error instanceof LocalControlError && error.code === 'BINDING_CONFLICT')
+                throw error;
+            if ((await inspectRuntime(directory)).state === 'stopped')
+                return;
+        }
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    throw new LocalControlError('OUTCOME_UNKNOWN', 'Device shutdown has not been confirmed');
+}
+export async function runtimeRequest(directory, action, expectedGeneration, extra = {}, timeoutMs = 3000) {
+    const paths = runtimePaths(directory);
+    const owner = JSON.parse(await readControlFile(paths.ownerFile));
+    if (typeof owner.generation !== 'string' || !pidAlive(owner.pid))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Runtime owner cannot be verified');
+    if (expectedGeneration && owner.generation !== expectedGeneration)
+        throw new LocalControlError('BINDING_CONFLICT', 'Runtime changed');
+    const token = await readControlFile(paths.tokenFile);
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(paths.socket);
+        let data = '';
+        let done = false;
+        const fail = (error) => { if (!done) {
+            done = true;
+            socket.destroy();
+            reject(error);
+        } };
+        socket.setTimeout(timeoutMs, () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Runtime did not respond')));
+        socket.on('error', () => fail(new LocalControlError('OUTCOME_UNKNOWN', 'Cannot contact runtime')));
+        socket.on('end', () => { if (!done)
+            fail(new LocalControlError('OUTCOME_UNKNOWN', 'Incomplete runtime response')); });
+        socket.on('connect', () => socket.write(JSON.stringify({ ...extra, action, generation: owner.generation, token }) + '\n'));
+        socket.on('data', chunk => {
+            data += chunk.toString();
+            if (Buffer.byteLength(data) > 65_536) {
+                fail(Error('Oversized response'));
+                return;
+            }
+            if (!data.includes('\n') || done)
+                return;
+            try {
+                const result = JSON.parse(data.split('\n')[0]);
+                if (!result.ok) {
+                    const code = localErrorCodeSchema.safeParse(result.code);
+                    throw new LocalControlError(code.success ? code.data : 'SERVICE_FAILED', 'Runtime rejected the request');
+                }
+                done = true;
+                socket.destroy();
+                resolve(result.value);
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+    });
+}
+export async function inspectRuntime(directory) {
+    try {
+        return runtimeSnapshotSchema.parse(await runtimeRequest(directory, 'inspect'));
+    }
+    catch (error) {
+        try {
+            const owner = JSON.parse(await readControlFile(runtimePaths(directory).ownerFile));
+            if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.command === 'string' && typeof owner.generation === 'string' && !await runtimeOwnerLive(owner))
+                return stoppedRuntime();
+        }
+        catch { /* Partial ownership evidence remains unknown. */ }
+        if (error.code === 'ENOENT') {
+            // No control files at all is stopped; partial state must remain uncertain.
+            const p = runtimePaths(directory);
+            const { promises: fs } = await import('node:fs');
+            try {
+                await fs.lstat(p.socket);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT') {
+                    try {
+                        await fs.lstat(p.ownerFile);
+                    }
+                    catch (e2) {
+                        if (e2.code === 'ENOENT')
+                            return stoppedRuntime();
+                    }
+                }
+            }
+        }
+        return { ...stoppedRuntime(), state: 'unknown', connection: 'unknown' };
+    }
+}
+export async function stopRuntime(directory, expectedGeneration) {
+    await runtimeRequest(directory, 'stop', expectedGeneration);
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+        const state = await inspectRuntime(directory);
+        if (state.state === 'stopped')
+            return;
+        if (state.generation && state.generation !== expectedGeneration)
+            throw new LocalControlError('BINDING_CONFLICT', 'A new daemon started');
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    throw new LocalControlError('OUTCOME_UNKNOWN', 'Workstation shutdown has not been confirmed');
+}
+export async function requestRuntimeUpdate(directory, release, operationId) {
+    return await runtimeRequest(directory, 'update', undefined, { release, operationId });
+}
+export async function requestDeviceRuntimeUpdate(directory, raw) {
+    const request = deviceRuntimeUpdateRequestSchema.parse(raw);
+    if (!request.guard.runtimeGeneration)
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'An original live device owner is required for update admission');
+    const status = await runtimeRequest(directory, 'update', request.guard.runtimeGeneration, { request }, 30_000);
+    if (!status || status.commandId !== request.operationId || !['REQUESTED', 'DRAINING', 'BUSY', 'DOWNLOADING', 'VERIFYING', 'INSTALLING', 'RESTARTING', 'SUCCEEDED', 'FAILED', 'ROLLED_BACK', 'UPDATE_IN_PROGRESS'].includes(status.phase))
+        throw new LocalControlError('OUTCOME_UNKNOWN', 'Original device update reply does not match its operation');
+    return status;
+}