@cruxy/cli 1.2.0 → 1.3.0

package/dist/session/log.js

@@ -0,0 +1,137 @@
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { APP_VERSION } from "../constants.js";
+import { sessionFile } from "./paths.js";
+import { SESSION_FILE_VERSION, } from "./types.js";
+export class SessionLog {
+    file;
+    logger;
+    currentRunId;
+    /** Set once a write fails: the log goes inert rather than warning per turn. */
+    broken = false;
+    constructor(file, opts) {
+        this.file = file;
+        this.logger = opts.logger;
+        this.currentRunId = opts.currentRunId;
+    }
+    /**
+     * Open (or create) a session log. A NEW file gets its `meta` line; reopening
+     * an existing one (a `--resume`) does not — `meta` describes where and when
+     * the conversation began, and a second copy written from wherever it was
+     * resumed would make "the session's directory" ambiguous. Replay already
+     * takes the first `meta`, so a duplicate could only ever mislead a later
+     * reader, never help one.
+     *
+     * Returns `null` when a new log cannot be created at all — the caller then
+     * runs without persistence rather than failing, exactly as a corrupt usage
+     * store is survivable. A reopen never returns null: a write problem on an
+     * existing file surfaces on the first append, which warns and goes inert.
+     */
+    static open(opts) {
+        const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
+        const log = new SessionLog(file, opts);
+        if (hasContent(file))
+            return log;
+        const ok = log.write({
+            kind: "meta",
+            version: SESSION_FILE_VERSION,
+            sessionId: opts.sessionId,
+            startedAt: new Date().toISOString(),
+            cwd: opts.cwd,
+            roots: opts.roots ?? [],
+            cliVersion: APP_VERSION,
+            ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+        return ok ? log : null;
+    }
+    /** Messages appended to the history since the last event. */
+    append(messages) {
+        if (messages.length === 0)
+            return;
+        this.write({
+            kind: "append",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            messages,
+        });
+    }
+    /** An older prefix of `replaced` messages was folded into `summary`. */
+    compaction(replaced, summary) {
+        this.write({
+            kind: "compaction",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            replaced,
+            summary,
+        });
+    }
+    /** `/clear` — history dropped, session kept. */
+    clear() {
+        this.write({ kind: "clear", at: new Date().toISOString() });
+    }
+    /**
+     * The session mode changed (P5 track 3). Replaces the `plan-mode` event,
+     * which is still READ for sessions recorded before modes existed but is no
+     * longer written.
+     */
+    mode(mode) {
+        this.write({ kind: "mode", at: new Date().toISOString(), mode });
+    }
+    /**
+     * One turn's token usage. Copied here rather than referenced, because the
+     * usage store keeps only its newest 50 runs while sessions are kept
+     * indefinitely — see the note on `UsageEventSchema`.
+     */
+    usage(inputTokens, outputTokens) {
+        this.write({
+            kind: "usage",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            inputTokens,
+            outputTokens,
+        });
+    }
+    runId() {
+        const id = this.currentRunId?.();
+        return id === undefined ? {} : { runId: id };
+    }
+    /**
+     * Append one event as a single line. Returns whether it landed. The first
+     * failure warns and latches `broken`, so a persistent problem (a full disk)
+     * produces one diagnostic rather than one per turn.
+     */
+    write(event) {
+        if (this.broken)
+            return false;
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true });
+            // `mode` applies only when the file is created — 0600 from the first
+            // line, matching credentials/usage/memory.
+            appendFileSync(this.file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+            return true;
+        }
+        catch (err) {
+            this.broken = true;
+            this.logger?.warn(`session not being saved: ${err.message} (the conversation continues in memory)`);
+            return false;
+        }
+    }
+}
+/**
+ * Whether `file` is an existing log with content — i.e. this is a reopen.
+ *
+ * `isFile()` matters: a DIRECTORY at this path reports a non-zero size, so a
+ * size check alone would read an unwritable path as a healthy existing log,
+ * skip the meta write, and hand back a recorder that silently fails on its
+ * first append instead of declining up front.
+ */
+function hasContent(file) {
+    try {
+        const stat = statSync(file);
+        return stat.isFile() && stat.size > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/session/paths.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+/**
+ * Where sessions live on disk (P2).
+ *
+ * ```
+ * ~/.cruxy/projects/<project>/
+ *   <session-id>.jsonl        ← the event log (P2)
+ *   subagents/                ← reserved, P3+
+ *   tool-results/             ← reserved, P3+
+ *   file-history/             ← reserved, P3+
+ *   memory/                   ← reserved, P3+
+ * ```
+ *
+ * Everything resolves through {@link globalDir}, never a fresh `homedir()` —
+ * one accessor owns the location of `~/.cruxy` and the tests can point it
+ * somewhere else by pointing that.
+ *
+ * The reserved subdirectories are DECLARED here and not created: an empty
+ * directory tree is noise until something writes to it, but naming the paths
+ * now is what stops P3 from inventing a second, conflicting layout.
+ */
+/** `~/.cruxy/projects` */
+export const PROJECTS_DIR_NAME = "projects";
+/** Session event-log extension. */
+export const SESSION_FILE_EXT = ".jsonl";
+/** Reserved subtrees — declared for P3+, deliberately not created by P2. */
+export const RESERVED_SUBDIRS = [
+    "subagents",
+    "tool-results",
+    "file-history",
+    "memory",
+];
+/**
+ * The directory key for a working directory: every run of non-alphanumerics
+ * collapses to a single `-`, with leading/trailing separators trimmed.
+ *
+ * Flattening the path rather than nesting it keeps one directory per project
+ * (so listing is a single readdir) and cannot escape the projects root the way
+ * a path fragment could. It is deliberately NOT reversible — the true `cwd` is
+ * recorded in each session's `meta` event, which is what resume validates
+ * against; the key is only an index.
+ *
+ * Two different directories CAN collide onto one key (`/a/b` and `/a-b`). That
+ * is why resume compares `meta.cwd`, not the key, before trusting a session.
+ */
+export function projectKey(cwd) {
+    const key = path.resolve(cwd).replace(/[^a-zA-Z0-9]+/g, "-");
+    const trimmed = key.replace(/^-+/, "").replace(/-+$/, "");
+    // A path of nothing but separators (`/`) collapses to empty; give it a name
+    // rather than writing into the projects root itself.
+    return trimmed === "" ? "root" : trimmed;
+}
+/** `~/.cruxy/projects` */
+export function projectsDir() {
+    return path.join(globalDir(), PROJECTS_DIR_NAME);
+}
+/**
+ * `~/.cruxy/projects/<project>` for a working directory. Multi-root sessions
+ * pass the PRIMARY root — the session belongs to one project even when it can
+ * read several, and `meta.roots` is what records the rest.
+ */
+export function projectDir(cwd) {
+    return path.join(projectsDir(), projectKey(cwd));
+}
+/** `~/.cruxy/projects/<project>/<session-id>.jsonl` */
+export function sessionFile(cwd, sessionId) {
+    return path.join(projectDir(cwd), `${sessionId}${SESSION_FILE_EXT}`);
+}
+/** A reserved subtree's path (P3+). Declared, not created. */
+export function reservedDir(cwd, name) {
+    return path.join(projectDir(cwd), name);
+}

package/dist/session/replay.js

@@ -0,0 +1,169 @@
+import { readFileSync } from "node:fs";
+import { modeFromFlags } from "../agent/mode.js";
+import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
+/**
+ * Replay: fold an append-only event log back into the state a session needs to
+ * resume (P2).
+ *
+ * The fold is total and order-dependent — `append` grows the array,
+ * `compaction` replaces its head, `clear` empties it — so the result is exactly
+ * the array the model last saw, including the synthetic compaction summaries.
+ * Nothing is re-derived or re-summarised on the way back in.
+ *
+ * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED and counted,
+ * never fatal:
+ *  - a torn final line from a crash mid-append would otherwise cost the whole
+ *    conversation (this is the failure temp-then-rename buys off at write time;
+ *    an append-only log buys it off here instead);
+ *  - a line from a NEWER cruxy carrying an event kind this build has never
+ *    heard of is skipped rather than rejected, which together with the
+ *    `.passthrough()` schemas is what keeps two CLI versions able to share one
+ *    home directory.
+ * `SessionState.skipped` carries the count so a caller can say so out loud
+ * rather than presenting a partial history as complete.
+ */
+/**
+ * The one cast in this module, isolated and explained.
+ *
+ * `MessageSchema` is `.passthrough()`, so its inferred type carries an index
+ * signature that the SDK's `Message` interface does not declare. The values are
+ * structurally identical — the schema validates every field `Message` requires
+ * and preserves the rest — so this narrows a validated value to the nominal
+ * type the rest of the CLI speaks. It is sound precisely BECAUSE the schema ran
+ * first; do not move it above the parse.
+ */
+function asMessages(validated) {
+    return validated;
+}
+/** Parse one line, or `null` when it is unusable (torn, or an unknown kind). */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const parsed = SessionEventSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * Fold events into {@link SessionState}. Exported separately from file reading
+ * so the fold is directly testable without a filesystem — the same split as
+ * `render/state.ts` (pure) versus the renderers.
+ *
+ * Throws only when there is no usable `meta` line: without it we do not know
+ * which directory the history refers to, and resuming a conversation whose
+ * origin is unknown is precisely what ruling 4 forbids.
+ */
+export function foldEvents(events, skipped = 0) {
+    const metaEvent = events.find((e) => e.kind === "meta");
+    if (!metaEvent) {
+        throw new Error("session log has no readable meta line");
+    }
+    const meta = metaEvent;
+    let messages = [];
+    // Both are folded, and `mode` wins when present. A journal written before P5
+    // has only `plan-mode` events; one written after has only `mode` events; a
+    // session resumed by a P5 build and then continued has both, in that order.
+    // Last-writer-wins across the two would be wrong — the pre-P5 events are all
+    // earlier, so the newer vocabulary must take precedence rather than the newer
+    // timestamp.
+    let planMode = false;
+    let mode = null;
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    for (const event of events) {
+        switch (event.kind) {
+            case "append":
+                messages = [...messages, ...asMessages(event.messages)];
+                break;
+            case "compaction":
+                // Exactly what `Session.runCompaction` did in memory: drop the head,
+                // splice the synthetic pair in front of what was kept.
+                messages = [
+                    ...asMessages(event.summary),
+                    ...messages.slice(event.replaced),
+                ];
+                break;
+            case "clear":
+                messages = [];
+                break;
+            case "plan-mode":
+                planMode = event.enabled;
+                break;
+            case "mode":
+                mode = event.mode;
+                break;
+            case "usage":
+                usage.input_tokens += event.inputTokens;
+                usage.output_tokens += event.outputTokens;
+                break;
+            case "meta":
+                break;
+        }
+    }
+    return {
+        meta,
+        messages,
+        usage,
+        // A pre-P5 journal's plan flag becomes the mode it was equivalent to.
+        // Auto-approve reads false there, which is right: it was not a thing that
+        // could be on, so nothing is being inferred.
+        mode: mode ?? modeFromFlags(planMode, false),
+        skipped,
+    };
+}
+/** Read and parse a session file into its events, counting unusable lines. */
+export function readEvents(file) {
+    const raw = readFileSync(file, "utf8");
+    const events = [];
+    let skipped = 0;
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const event = parseLine(line);
+        if (event)
+            events.push(event);
+        else
+            skipped++;
+    }
+    return { events, skipped };
+}
+/** Read a session file and fold it into resumable state. */
+export function replaySession(file) {
+    const { events, skipped } = readEvents(file);
+    return foldEvents(events, skipped);
+}
+/**
+ * Read ONLY the meta line — enough to list a session without folding its whole
+ * history. Returns null when the file has no usable meta.
+ */
+export function readMeta(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const parsed = SessionMetaSchema.safeParse(JSON.parse(line));
+            if (parsed.success)
+                return parsed.data;
+        }
+        catch {
+            // keep scanning: a torn first line must not hide a good meta below it
+        }
+        // Only the meta line is expected first; if the first usable line is some
+        // other event the file is malformed for our purposes, but keep scanning
+        // rather than giving up — the cost is bounded and the payoff is a session
+        // that lists instead of vanishing.
+    }
+    return null;
+}

package/dist/session/resume.js

@@ -0,0 +1,128 @@
+import { selectList } from "../components/index.js";
+import { usageError } from "../errors/index.js";
+import { findSession, isAmbiguous, listSessions } from "./list.js";
+import { replaySession } from "./replay.js";
+/** How many sessions the bare-`--resume` picker offers. */
+export const PICKER_LIMIT = 10;
+/** Short, stable id form — enough to identify a session, short enough to type. */
+export function shortId(sessionId) {
+    return sessionId.slice(0, 8);
+}
+/** `2h ago`, `3d ago` — relative age for the picker and the sidebar. */
+export function relativeAge(iso, now = Date.now()) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return "unknown";
+    const seconds = Math.max(0, Math.floor((now - then) / 1000));
+    if (seconds < 60)
+        return "just now";
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+/** One picker/sidebar row: `3f2a1b0c  2h ago  fix the failing test  (4 turns)`. */
+export function describeSession(s, now = Date.now()) {
+    const turns = `${s.turns} turn${s.turns === 1 ? "" : "s"}`;
+    return `${shortId(s.sessionId)}  ${relativeAge(s.updatedAt, now)}  ${s.title}  (${turns})`;
+}
+/**
+ * Compare the session's recorded directory with the one we are resuming into.
+ * Returns a warning to print, or null when they agree.
+ *
+ * This is ruling 4's "warn loudly, never silently mismatch". The history is
+ * full of file paths, diffs and tool results that only mean anything relative
+ * to the directory they were produced in; replaying it somewhere else does not
+ * corrupt anything, but it does mean the model is reasoning about a tree that
+ * is not the one in front of it. So the resume PROCEEDS — the user asked for
+ * it, and refusing a resume because a repo moved would be worse — but it says
+ * exactly what is off.
+ */
+export function cwdMismatchWarning(state, cwd) {
+    if (state.meta.cwd === cwd)
+        return null;
+    return (`this session was recorded in ${state.meta.cwd}, but you are in ${cwd} — ` +
+        `its history refers to files and paths from the original directory`);
+}
+/**
+ * Load one session and collect its warnings. Throws a usage error when the
+ * file cannot be replayed at all (no meta line) — an unreadable session is
+ * worth failing loudly on, unlike an individual torn line.
+ */
+export function loadResume(session, cwd) {
+    let state;
+    try {
+        state = replaySession(session.file);
+    }
+    catch (err) {
+        throw usageError(`could not resume session ${shortId(session.sessionId)}`, [
+            `the log at ${session.file} is not readable: ${err.message}`,
+            "start a new session with `cruxy`",
+        ]);
+    }
+    const warnings = [];
+    const mismatch = cwdMismatchWarning(state, cwd);
+    if (mismatch)
+        warnings.push(mismatch);
+    if (state.skipped > 0) {
+        warnings.push(`${state.skipped} unreadable line${state.skipped === 1 ? "" : "s"} in the session log were skipped — ` +
+            `the restored history may be incomplete`);
+    }
+    return { session, state, warnings };
+}
+/**
+ * Resolve `--resume <id>`. Fails loud on an unknown or ambiguous id rather than
+ * silently starting a new session — the user named something specific.
+ */
+export function resumeById(cwd, id) {
+    if (isAmbiguous(cwd, id)) {
+        const matches = listSessions(cwd)
+            .filter((s) => s.sessionId.startsWith(id))
+            .map((s) => shortId(s.sessionId));
+        throw usageError(`\`${id}\` matches more than one session`, [
+            `did you mean one of: ${matches.join(", ")}?`,
+            "run `cruxy --resume` to pick from a list",
+        ]);
+    }
+    const found = findSession(cwd, id);
+    if (!found) {
+        throw usageError(`no session \`${id}\` in this project`, [
+            "run `cruxy --resume` to pick from recent sessions",
+            "sessions are per-directory; check you are in the right one",
+        ]);
+    }
+    return loadResume(found, cwd);
+}
+/**
+ * Bare `--resume`: pick from the most recent sessions, or start a new one.
+ * Returns null when the user chose "new session" (or cancelled) — the caller
+ * then proceeds exactly as an unresumed run.
+ */
+export async function resumePicker(cwd, opts = {}) {
+    const sessions = listSessions(cwd, PICKER_LIMIT);
+    if (sessions.length === 0) {
+        opts.logger?.info("no saved sessions for this project — starting a new one");
+        return null;
+    }
+    const now = opts.now ?? Date.now();
+    const rows = [
+        ...sessions.map((session) => ({ kind: "session", session })),
+        { kind: "new" },
+    ];
+    const picked = await selectList(rows, {
+        title: "resume a session",
+        toLabel: (row) => row.kind === "new"
+            ? "+ new session"
+            : describeSession(row.session, now),
+        // Non-interactive with no id named: starting fresh is the safe default,
+        // never an arbitrary session picked on the user's behalf.
+        defaultValue: { kind: "new" },
+        nonInteractiveHint: ["pass an id: `cruxy --resume <id>`"],
+    }, opts.io);
+    if (picked.kind === "cancelled" || picked.value.kind === "new")
+        return null;
+    return loadResume(picked.value.session, cwd);
+}