@msvesper/vesper-link 0.1.4

package/dist/queue.js

@@ -0,0 +1,129 @@
+import * as fs from 'node:fs/promises';
+import { defaultFormat, stableSessionKey } from './session.js';
+export const STABLE_FILE_AGE_MS = 6 * 60 * 60 * 1000;
+export const MAX_SESSIONS_PER_RUN = 2_000;
+async function markerToCandidate(marker) {
+    let size = 0;
+    let mtimeMs = Date.parse(marker.queuedAt);
+    try {
+        const stat = await fs.stat(marker.transcriptPath);
+        size = stat.size;
+        mtimeMs = stat.mtimeMs;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    return {
+        provider: marker.provider,
+        format: defaultFormat(marker.provider),
+        formatVersion: 'observed-v1',
+        providerSessionId: marker.providerSessionId,
+        transcriptPath: marker.transcriptPath,
+        sourceUpdatedAt: new Date(mtimeMs).toISOString(),
+        size,
+        mtimeMs,
+        discovery: 'marker',
+    };
+}
+async function stateToCandidate(state) {
+    let size = state.lastSeenSize;
+    let mtimeMs = state.lastSeenMtimeMs;
+    let sourceUpdatedAt = state.sourceUpdatedAt;
+    try {
+        const stat = await fs.stat(state.transcriptPath);
+        size = stat.size;
+        mtimeMs = stat.mtimeMs;
+        sourceUpdatedAt = stat.mtime.toISOString();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    return {
+        provider: state.provider,
+        format: state.format,
+        formatVersion: state.formatVersion,
+        providerSessionId: state.providerSessionId,
+        transcriptPath: state.transcriptPath,
+        projectKey: state.projectKey,
+        cwdUri: state.cwdUri,
+        sourceCreatedAt: state.sourceCreatedAt,
+        sourceUpdatedAt,
+        size,
+        mtimeMs,
+        discovery: state.requiresStability ? 'scan' : 'state',
+    };
+}
+function unchangedSinceTerminalState(candidate, state) {
+    return (state?.status === 'uploaded' || state?.status === 'failed')
+        && (!candidate.projectKey || candidate.projectKey === state.projectKey)
+        && state.lastSeenSize === candidate.size
+        && state.lastSeenMtimeMs === candidate.mtimeMs;
+}
+export function isStableForUpload(candidate, mtimeMs, nowMs) {
+    return candidate.discovery !== 'scan' || candidate.archived === true || nowMs - mtimeMs >= STABLE_FILE_AGE_MS;
+}
+function markerPredatesTerminalFailure(marker, state) {
+    if (state?.status !== 'failed' || !state.lastError) {
+        return false;
+    }
+    return Date.parse(marker.queuedAt) <= Date.parse(state.lastError.at);
+}
+export async function selectQueueItems(options) {
+    const limit = options.limit ?? MAX_SESSIONS_PER_RUN;
+    const selected = new Map();
+    const scannedByKey = new Map(options.scanned.map((candidate) => [
+        stableSessionKey(candidate.provider, candidate.providerSessionId), candidate,
+    ]));
+    const markerItems = [];
+    for (const { path: markerPath, marker } of options.markers) {
+        const key = stableSessionKey(marker.provider, marker.providerSessionId);
+        if (!markerPredatesTerminalFailure(marker, options.states.get(key))) {
+            const candidate = await markerToCandidate(marker);
+            const scanned = scannedByKey.get(key);
+            if (scanned) {
+                candidate.projectKey = scanned.projectKey;
+                candidate.cwdUri = scanned.cwdUri;
+                candidate.sourceCreatedAt = scanned.sourceCreatedAt;
+            }
+            markerItems.push({ candidate, markerPath, markerQueuedAt: marker.queuedAt });
+        }
+    }
+    markerItems.sort((a, b) => a.candidate.sourceUpdatedAt.localeCompare(b.candidate.sourceUpdatedAt));
+    for (const item of markerItems) {
+        selected.set(stableSessionKey(item.candidate.provider, item.candidate.providerSessionId), item);
+    }
+    const pendingStates = [...options.states.values()]
+        .filter((state) => state.status === 'pending')
+        .sort((a, b) => (a.lastError?.at ?? '').localeCompare(b.lastError?.at ?? ''));
+    for (const state of pendingStates) {
+        const key = stableSessionKey(state.provider, state.providerSessionId);
+        if (!selected.has(key)) {
+            const candidate = await stateToCandidate(state);
+            const scanned = scannedByKey.get(key);
+            if (scanned) {
+                candidate.projectKey = scanned.projectKey;
+                candidate.cwdUri = scanned.cwdUri;
+                candidate.sourceCreatedAt = scanned.sourceCreatedAt;
+            }
+            selected.set(key, { candidate });
+        }
+    }
+    const eligibleScanned = options.scanned
+        .filter((candidate) => isStableForUpload(candidate, candidate.mtimeMs, options.nowMs))
+        .filter((candidate) => {
+        const key = stableSessionKey(candidate.provider, candidate.providerSessionId);
+        return !unchangedSinceTerminalState(candidate, options.states.get(key));
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const candidate of eligibleScanned) {
+        const key = stableSessionKey(candidate.provider, candidate.providerSessionId);
+        if (!selected.has(key)) {
+            selected.set(key, { candidate });
+        }
+    }
+    return [...selected.values()].slice(0, limit);
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,51 @@
+import { type ProcessRunner } from './process-runner.js';
+export type SchedulerState = {
+    kind: 'windows-task';
+    name: string;
+    installationId: string;
+    minuteOffset: number;
+    nodePath: string;
+    launcherPath: string;
+} | {
+    kind: 'cron';
+    marker: string;
+    minuteOffset: number;
+    nodePath: string;
+    launcherPath: string;
+};
+export type SchedulerSnapshot = {
+    kind: 'windows-task';
+    existed: boolean;
+    xml?: string;
+} | {
+    kind: 'cron';
+    content: string;
+};
+export declare function stableMinuteOffset(homeDir: string, machineName?: string): number;
+export declare function prepareScheduler(options: {
+    platform?: NodeJS.Platform;
+    runner?: ProcessRunner;
+    minuteOffset: number;
+    nodePath: string;
+    launcherPath: string;
+    installationId: string;
+}): Promise<{
+    state: SchedulerState;
+    snapshot: SchedulerSnapshot;
+}>;
+export declare function applyScheduler(state: SchedulerState, snapshot: SchedulerSnapshot, runner?: ProcessRunner): Promise<void>;
+export declare function installScheduler(options: {
+    platform?: NodeJS.Platform;
+    runner?: ProcessRunner;
+    minuteOffset: number;
+    nodePath: string;
+    launcherPath: string;
+    installationId: string;
+}): Promise<{
+    state: SchedulerState;
+    snapshot: SchedulerSnapshot;
+}>;
+export declare function restoreScheduler(state: SchedulerState, snapshot: SchedulerSnapshot, runner?: ProcessRunner): Promise<void>;
+export declare function schedulerInstalled(state: SchedulerState, runner?: ProcessRunner): Promise<boolean>;
+export declare function uninstallScheduler(state: SchedulerState, runner?: ProcessRunner): Promise<void>;
+export declare function assertSchedulerOwned(state: SchedulerState, runner?: ProcessRunner): Promise<void>;

package/dist/scheduler.js

@@ -0,0 +1,176 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { NodeProcessRunner } from './process-runner.js';
+const WINDOWS_TASK_PREFIX = 'VesperLinkSessionSync-';
+const CRON_MARKER = '# vesper-link:session-sync';
+function quoteCommand(value) {
+    return '"' + value.replace(/"/g, '\\"') + '"';
+}
+function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\"'\"'") + "'";
+}
+function ownerToken(installationId) {
+    return '--owner ' + installationId;
+}
+export function stableMinuteOffset(homeDir, machineName = os.hostname()) {
+    return Number.parseInt(createHash('sha256').update(machineName).update('\0').update(homeDir).digest('hex').slice(0, 8), 16) % 60;
+}
+async function readCron(runner) {
+    const environment = { ...process.env, LC_ALL: 'C', LANG: 'C' };
+    const result = await runner.run('crontab', ['-l'], undefined, environment);
+    if (result.code === 0) {
+        return result.stdout;
+    }
+    const output = result.stdout + result.stderr;
+    if (result.code === 1 && /^\s*no crontab for [^\r\n]+\s*$/i.test(output)) {
+        return '';
+    }
+    throw new Error('Cannot read user crontab: ' + (result.stderr || result.stdout).trim());
+}
+function withoutOwnedCron(content) {
+    return content.split(/\r?\n/).filter((line) => !line.trimEnd().endsWith(CRON_MARKER)).join('\n');
+}
+async function writeCron(runner, content) {
+    const environment = { ...process.env, LC_ALL: 'C', LANG: 'C' };
+    const result = await runner.run('crontab', ['-'], content, environment);
+    if (result.code !== 0) {
+        throw new Error('Cannot update user crontab: ' + result.stderr.trim());
+    }
+}
+async function queryWindowsTask(runner, name) {
+    return runner.run('schtasks.exe', ['/Query', '/TN', name, '/XML']);
+}
+async function createWindowsTask(runner, state, replace) {
+    const command = quoteCommand(state.nodePath) + ' ' + quoteCommand(state.launcherPath)
+        + ' scheduled-sync ' + ownerToken(state.installationId);
+    const args = [
+        '/Create', '/TN', state.name, '/SC', 'HOURLY', '/MO', '1',
+        '/ST', '00:' + String(state.minuteOffset).padStart(2, '0'), '/TR', command, '/RL', 'LIMITED',
+    ];
+    if (replace) {
+        args.push('/F');
+    }
+    const result = await runner.run('schtasks.exe', args);
+    if (result.code !== 0) {
+        throw new Error('Cannot install Scheduled Task: ' + result.stderr.trim());
+    }
+}
+export async function prepareScheduler(options) {
+    const platform = options.platform ?? process.platform;
+    const runner = options.runner ?? new NodeProcessRunner();
+    if (platform === 'linux') {
+        const original = await readCron(runner);
+        return {
+            state: { kind: 'cron', marker: CRON_MARKER, minuteOffset: options.minuteOffset, nodePath: options.nodePath, launcherPath: options.launcherPath },
+            snapshot: { kind: 'cron', content: original },
+        };
+    }
+    if (platform === 'win32') {
+        const name = WINDOWS_TASK_PREFIX + options.installationId;
+        const state = {
+            kind: 'windows-task', name, installationId: options.installationId, minuteOffset: options.minuteOffset,
+            nodePath: options.nodePath, launcherPath: options.launcherPath,
+        };
+        const current = await queryWindowsTask(runner, name);
+        if (current.code === 0 && !current.stdout.includes(ownerToken(options.installationId))) {
+            throw new Error('Scheduled Task name collision: ' + name);
+        }
+        return {
+            state,
+            snapshot: { kind: 'windows-task', existed: current.code === 0, xml: current.code === 0 ? current.stdout : undefined },
+        };
+    }
+    throw new Error('Unsupported platform: ' + platform);
+}
+export async function applyScheduler(state, snapshot, runner = new NodeProcessRunner()) {
+    if (state.kind === 'cron' && snapshot.kind === 'cron') {
+        const current = withoutOwnedCron(snapshot.content);
+        const entry = String(state.minuteOffset) + ' * * * * ' + shellQuote(state.nodePath) + ' '
+            + shellQuote(state.launcherPath) + ' scheduled-sync ' + CRON_MARKER;
+        const separator = current && !current.endsWith('\n') ? '\n' : '';
+        await writeCron(runner, current + separator + entry + '\n');
+        return;
+    }
+    if (state.kind === 'windows-task' && snapshot.kind === 'windows-task') {
+        await createWindowsTask(runner, state, snapshot.existed);
+        return;
+    }
+    throw new Error('Scheduler apply kind mismatch');
+}
+export async function installScheduler(options) {
+    const prepared = await prepareScheduler(options);
+    await applyScheduler(prepared.state, prepared.snapshot, options.runner);
+    return prepared;
+}
+export async function restoreScheduler(state, snapshot, runner = new NodeProcessRunner()) {
+    if (state.kind === 'cron' && snapshot.kind === 'cron') {
+        await writeCron(runner, snapshot.content);
+        return;
+    }
+    if (state.kind !== 'windows-task' || snapshot.kind !== 'windows-task') {
+        throw new Error('Scheduler rollback kind mismatch');
+    }
+    if (!snapshot.existed) {
+        const query = await queryWindowsTask(runner, state.name);
+        if (query.code !== 0) {
+            return;
+        }
+        if (!query.stdout.includes(ownerToken(state.installationId))) {
+            throw new Error('Rollback found a non-owned Scheduled Task; refusing to delete ' + state.name);
+        }
+        const result = await runner.run('schtasks.exe', ['/Delete', '/TN', state.name, '/F']);
+        if (result.code !== 0) {
+            throw new Error('Cannot remove rolled-back Scheduled Task: ' + result.stderr.trim());
+        }
+        return;
+    }
+    const temporary = path.join(os.tmpdir(), 'vesper-link-task-' + process.pid + '-' + Date.now() + '.xml');
+    try {
+        await fs.writeFile(temporary, snapshot.xml, 'utf8');
+        const result = await runner.run('schtasks.exe', ['/Create', '/TN', state.name, '/XML', temporary, '/F']);
+        if (result.code !== 0) {
+            throw new Error('Cannot restore Scheduled Task: ' + result.stderr.trim());
+        }
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+export async function schedulerInstalled(state, runner = new NodeProcessRunner()) {
+    if (state.kind === 'cron') {
+        const cron = await readCron(runner);
+        return cron.includes(state.marker) && cron.includes(state.launcherPath);
+    }
+    const current = await queryWindowsTask(runner, state.name);
+    return current.code === 0 && current.stdout.includes(ownerToken(state.installationId))
+        && current.stdout.includes(state.launcherPath);
+}
+export async function uninstallScheduler(state, runner = new NodeProcessRunner()) {
+    if (state.kind === 'cron') {
+        await writeCron(runner, withoutOwnedCron(await readCron(runner)));
+        return;
+    }
+    const current = await queryWindowsTask(runner, state.name);
+    if (current.code !== 0 || !current.stdout.includes(ownerToken(state.installationId))) {
+        throw new Error('Scheduled Task ownership changed; refusing to delete ' + state.name);
+    }
+    const result = await runner.run('schtasks.exe', ['/Delete', '/TN', state.name, '/F']);
+    if (result.code !== 0) {
+        throw new Error('Cannot remove Scheduled Task: ' + result.stderr.trim());
+    }
+}
+export async function assertSchedulerOwned(state, runner = new NodeProcessRunner()) {
+    if (state.kind === 'cron') {
+        const current = await readCron(runner);
+        if (!current.includes(state.marker)) {
+            throw new Error('Owned cron entry is missing; refusing a partial uninstall');
+        }
+        return;
+    }
+    const current = await queryWindowsTask(runner, state.name);
+    if (current.code !== 0 || !current.stdout.includes(ownerToken(state.installationId))) {
+        throw new Error('Scheduled Task ownership changed; refusing to modify ' + state.name);
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+import { type Provider } from './contracts.js';
+export interface SessionCandidate {
+    provider: Provider;
+    format: string;
+    formatVersion: string;
+    providerSessionId: string;
+    transcriptPath: string;
+    projectKey?: string;
+    cwdUri?: string;
+    sourceCreatedAt?: string;
+    sourceUpdatedAt: string;
+    size: number;
+    mtimeMs: number;
+    discovery: 'marker' | 'state' | 'scan';
+    archived?: boolean;
+}
+export interface PendingMarker {
+    schemaVersion: 1;
+    provider: Provider;
+    providerSessionId: string;
+    transcriptPath: string;
+    queuedAt: string;
+}
+export interface SessionState {
+    schemaVersion: 1;
+    provider: Provider;
+    format: string;
+    formatVersion: string;
+    providerSessionId: string;
+    transcriptPath: string;
+    projectKey?: string;
+    cwdUri?: string;
+    sourceCreatedAt?: string;
+    sourceUpdatedAt: string;
+    lastSeenSize: number;
+    lastSeenMtimeMs: number;
+    requiresStability?: boolean;
+    lastUploadedSha256?: string;
+    lastUploadedAt?: string;
+    status: 'pending' | 'uploaded' | 'failed';
+    pendingReason?: string;
+    missingSince?: string;
+    lastError?: {
+        code: string;
+        message: string;
+        at: string;
+    };
+}
+export declare function stableSessionKey(provider: Provider, providerSessionId: string): string;
+export declare function defaultFormat(provider: Provider): string;

package/dist/session.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+import { PROVIDER_FORMATS } from './contracts.js';
+export function stableSessionKey(provider, providerSessionId) {
+    return createHash('sha256')
+        .update(provider)
+        .update('\0')
+        .update(providerSessionId)
+        .digest('hex');
+}
+export function defaultFormat(provider) {
+    return PROVIDER_FORMATS[provider];
+}

package/dist/source.d.ts

@@ -0,0 +1,11 @@
+export interface SourceFingerprint {
+    size: number;
+    mtimeMs: number;
+    sha256: string;
+}
+export declare function fingerprintStableSource(filePath: string): Promise<SourceFingerprint>;
+export declare function assertSourceUnchanged(filePath: string, expected: Pick<SourceFingerprint, 'size' | 'mtimeMs'>): Promise<void>;
+export declare class LocalTaskError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/source.js

@@ -0,0 +1,45 @@
+import * as fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { MAX_FILE_BYTES } from './contracts.js';
+async function hashFile(filePath) {
+    const handle = await fs.open(filePath, 'r');
+    const hash = createHash('sha256');
+    try {
+        for await (const chunk of handle.createReadStream()) {
+            hash.update(chunk);
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function fingerprintStableSource(filePath) {
+    const before = await fs.stat(filePath);
+    if (!before.isFile()) {
+        throw new LocalTaskError('missing_source', 'Source is not a regular file');
+    }
+    if (before.size > MAX_FILE_BYTES) {
+        throw new LocalTaskError('file_too_large', `Source exceeds ${MAX_FILE_BYTES} bytes`);
+    }
+    const sha256 = await hashFile(filePath);
+    const after = await fs.stat(filePath);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+        throw new LocalTaskError('source_changed', 'Source changed while hashing');
+    }
+    return { size: after.size, mtimeMs: after.mtimeMs, sha256 };
+}
+export async function assertSourceUnchanged(filePath, expected) {
+    const stat = await fs.stat(filePath);
+    if (stat.size !== expected.size || stat.mtimeMs !== expected.mtimeMs) {
+        throw new LocalTaskError('source_changed', 'Source changed while uploading');
+    }
+}
+export class LocalTaskError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalTaskError';
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,11 @@
+import { type SessionState } from './session.js';
+export declare function sessionStatePath(sessionsDir: string, state: Pick<SessionState, 'provider' | 'providerSessionId'>): string;
+export declare function readSessionStates(sessionsDir: string): Promise<Map<string, SessionState>>;
+export declare function writeSessionState(sessionsDir: string, state: SessionState): Promise<void>;
+export interface SyncState {
+    schemaVersion: 1;
+    retryAfterUntil?: string;
+}
+export declare function readSyncState(filePath: string): Promise<SyncState>;
+export declare function writeSyncState(filePath: string, state: SyncState): Promise<void>;
+export declare function clearSyncState(filePath: string): Promise<void>;

package/dist/state.js

@@ -0,0 +1,37 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { listJsonFiles, readJsonFile, writeJsonAtomic } from './atomic-json.js';
+import { stableSessionKey } from './session.js';
+export function sessionStatePath(sessionsDir, state) {
+    return path.join(sessionsDir, `${stableSessionKey(state.provider, state.providerSessionId)}.json`);
+}
+export async function readSessionStates(sessionsDir) {
+    const states = new Map();
+    for (const filePath of await listJsonFiles(sessionsDir)) {
+        const state = await readJsonFile(filePath);
+        if (!state || state.schemaVersion !== 1 || !state.provider || !state.providerSessionId) {
+            throw new Error(`Malformed session state: ${filePath}`);
+        }
+        states.set(stableSessionKey(state.provider, state.providerSessionId), state);
+    }
+    return states;
+}
+export async function writeSessionState(sessionsDir, state) {
+    await writeJsonAtomic(sessionStatePath(sessionsDir, state), state);
+}
+export async function readSyncState(filePath) {
+    const state = await readJsonFile(filePath);
+    if (!state) {
+        return { schemaVersion: 1 };
+    }
+    if (state.schemaVersion !== 1 || (state.retryAfterUntil !== undefined && Number.isNaN(Date.parse(state.retryAfterUntil)))) {
+        throw new Error(`Malformed sync state: ${filePath}`);
+    }
+    return state;
+}
+export async function writeSyncState(filePath, state) {
+    await writeJsonAtomic(filePath, state);
+}
+export async function clearSyncState(filePath) {
+    await fs.rm(filePath, { force: true });
+}

package/dist/sync.d.ts

@@ -0,0 +1,18 @@
+import { type CollectorIssue } from './collectors/index.js';
+import { type LinkPaths } from './paths.js';
+import { type RemoteTransport } from './transport.js';
+export interface SyncSummary {
+    discovered: number;
+    queued: number;
+    uploaded: number;
+    unchanged: number;
+    failed: number;
+    collectorIssues: CollectorIssue[];
+    stoppedBy?: string;
+    alreadyRunning?: boolean;
+}
+export declare function runSyncOnce(options?: {
+    paths?: LinkPaths;
+    nowMs?: number;
+    acquireTransport?: (paths: LinkPaths, hostUrl: string) => Promise<RemoteTransport>;
+}): Promise<SyncSummary>;