lark-remote 0.1.0

package/dist/instance-lock.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+export class InstanceAlreadyRunningError extends Error {
+    pid;
+    lockPath;
+    constructor(pid, lockPath) {
+        super(`lark-remote is already running for this config: pid ${pid}`);
+        this.pid = pid;
+        this.lockPath = lockPath;
+    }
+}
+/**
+ * Probe whether a pid is alive. P2-20:
+ *  - process.kill(pid, 0) returning normally → alive.
+ *  - ESRCH (no such process) → dead.
+ *  - EPERM (operation not permitted) → the process EXISTS but is owned by
+ *    another user; we just lack permission to signal it. Returning true here
+ *    is correct: the single instance that owns the lock is still running, so
+ *    we must refuse to acquire. Previously EPERM was swallowed as "not
+ *    running", allowing a second instance to overwrite the lock.
+ *  - EINVAL / other → conservative true (do not clobber a lock we cannot
+ *    prove is stale).
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return false;
+        // EPERM and any unexpected error → assume alive (never clobber a lock
+        // we cannot disprove is held by a running instance).
+        return true;
+    }
+}
+export class InstanceLock {
+    lockPath;
+    /**
+     * P2-20: injectable process-running probe for testing, and a process-name
+     * verifier to defend against PID reuse (a stale pid recycled by an unrelated
+     * process would otherwise be misjudged as "our instance still running").
+     * Default implementation checks the process name via `ps` when available.
+     */
+    isProcessRunning;
+    constructor(lockPath, opts) {
+        this.lockPath = lockPath;
+        this.isProcessRunning =
+            opts?.isProcessRunning ?? ((pid, expectedComm) => defaultIsProcessRunning(pid, expectedComm));
+    }
+    acquire() {
+        fs.mkdirSync(path.dirname(this.lockPath), { recursive: true });
+        // Atomic create-with-exclusive: 'wx' fails if file already exists.
+        // This eliminates the TOCTOU race between readPid+isProcessRunning
+        // and writeFileSync in the previous implementation.
+        try {
+            const fd = fs.openSync(this.lockPath, 'wx');
+            fs.writeSync(fd, this.lockContents(process.pid));
+            fs.closeSync(fd);
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                // Lock file exists — check if the owner is still alive
+                const { pid, comm } = this.readPidAndComm();
+                if (pid && this.isProcessRunning(pid, comm)) {
+                    throw new InstanceAlreadyRunningError(pid, this.lockPath);
+                }
+                // Stale lock: remove and retry once
+                try {
+                    fs.unlinkSync(this.lockPath);
+                }
+                catch { }
+                try {
+                    const fd = fs.openSync(this.lockPath, 'wx');
+                    fs.writeSync(fd, this.lockContents(process.pid));
+                    fs.closeSync(fd);
+                }
+                catch (retryErr) {
+                    if (retryErr.code === 'EEXIST') {
+                        // Another process created the lock between unlink and retry.
+                        // Bounded retry (max 1): give up rather than recurse.
+                        const { pid, comm } = this.readPidAndComm();
+                        if (pid && this.isProcessRunning(pid, comm)) {
+                            throw new InstanceAlreadyRunningError(pid, this.lockPath);
+                        }
+                        // New lock is also stale — give up rather than recurse.
+                        throw new InstanceAlreadyRunningError(pid ?? -1, this.lockPath);
+                    }
+                    throw retryErr;
+                }
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    release() {
+        const { pid } = this.readPidAndComm();
+        if (pid === process.pid) {
+            try {
+                fs.unlinkSync(this.lockPath);
+            }
+            catch { }
+        }
+    }
+    registerExitHandlers() {
+        process.on('exit', () => this.release());
+        process.on('SIGINT', () => {
+            this.release();
+            process.exit(130);
+        });
+        process.on('SIGTERM', () => {
+            this.release();
+            process.exit(143);
+        });
+        if (process.platform !== 'win32') {
+            process.on('SIGHUP', () => {
+                this.release();
+                process.exit(129);
+            });
+        }
+    }
+    /**
+     * Lock file stores `pid\ncomm` where comm is the owning process's command
+     * name (captured at acquire time). On stale-lock checks we verify the
+     * recorded pid is still alive AND still running a process whose comm
+     * matches — defending against PID reuse where an unrelated process recycled
+     * the stale pid.
+     */
+    lockContents(pid) {
+        return `${pid}\n${currentComm()}`;
+    }
+    readPidAndComm() {
+        if (!fs.existsSync(this.lockPath))
+            return { pid: undefined, comm: undefined };
+        const raw = fs.readFileSync(this.lockPath, 'utf-8').trim();
+        const [pidStr, ...commParts] = raw.split('\n');
+        const pid = Number(pidStr);
+        const comm = commParts.join('\n') || undefined;
+        if (Number.isInteger(pid) && pid > 0 && comm)
+            return { pid, comm };
+        // Malformed or missing comm — treat as corrupt, unlink and return undefined
+        try {
+            fs.unlinkSync(this.lockPath);
+        }
+        catch { }
+        return { pid: undefined, comm: undefined };
+    }
+}
+/**
+ * Default probe: alive by ESRCH/EPERM semantics, plus a weak comm-name match
+ * to reject PID reuse. If `ps` is unavailable we fall back to the pid-alive
+ * check alone (no false negatives, only weaker reuse protection).
+ */
+function defaultIsProcessRunning(pid, expectedComm) {
+    if (!isPidAlive(pid))
+        return false;
+    if (!expectedComm)
+        return false;
+    const actualComm = readComm(pid);
+    if (actualComm === null)
+        return true; // ps unavailable → trust pid-alive
+    // Match on the basename so `/usr/local/bin/node` vs `node` still align.
+    const base = (s) => s.split('/').pop() ?? s;
+    return base(actualComm) === base(expectedComm) || actualComm.includes(expectedComm);
+}
+function currentComm() {
+    return readComm(process.pid) ?? 'lark-remote';
+}
+function readComm(pid) {
+    try {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/logger/index.d.ts

@@ -0,0 +1,57 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+    /** Log directory. Defaults to ~/.lark-remote/logs */
+    dir?: string;
+    /** Minimum level to write. Defaults to 'info'. */
+    level?: LogLevel;
+    /** File prefix. Defaults to 'lark-remote'. */
+    prefix?: string;
+    /** Override pid (for testing). */
+    pid?: number;
+    /** Override now() (for testing). */
+    now?: () => Date;
+}
+/**
+ * File-based logger with daily rotation.
+ *
+ * - Each day gets its own subdirectory: `<dir>/YYYY-MM-DD/`.
+ * - Log files are named `<prefix>-<pid>.log` inside the daily subdirectory.
+ * - When the calendar date changes (across midnight), a new directory and file
+ *   are created automatically, so each file never spans two days.
+ * - Nothing is written to stdout/stderr; all output goes to the file.
+ * - Writes are synchronous (fs.appendFileSync) — log volume is low and this
+ *   guarantees ordering without leaving dangling file handles on exit.
+ */
+export declare class Logger {
+    private dir;
+    private level;
+    private prefix;
+    private pid;
+    private now;
+    private currentDate;
+    private currentFile;
+    constructor(opts?: LoggerOptions);
+    /** Get the current log file path (e.g., ~/.lark-remote/logs/2026-07-11/lark-remote-12345.log). */
+    getCurrentLogFile(): string;
+    private ensureFile;
+    /**
+     * P2-19①: remove daily subdirectories older than the retention window.
+     * Best-effort — any error is swallowed (logging must never throw).
+     */
+    private pruneOldDirs;
+    private write;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    /** Reset internal file state so the next write rotates to a fresh daily file. */
+    close(): void;
+}
+/**
+ * Initialize (or reinitialize) the global logger. Must be called once at
+ * startup, before any logging is expected to land in the right place.
+ * Returns the initialized logger.
+ */
+export declare function initLogger(opts: LoggerOptions): Logger;
+export declare function getLogger(): Logger;
+export {};

package/dist/logger/index.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { format } from 'node:util';
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const LEVEL_UPPER = {
+    debug: 'DEBUG',
+    info: 'INFO',
+    warn: 'WARN',
+    error: 'ERROR',
+};
+function todayStr(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+function timestampStr(d) {
+    // P2-19②: local ISO 8601 with milliseconds and explicit offset, e.g.
+    // 2026-08-03T01:30:00.000+08:00. Previously this used toISOString() (UTC)
+    // while the daily directory boundary (todayStr) used local time — after
+    // local midnight in a +08:00 zone the new day's directory held lines
+    // timestamped with the previous UTC day. Local offset keeps the timestamp's
+    // calendar date consistent with the directory date across all timezones.
+    const pad = (n) => String(n).padStart(2, '0');
+    const y = d.getFullYear();
+    const mo = pad(d.getMonth() + 1);
+    const da = pad(d.getDate());
+    const h = pad(d.getHours());
+    const mi = pad(d.getMinutes());
+    const s = pad(d.getSeconds());
+    const ms = String(d.getMilliseconds()).padStart(3, '0');
+    const offsetMin = -d.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? '+' : '-';
+    const absOff = Math.abs(offsetMin);
+    const offH = pad(Math.floor(absOff / 60));
+    const offM = pad(absOff % 60);
+    return `${y}-${mo}-${da}T${h}:${mi}:${s}.${ms}${sign}${offH}:${offM}`;
+}
+/**
+ * File-based logger with daily rotation.
+ *
+ * - Each day gets its own subdirectory: `<dir>/YYYY-MM-DD/`.
+ * - Log files are named `<prefix>-<pid>.log` inside the daily subdirectory.
+ * - When the calendar date changes (across midnight), a new directory and file
+ *   are created automatically, so each file never spans two days.
+ * - Nothing is written to stdout/stderr; all output goes to the file.
+ * - Writes are synchronous (fs.appendFileSync) — log volume is low and this
+ *   guarantees ordering without leaving dangling file handles on exit.
+ */
+export class Logger {
+    dir;
+    level;
+    prefix;
+    pid;
+    now;
+    currentDate = '';
+    currentFile = '';
+    constructor(opts = {}) {
+        this.dir = opts.dir ?? path.join(os.homedir(), '.lark-remote', 'logs');
+        this.level = LEVEL_ORDER[opts.level ?? 'info'];
+        this.prefix = opts.prefix ?? 'lark-remote';
+        this.pid = opts.pid ?? process.pid;
+        this.now = opts.now ?? (() => new Date());
+    }
+    /** Get the current log file path (e.g., ~/.lark-remote/logs/2026-07-11/lark-remote-12345.log). */
+    getCurrentLogFile() {
+        // Ensure the file is up-to-date before returning
+        this.ensureFile(this.now());
+        return this.currentFile;
+    }
+    ensureFile(date) {
+        const dateStr = todayStr(date);
+        if (this.currentFile && this.currentDate === dateStr)
+            return this.currentFile;
+        // Date changed (or first call): rotate to a new daily subdirectory
+        const dayDir = path.join(this.dir, dateStr);
+        fs.mkdirSync(dayDir, { recursive: true });
+        this.currentFile = path.join(dayDir, `${this.prefix}-${this.pid}.log`);
+        this.currentDate = dateStr;
+        // P2-19①: prune daily log directories older than the retention window so
+        // the logs directory does not grow without bound (single-day size cap is
+        // out of scope; bounded retention by day is the requested guard). Wrapped
+        // defensively so cleanup failure never blocks logging.
+        this.pruneOldDirs(dateStr);
+        return this.currentFile;
+    }
+    /**
+     * P2-19①: remove daily subdirectories older than the retention window.
+     * Best-effort — any error is swallowed (logging must never throw).
+     */
+    pruneOldDirs(currentDateStr) {
+        const RETENTION_DAYS = 30;
+        try {
+            const entries = fs.readdirSync(this.dir, { withFileTypes: true });
+            const cutoff = new Date(`${currentDateStr}T00:00:00`).getTime() - RETENTION_DAYS * 86400000;
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                // Only prune directories that look like YYYY-MM-DD daily dirs.
+                if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.name))
+                    continue;
+                const t = new Date(`${entry.name}T00:00:00`).getTime();
+                if (Number.isNaN(t))
+                    continue;
+                if (t < cutoff) {
+                    fs.rmSync(path.join(this.dir, entry.name), { recursive: true, force: true });
+                }
+            }
+        }
+        catch {
+            /* best-effort cleanup; never throw */
+        }
+    }
+    write(level, args) {
+        if (LEVEL_ORDER[level] < this.level)
+            return;
+        const date = this.now();
+        const ts = timestampStr(date);
+        const message = format(...args);
+        const line = `${ts} [${LEVEL_UPPER[level]}] ${message}\n`;
+        const file = this.ensureFile(date);
+        // P2-19③: never let a disk error (EACCES / ENOSPC / EROFS) escape write().
+        // If logging itself throws — especially inside an uncaughtException handler
+        // that calls logger.error(...) — a re-throw would abort Node and skip
+        // instanceLock.release(), leaking the singleton lock. Logging must never
+        // kill the process. Fall back to a single stderr line for diagnosis.
+        try {
+            fs.appendFileSync(file, line);
+        }
+        catch {
+            try {
+                process.stderr.write(`[logger] failed to write log: ${message}\n`);
+            }
+            catch {
+                /* nothing left to do; never throw */
+            }
+        }
+    }
+    debug(...args) {
+        this.write('debug', args);
+    }
+    info(...args) {
+        this.write('info', args);
+    }
+    warn(...args) {
+        this.write('warn', args);
+    }
+    error(...args) {
+        this.write('error', args);
+    }
+    /** Reset internal file state so the next write rotates to a fresh daily file. */
+    close() {
+        this.currentFile = '';
+        this.currentDate = '';
+    }
+}
+// --- Singleton ---
+let defaultLogger = new Logger();
+/**
+ * Initialize (or reinitialize) the global logger. Must be called once at
+ * startup, before any logging is expected to land in the right place.
+ * Returns the initialized logger.
+ */
+export function initLogger(opts) {
+    defaultLogger.close();
+    defaultLogger = new Logger(opts);
+    return defaultLogger;
+}
+export function getLogger() {
+    return defaultLogger;
+}
+//# sourceMappingURL=index.js.map

package/dist/order/index.d.ts

@@ -0,0 +1,27 @@
+interface OrderEntry {
+    id: string;
+    text: string;
+    createdAt: string;
+    usedAt?: string;
+}
+/**
+ * Global persistent order store.
+ *
+ * Atomic write (tmp + rename) and corrupt-file recovery,
+ * following the same pattern as WorkspaceStore.
+ */
+export declare class OrderStore {
+    private filePath;
+    private data;
+    constructor(filePath?: string);
+    /** Reload data from disk (useful when another process may have written) */
+    reload(): void;
+    private load;
+    private persist;
+    save(text: string): OrderEntry;
+    updateUsedAt(id: string): void;
+    get(): OrderEntry[];
+    has(id: string): boolean;
+    remove(id: string): void;
+}
+export {};

package/dist/order/index.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import os from 'node:os';
+import { atomicWriteJson } from '../persistence/atomic-write.js';
+import { loadJsonFile } from '../persistence/load-json-file.js';
+const MAX_TEXT_LENGTH = 200;
+const MAX_ORDERS = 50;
+/**
+ * Global persistent order store.
+ *
+ * Atomic write (tmp + rename) and corrupt-file recovery,
+ * following the same pattern as WorkspaceStore.
+ */
+export class OrderStore {
+    filePath;
+    data;
+    constructor(filePath) {
+        this.filePath = filePath ?? path.join(os.homedir(), '.lark-remote', 'orders.json');
+        this.data = [];
+        this.load();
+    }
+    /** Reload data from disk (useful when another process may have written) */
+    reload() {
+        this.load();
+    }
+    load() {
+        const parsed = loadJsonFile(this.filePath, undefined);
+        if (!parsed) {
+            this.data = [];
+            return;
+        }
+        if (!Array.isArray(parsed)) {
+            this.data = [];
+            return;
+        }
+        const valid = [];
+        for (const e of parsed) {
+            if (e &&
+                typeof e.id === 'string' &&
+                typeof e.text === 'string' &&
+                typeof e.createdAt === 'string') {
+                const entry = {
+                    id: e.id,
+                    text: e.text.slice(0, MAX_TEXT_LENGTH),
+                    createdAt: e.createdAt,
+                };
+                if (typeof e.usedAt === 'string')
+                    entry.usedAt = e.usedAt;
+                valid.push(entry);
+            }
+        }
+        this.data = valid;
+    }
+    persist() {
+        atomicWriteJson(this.filePath, this.data);
+    }
+    save(text) {
+        if (text.length > MAX_TEXT_LENGTH) {
+            throw new Error(`指令文本超过 ${MAX_TEXT_LENGTH} 字符限制`);
+        }
+        if (this.data.length >= MAX_ORDERS) {
+            throw new Error(`指令数量已达上限 ${MAX_ORDERS}`);
+        }
+        const entry = {
+            id: crypto.randomUUID(),
+            text,
+            createdAt: new Date().toISOString(),
+        };
+        this.data.push(entry);
+        this.persist();
+        return entry;
+    }
+    updateUsedAt(id) {
+        const entry = this.data.find((e) => e.id === id);
+        if (entry) {
+            entry.usedAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    get() {
+        return [...this.data];
+    }
+    has(id) {
+        return this.data.some((e) => e.id === id);
+    }
+    remove(id) {
+        this.data = this.data.filter((e) => e.id !== id);
+        this.persist();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/persistence/atomic-write.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Atomically write string content to a file via tmp + rename.
+ * Falls back to copy+unlink when rename fails with EXDEV (cross-device).
+ */
+export declare function atomicWrite(filePath: string, content: string, encoding?: BufferEncoding): void;
+/**
+ * Atomically write JSON data to a file via tmp + rename.
+ * Ensures a crash mid-write cannot leave a truncated file.
+ */
+export declare function atomicWriteJson(filePath: string, data: unknown): void;

package/dist/persistence/atomic-write.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Atomically write string content to a file via tmp + rename.
+ * Falls back to copy+unlink when rename fails with EXDEV (cross-device).
+ */
+export function atomicWrite(filePath, content, encoding = 'utf-8') {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = filePath + '.tmp';
+    fs.writeFileSync(tmpPath, content, encoding);
+    // fsync the tmp file before rename so its data is durable on disk;
+    // rename itself is only a metadata change, so without fsync a crash after
+    // rename could leave the target as a 0-byte file. Best-effort: some
+    // filesystems (tmpfs) may not support fsync — ignore those errors.
+    let fd;
+    try {
+        fd = fs.openSync(tmpPath, 'r');
+        fs.fsyncSync(fd);
+    }
+    catch {
+        /* fsync unavailable on this fs — best-effort durability */
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore close failure */
+            }
+        }
+    }
+    try {
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        if (err.code === 'EXDEV') {
+            // Cross-device rename: copy then unlink (tmp cleanup handled by finally)
+            fs.copyFileSync(tmpPath, filePath);
+        }
+        else {
+            throw err;
+        }
+    }
+    finally {
+        // Best-effort cleanup: on success the tmp was renamed away (ENOENT here,
+        // silently ignored); on EXDEV it was copied and now needs removal; on other
+        // errors we must not leak the tmp file.
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* already moved or never created */
+        }
+    }
+}
+/**
+ * Atomically write JSON data to a file via tmp + rename.
+ * Ensures a crash mid-write cannot leave a truncated file.
+ */
+export function atomicWriteJson(filePath, data) {
+    atomicWrite(filePath, JSON.stringify(data, null, 2));
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/persistence/load-json-file.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Load and parse a JSON file with fallback on corruption.
+ * Returns the parsed data or the fallback value if loading fails.
+ *
+ * @param filePath - Path to the JSON file
+ * @param fallback - Value to return if file doesn't exist or is corrupted
+ * @param parseFn - Optional custom parser (defaults to JSON.parse)
+ */
+export declare function loadJsonFile<T>(filePath: string, fallback: T, parseFn?: (raw: string) => T): T;

package/dist/persistence/load-json-file.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import { getLogger } from '../logger/index.js';
+/**
+ * Load and parse a JSON file with fallback on corruption.
+ * Returns the parsed data or the fallback value if loading fails.
+ *
+ * @param filePath - Path to the JSON file
+ * @param fallback - Value to return if file doesn't exist or is corrupted
+ * @param parseFn - Optional custom parser (defaults to JSON.parse)
+ */
+export function loadJsonFile(filePath, fallback, parseFn = JSON.parse) {
+    try {
+        if (!fs.existsSync(filePath))
+            return fallback;
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        return parseFn(raw);
+    }
+    catch (err) {
+        getLogger().warn(`[persistence] failed to load ${filePath}, using fallback:`, err);
+        return fallback;
+    }
+}
+//# sourceMappingURL=load-json-file.js.map

package/dist/restart.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Self-restart without an external watchdog/cron: the only process that can
+ * reliably start the successor is the dying bridge itself. The old process
+ * spawns a detached replacement (same executable + argv, hence same
+ * --config-dir), then exits cleanly. The child learns the old pid via env
+ * and waits for it to die before acquiring the instance lock, so the lock
+ * file stays the single source of truth for the handoff.
+ */
+/** Env var telling a replacement child which parent pid to wait for before acquiring the instance lock. */
+export declare const RESTART_WAIT_PID_ENV = "LARK_REMOTE_RESTART_WAIT_PID";
+/**
+ * Spawn a detached replacement bridge with the same executable and argv
+ * (including --config-dir) and return its pid. The caller is expected to
+ * exit right after. stdio is redirected to restart-child.log so early
+ * startup failures (before the file logger initializes) are not lost.
+ */
+export declare function spawnReplacementBridge(logsDir: string): number;
+/**
+ * On startup, if this process was spawned as a restart replacement, wait for
+ * the previous bridge process to exit (and release the instance lock) before
+ * continuing. No-op for normal starts. On timeout, proceed anyway — lock
+ * acquisition remains the authority.
+ */
+export declare function waitForPreviousInstance(): Promise<void>;