@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/core/repl/store/index.js

@@ -1,12 +0,0 @@
-/**
- * Public re-exports for the SessionStore module — Sprint .
- *
- * Consumers (`repl/session.ts`, `runtime/cli.ts`, the `/resume`
- * dispatcher) import from `./store/index.js` so the internal split
- * (types / lockfile / jsonl-log / session-store / uuid-v7) can change
- * without touching the call sites.
- */
-export { SessionLockBusyError, } from './types.js';
-export { SqliteSessionStore, SqliteSessionStoreReadOnlyView, FtsSyntaxError, resolveProjectStoreDir, } from './session-store.js';
-export { uuidV7, uuidV7Timestamp } from './uuid-v7.js';
-//# sourceMappingURL=index.js.map

package/dist/core/repl/store/jsonl-log.js

@@ -1,321 +0,0 @@
-/**
- * Append-only JSONL event log — Sprint .
- *
- * Durable truth for the session. The SQLite index is rebuildable from
- * the JSONL; if the index is lost or corrupt, `pugi sessions --rebuild`
- * walks every line and reconstructs the table. The JSONL is therefore
- * the source of truth and the SQLite is the cache.
- *
- * File layout per session directory:
- *
- *  <sessionDir>/events.0.jsonl      active rotation file
- *  <sessionDir>/events.1.jsonl      previous rotation, oldest event first
- *  <sessionDir>/events.2.jsonl      older still
- *  ...
- *
- * Rotation threshold is 50 MB per spec §4.2 must-ship #2. When the
- * active file exceeds the threshold AFTER a write, we close it, rename
- * it to the next numbered slot, and resume appending to a fresh
- * `events.0.jsonl`. The reader stitches across files in REVERSE numeric
- * order so the on-disk order is preserved.
- *
- * Crash safety:
- *
- *  - Each write is a single `appendFileSync` of `JSON.stringify(event)\n`.
- *    On Linux/macOS, append-mode writes of bytes < PIPE_BUF (4096) are
- *    atomic with respect to other appends. Our events are well under
- *    4 KB so the OS guarantees per-line atomicity even if two
- *    processes hold append fds (the lockfile already prevents that,
- *    but defence-in-depth).
- *  - After each write we call `fsync(fd)` so the bytes are durable
- *    against power loss / kernel panic. Slow but correct — the
- *    conversation-flow path is throughput-bound by the LLM, not by
- *    the disk, so a few hundred extra microseconds per event is
- *    invisible to the operator.
- *  - On reopen we walk every line and drop any that fail JSON parse.
- *    A crash mid-write leaves a truncated tail; we treat it as
- *    "event was never written" and continue from there. The next
- *    write may overlap with the truncated bytes; that is acceptable
- *    because the truncated line is invalid JSON either way and the
- *    reader is already designed to skip it.
- */
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeSync, } from 'node:fs';
-import { resolve } from 'node:path';
-/**
- * Rotate the active JSONL file when its size exceeds this threshold.
- * Picked per spec §4.2. Operators can override via the
- * `PUGI_SESSION_LOG_ROTATE_BYTES` env so heavy-traffic dogfooding can
- * keep more events in the active file before rotation.
- */
-const DEFAULT_ROTATE_BYTES = 50 * 1024 * 1024;
-/**
- * Active JSONL filename. The store opens fd against this path; the
- * reader stitches across `events.<n>.jsonl` for n > 0.
- */
-const ACTIVE_FILE = 'events.0.jsonl';
-/**
- * Append-only writer + reader for one session's JSONL log. The writer
- * keeps a fd open for the lifetime of the session so each append
- * avoids a fresh syscall pair; the fd is reopened transparently on
- * rotation. `close()` releases the fd and is idempotent.
- */
-export class JsonlEventLog {
-    sessionDir;
-    rotateBytes;
-    activeFd = null;
-    activeBytes = 0;
-    constructor(opts) {
-        this.sessionDir = opts.sessionDir;
-        this.rotateBytes =
-            opts.rotateBytes
-                ?? readEnvInt('PUGI_SESSION_LOG_ROTATE_BYTES')
-                ?? DEFAULT_ROTATE_BYTES;
-        mkdirSync(this.sessionDir, { recursive: true, mode: 0o700 });
-    }
-    /**
-     * Append one event. Returns the on-disk byte length written so the
-     * caller can budget without re-stat()-ing the file. The write is
-     * fsynced before this call returns.
-     *
-     * Rotation runs AFTER the event is durable. A rotation failure does
-     * NOT roll back the write — the event is already on disk. The error
-     * is surfaced to the caller so the operator knows the rotation
-     * threshold was tripped but the underlying filesystem refused the
-     * rename (EPERM / EXDEV / ENOSPC during rename). The next append
-     * will attempt rotation again from a fresh ensureFd().
-     */
-    append(event) {
-        const line = `${JSON.stringify(event)}\n`;
-        const fd = this.ensureFd();
-        const bytes = Buffer.byteLength(line, 'utf8');
-        writeSync(fd, line, null, 'utf8');
-        fsyncSync(fd);
-        this.activeBytes += bytes;
-        if (this.activeBytes >= this.rotateBytes) {
-            this.rotate();
-        }
-        return bytes;
-    }
-    /**
-     * Load events in insertion order. Stitches across rotation files in
-     * REVERSE numeric order (events.N.jsonl ... events.0.jsonl) so the
-     * returned stream is oldest-first.
-     *
-     * `fromOffset` skips the first N events from the stitched stream;
-     * `limit` caps the returned count. Defaults: return all events.
-     */
-    read(opts) {
-        const files = this.discoverRotationFiles();
-        // Reverse numeric order so events.N.jsonl (oldest) is read first.
-        const ordered = files.slice().sort((a, b) => b.index - a.index);
-        const fromOffset = Math.max(0, opts?.fromOffset ?? 0);
-        const limit = clampLimit(opts?.limit ?? Number.MAX_SAFE_INTEGER);
-        const out = [];
-        let skipped = 0;
-        for (const file of ordered) {
-            const raw = safeReadText(file.path);
-            if (raw.length === 0)
-                continue;
-            for (const line of raw.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed.length === 0)
-                    continue;
-                const parsed = safeParseEvent(trimmed);
-                if (!parsed)
-                    continue;
-                if (skipped < fromOffset) {
-                    skipped += 1;
-                    continue;
-                }
-                out.push(parsed);
-                if (out.length >= limit)
-                    return out;
-            }
-        }
-        return out;
-    }
-    /**
-     * Count the total events on disk (across all rotation files). Used
-     * by the SessionStore to reconcile `event_count` on the SQLite row
-     * after a crash recovery walk.
-     */
-    countEvents() {
-        const files = this.discoverRotationFiles();
-        let total = 0;
-        for (const file of files) {
-            const raw = safeReadText(file.path);
-            if (raw.length === 0)
-                continue;
-            for (const line of raw.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed.length === 0)
-                    continue;
-                if (safeParseEvent(trimmed))
-                    total += 1;
-            }
-        }
-        return total;
-    }
-    /** Release the file descriptor. Idempotent. */
-    close() {
-        if (this.activeFd !== null) {
-            try {
-                fsyncSync(this.activeFd);
-            }
-            catch {
-                /* ignore — fd may have been closed elsewhere */
-            }
-            try {
-                closeSync(this.activeFd);
-            }
-            catch {
-                /* ignore */
-            }
-            this.activeFd = null;
-        }
-    }
-    ensureFd() {
-        if (this.activeFd !== null)
-            return this.activeFd;
-        const path = resolve(this.sessionDir, ACTIVE_FILE);
-        // Read the existing size BEFORE opening with 'a' — `openSync(path,
-        // 'a', ...)` creates the file when missing, which makes a post-open
-        // `existsSync` always true. If a previous rotate() failed midway
-        // and left stale bytes at this path, we want `activeBytes` to
-        // inherit the real pre-open size so the next append accounting is
-        // consistent. Without this ordering the rotate-threshold check
-        // tripped on a fresh 0-byte file holding pre-rotation bytes,
-        // causing an immediate re-rotation loop.
-        let preOpenBytes = 0;
-        try {
-            preOpenBytes = existsSync(path) ? statSync(path).size : 0;
-        }
-        catch {
-            preOpenBytes = 0;
-        }
-        // O_APPEND so concurrent appends from a future feature (e.g. an
-        // out-of-band tool process) cannot overwrite each other. The
-        // lockfile already serializes us; this is defence-in-depth.
-        this.activeFd = openSync(path, 'a', 0o600);
-        this.activeBytes = preOpenBytes;
-        return this.activeFd;
-    }
-    /**
-     * Close the active file, shift every existing rotation file's number
-     * up by one (events.N -> events.N+1), and reopen a fresh
-     * events.0.jsonl. Synchronous and rare (50 MB / few-KB events =
-     * thousands of events between rotations).
-     *
-     * A rename failure is NOT swallowed — we rethrow so the caller knows
-     * the active file is over the threshold but the data inside it is
-     * still durable (we already fsynced before invoking rotate). Without
-     * the rethrow, ensureFd() inherited the pre-rotation size on the
-     * next append and tripped an infinite re-rotation loop.
-     */
-    rotate() {
-        this.close();
-        const files = this.discoverRotationFiles();
-        // Rename in REVERSE order so we never clobber an existing slot.
-        const ordered = files.slice().sort((a, b) => b.index - a.index);
-        const renameErrors = [];
-        for (const file of ordered) {
-            const next = resolve(this.sessionDir, `events.${file.index + 1}.jsonl`);
-            try {
-                renameSync(file.path, next);
-            }
-            catch (err) {
-                // Collect every failed rename so the caller sees the full
-                // picture instead of just the first failure. We still
-                // continue the loop: any rename that succeeds shifts at
-                // least some history out of the way.
-                renameErrors.push(err instanceof Error ? err : new Error(String(err)));
-            }
-        }
-        this.activeBytes = 0;
-        if (renameErrors.length > 0) {
-            const msg = renameErrors.map((e) => e.message).join('; ');
-            const wrapped = new Error(`JSONL rotation failed in ${this.sessionDir}: ${msg}. ` +
-                'The data already on disk is safe; the active log may exceed ' +
-                'the configured threshold until the underlying issue is fixed.');
-            // Preserve the original errors on .cause for upstream
-            // observability. Node 16.9+ supports the standard cause field.
-            wrapped.cause = renameErrors;
-            throw wrapped;
-        }
-        // Lazily reopen on next append.
-    }
-    /**
-     * Walk the session directory and return every `events.<n>.jsonl`
-     * file with its numeric index. Sort order is left to the caller.
-     */
-    discoverRotationFiles() {
-        if (!existsSync(this.sessionDir))
-            return [];
-        let entries;
-        try {
-            entries = readdirSync(this.sessionDir);
-        }
-        catch {
-            return [];
-        }
-        const out = [];
-        for (const name of entries) {
-            const match = /^events\.(\d+)\.jsonl$/.exec(name);
-            if (!match)
-                continue;
-            const index = Number.parseInt(match[1] ?? '', 10);
-            if (!Number.isFinite(index))
-                continue;
-            out.push({ index, path: resolve(this.sessionDir, name) });
-        }
-        return out;
-    }
-}
-function safeReadText(path) {
-    try {
-        return readFileSync(path, 'utf8');
-    }
-    catch {
-        return '';
-    }
-}
-function safeParseEvent(line) {
-    try {
-        const parsed = JSON.parse(line);
-        if (typeof parsed === 'object'
-            && parsed !== null
-            && typeof parsed.t === 'number'
-            && typeof parsed.kind === 'string') {
-            // `payload` may be undefined on the wire (older clients); coerce
-            // to null so the consumer never has to type-narrow `unknown |
-            // undefined`.
-            const payload = parsed.payload ?? null;
-            return {
-                t: parsed.t,
-                kind: parsed.kind,
-                payload,
-            };
-        }
-    }
-    catch {
-        /* fall through — truncated tail, JSON parse error */
-    }
-    return null;
-}
-function clampLimit(raw) {
-    if (!Number.isFinite(raw) || raw <= 0)
-        return 1;
-    if (raw > 100000)
-        return 100000;
-    return Math.floor(raw);
-}
-function readEnvInt(key) {
-    const raw = process.env[key];
-    if (!raw)
-        return undefined;
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n <= 0)
-        return undefined;
-    return n;
-}
-//# sourceMappingURL=jsonl-log.js.map

package/dist/core/repl/store/lockfile.js

@@ -1,155 +0,0 @@
-/**
- * PID lockfile — Sprint .
- *
- * Prevents two REPL processes in the same project directory from
- * writing to the same `session.db` concurrently. SQLite's WAL handles
- * that case correctly at the page level, but the JSONL event log lives
- * outside the SQL transaction — concurrent appends from two processes
- * would interleave events. The lockfile is the higher-level mutex.
- *
- * Algorithm:
- *
- *  1. Try `O_CREAT | O_EXCL` open of `<dir>/session.lock`. Write the
- *     caller's PID + process start time as the body. If the open
- *     succeeds, we hold the lock; return.
- *  2. If `EEXIST`, read the existing PID. Probe with `kill(pid, 0)`
- *     (signal 0 = "check liveness, do not deliver"). If the probe
- *     returns ESRCH, the holder is dead — unlink the stale lock and
- *     retry the exclusive create.
- *  3. If the probe says the PID is alive, throw `SessionLockBusyError`
- *     so the caller surfaces a clean message to the operator.
- *
- * Why not `proper-lockfile`: pulling a 14kB dependency for a 60-line
- * PID file is poor cost/benefit. The stale-detection loop is the only
- * tricky part and we test it explicitly. The dependency would also
- * pull `signal-exit` + `retry` transitively, raising the install
- * footprint of the CLI bundle.
- *
- * Brand voice / privacy: the lockfile body is `{"pid":N,"createdAt":"…"}`
- * — operator-readable if they `cat` the file, no secrets. Mode 0600 so
- * other users on the box cannot read which PID is editing the store.
- */
-import { closeSync, openSync, readFileSync, unlinkSync, writeSync, } from 'node:fs';
-import { SessionLockBusyError } from './types.js';
-/**
- * Take an exclusive lock on `lockPath`. Throws `SessionLockBusyError`
- * if a live process already holds the lock. `kill` is injectable for
- * tests so the stale-detection branch is exercisable without spawning
- * a real child process.
- */
-export function takeLock(lockPath, options) {
-    const kill = options?.kill ?? ((pid, signal) => process.kill(pid, signal));
-    const now = options?.now ?? (() => new Date());
-    const body = { pid: process.pid, createdAt: now().toISOString() };
-    const serialized = JSON.stringify(body);
-    // First attempt: exclusive create. Retry once if the existing lock
-    // turns out to be stale (dead PID).
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            const fd = openSync(lockPath, 'wx', 0o600);
-            try {
-                writeSync(fd, serialized);
-            }
-            finally {
-                closeSync(fd);
-            }
-            return { path: lockPath, release: () => releaseLock(lockPath, process.pid) };
-        }
-        catch (error) {
-            // EEXIST is the only branch that triggers stale-detection. Any
-            // other error (EACCES, ENOENT on parent, ENOSPC) propagates so
-            // the caller sees the real failure.
-            if (!isEexist(error)) {
-                throw error;
-            }
-            const holder = readLockBody(lockPath);
-            if (!holder) {
-                // Corrupt body — treat as stale and unlink.
-                tryUnlink(lockPath);
-                continue;
-            }
-            if (holder.pid === process.pid) {
-                // We already hold the lock (reentrant open from same process).
-                // Return a handle that is a no-op on release; the original
-                // owner's release will unlink.
-                return { path: lockPath, release: () => undefined };
-            }
-            if (isAlive(holder.pid, kill)) {
-                throw new SessionLockBusyError(holder.pid, lockPath);
-            }
-            // Stale lock — unlink and retry the exclusive create.
-            tryUnlink(lockPath);
-        }
-    }
-    // Two retries failed — the lock is contested by another process
-    // racing us. Surface as busy rather than spinning.
-    const holder = readLockBody(lockPath);
-    throw new SessionLockBusyError(holder?.pid ?? 0, lockPath);
-}
-/**
- * Read a lockfile body. Returns null when the file is missing,
- * unreadable, or malformed. The store never throws from this path —
- * the caller treats null as "stale, unlink and retry".
- */
-export function readLockBody(lockPath) {
-    let raw;
-    try {
-        raw = readFileSync(lockPath, 'utf8');
-    }
-    catch {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed === 'object'
-            && parsed !== null
-            && typeof parsed.pid === 'number'
-            && typeof parsed.createdAt === 'string') {
-            return parsed;
-        }
-    }
-    catch {
-        /* fall through */
-    }
-    return null;
-}
-function isAlive(pid, kill) {
-    if (!Number.isFinite(pid) || pid <= 0)
-        return false;
-    try {
-        kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        // ESRCH = no such process. Any other error (EPERM = process exists
-        // but we lack permission) means the process IS alive.
-        const code = error?.code;
-        if (code === 'ESRCH')
-            return false;
-        return true;
-    }
-}
-function releaseLock(lockPath, expectedPid) {
-    const holder = readLockBody(lockPath);
-    if (!holder)
-        return;
-    // Defence-in-depth: only unlink if we still own the lock. A future
-    // session may have taken over after our process died and was
-    // replaced — better to leave the new owner's file in place than to
-    // race-condition delete it.
-    if (holder.pid !== expectedPid)
-        return;
-    tryUnlink(lockPath);
-}
-function tryUnlink(path) {
-    try {
-        unlinkSync(path);
-    }
-    catch {
-        /* ignore — file may be gone already */
-    }
-}
-function isEexist(error) {
-    return error?.code === 'EEXIST';
-}
-//# sourceMappingURL=lockfile.js.map