@msvesper/vesper-link 0.1.4

package/dist/contracts.d.ts

@@ -0,0 +1,83 @@
+export declare const SCHEMA_VERSION: 1;
+export declare const MAX_FILE_BYTES: number;
+export declare const MAX_MANIFEST_BYTES: number;
+export declare const PROVIDERS: readonly ["claude-code", "github-copilot", "openai-codex"];
+export type Provider = typeof PROVIDERS[number];
+export declare const PROVIDER_FORMATS: {
+    readonly 'claude-code': "claude-code-session-jsonl";
+    readonly 'github-copilot': "github-copilot-events-jsonl";
+    readonly 'openai-codex': "openai-codex-rollout-jsonl";
+};
+export type ProviderFormat = typeof PROVIDER_FORMATS[Provider];
+export interface TranscriptManifest {
+    schemaVersion: typeof SCHEMA_VERSION;
+    provider: Provider;
+    format: string;
+    formatVersion: string;
+    providerSessionId: string;
+    projectKey?: string;
+    cwdUri?: string;
+    sourceTranscriptUri: string;
+    sourceCreatedAt?: string;
+    sourceUpdatedAt: string;
+    byteLength: number;
+    sha256: string;
+}
+export type UploadStatus = 'needs_content' | 'archived' | 'updated' | 'already_archived';
+export type ProcessingStatus = 'pending_upload' | 'archived' | 'parse_pending' | 'unsupported' | 'analysis_paused_memory_disabled' | 'analyzing' | 'result_persisted' | 'fanout_pending' | 'completed' | 'analysis_partial' | 'retry_wait' | 'failed_permanent' | 'analysis_skipped_empty' | 'analysis_skipped_internal' | 'analysis_stale';
+export interface TranscriptResponse {
+    requestId: string;
+    transcriptId: string;
+    uploadStatus: UploadStatus;
+    processingStatus: ProcessingStatus;
+    currentSha256: string | null;
+}
+export interface HealthResponse {
+    requestId: string;
+    archiveReady: boolean;
+    memoryReady: boolean;
+    serverVersion: string;
+    minimumClientVersion: string;
+}
+export interface CapabilitiesResponse {
+    requestId: string;
+    canUploadSessions: boolean;
+    canSearchMemory: boolean;
+    canAddFact: boolean;
+    sourceTrust: 'trusted' | 'uploader';
+}
+export interface ErrorEnvelope {
+    requestId: string;
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+export interface MemorySearchItem {
+    content: string;
+    score: number;
+    schemaType: string;
+    source: 'extracted' | 'files' | 'kg' | 'wiki' | 'signals';
+    provenance: {
+        id: string;
+        signalId?: string;
+    };
+}
+export interface MemorySearchResponse {
+    requestId: string;
+    results: MemorySearchItem[];
+}
+export interface AddFactResponse {
+    requestId: string;
+    id: string;
+    schemaType: string;
+    status: 'written' | 'already_present';
+}
+export declare function isProvider(value: unknown): value is Provider;
+export declare function validateManifest(manifest: TranscriptManifest): void;
+export declare function parseTranscriptResponse(value: unknown): TranscriptResponse;
+export declare function parseHealthResponse(value: unknown): HealthResponse;
+export declare function parseCapabilitiesResponse(value: unknown): CapabilitiesResponse;
+export declare function parseMemorySearchResponse(value: unknown): MemorySearchResponse;
+export declare function parseAddFactResponse(value: unknown): AddFactResponse;

package/dist/contracts.js

@@ -0,0 +1,144 @@
+export const SCHEMA_VERSION = 1;
+export const MAX_FILE_BYTES = 50 * 1024 * 1024;
+export const MAX_MANIFEST_BYTES = 16 * 1024;
+export const PROVIDERS = ['claude-code', 'github-copilot', 'openai-codex'];
+export const PROVIDER_FORMATS = {
+    'claude-code': 'claude-code-session-jsonl',
+    'github-copilot': 'github-copilot-events-jsonl',
+    'openai-codex': 'openai-codex-rollout-jsonl',
+};
+const LOWERCASE_SHA256 = /^[a-f0-9]{64}$/;
+function hasControlCharacters(value) {
+    return [...value].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127;
+    });
+}
+function utf8Length(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function isCanonicalInstant(value) {
+    const parsed = new Date(value);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}
+export function isProvider(value) {
+    return typeof value === 'string' && PROVIDERS.includes(value);
+}
+export function validateManifest(manifest) {
+    if (manifest.schemaVersion !== SCHEMA_VERSION) {
+        throw new Error('schemaVersion must be 1');
+    }
+    if (!isProvider(manifest.provider)) {
+        throw new Error('unsupported provider');
+    }
+    if (!manifest.format || utf8Length(manifest.format) > 128 || hasControlCharacters(manifest.format)) {
+        throw new Error('format must be 1-128 UTF-8 bytes without control characters');
+    }
+    if (!manifest.formatVersion || utf8Length(manifest.formatVersion) > 128 || hasControlCharacters(manifest.formatVersion)) {
+        throw new Error('formatVersion must be 1-128 UTF-8 bytes without control characters');
+    }
+    if (!manifest.providerSessionId || utf8Length(manifest.providerSessionId) > 512 || hasControlCharacters(manifest.providerSessionId)) {
+        throw new Error('providerSessionId must be 1-512 UTF-8 bytes without control characters');
+    }
+    if (manifest.cwdUri !== undefined && utf8Length(manifest.cwdUri) > 4096) {
+        throw new Error('cwdUri must not exceed 4096 UTF-8 bytes');
+    }
+    if (!manifest.sourceTranscriptUri.startsWith('file://') || utf8Length(manifest.sourceTranscriptUri) > 4096
+        || hasControlCharacters(manifest.sourceTranscriptUri)) {
+        throw new Error('sourceTranscriptUri must be a file URI of at most 4096 UTF-8 bytes without control characters');
+    }
+    if (manifest.projectKey !== undefined
+        && (!/^[A-Za-z0-9-]+$/.test(manifest.projectKey) || utf8Length(manifest.projectKey) > 96)) {
+        throw new Error('projectKey must contain only letters, numbers, and hyphens and not exceed 96 UTF-8 bytes');
+    }
+    if (manifest.sourceCreatedAt !== undefined && !isCanonicalInstant(manifest.sourceCreatedAt)) {
+        throw new Error('sourceCreatedAt must be a canonical ISO-8601 instant');
+    }
+    if (!isCanonicalInstant(manifest.sourceUpdatedAt)) {
+        throw new Error('sourceUpdatedAt must be a canonical ISO-8601 instant');
+    }
+    if (!Number.isSafeInteger(manifest.byteLength) || manifest.byteLength < 0 || manifest.byteLength > MAX_FILE_BYTES) {
+        throw new Error(`byteLength must be an integer between 0 and ${MAX_FILE_BYTES}`);
+    }
+    if (!LOWERCASE_SHA256.test(manifest.sha256)) {
+        throw new Error('sha256 must be 64 lowercase hexadecimal characters');
+    }
+}
+export function parseTranscriptResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('response must be an object');
+    }
+    const response = value;
+    const uploadStatuses = ['needs_content', 'archived', 'updated', 'already_archived'];
+    const processingStatuses = [
+        'pending_upload', 'archived', 'parse_pending', 'unsupported',
+        'analysis_paused_memory_disabled', 'analyzing', 'result_persisted',
+        'fanout_pending', 'completed', 'analysis_partial', 'retry_wait', 'failed_permanent',
+        'analysis_skipped_empty', 'analysis_skipped_internal', 'analysis_stale',
+    ];
+    if (typeof response.requestId !== 'string' || typeof response.transcriptId !== 'string'
+        || !LOWERCASE_SHA256.test(response.transcriptId)
+        || !uploadStatuses.includes(String(response.uploadStatus))
+        || !processingStatuses.includes(String(response.processingStatus))
+        || !(response.currentSha256 === null || (typeof response.currentSha256 === 'string' && LOWERCASE_SHA256.test(response.currentSha256)))) {
+        throw new Error('malformed transcript response');
+    }
+    return response;
+}
+export function parseHealthResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('health response must be an object');
+    }
+    const health = value;
+    if (typeof health.requestId !== 'string' || typeof health.archiveReady !== 'boolean'
+        || typeof health.memoryReady !== 'boolean' || typeof health.serverVersion !== 'string'
+        || typeof health.minimumClientVersion !== 'string') {
+        throw new Error('malformed health response');
+    }
+    return health;
+}
+export function parseCapabilitiesResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('capabilities response must be an object');
+    }
+    const capabilities = value;
+    if (typeof capabilities.requestId !== 'string'
+        || typeof capabilities.canUploadSessions !== 'boolean'
+        || typeof capabilities.canSearchMemory !== 'boolean'
+        || typeof capabilities.canAddFact !== 'boolean'
+        || (capabilities.sourceTrust !== 'trusted' && capabilities.sourceTrust !== 'uploader')) {
+        throw new Error('malformed capabilities response');
+    }
+    return capabilities;
+}
+export function parseMemorySearchResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('memory search response must be an object');
+    }
+    const response = value;
+    if (typeof response.requestId !== 'string' || !Array.isArray(response.results) || response.results.length > 10) {
+        throw new Error('malformed memory search response');
+    }
+    for (const item of response.results) {
+        if (!item || typeof item !== 'object' || typeof item.content !== 'string'
+            || typeof item.score !== 'number' || !Number.isFinite(item.score)
+            || typeof item.schemaType !== 'string' || typeof item.source !== 'string'
+            || !item.provenance || typeof item.provenance.id !== 'string'
+            || (item.provenance.signalId !== undefined && typeof item.provenance.signalId !== 'string')) {
+            throw new Error('malformed memory search item');
+        }
+    }
+    return response;
+}
+export function parseAddFactResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('add fact response must be an object');
+    }
+    const response = value;
+    if (typeof response.requestId !== 'string' || typeof response.id !== 'string'
+        || typeof response.schemaType !== 'string'
+        || (response.status !== 'written' && response.status !== 'already_present')) {
+        throw new Error('malformed add fact response');
+    }
+    return response;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,37 @@
+import { getCapabilities, getHealth } from './http-client.js';
+import { type InstallationStatus } from './installation.js';
+import type { LinkPaths } from './paths.js';
+import { type ProcessRunner } from './process-runner.js';
+import { type RemoteTransport } from './transport.js';
+export interface QueueStatus {
+    pendingMarkers: number;
+    pendingSessions: number;
+    uploadedSessions: number;
+    failedSessions: number;
+}
+export interface StatusReport extends InstallationStatus {
+    queue: QueueStatus;
+    enrollment?: {
+        state: string;
+        tailnetName?: string;
+        nodeName?: string;
+        ipv4?: string;
+    };
+}
+export declare function getStatusReport(paths: LinkPaths, runner?: ProcessRunner): Promise<StatusReport>;
+export interface DoctorReport {
+    healthy: boolean;
+    checks: {
+        config: boolean;
+        host: boolean;
+        installation: InstallationStatus;
+        queue: QueueStatus;
+        health?: Awaited<ReturnType<typeof getHealth>>;
+        capabilities?: Awaited<ReturnType<typeof getCapabilities>>;
+        error?: string;
+    };
+}
+export declare function getDoctorReport(paths: LinkPaths, runner?: ProcessRunner, remote?: {
+    health: typeof getHealth;
+    capabilities: typeof getCapabilities;
+}, acquireTransport?: (paths: LinkPaths, hostUrl: string) => Promise<RemoteTransport>): Promise<DoctorReport>;

package/dist/diagnostics.js

@@ -0,0 +1,64 @@
+import { readConfig } from './config.js';
+import { getCapabilities, getHealth } from './http-client.js';
+import { getInstallationStatus } from './installation.js';
+import { readPendingMarkers } from './pending.js';
+import { NodeProcessRunner } from './process-runner.js';
+import { readSessionStates } from './state.js';
+import { acquireRemoteTransport } from './transport.js';
+export async function getStatusReport(paths, runner = new NodeProcessRunner()) {
+    const [installation, pending, states, progress] = await Promise.all([
+        getInstallationStatus(paths, runner), readPendingMarkers(paths.pendingDir), readSessionStates(paths.sessionsDir),
+        import('./atomic-json.js').then(({ readJsonFile }) => readJsonFile(paths.installProgressPath)),
+    ]);
+    const queue = { pendingMarkers: pending.length, pendingSessions: 0, uploadedSessions: 0, failedSessions: 0 };
+    for (const state of states.values()) {
+        if (state.status === 'pending') {
+            queue.pendingSessions += 1;
+        }
+        if (state.status === 'uploaded') {
+            queue.uploadedSessions += 1;
+        }
+        if (state.status === 'failed') {
+            queue.failedSessions += 1;
+        }
+    }
+    const enrollment = progress && typeof progress.state === 'string' ? {
+        state: progress.state,
+        tailnetName: typeof progress.tailnetName === 'string' ? progress.tailnetName : undefined,
+        nodeName: typeof progress.nodeName === 'string' ? progress.nodeName : undefined,
+        ipv4: typeof progress.ipv4 === 'string' ? progress.ipv4 : undefined,
+    } : undefined;
+    return { ...installation, queue, enrollment };
+}
+export async function getDoctorReport(paths, runner = new NodeProcessRunner(), remote = { health: getHealth, capabilities: getCapabilities }, acquireTransport = (linkPaths, hostUrl) => acquireRemoteTransport({ paths: linkPaths, hostUrl })) {
+    const status = await getStatusReport(paths, runner);
+    const installation = status;
+    const checks = { config: false, host: false, installation, queue: status.queue };
+    try {
+        const config = await readConfig(paths.configPath);
+        checks.config = true;
+        const transport = await acquireTransport(paths, config.host);
+        let health;
+        let capabilities;
+        try {
+            [health, capabilities] = await Promise.all([
+                remote.health(transport.hostUrl, transport.fetch), remote.capabilities(transport.hostUrl, transport.fetch),
+            ]);
+        }
+        finally {
+            await transport.release();
+        }
+        checks.host = health.archiveReady && capabilities.canUploadSessions;
+        checks.health = health;
+        checks.capabilities = capabilities;
+    }
+    catch (error) {
+        checks.error = error instanceof Error ? error.message : String(error);
+    }
+    return {
+        healthy: checks.config && checks.host && installation.installed && !installation.paused
+            && installation.claudeHookInstalled && installation.copilotHookInstalled && installation.schedulerInstalled
+            && (installation.sourceTrust !== 'trusted' || installation.trustedIntegrationsInstalled),
+        checks,
+    };
+}

package/dist/fs-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function walkFiles(root: string, accept: (filePath: string) => boolean): Promise<string[]>;
+export declare function pathToOpaqueFileUri(filePath: string): string;
+export declare function normalizeProjectKey(value: string): string | undefined;
+export declare function pathToProjectKey(filePath: string): string | undefined;
+export declare function readFirstLine(filePath: string, maxBytes?: number): Promise<string>;

package/dist/fs-utils.js

@@ -0,0 +1,69 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+const MAX_PROJECT_KEY_LENGTH = 96;
+export async function walkFiles(root, accept) {
+    const files = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'EACCES' || code === 'EPERM') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(entryPath);
+            }
+            else if (entry.isFile() && accept(entryPath)) {
+                files.push(entryPath);
+            }
+        }
+    }
+    return files;
+}
+export function pathToOpaqueFileUri(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    if (/^[A-Za-z]:\//.test(normalized)) {
+        return `file:///${normalized}`;
+    }
+    return normalized.startsWith('/') ? `file://${normalized}` : `file:///${normalized}`;
+}
+export function normalizeProjectKey(value) {
+    const key = value.replace(/[^A-Za-z0-9]/g, '-');
+    if (!key) {
+        return undefined;
+    }
+    if (key.length <= MAX_PROJECT_KEY_LENGTH) {
+        return key;
+    }
+    const suffix = createHash('sha256').update(key).digest('hex').slice(0, 16);
+    return `${key.slice(0, MAX_PROJECT_KEY_LENGTH - suffix.length - 1)}-${suffix}`;
+}
+export function pathToProjectKey(filePath) {
+    return normalizeProjectKey(filePath);
+}
+export async function readFirstLine(filePath, maxBytes = 64 * 1024) {
+    const handle = await fs.open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const text = buffer.subarray(0, bytesRead).toString('utf8');
+        const newline = text.indexOf('\n');
+        if (newline < 0 && bytesRead === maxBytes) {
+            throw new Error(`First JSONL record exceeds ${maxBytes} bytes`);
+        }
+        return (newline >= 0 ? text.slice(0, newline) : text).replace(/\r$/, '');
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/hook-report.d.ts

@@ -0,0 +1,8 @@
+import { type Provider } from './contracts.js';
+import type { LinkPaths } from './paths.js';
+export interface HookReport {
+    provider: Provider;
+    providerSessionId: string;
+    transcriptPath: string;
+}
+export declare function resolveHookReport(values: Map<string, string>, stdin: Record<string, unknown> | null, paths: LinkPaths): HookReport;

package/dist/hook-report.js

@@ -0,0 +1,21 @@
+import * as path from 'node:path';
+import { isProvider } from './contracts.js';
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+export function resolveHookReport(values, stdin, paths) {
+    const providerValue = values.get('provider') ?? stringValue(stdin?.provider);
+    const providerSessionId = values.get('session')
+        ?? stringValue(stdin?.session_id)
+        ?? stringValue(stdin?.sessionId);
+    let transcriptPath = values.get('path')
+        ?? stringValue(stdin?.transcript_path)
+        ?? stringValue(stdin?.transcriptPath);
+    if (!transcriptPath && providerValue === 'github-copilot' && providerSessionId) {
+        transcriptPath = path.join(paths.copilotSessionsDir, providerSessionId, 'events.jsonl');
+    }
+    if (!isProvider(providerValue) || !providerSessionId || !transcriptPath) {
+        throw new Error('report-session requires --provider, --session, and --path');
+    }
+    return { provider: providerValue, providerSessionId, transcriptPath };
+}

package/dist/http-client.d.ts

@@ -0,0 +1,25 @@
+import { type AddFactResponse, type CapabilitiesResponse, type HealthResponse, type MemorySearchResponse, type TranscriptManifest, type TranscriptResponse } from './contracts.js';
+export declare function getHealth(host: string, fetchImpl?: typeof fetch): Promise<HealthResponse>;
+export declare function getCapabilities(host: string, fetchImpl?: typeof fetch): Promise<CapabilitiesResponse>;
+export declare function searchMemory(host: string, query: string, limit?: number, fetchImpl?: typeof fetch): Promise<MemorySearchResponse>;
+export declare function addFact(host: string, fact: string, fetchImpl?: typeof fetch): Promise<AddFactResponse>;
+export declare function getTranscriptStatus(host: string, transcriptId: string, fetchImpl?: typeof fetch): Promise<TranscriptResponse>;
+export declare function postManifest(host: string, manifest: TranscriptManifest, fetchImpl?: typeof fetch): Promise<TranscriptResponse>;
+export declare function putContent(options: {
+    host: string;
+    transcriptId: string;
+    filePath: string;
+    byteLength: number;
+    fetchImpl?: typeof fetch;
+}): Promise<TranscriptResponse>;
+export declare class TaskUploadError extends Error {
+    readonly code: string;
+    readonly httpStatus?: number | undefined;
+    constructor(code: string, message: string, httpStatus?: number | undefined);
+}
+export declare class SystemicUploadError extends Error {
+    readonly code: string;
+    readonly httpStatus?: number | undefined;
+    readonly retryAfterUntil?: string | undefined;
+    constructor(code: string, message: string, httpStatus?: number | undefined, retryAfterUntil?: string | undefined);
+}