@msvesper/vesper-link 0.1.4

package/LICENSE.md

@@ -0,0 +1,44 @@
+# Vesper Link End User License Agreement (EULA)
+
+**Copyright (c) 2026 VSWork. All Rights Reserved.**
+
+## 1. Grant of License
+
+This End User License Agreement ("Agreement") grants you ("User") a limited, non-exclusive, non-transferable, revocable license to install and use Vesper Link ("Software") for personal or internal business purposes, subject to the terms below.
+
+## 2. Restrictions
+
+You may NOT:
+- Copy, modify, adapt, translate, or create derivative works of the Software
+- Reverse engineer, decompile, disassemble, or attempt to derive the source code
+- Redistribute, sublicense, rent, lease, or lend the Software to any third party
+- Remove or alter any proprietary notices, labels, or marks on the Software
+- Use the Software for any unlawful purpose or in violation of any applicable laws
+
+## 3. Intellectual Property
+
+The Software, including all copies, modifications, and derivative works, is the exclusive property of VSWork and is protected by copyright and other intellectual property laws. This Agreement does not grant you any ownership rights to the Software.
+
+## 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
+
+## 5. Limitation of Liability
+
+IN NO EVENT SHALL VSWORK BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, OR LOSS OF PROFITS) ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT OR THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+## 6. Termination
+
+This license is effective until terminated. Your rights under this license will terminate automatically without notice if you fail to comply with any of its terms. Upon termination, you must destroy all copies of the Software in your possession.
+
+## 7. Governing Law
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which VSWork operates, without regard to its conflict of law provisions.
+
+## 8. Entire Agreement
+
+This Agreement constitutes the entire agreement between you and VSWork regarding the Software and supersedes all prior agreements and understandings, whether written or oral.
+
+---
+
+By installing or using this Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this Agreement.

package/README.md

@@ -0,0 +1,26 @@
+# vesper-link
+
+**Vesper Memory Link — One Memory across all your devices.**
+
+`vesper-link` connects a supported Windows or Linux device to Vesper Memory. It can:
+
+- Sync completed Claude Code, GitHub Copilot CLI, and OpenAI Codex sessions to your Vesper Host.
+- Let full-access devices search and add Vesper Memory through MCP.
+
+## Connect a Device
+
+On the Windows device running Vesper, open **Memory Links** and copy a connection command. Run it on the device you want to connect; no global installation is required.
+
+Node.js 20 or later is required. V1 supports Windows x64 and Linux x64.
+
+## Manage the Connection
+
+```bash
+npx --yes @msvesper/vesper-link@0.1.4 status
+npx --yes @msvesper/vesper-link@0.1.4 pause
+npx --yes @msvesper/vesper-link@0.1.4 resume
+npx --yes @msvesper/vesper-link@0.1.4 doctor
+npx --yes @msvesper/vesper-link@0.1.4 uninstall
+```
+
+Session transcripts are sent to the Vesper Host selected during setup and retained there. They are not uploaded to a Vesper-operated cloud service. Uninstalling the connection does not delete the original transcripts or Memory already saved on the Host.

package/dist/atomic-json.d.ts

@@ -0,0 +1,3 @@
+export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function writeJsonAtomic(filePath: string, value: unknown): Promise<void>;
+export declare function listJsonFiles(directory: string): Promise<string[]>;

package/dist/atomic-json.js

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+export async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeJsonAtomic(filePath, value) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        const handle = await fs.open(tempPath, 'wx');
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(tempPath, filePath);
+    }
+    finally {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+    }
+}
+export async function listJsonFiles(directory) {
+    try {
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => path.join(directory, entry.name));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import { writeConfig } from './config.js';
+import { getDoctorReport, getStatusReport } from './diagnostics.js';
+import { resolveHookReport } from './hook-report.js';
+import { pauseIntegrations, resetRemoteIdentity, resumeIntegrations, uninstallIntegrations } from './installation.js';
+import { parseInstallArguments } from './install-args.js';
+import { installVesperLink } from './installer.js';
+import { runMemoryMcp } from './memory-mcp.js';
+import { appendSyncLog } from './operational-log.js';
+import { writePendingMarker } from './pending.js';
+import { resolveLinkPaths } from './paths.js';
+import { runSyncOnce } from './sync.js';
+import { VESPER_LINK_VERSION } from './version.js';
+const USAGE = 'Usage: vesper-link <configure|report-session|sync-once|scheduled-sync|mcp|install|pause|resume|uninstall|reset-identity|status|doctor>';
+function flags(args) {
+    const result = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const current = args[index];
+        if (!current.startsWith('--') || index + 1 >= args.length) {
+            throw new Error(`Invalid argument: ${current}`);
+        }
+        result.set(current.slice(2), args[++index]);
+    }
+    return result;
+}
+async function readStdinJson() {
+    if (process.stdin.isTTY) {
+        return null;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    return text ? JSON.parse(text) : null;
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (command === '--help' || command === '-h') {
+        process.stdout.write(USAGE + String.fromCharCode(10));
+        return;
+    }
+    if (command === '--version' || command === '-v') {
+        process.stdout.write(VESPER_LINK_VERSION + String.fromCharCode(10));
+        return;
+    }
+    const paths = resolveLinkPaths();
+    if (command === 'configure') {
+        const values = flags(args);
+        const host = values.get('host');
+        if (!host) {
+            throw new Error('Usage: vesper-link configure --host <url>');
+        }
+        const config = await writeConfig(paths.configPath, host);
+        process.stdout.write(`${JSON.stringify(config)}\n`);
+        return;
+    }
+    if (command === 'report-session') {
+        const values = flags(args);
+        const stdin = await readStdinJson();
+        const report = resolveHookReport(values, stdin, paths);
+        const markerPath = await writePendingMarker(paths.pendingDir, {
+            schemaVersion: 1,
+            provider: report.provider,
+            providerSessionId: report.providerSessionId,
+            transcriptPath: report.transcriptPath,
+            queuedAt: new Date().toISOString(),
+        });
+        process.stdout.write(`${JSON.stringify({ queued: true, markerPath })}\n`);
+        return;
+    }
+    if (command === 'sync-once') {
+        const summary = await runSyncOnce({ paths });
+        process.stdout.write(`${JSON.stringify(summary)}\n`);
+        return;
+    }
+    if (command === 'mcp') {
+        if (args.length > 0) {
+            throw new Error('Usage: vesper-link mcp');
+        }
+        await runMemoryMcp(paths);
+        return;
+    }
+    if (command === 'scheduled-sync') {
+        flags(args);
+        try {
+            const summary = await runSyncOnce({ paths });
+            await appendSyncLog(paths.logsDir, {
+                timestamp: new Date().toISOString(), event: 'sync_completed',
+                discovered: summary.discovered, queued: summary.queued, uploaded: summary.uploaded,
+                unchanged: summary.unchanged, failed: summary.failed,
+                collectorIssueCount: summary.collectorIssues.length, stoppedBy: summary.stoppedBy,
+            });
+            process.stdout.write(`${JSON.stringify(summary)}\n`);
+        }
+        catch (error) {
+            await appendSyncLog(paths.logsDir, {
+                timestamp: new Date().toISOString(), event: 'sync_failed',
+                errorCode: typeof error.code === 'string' ? error.code : undefined,
+                errorType: error instanceof Error ? error.name : typeof error,
+            });
+            throw error;
+        }
+        return;
+    }
+    if (command === 'install') {
+        const { host, expectedRole, bootstrapAuthKey } = parseInstallArguments(args);
+        const result = await installVesperLink({
+            paths, host, expectedRole, bootstrapAuthKey,
+            onNeedsLogin: (url) => process.stderr.write(`Authorize vesper-link: ${url}\n`),
+            onWaitingForTag: (progress) => process.stderr.write(`Waiting for ${progress.expectedRole ? `tag:vesper-${progress.expectedRole}` : 'one Vesper capability tag'} on ${progress.nodeName ?? 'this node'} (${progress.tailnetName ?? 'unknown tailnet'})...\n`),
+        });
+        process.stdout.write(`${JSON.stringify({
+            installed: true, minuteOffset: result.state.minuteOffset,
+            sourceTrust: result.state.sourceTrust, firstSyncStarted: result.firstSyncStarted,
+        })}\n`);
+        return;
+    }
+    if (command === 'uninstall') {
+        process.stdout.write(`${JSON.stringify({ removed: await uninstallIntegrations(paths) })}\n`);
+        return;
+    }
+    if (command === 'pause') {
+        if (args.length > 0) {
+            throw new Error('Usage: vesper-link pause');
+        }
+        process.stdout.write(JSON.stringify({ paused: await pauseIntegrations(paths) }) + String.fromCharCode(10));
+        return;
+    }
+    if (command === 'resume') {
+        if (args.length > 0) {
+            throw new Error('Usage: vesper-link resume');
+        }
+        const resumed = await resumeIntegrations(paths);
+        if (resumed) {
+            const summary = await runSyncOnce({ paths });
+            process.stdout.write(JSON.stringify({ resumed: true, sync: summary }) + String.fromCharCode(10));
+        }
+        else {
+            process.stdout.write(JSON.stringify({ resumed: false }) + String.fromCharCode(10));
+        }
+        return;
+    }
+    if (command === 'reset-identity') {
+        const values = flags(args);
+        if (values.get('confirm') !== 'RESET') {
+            throw new Error('Usage: vesper-link reset-identity --confirm RESET');
+        }
+        await resetRemoteIdentity(paths, true);
+        process.stdout.write(`${JSON.stringify({ reset: true })}\n`);
+        return;
+    }
+    if (command === 'status') {
+        process.stdout.write(`${JSON.stringify(await getStatusReport(paths))}\n`);
+        return;
+    }
+    if (command === 'doctor') {
+        const report = await getDoctorReport(paths);
+        process.stdout.write(`${JSON.stringify(report)}\n`);
+        if (!report.healthy) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    throw new Error(USAGE);
+}
+main().catch((error) => {
+    process.stderr.write(`vesper-link: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/collectors/claude.d.ts

@@ -0,0 +1,5 @@
+import type { SessionCandidate } from '../session.js';
+import type { CollectorContext, SessionCollector } from './types.js';
+export declare class ClaudeCollector implements SessionCollector {
+    collect(context: CollectorContext): Promise<SessionCandidate[]>;
+}

package/dist/collectors/claude.js

@@ -0,0 +1,42 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { normalizeProjectKey, pathToOpaqueFileUri, readFirstLine, walkFiles } from '../fs-utils.js';
+export class ClaudeCollector {
+    async collect(context) {
+        const files = await walkFiles(context.claudeProjectsDir, (filePath) => filePath.endsWith('.jsonl'));
+        const candidates = [];
+        for (const transcriptPath of files) {
+            try {
+                const stat = await fs.stat(transcriptPath);
+                let cwdUri;
+                try {
+                    const firstRecord = JSON.parse(await readFirstLine(transcriptPath));
+                    if (typeof firstRecord.cwd === 'string' && firstRecord.cwd) {
+                        cwdUri = pathToOpaqueFileUri(firstRecord.cwd);
+                    }
+                }
+                catch {
+                    // Claude's native project key is sufficient when optional cwd metadata is unavailable.
+                }
+                candidates.push({
+                    provider: 'claude-code',
+                    format: 'claude-code-session-jsonl',
+                    formatVersion: 'observed-v1',
+                    providerSessionId: path.basename(transcriptPath, '.jsonl'),
+                    transcriptPath,
+                    projectKey: normalizeProjectKey(path.relative(context.claudeProjectsDir, transcriptPath).split(path.sep)[0]),
+                    cwdUri,
+                    sourceCreatedAt: stat.birthtime.toISOString(),
+                    sourceUpdatedAt: stat.mtime.toISOString(),
+                    size: stat.size,
+                    mtimeMs: stat.mtimeMs,
+                    discovery: 'scan',
+                });
+            }
+            catch (error) {
+                context.reportIssue?.({ provider: 'claude-code', code: 'source_unreadable', message: String(error) });
+            }
+        }
+        return candidates;
+    }
+}

package/dist/collectors/codex.d.ts

@@ -0,0 +1,5 @@
+import { type SessionCandidate } from '../session.js';
+import type { CollectorContext, SessionCollector } from './types.js';
+export declare class CodexCollector implements SessionCollector {
+    collect(context: CollectorContext): Promise<SessionCandidate[]>;
+}

package/dist/collectors/codex.js

@@ -0,0 +1,65 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { pathToOpaqueFileUri, pathToProjectKey, readFirstLine, walkFiles } from '../fs-utils.js';
+import { stableSessionKey } from '../session.js';
+async function readCandidate(transcriptPath, archived) {
+    const firstLine = await readFirstLine(transcriptPath);
+    const record = JSON.parse(firstLine);
+    if (record.type !== 'session_meta' || !record.payload?.id) {
+        throw new Error(`Codex rollout has no first-record session_meta.id: ${transcriptPath}`);
+    }
+    if (record.payload.session_id && record.payload.session_id !== record.payload.id) {
+        throw new Error(`Codex session_meta id/session_id mismatch: ${transcriptPath}`);
+    }
+    const stat = await fs.stat(transcriptPath);
+    const createdValue = record.payload.timestamp || record.timestamp;
+    const createdAt = createdValue && !Number.isNaN(Date.parse(createdValue))
+        ? new Date(createdValue).toISOString()
+        : stat.birthtime.toISOString();
+    return {
+        provider: 'openai-codex',
+        format: 'openai-codex-rollout-jsonl',
+        formatVersion: record.payload.cli_version || 'observed-v1',
+        providerSessionId: record.payload.id,
+        transcriptPath,
+        projectKey: record.payload.cwd ? pathToProjectKey(record.payload.cwd) : undefined,
+        cwdUri: record.payload.cwd ? pathToOpaqueFileUri(record.payload.cwd) : undefined,
+        sourceCreatedAt: createdAt,
+        sourceUpdatedAt: stat.mtime.toISOString(),
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        discovery: 'scan',
+        archived,
+    };
+}
+export class CodexCollector {
+    async collect(context) {
+        const roots = [
+            { directory: path.join(context.codexHome, 'sessions'), archived: false },
+            { directory: path.join(context.codexHome, 'archived_sessions'), archived: true },
+        ];
+        const fileGroups = await Promise.all(roots.map(async ({ directory, archived }) => {
+            const files = await walkFiles(directory, (filePath) => path.basename(filePath).startsWith('rollout-') && filePath.endsWith('.jsonl'));
+            return files.map((filePath) => ({ filePath, archived }));
+        }));
+        const discovered = [];
+        for (const { filePath, archived } of fileGroups.flat()) {
+            try {
+                discovered.push(await readCandidate(filePath, archived));
+            }
+            catch (error) {
+                context.reportIssue?.({ provider: 'openai-codex', code: 'invalid_session_meta', message: String(error) });
+            }
+        }
+        const byIdentity = new Map();
+        for (const candidate of discovered) {
+            const key = stableSessionKey(candidate.provider, candidate.providerSessionId);
+            const current = byIdentity.get(key);
+            if (!current || candidate.mtimeMs > current.mtimeMs
+                || (candidate.mtimeMs === current.mtimeMs && candidate.archived && !current.archived)) {
+                byIdentity.set(key, candidate);
+            }
+        }
+        return [...byIdentity.values()];
+    }
+}

package/dist/collectors/copilot.d.ts

@@ -0,0 +1,5 @@
+import type { SessionCandidate } from '../session.js';
+import type { CollectorContext, SessionCollector } from './types.js';
+export declare class CopilotCollector implements SessionCollector {
+    collect(context: CollectorContext): Promise<SessionCandidate[]>;
+}

package/dist/collectors/copilot.js

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { pathToOpaqueFileUri, pathToProjectKey, walkFiles } from '../fs-utils.js';
+function parseYamlScalars(text) {
+    const values = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        let value = match[2];
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        values[match[1]] = value;
+    }
+    return values;
+}
+export class CopilotCollector {
+    async collect(context) {
+        const files = await walkFiles(context.copilotSessionsDir, (filePath) => path.basename(filePath) === 'events.jsonl');
+        const candidates = [];
+        for (const transcriptPath of files) {
+            try {
+                const stat = await fs.stat(transcriptPath);
+                const directory = path.dirname(transcriptPath);
+                const fallbackId = path.basename(directory);
+                let metadata = {};
+                try {
+                    metadata = parseYamlScalars(await fs.readFile(path.join(directory, 'workspace.yaml'), 'utf8'));
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+                const createdAt = metadata.created_at && !Number.isNaN(Date.parse(metadata.created_at))
+                    ? new Date(metadata.created_at).toISOString()
+                    : stat.birthtime.toISOString();
+                const updatedAt = metadata.updated_at && !Number.isNaN(Date.parse(metadata.updated_at))
+                    ? new Date(metadata.updated_at).toISOString()
+                    : stat.mtime.toISOString();
+                candidates.push({
+                    provider: 'github-copilot',
+                    format: 'github-copilot-events-jsonl',
+                    formatVersion: 'observed-v1',
+                    providerSessionId: metadata.id || fallbackId,
+                    transcriptPath,
+                    projectKey: metadata.cwd ? pathToProjectKey(metadata.cwd) : undefined,
+                    cwdUri: metadata.cwd ? pathToOpaqueFileUri(metadata.cwd) : undefined,
+                    sourceCreatedAt: createdAt,
+                    sourceUpdatedAt: updatedAt,
+                    size: stat.size,
+                    mtimeMs: stat.mtimeMs,
+                    discovery: 'scan',
+                });
+            }
+            catch (error) {
+                context.reportIssue?.({ provider: 'github-copilot', code: 'source_unreadable', message: String(error) });
+            }
+        }
+        return candidates;
+    }
+}

package/dist/collectors/index.d.ts

@@ -0,0 +1,4 @@
+export { ClaudeCollector } from './claude.js';
+export { CopilotCollector } from './copilot.js';
+export { CodexCollector } from './codex.js';
+export type { CollectorContext, CollectorIssue, SessionCollector } from './types.js';

package/dist/collectors/index.js

@@ -0,0 +1,3 @@
+export { ClaudeCollector } from './claude.js';
+export { CopilotCollector } from './copilot.js';
+export { CodexCollector } from './codex.js';

package/dist/collectors/types.d.ts

@@ -0,0 +1,16 @@
+import type { SessionCandidate } from '../session.js';
+export interface CollectorContext {
+    nowMs: number;
+    claudeProjectsDir: string;
+    copilotSessionsDir: string;
+    codexHome: string;
+    reportIssue?: (issue: CollectorIssue) => void;
+}
+export interface CollectorIssue {
+    provider: 'claude-code' | 'github-copilot' | 'openai-codex';
+    code: string;
+    message: string;
+}
+export interface SessionCollector {
+    collect(context: CollectorContext): Promise<SessionCandidate[]>;
+}

package/dist/collectors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/companion.d.ts

@@ -0,0 +1,12 @@
+export declare const VESPER_NET_PROTOCOL_VERSION = 2;
+export interface CompanionInfo {
+    executable: string;
+    packageName: string;
+    version: string;
+}
+export type CompanionProtocolRunner = (executable: string, environment: NodeJS.ProcessEnv) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function assertCompanionProtocol(companion: CompanionInfo, environment: NodeJS.ProcessEnv, runner?: CompanionProtocolRunner): Promise<void>;
+export declare function resolveCompanion(platform?: NodeJS.Platform, architecture?: string, resolvePackageJson?: (specifier: string) => string, mainPackageJsonPath?: string): Promise<CompanionInfo>;

package/dist/companion.js

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+export const VESPER_NET_PROTOCOL_VERSION = 2;
+function defaultProtocolRunner(executable, environment) {
+    return new Promise((resolve, reject) => {
+        execFile(executable, ['--protocol-version'], {
+            env: environment, windowsHide: true, timeout: 5_000, maxBuffer: 16 * 1024, encoding: 'utf8',
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(`vesper-net protocol probe failed: ${error.message}`));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+export async function assertCompanionProtocol(companion, environment, runner = defaultProtocolRunner) {
+    const result = await runner(companion.executable, environment);
+    if (result.stderr.trim() !== '' || result.stdout.trim() !== String(VESPER_NET_PROTOCOL_VERSION)) {
+        throw new Error(`vesper-net protocol mismatch: expected ${VESPER_NET_PROTOCOL_VERSION}`);
+    }
+}
+async function readPackageMetadata(filePath) {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+export async function resolveCompanion(platform = process.platform, architecture = process.arch, resolvePackageJson = (specifier) => createRequire(import.meta.url).resolve(specifier), mainPackageJsonPath = fileURLToPath(new URL('../package.json', import.meta.url))) {
+    const packageName = platform === 'win32' && architecture === 'x64'
+        ? '@msvesper/vesper-net-win32-x64'
+        : platform === 'linux' && architecture === 'x64'
+            ? '@msvesper/vesper-net-linux-x64'
+            : null;
+    if (!packageName) {
+        throw new Error(`Unsupported vesper-net platform: ${platform}-${architecture}`);
+    }
+    const mainMetadata = await readPackageMetadata(mainPackageJsonPath);
+    if (typeof mainMetadata.version !== 'string') {
+        throw new Error('vesper-link package version is unavailable');
+    }
+    const optionalDependencies = mainMetadata.optionalDependencies;
+    if (!optionalDependencies || typeof optionalDependencies !== 'object'
+        || optionalDependencies[packageName] !== mainMetadata.version) {
+        throw new Error(`vesper-link must depend on ${packageName}@${mainMetadata.version} exactly`);
+    }
+    let packageJsonPath;
+    try {
+        packageJsonPath = resolvePackageJson(`${packageName}/package.json`);
+    }
+    catch {
+        throw new Error(`Missing optional companion package ${packageName}@${mainMetadata.version}`);
+    }
+    const companionMetadata = await readPackageMetadata(packageJsonPath);
+    if (companionMetadata.name !== packageName || companionMetadata.version !== mainMetadata.version) {
+        throw new Error(`Companion package mismatch: expected ${packageName}@${mainMetadata.version}`);
+    }
+    const executable = path.join(path.dirname(packageJsonPath), 'bin', platform === 'win32' ? 'vesper-net.exe' : 'vesper-net');
+    await fs.access(executable, platform === 'win32' ? fsConstants.F_OK : fsConstants.X_OK);
+    return { executable, packageName, version: mainMetadata.version };
+}

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export interface LinkConfig {
+    schemaVersion: 1;
+    host: string;
+}
+export declare function normalizeHost(value: string): string;
+export declare function readConfig(configPath: string): Promise<LinkConfig>;
+export declare function writeConfig(configPath: string, host: string): Promise<LinkConfig>;

package/dist/config.js

@@ -0,0 +1,41 @@
+import { isIPv4 } from 'node:net';
+import { readJsonFile, writeJsonAtomic } from './atomic-json.js';
+function isTailscaleIpv4(hostname) {
+    if (!isIPv4(hostname)) {
+        return false;
+    }
+    const octets = hostname.split('.').map(Number);
+    return octets.length === 4
+        && octets.every((octet) => Number.isInteger(octet) && octet >= 0 && octet <= 255)
+        && octets[0] === 100
+        && octets[1] >= 64
+        && octets[1] <= 127;
+}
+export function normalizeHost(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'http:') {
+        throw new Error('host must use http');
+    }
+    if (url.username || url.password || url.search || url.hash || (url.pathname !== '' && url.pathname !== '/')) {
+        throw new Error('host must not contain credentials, path, query, or fragment');
+    }
+    if (!isTailscaleIpv4(url.hostname)) {
+        throw new Error('host must use a Tailscale IPv4 address in 100.64.0.0/10');
+    }
+    if (url.port !== '11723') {
+        throw new Error('host must use port 11723');
+    }
+    return `http://${url.hostname}:11723`;
+}
+export async function readConfig(configPath) {
+    const config = await readJsonFile(configPath);
+    if (!config || config.schemaVersion !== 1 || typeof config.host !== 'string') {
+        throw new Error(`Missing or invalid config at ${configPath}; run vesper-link configure --host <url>`);
+    }
+    return { schemaVersion: 1, host: normalizeHost(config.host) };
+}
+export async function writeConfig(configPath, host) {
+    const config = { schemaVersion: 1, host: normalizeHost(host) };
+    await writeJsonAtomic(configPath, config);
+    return config;
+}