@msvesper/vesper-link 0.1.4

package/dist/installation.js

@@ -0,0 +1,524 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readJsonFile, writeJsonAtomic } from './atomic-json.js';
+import { stableLauncherSource } from './managed-runtime.js';
+import { acquireSyncLock } from './lock.js';
+import { NodeProcessRunner } from './process-runner.js';
+import { applyProviderIntegrations, detectInstalledProviders, providerLocations, providerTargetPaths, removeProviderIntegrations, } from './provider-integrations.js';
+import { applyScheduler, assertSchedulerOwned, prepareScheduler, restoreScheduler, schedulerInstalled, stableMinuteOffset, uninstallScheduler, } from './scheduler.js';
+async function snapshotFile(filePath) {
+    try {
+        return { filePath, existed: true, content: await fs.readFile(filePath) };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { filePath, existed: false };
+        }
+        throw error;
+    }
+}
+async function restoreFile(snapshot) {
+    if (!snapshot.existed) {
+        await fs.rm(snapshot.filePath, { force: true });
+        return;
+    }
+    await fs.mkdir(path.dirname(snapshot.filePath), { recursive: true });
+    const temporary = snapshot.filePath + '.' + process.pid + '.rollback';
+    try {
+        await fs.writeFile(temporary, snapshot.content);
+        await fs.rename(temporary, snapshot.filePath);
+    }
+    finally {
+        await fs.rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function ensureLauncher(paths) {
+    await fs.mkdir(path.dirname(paths.launcherPath), { recursive: true });
+    const desired = stableLauncherSource();
+    const current = await fs.readFile(paths.launcherPath, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT') {
+            return '';
+        }
+        throw error;
+    });
+    if (current !== desired) {
+        await fs.writeFile(paths.launcherPath, desired, 'utf8');
+        if (process.platform !== 'win32') {
+            await fs.chmod(paths.launcherPath, 0o755);
+        }
+    }
+}
+async function readJsonObject(filePath) {
+    const value = await readJsonFile(filePath);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Configuration file must contain a JSON object: ' + filePath);
+    }
+    return value;
+}
+function containsJson(value, expected) {
+    if (JSON.stringify(value) === JSON.stringify(expected)) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.some((entry) => containsJson(entry, expected));
+    }
+    if (value && typeof value === 'object') {
+        return Object.values(value).some((entry) => containsJson(entry, expected));
+    }
+    return false;
+}
+async function verifyProviderIntegrations(paths, state) {
+    const locations = providerLocations(paths);
+    const owned = state.integrations;
+    if (owned.claudeHook && !containsJson(await readJsonObject(locations.claudeSettingsPath), owned.claudeHook)) {
+        throw new Error('Claude hook is missing after install');
+    }
+    if (owned.copilotHook && !containsJson(await readJsonObject(locations.copilotSettingsPath), owned.copilotHook)) {
+        throw new Error('Copilot hook is missing after install');
+    }
+    if (state.sourceTrust === 'trusted') {
+        if (owned.claudeMcp && !containsJson(await readJsonObject(locations.claudeUserConfigPath), owned.claudeMcp)) {
+            throw new Error('Claude MCP is missing after install');
+        }
+        if (owned.copilotMcp && !containsJson(await readJsonObject(locations.copilotMcpPath), owned.copilotMcp)) {
+            throw new Error('Copilot MCP is missing after install');
+        }
+        for (const [filePath, marker] of [
+            [locations.claudeInstructionPath, owned.claudeInstruction],
+            [locations.copilotInstructionPath, owned.copilotInstruction],
+            [locations.codexConfigPath, owned.codexMcpBlock],
+            [locations.codexInstructionPath, owned.codexInstruction],
+        ]) {
+            if (marker && !(await fs.readFile(filePath, 'utf8')).includes(marker)) {
+                throw new Error('Managed provider block is missing after install: ' + filePath);
+            }
+        }
+    }
+}
+export async function verifyInstalledState(paths, expected, runner = new NodeProcessRunner()) {
+    const current = await readJsonFile(paths.currentPath);
+    if (!current || current.schemaVersion !== 1 || current.version !== expected.runtime.version
+        || current.runtimePath !== expected.runtime.runtimePath) {
+        throw new Error('Managed runtime pointer is not current');
+    }
+    await fs.access(path.join(current.runtimePath, 'package', 'dist', 'cli.js'));
+    if (!await schedulerInstalled(expected.scheduler, runner)) {
+        throw new Error('Scheduler is missing after install');
+    }
+    await verifyProviderIntegrations(paths, expected);
+}
+async function backupSnapshot(snapshot, backupDir) {
+    if (!snapshot.existed) {
+        return undefined;
+    }
+    await fs.mkdir(backupDir, { recursive: true });
+    const name = Buffer.from(snapshot.filePath).toString('base64url') + '.before-vesper-link';
+    const backupPath = path.join(backupDir, name);
+    try {
+        await fs.writeFile(backupPath, snapshot.content, { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            throw error;
+        }
+    }
+    return backupPath;
+}
+export async function readInstalledState(paths) {
+    const state = await readJsonFile(paths.installStatePath);
+    if (!state) {
+        return null;
+    }
+    if (state.schemaVersion !== 2 || !state.installationId || !state.runtime || !state.scheduler || !state.integrations
+        || !Array.isArray(state.createdProviderFiles)) {
+        throw new Error('Malformed installed state: ' + paths.installStatePath);
+    }
+    return { ...state, paused: state.paused === true };
+}
+async function prepareInstall(options) {
+    const previous = await readInstalledState(options.paths);
+    const providers = options.providers ?? await detectInstalledProviders(options.paths);
+    const targetPaths = providerTargetPaths(options.paths, providers);
+    const [currentPointer, installState, launcher, config, ...providerFiles] = await Promise.all([
+        snapshotFile(options.paths.currentPath), snapshotFile(options.paths.installStatePath),
+        snapshotFile(options.paths.launcherPath), snapshotFile(options.paths.configPath), ...targetPaths.map(snapshotFile),
+    ]);
+    // Validate every provider file before the first transaction mutation.
+    for (const snapshot of providerFiles) {
+        if (snapshot.existed && snapshot.filePath.endsWith('.json')) {
+            JSON.parse(snapshot.content.toString('utf8'));
+        }
+    }
+    const installationId = previous?.installationId ?? randomUUID();
+    const minuteOffset = previous?.minuteOffset ?? stableMinuteOffset(options.paths.homeDir);
+    const scheduler = await prepareScheduler({
+        platform: options.platform, runner: options.runner, minuteOffset, nodePath: options.nodePath,
+        launcherPath: options.paths.launcherPath, installationId,
+    });
+    const backups = { ...previous?.backups };
+    const backupDir = path.join(options.paths.stateDir, 'backups');
+    for (const snapshot of providerFiles) {
+        if (!backups[snapshot.filePath]) {
+            const backup = await backupSnapshot(snapshot, backupDir);
+            if (backup) {
+                backups[snapshot.filePath] = backup;
+            }
+        }
+    }
+    return {
+        previous, currentPointer, installState, launcher, config, providerFiles,
+        schedulerState: scheduler.state, schedulerSnapshot: scheduler.snapshot, providers, backups,
+        installationId,
+        createdProviderFiles: [...new Set([
+                ...(previous?.createdProviderFiles ?? []),
+                ...providerFiles.filter((snapshot) => !snapshot.existed).map((snapshot) => snapshot.filePath),
+            ])],
+    };
+}
+export async function installManagedRuntime(options) {
+    const runner = options.runner ?? new NodeProcessRunner();
+    const platform = options.platform ?? process.platform;
+    const nodePath = options.nodePath ?? process.execPath;
+    const now = options.now ?? new Date();
+    const prepared = await prepareInstall({
+        paths: options.paths, runtime: options.runtime, host: options.host,
+        sourceTrust: options.capabilities.sourceTrust, providers: options.providers,
+        nodePath, platform, runner, now,
+    });
+    const installationId = prepared.installationId;
+    const pointer = {
+        schemaVersion: 1, version: options.runtime.version, runtimePath: options.runtime.runtimePath,
+    };
+    let providersApplied = false;
+    let schedulerApplied = false;
+    try {
+        await ensureLauncher(options.paths);
+        await writeJsonAtomic(options.paths.currentPath, pointer);
+        await options.faults?.afterStep?.('current');
+        await writeJsonAtomic(options.paths.configPath, { schemaVersion: 1, host: options.host });
+        await options.faults?.afterStep?.('config');
+        providersApplied = true;
+        const integrations = await applyProviderIntegrations({
+            paths: options.paths, providers: prepared.providers, trusted: options.capabilities.sourceTrust === 'trusted',
+            nodePath, launcherPath: options.paths.launcherPath, previous: prepared.previous?.integrations,
+            afterMutation: options.faults?.afterProviderMutation,
+        });
+        await options.faults?.afterStep?.('providers');
+        schedulerApplied = true;
+        await applyScheduler(prepared.schedulerState, prepared.schedulerSnapshot, runner);
+        await options.faults?.afterStep?.('scheduler');
+        const installed = {
+            schemaVersion: 2, installedAt: now.toISOString(), host: options.host,
+            sourceTrust: options.capabilities.sourceTrust, installationId, runtime: pointer, nodePath,
+            launcherPath: options.paths.launcherPath, minuteOffset: prepared.schedulerState.minuteOffset,
+            scheduler: prepared.schedulerState, integrations, backups: prepared.backups,
+            createdProviderFiles: prepared.createdProviderFiles,
+        };
+        await writeJsonAtomic(options.paths.installStatePath, installed);
+        await options.faults?.afterStep?.('state');
+        await verifyInstalledState(options.paths, installed, runner);
+        await options.postInstallDoctor?.();
+        return installed;
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        if (schedulerApplied) {
+            try {
+                await restoreScheduler(prepared.schedulerState, prepared.schedulerSnapshot, runner);
+            }
+            catch (rollback) {
+                rollbackErrors.push(rollback);
+            }
+        }
+        if (providersApplied) {
+            for (const snapshot of prepared.providerFiles) {
+                try {
+                    await restoreFile(snapshot);
+                }
+                catch (rollback) {
+                    rollbackErrors.push(rollback);
+                }
+            }
+        }
+        for (const snapshot of [prepared.config, prepared.installState, prepared.currentPointer, prepared.launcher]) {
+            try {
+                await restoreFile(snapshot);
+            }
+            catch (rollback) {
+                rollbackErrors.push(rollback);
+            }
+        }
+        if (rollbackErrors.length > 0) {
+            throw new AggregateError([error, ...rollbackErrors], 'Installation failed and rollback was incomplete');
+        }
+        throw error;
+    }
+}
+export async function uninstallIntegrations(paths, runner = new NodeProcessRunner(), probeProcess = probeProcessState) {
+    const resolvedStateDir = path.resolve(paths.stateDir);
+    if (resolvedStateDir === path.parse(resolvedStateDir).root) {
+        throw new Error('Refusing to uninstall a filesystem root');
+    }
+    const stateDirectoryExisted = await fs.stat(resolvedStateDir).then((stat) => {
+        if (!stat.isDirectory()) {
+            throw new Error('Vesper Link state path is not a directory');
+        }
+        return true;
+    }).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    });
+    const releaseLock = await acquireSyncLock(paths.lockPath);
+    try {
+        const state = await readInstalledState(paths);
+        if (!state && !stateDirectoryExisted) {
+            return false;
+        }
+        const defaultStateDir = path.resolve(paths.homeDir, '.vesper-link');
+        if (!state && resolvedStateDir !== defaultStateDir) {
+            throw new Error('Refusing to remove a custom directory without Vesper Link installed state');
+        }
+        await assertTransportStopped(paths, probeProcess);
+        if (state && !state.paused) {
+            await removeActiveIntegrations(paths, state, runner, () => writeJsonAtomic(paths.installStatePath, { ...state, paused: true }));
+        }
+        await fs.rm(resolvedStateDir, { recursive: true, force: true });
+        return true;
+    }
+    finally {
+        await releaseLock();
+    }
+}
+async function removeEmptyCreatedProviderFiles(state) {
+    for (const filePath of state.createdProviderFiles) {
+        try {
+            const content = await fs.readFile(filePath, 'utf8');
+            const emptyJson = filePath.endsWith('.json') && JSON.stringify(JSON.parse(content)) === '{}';
+            if (!content.trim() || emptyJson) {
+                await fs.rm(filePath, { force: true });
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+}
+async function removeActiveIntegrations(paths, state, runner, finalize) {
+    await assertSchedulerOwned(state.scheduler, runner);
+    const providerFiles = await Promise.all(providerTargetPaths(paths, state.integrations.providers).map(snapshotFile));
+    const scheduler = await prepareScheduler({
+        platform: state.scheduler.kind === 'windows-task' ? 'win32' : 'linux', runner,
+        minuteOffset: state.minuteOffset, nodePath: state.nodePath,
+        launcherPath: state.launcherPath, installationId: state.installationId,
+    });
+    try {
+        await removeProviderIntegrations(paths, state.integrations);
+        await uninstallScheduler(state.scheduler, runner);
+        await removeEmptyCreatedProviderFiles(state);
+        await finalize?.();
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        for (const snapshot of providerFiles) {
+            try {
+                await restoreFile(snapshot);
+            }
+            catch (rollback) {
+                rollbackErrors.push(rollback);
+            }
+        }
+        try {
+            await restoreScheduler(scheduler.state, scheduler.snapshot, runner);
+        }
+        catch (rollback) {
+            rollbackErrors.push(rollback);
+        }
+        if (rollbackErrors.length > 0) {
+            throw new AggregateError([error, ...rollbackErrors], 'Integration removal failed and rollback was incomplete');
+        }
+        throw error;
+    }
+}
+export async function pauseIntegrations(paths, runner = new NodeProcessRunner()) {
+    const releaseLock = await acquireSyncLock(paths.lockPath);
+    try {
+        const state = await readInstalledState(paths);
+        if (!state || state.paused) {
+            return false;
+        }
+        await removeActiveIntegrations(paths, state, runner, () => writeJsonAtomic(paths.installStatePath, { ...state, paused: true }));
+        return true;
+    }
+    finally {
+        await releaseLock();
+    }
+}
+export async function resumeIntegrations(paths, runner = new NodeProcessRunner()) {
+    const releaseLock = await acquireSyncLock(paths.lockPath);
+    try {
+        const state = await readInstalledState(paths);
+        if (!state || !state.paused) {
+            return false;
+        }
+        const providerFiles = await Promise.all(providerTargetPaths(paths, state.integrations.providers).map(snapshotFile));
+        const installState = await snapshotFile(paths.installStatePath);
+        const scheduler = await prepareScheduler({
+            platform: state.scheduler.kind === 'windows-task' ? 'win32' : 'linux', runner,
+            minuteOffset: state.minuteOffset, nodePath: state.nodePath,
+            launcherPath: state.launcherPath, installationId: state.installationId,
+        });
+        let providersApplied = false;
+        let schedulerApplied = false;
+        try {
+            const current = await readJsonFile(paths.currentPath);
+            if (!current || current.schemaVersion !== 1 || current.version !== state.runtime.version
+                || current.runtimePath !== state.runtime.runtimePath) {
+                throw new Error('Cannot resume because the managed runtime pointer changed');
+            }
+            await fs.access(path.join(current.runtimePath, 'package', 'dist', 'cli.js'));
+            providersApplied = true;
+            const integrations = await applyProviderIntegrations({
+                paths, providers: state.integrations.providers, trusted: state.sourceTrust === 'trusted',
+                nodePath: state.nodePath, launcherPath: state.launcherPath, previous: state.integrations,
+            });
+            schedulerApplied = true;
+            await applyScheduler(scheduler.state, scheduler.snapshot, runner);
+            const resumed = { ...state, integrations, paused: false };
+            await writeJsonAtomic(paths.installStatePath, resumed);
+            await verifyInstalledState(paths, resumed, runner);
+            return true;
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            if (schedulerApplied) {
+                try {
+                    await restoreScheduler(scheduler.state, scheduler.snapshot, runner);
+                }
+                catch (rollback) {
+                    rollbackErrors.push(rollback);
+                }
+            }
+            if (providersApplied) {
+                for (const snapshot of providerFiles) {
+                    try {
+                        await restoreFile(snapshot);
+                    }
+                    catch (rollback) {
+                        rollbackErrors.push(rollback);
+                    }
+                }
+            }
+            try {
+                await restoreFile(installState);
+            }
+            catch (rollback) {
+                rollbackErrors.push(rollback);
+            }
+            if (rollbackErrors.length > 0) {
+                throw new AggregateError([error, ...rollbackErrors], 'Resume failed and rollback was incomplete');
+            }
+            throw error;
+        }
+    }
+    finally {
+        await releaseLock();
+    }
+}
+function probeProcessState(pid) {
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'absent' : 'unknown';
+    }
+}
+async function assertTransportStopped(paths, probeProcess = probeProcessState) {
+    let rendezvous;
+    try {
+        rendezvous = JSON.parse(await fs.readFile(paths.transportRendezvousPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    if (!rendezvous || typeof rendezvous !== 'object' || Array.isArray(rendezvous)) {
+        throw new Error('Cannot verify whether vesper-net transport is stopped');
+    }
+    const pid = rendezvous.pid;
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        throw new Error('Cannot verify whether vesper-net transport is stopped');
+    }
+    const state = probeProcess(pid);
+    if (state === 'alive') {
+        throw new Error('Cannot modify identity while vesper-net transport is running');
+    }
+    if (state === 'unknown') {
+        throw new Error('Cannot verify whether vesper-net transport is stopped');
+    }
+}
+export async function resetRemoteIdentity(paths, confirmed) {
+    if (!confirmed) {
+        throw new Error('reset-identity requires --confirm; this changes the remote Node ID and transcript identity');
+    }
+    await assertTransportStopped(paths);
+    await fs.rm(paths.tsnetDir, { recursive: true, force: true });
+    await fs.rm(paths.transportDir, { recursive: true, force: true });
+}
+export async function getInstallationStatus(paths, runner = new NodeProcessRunner()) {
+    const state = await readInstalledState(paths);
+    if (!state) {
+        return {
+            installed: false, paused: false, providers: [], claudeHookInstalled: false, copilotHookInstalled: false,
+            schedulerInstalled: false, trustedIntegrationsInstalled: false,
+        };
+    }
+    const current = await readJsonFile(paths.currentPath);
+    const runtimeCurrent = current?.schemaVersion === 1 && current.runtimePath === state.runtime.runtimePath
+        && current.version === state.runtime.version;
+    const locations = providerLocations(paths);
+    if (state.paused) {
+        return {
+            installed: runtimeCurrent, paused: true, providers: state.integrations.providers,
+            claudeHookInstalled: false, copilotHookInstalled: false, sourceTrust: state.sourceTrust,
+            schedulerInstalled: false, schedulerKind: state.scheduler.kind, minuteOffset: state.minuteOffset,
+            runtimeVersion: state.runtime.version, trustedIntegrationsInstalled: false,
+        };
+    }
+    const claudeHookInstalled = !state.integrations.providers.includes('claude-code')
+        || (state.integrations.claudeHook !== undefined
+            && containsJson(await readJsonObject(locations.claudeSettingsPath), state.integrations.claudeHook));
+    const copilotHookInstalled = !state.integrations.providers.includes('github-copilot')
+        || (state.integrations.copilotHook !== undefined
+            && containsJson(await readJsonObject(locations.copilotSettingsPath), state.integrations.copilotHook));
+    let trustedIntegrationsInstalled = false;
+    if (state.sourceTrust === 'trusted') {
+        try {
+            await verifyProviderIntegrations(paths, state);
+            trustedIntegrationsInstalled = true;
+        }
+        catch {
+            trustedIntegrationsInstalled = false;
+        }
+    }
+    return {
+        installed: runtimeCurrent,
+        paused: false,
+        providers: state.integrations.providers,
+        claudeHookInstalled,
+        copilotHookInstalled,
+        sourceTrust: state.sourceTrust,
+        schedulerInstalled: await schedulerInstalled(state.scheduler, runner),
+        schedulerKind: state.scheduler.kind,
+        minuteOffset: state.minuteOffset,
+        runtimeVersion: state.runtime.version,
+        trustedIntegrationsInstalled,
+    };
+}

package/dist/installer.d.ts

@@ -0,0 +1,59 @@
+import { getCapabilities, getHealth } from './http-client.js';
+import { installManagedRuntime, type InstalledState } from './installation.js';
+import { prepareManagedRuntime, validateInstallPrerequisites, type ManagedRuntime } from './managed-runtime.js';
+import type { LinkPaths } from './paths.js';
+import { type ProcessRunner } from './process-runner.js';
+import { type RemoteTransport } from './transport.js';
+export type ExpectedRole = 'trusted' | 'uploader';
+export interface InstallProgress {
+    schemaVersion: 1;
+    state: 'enrolling' | 'waiting_for_tag';
+    host: string;
+    expectedRole?: ExpectedRole;
+    tailnetName?: string;
+    nodeName?: string;
+    ipv4?: string;
+    updatedAt: string;
+}
+export interface InstallResult {
+    state: InstalledState;
+    firstSyncStarted: boolean;
+}
+export declare class WaitingForTagError extends Error {
+    readonly progress: InstallProgress;
+    readonly code = "waiting_for_tag";
+    constructor(progress: InstallProgress);
+}
+export declare class AutomaticEnrollmentConflictError extends Error {
+    readonly code = "automatic_enrollment_existing_identity";
+    constructor(progress: InstallProgress);
+}
+export interface InstallerDependencies {
+    validatePrerequisites: typeof validateInstallPrerequisites;
+    prepareRuntime(options: Parameters<typeof prepareManagedRuntime>[0]): Promise<ManagedRuntime>;
+    validateRuntime(runtime: ManagedRuntime): Promise<void>;
+    acquireTransport(options: {
+        paths: LinkPaths;
+        hostUrl: string;
+        onNeedsLogin?: (url: string) => void;
+        requiredCompanion?: ManagedRuntime['companion'];
+        bootstrapAuthKey?: string;
+    }): Promise<RemoteTransport>;
+    getHealth: typeof getHealth;
+    getCapabilities: typeof getCapabilities;
+    installManaged: typeof installManagedRuntime;
+    triggerFirstSync(paths: LinkPaths): Promise<void>;
+}
+export declare function installVesperLink(options: {
+    paths: LinkPaths;
+    host: string;
+    expectedRole?: ExpectedRole;
+    bootstrapAuthKey?: string;
+    runner?: ProcessRunner;
+    onNeedsLogin?: (url: string) => void;
+    onWaitingForTag?: (progress: InstallProgress) => void;
+    pollAuthorization?: boolean;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    dependencies?: InstallerDependencies;
+}): Promise<InstallResult>;