@giovannijecha/jecode 0.3.2 → 0.5.0

package/dist/sessions/store.js

@@ -0,0 +1,368 @@
+// Durable, workspace-scoped conversation storage.
+//
+// Each node is its own atomically replaced file. The head is advanced only
+// after that node is durable, so a crash leaves either the prior checkpoint or
+// one strictly recoverable mutation -- never an ambiguous partial history.
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite } from "../atomic.js";
+import { CONVERSATION_LIMITS, ConversationTree } from "../conversation.js";
+import { userDataPath } from "../user-data.js";
+import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, } from "./codec.js";
+import { leaseOwner, leaseToken, pidIsAlive, removeLease, sessionLease, } from "./lease.js";
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const MAX_CATALOG_SCAN = 128;
+const MAX_JSON_BYTES = 20 * 1024 * 1024;
+const SESSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const NODE_NAME = /^(\d{6})\.json$/;
+const ATOMIC_NODE_TEMP = /^\.\d{6}\.json\.\d+\.[a-f0-9-]+\.tmp$/;
+export class DurableSessionStore {
+    workspaceRoot;
+    workspaceDigest;
+    #sessionsRoot;
+    #bucket;
+    constructor(workspaceRoot, sessionsRoot) {
+        this.workspaceRoot = workspaceRoot;
+        this.workspaceDigest = digestWorkspace(workspaceRoot);
+        this.#sessionsRoot = sessionsRoot;
+        this.#bucket = path.join(sessionsRoot, this.workspaceDigest);
+    }
+    static async open(workspaceRoot, sessionsRoot = userDataPath("sessions")) {
+        const canonical = await realpath(path.resolve(workspaceRoot));
+        return new DurableSessionStore(canonical, path.resolve(sessionsRoot));
+    }
+    async list(limit = 32) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) {
+            throw new Error("session catalogue limit is invalid");
+        }
+        const entries = await directoryEntries(this.#bucket);
+        const names = entries
+            .filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
+            .map((entry) => entry.name)
+            .sort((left, right) => right.localeCompare(left))
+            .slice(0, MAX_CATALOG_SCAN);
+        const catalog = [];
+        for (const id of names) {
+            try {
+                const snapshot = await this.load(id);
+                const conversation = snapshot.conversation.latestCompleted();
+                if (conversation === undefined)
+                    continue;
+                catalog.push({
+                    id,
+                    createdAt: snapshot.meta.createdAt,
+                    updatedAt: snapshot.head.updatedAt,
+                    turns: selectedTurnCount(conversation),
+                    preview: firstUserText(conversation),
+                    active: await this.#leaseIsActive(id),
+                });
+            }
+            catch {
+                // Corrupt or foreign data never becomes a resume candidate.
+            }
+        }
+        return catalog
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+            .slice(0, limit);
+    }
+    async load(id) {
+        assertSessionId(id);
+        const directory = this.#sessionDirectory(id);
+        await assertDirectory(directory);
+        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), 64 * 1024));
+        if (meta.id !== id || meta.workspaceDigest !== this.workspaceDigest ||
+            workspaceKey(meta.workspaceRoot) !== workspaceKey(this.workspaceRoot))
+            throw new Error("session belongs to a different workspace");
+        let head = decodeHead(await readJson(path.join(directory, "head.json"), 64 * 1024));
+        const stored = await readNodes(path.join(directory, "nodes"));
+        const ahead = stored.filter((entry) => entry.sequence > head.sequence);
+        if (ahead.some((entry) => entry.sequence !== head.sequence + 1) || ahead.length > 1) {
+            throw new Error("session has an ambiguous incomplete checkpoint");
+        }
+        const byId = new Map(stored.map((entry) => [entry.node.id, entry]));
+        const headed = byId.get(head.nodeId);
+        if (headed === undefined)
+            throw new Error("session head is missing its conversation node");
+        if (ahead.length === 0) {
+            if (headed.sequence !== head.sequence || headed.node.revision !== head.revision ||
+                headed.node.parentId !== head.parentId) {
+                throw new Error("session head does not match its conversation node");
+            }
+        }
+        else {
+            const candidate = ahead[0];
+            const replacesHead = candidate.node.id === head.nodeId &&
+                candidate.node.parentId === head.parentId &&
+                candidate.node.revision === head.revision + 1;
+            const candidateParent = byId.get(candidate.node.parentId);
+            const extendsTree = candidate.node.id === stored.length &&
+                candidate.node.revision === 1 && candidateParent !== undefined &&
+                candidateParent.sequence <= head.sequence;
+            if (!replacesHead && !extendsTree) {
+                throw new Error("session checkpoint cannot be recovered safely");
+            }
+            head = {
+                version: 1,
+                sequence: candidate.sequence,
+                nodeId: candidate.node.id,
+                parentId: candidate.node.parentId,
+                revision: candidate.node.revision,
+                updatedAt: candidate.updatedAt,
+            };
+            await atomicWrite(path.join(directory, "head.json"), encodeHead(head), { mode: FILE_MODE });
+        }
+        const nodes = stored.map((entry) => entry.node);
+        const conversation = ConversationTree.restore(nodes, head.nodeId);
+        return Object.freeze({ meta, head, conversation });
+    }
+    async publish(conversation, claim) {
+        const active = conversation.activeNode;
+        if (active === undefined)
+            throw new Error("an empty conversation cannot be persisted");
+        await this.#ensureBucket();
+        const now = new Date().toISOString();
+        const id = sessionId(now);
+        const token = claim === true ? leaseToken() : undefined;
+        const temporary = path.join(this.#bucket, `.${id}.${randomUUID()}.tmp`);
+        const target = this.#sessionDirectory(id);
+        const meta = {
+            version: 1,
+            id,
+            workspaceRoot: this.workspaceRoot,
+            workspaceDigest: this.workspaceDigest,
+            createdAt: now,
+        };
+        const head = {
+            version: 1,
+            sequence: conversation.nodes.length,
+            nodeId: active.id,
+            parentId: active.parentId,
+            revision: active.revision,
+            updatedAt: now,
+        };
+        try {
+            await makePrivateDirectory(temporary);
+            const nodes = path.join(temporary, "nodes");
+            await makePrivateDirectory(nodes);
+            for (let index = 0; index < conversation.nodes.length; index++) {
+                const node = conversation.nodes[index];
+                await atomicWrite(path.join(nodes, nodeName(node.id)), encodeNode(node, index + 1, now), { mode: FILE_MODE });
+            }
+            await atomicWrite(path.join(temporary, "meta.json"), encodeMeta(meta), { mode: FILE_MODE });
+            await atomicWrite(path.join(temporary, "head.json"), encodeHead(head), { mode: FILE_MODE });
+            if (token !== undefined) {
+                await atomicWrite(path.join(temporary, "active"), token, { mode: FILE_MODE });
+            }
+            await rename(temporary, target);
+        }
+        catch (error) {
+            await removeTemporaryDirectory(temporary, this.#bucket);
+            throw error;
+        }
+        const snapshot = Object.freeze({ meta, head, conversation });
+        if (token === undefined)
+            return snapshot;
+        const lease = sessionLease(id, path.join(target, "active"), token);
+        return Object.freeze({ ...snapshot, lease });
+    }
+    async checkpoint(id, conversation) {
+        const previous = await this.load(id);
+        const active = conversation.activeNode;
+        if (active === undefined)
+            throw new Error("an empty conversation cannot be checkpointed");
+        if (sameNode(active, previous.conversation.activeNode)) {
+            return Object.freeze({ ...previous, conversation });
+        }
+        const replacesHead = active.id === previous.head.nodeId &&
+            active.revision === previous.head.revision + 1 &&
+            conversation.nodes.length === previous.conversation.nodes.length;
+        const extendsTree = active.id === previous.conversation.nodes.length + 1 &&
+            previous.conversation.node(active.parentId) !== undefined && active.revision === 1 &&
+            conversation.nodes.length === previous.conversation.nodes.length + 1;
+        if (!replacesHead && !extendsTree) {
+            throw new Error("session checkpoint does not extend its durable tree");
+        }
+        assertSharedNodes(previous.conversation, conversation, replacesHead ? active.id : undefined);
+        const now = new Date().toISOString();
+        const head = {
+            version: 1,
+            sequence: previous.head.sequence + 1,
+            nodeId: active.id,
+            parentId: active.parentId,
+            revision: active.revision,
+            updatedAt: now,
+        };
+        const directory = this.#sessionDirectory(id);
+        await atomicWrite(path.join(directory, "nodes", nodeName(active.id)), encodeNode(active, head.sequence, now), { mode: FILE_MODE });
+        await atomicWrite(path.join(directory, "head.json"), encodeHead(head), { mode: FILE_MODE });
+        return Object.freeze({ meta: previous.meta, head, conversation });
+    }
+    async claim(id) {
+        assertSessionId(id);
+        await assertDirectory(this.#sessionDirectory(id));
+        const file = path.join(this.#sessionDirectory(id), "active");
+        const token = leaseToken();
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const handle = await open(file, "wx", FILE_MODE);
+                try {
+                    await handle.writeFile(token, "utf8");
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                return sessionLease(id, file, token);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const owner = await leaseOwner(file);
+                if (owner !== undefined && pidIsAlive(owner.pid)) {
+                    throw new Error("session is already open in another Jecode process");
+                }
+                if (owner !== undefined) {
+                    await removeLease(file, owner.token);
+                }
+            }
+        }
+        throw new Error("session could not be claimed");
+    }
+    #sessionDirectory(id) {
+        return path.join(this.#bucket, id);
+    }
+    async #ensureBucket() {
+        await makePrivateDirectory(this.#sessionsRoot);
+        await makePrivateDirectory(this.#bucket);
+    }
+    async #leaseIsActive(id) {
+        const owner = await leaseOwner(path.join(this.#sessionDirectory(id), "active"));
+        return owner !== undefined && pidIsAlive(owner.pid);
+    }
+}
+function assertSharedNodes(previous, next, replacedId) {
+    for (const node of previous.nodes) {
+        if (node.id === replacedId)
+            continue;
+        const candidate = next.node(node.id);
+        if (candidate === undefined || normalizedNode(candidate) !== normalizedNode(node)) {
+            throw new Error("session checkpoint rewrites prior conversation history");
+        }
+    }
+}
+function normalizedNode(node) {
+    const encoded = JSON.parse(encodeNode(node, 1, "2026-01-01T00:00:00.000Z"));
+    return JSON.stringify(encoded.node);
+}
+function sameNode(left, right) {
+    return right !== undefined && normalizedNode(left) === normalizedNode(right);
+}
+async function readNodes(directory) {
+    await assertDirectory(directory);
+    const entries = await readdir(directory, { withFileTypes: true });
+    const names = entries.filter((entry) => entry.isFile() && NODE_NAME.test(entry.name))
+        .map((entry) => entry.name).sort();
+    if (names.length === 0 || names.length > CONVERSATION_LIMITS.nodes) {
+        throw new Error("session has an invalid conversation size");
+    }
+    if (entries.length > CONVERSATION_LIMITS.nodes + 64 ||
+        entries.some((entry) => !entry.isFile() || (!NODE_NAME.test(entry.name) && !ATOMIC_NODE_TEMP.test(entry.name)))) {
+        throw new Error("session node directory contains unsupported data");
+    }
+    const stored = [];
+    const sequences = new Set();
+    for (let index = 0; index < names.length; index++) {
+        const name = names[index];
+        const id = Number(NODE_NAME.exec(name)?.[1]);
+        if (id !== index + 1)
+            throw new Error("session conversation nodes are not contiguous");
+        const decoded = decodeNode(await readJson(path.join(directory, name), MAX_JSON_BYTES));
+        if (decoded.node.id !== id || sequences.has(decoded.sequence)) {
+            throw new Error("session conversation node identity is invalid");
+        }
+        sequences.add(decoded.sequence);
+        stored.push(decoded);
+    }
+    return stored;
+}
+async function readJson(file, limit) {
+    const details = await lstat(file);
+    if (details.isSymbolicLink() || !details.isFile() || details.size > limit) {
+        throw new Error("session file is unsafe or too large");
+    }
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new Error("session file is not valid JSON");
+    }
+}
+async function assertDirectory(directory) {
+    const details = await lstat(directory);
+    if (details.isSymbolicLink() || !details.isDirectory()) {
+        throw new Error("session path is not a direct directory");
+    }
+}
+async function makePrivateDirectory(directory) {
+    await mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+    await assertDirectory(directory);
+    if (process.platform !== "win32")
+        await chmod(directory, DIRECTORY_MODE);
+}
+async function directoryEntries(directory) {
+    try {
+        await assertDirectory(directory);
+        return await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function removeTemporaryDirectory(directory, bucket) {
+    const relative = path.relative(bucket, directory);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative) ||
+        !path.basename(directory).startsWith(".") || !path.basename(directory).endsWith(".tmp"))
+        throw new Error("refusing to remove an unverified session directory");
+    await rm(directory, { recursive: true, force: true });
+}
+function selectedTurnCount(conversation) {
+    let count = 0;
+    let id = conversation.activeNodeId;
+    while (id !== 0) {
+        count++;
+        id = conversation.node(id)?.parentId ?? 0;
+    }
+    return count;
+}
+function firstUserText(conversation) {
+    for (const message of conversation.history) {
+        if (message.role !== "user")
+            continue;
+        const text = message.content.find((block) => block.kind === "text")?.text
+            .replace(/\s+/gu, " ").trim();
+        if (text !== undefined && text !== "")
+            return text.slice(0, 160);
+    }
+    return "Untitled session";
+}
+function nodeName(id) {
+    return `${String(id).padStart(6, "0")}.json`;
+}
+function sessionId(now) {
+    return `${now.replace(/[-:.]/g, "").replace("Z", "Z")}-${randomUUID()}`;
+}
+function digestWorkspace(workspaceRoot) {
+    return createHash("sha256").update(workspaceKey(workspaceRoot)).digest("hex");
+}
+function workspaceKey(workspaceRoot) {
+    const normalized = path.normalize(workspaceRoot);
+    return process.platform === "win32" ? normalized.toLocaleLowerCase("en-US") : normalized;
+}
+function assertSessionId(id) {
+    if (!SESSION_NAME.test(id))
+        throw new Error("session id is invalid");
+}

package/dist/settings-command.js

@@ -1,10 +1,11 @@
-// The persistent settings hub. Every interaction uses the shared dock picker
-// and field contracts; this module owns choices and persistence, not drawing.
-import { modelsCommand, providersCommand } from "./provider-commands.js";
-import { credentialsCommand } from "./credential-commands.js";
-import { EFFORTS, readSettings, settingsLabel, updateSettings } from "./settings.js";
+// The persistent settings hub. Provider access and model selection reuse the
+// same command flows exposed directly through /providers and /models.
+import { saveCommandSettings } from "./command-settings.js";
+import { modelsCommand } from "./model-command.js";
 import { providerFailure } from "./provider-errors.js";
-import { ollamaConnectionHint, ollamaConnectionSetting, } from "./ollama-settings-command.js";
+import { providerLabel } from "./provider-label.js";
+import { providersCommand } from "./provider-commands.js";
+import { EFFORTS } from "./settings.js";
 import { of } from "./tui/editor.js";
 import { heading } from "./tui/picker.js";
 /** A focused path to the same saved reasoning default exposed by /settings. */
@@ -22,7 +23,7 @@ export async function settingsCommand(session, host) {
     while (true) {
         const values = settingsValues(session);
         const items = settingsItems(values);
-        const index = await choose(settingsPicker(values, session.palette, selected));
+        const index = await choose(settingsPicker(values, selected));
         if (index === undefined)
             return;
         const action = items[index]?.action;
@@ -30,14 +31,8 @@ export async function settingsCommand(session, host) {
             return;
         selected = index;
         switch (action) {
-            case "provider":
-                await providerSetting(session, host);
-                break;
-            case "ollamaConnection":
-                await ollamaConnectionSetting(session, host, (patch) => persist(host, patch));
-                break;
             case "model":
-                await modelSetting(session, host);
+                await modelsCommand(session, host, { announce: false });
                 break;
             case "effort":
                 await effortSetting(session, host);
@@ -51,45 +46,43 @@ export async function settingsCommand(session, host) {
             case "reducedMotion":
                 await motionSetting(session, host);
                 break;
-            case "credentials":
-                await credentialsCommand(session, host);
+            case "providers":
+                await providersCommand(session, host);
                 break;
         }
     }
 }
-export function settingsPicker(values, pal, index = 0, store = settingsLabel()) {
+export function settingsPicker(values, index = 0) {
     return {
-        title: heading("settings", store, pal),
-        description: "Changes apply now · flags and environment win at launch",
+        title: [],
         options: settingsItems(values).map((item) => item.option),
         index,
     };
 }
 function settingsItems(values) {
     return [
-        { action: "provider", option: { label: "provider", hint: values.provider } },
-        ...(values.ollamaConnection === undefined
-            ? []
-            : [{
-                    action: "ollamaConnection",
-                    option: { label: "ollama connection", hint: values.ollamaConnection },
-                }]),
-        { action: "model", option: { label: "model", hint: values.model || "choose a model" } },
-        { action: "effort", option: { label: "effort", hint: values.effort } },
+        {
+            action: "model",
+            option: {
+                label: "model",
+                value: `${providerLabel(values.provider)} · ${values.model || "choose a model"}`,
+            },
+        },
+        { action: "effort", option: { label: "effort", value: values.effort } },
         ...(values.maxTokens === undefined
             ? []
             : [{
                     action: "maxTokens",
-                    option: { label: "max output tokens", hint: String(values.maxTokens) },
+                    option: { label: "max output tokens", value: String(values.maxTokens) },
                 }]),
-        { action: "maxSteps", option: { label: "max tool steps", hint: String(values.maxSteps) } },
+        { action: "maxSteps", option: { label: "max tool steps", value: String(values.maxSteps) } },
         {
             action: "reducedMotion",
-            option: { label: "reduced motion", hint: values.reducedMotion ? "on" : "off" },
+            option: { label: "reduced motion", value: values.reducedMotion ? "on" : "off" },
         },
         {
-            action: "credentials",
-            option: { label: "authentication", hint: "manage API keys and accounts" },
+            action: "providers",
+            option: { label: "providers", hint: "manage access and connections" },
         },
     ];
 }
@@ -97,65 +90,18 @@ function settingsValues(session) {
     return {
         provider: session.provider.id,
         model: session.model,
-        ...(session.provider.id === "ollama" ? { ollamaConnection: ollamaConnectionHint() } : {}),
         effort: session.config.effort,
         ...(session.provider.id === "openai-codex" ? {} : { maxTokens: session.config.maxTokens }),
         maxSteps: session.config.maxSteps,
         reducedMotion: session.config.reducedMotion,
     };
 }
-async function providerSetting(session, host) {
-    const before = {
-        provider: session.provider,
-        model: session.model,
-        providerId: session.config.providerId,
-        configModel: session.config.model,
-        effort: session.config.effort,
-    };
-    if (!(await providersCommand(session, host, { announce: false, save: false })))
-        return;
-    const current = readSettings();
-    const models = { ...current.models };
-    if (session.model !== "")
-        models[session.provider.id] = session.model;
-    const patch = {
-        provider: session.provider.id,
-        models,
-        ...(session.config.effort === before.effort ? {} : { effort: session.config.effort }),
-    };
-    if (await persist(host, patch))
-        return;
-    session.provider = before.provider;
-    session.model = before.model;
-    session.config.providerId = before.providerId;
-    session.config.model = before.configModel;
-    session.config.effort = before.effort;
-}
-async function modelSetting(session, host) {
-    const before = {
-        model: session.model,
-        configModel: session.config.model,
-        effort: session.config.effort,
-    };
-    if (!(await modelsCommand(session, host, { announce: false, save: false })))
-        return;
-    const current = readSettings();
-    const models = { ...current.models, [session.provider.id]: session.model };
-    const patch = {
-        models,
-        ...(session.config.effort === before.effort ? {} : { effort: session.config.effort }),
-    };
-    if (await persist(host, patch))
-        return;
-    session.model = before.model;
-    session.config.model = before.configModel;
-    session.config.effort = before.effort;
-}
 async function effortSetting(session, host) {
     const choose = chooser(host);
     if (choose === undefined)
         return;
     const efforts = await availableEfforts(session, host);
+    throwIfAborted(host.signal);
     if (efforts === undefined)
         return;
     if (efforts.length === 0) {
@@ -168,12 +114,12 @@ async function effortSetting(session, host) {
     }
     const current = session.config.effort;
     const index = await choose({
-        title: heading("effort", "saved default", session.palette),
+        title: [],
         options: efforts.map((value) => ({ label: value })),
         index: Math.max(0, efforts.findIndex((value) => value === current)),
     });
     const value = index === undefined ? undefined : efforts[index];
-    if (value === undefined || !(await persist(host, { effort: value })))
+    if (value === undefined || !(await saveCommandSettings(host, { effort: value })))
         return;
     session.config.effort = value;
     return value;
@@ -181,11 +127,15 @@ async function effortSetting(session, host) {
 async function availableEfforts(session, host) {
     if (session.provider.efforts === undefined)
         return EFFORTS;
-    host.status?.(`Asking ${session.provider.id}`);
+    host.status?.(`Asking ${providerLabel(session.provider.id)}`);
     try {
-        return await session.provider.efforts(session.model, host.signal, (status) => host.status?.(status));
+        throwIfAborted(host.signal);
+        const efforts = await session.provider.efforts(session.model, host.signal, (status) => host.status?.(status));
+        throwIfAborted(host.signal);
+        return efforts;
     }
     catch (error) {
+        throwIfAborted(host.signal);
         host.emit({
             kind: "notice",
             text: providerFailure(session.provider, error, true),
@@ -203,12 +153,12 @@ async function motionSetting(session, host) {
         return;
     const values = [false, true];
     const index = await choose({
-        title: heading("reduced motion", "saved default", session.palette),
+        title: [],
         options: values.map((value) => ({ label: value ? "on" : "off" })),
         index: session.config.reducedMotion ? 1 : 0,
     });
     const value = index === undefined ? undefined : values[index];
-    if (value === undefined || !(await persist(host, { reducedMotion: value })))
+    if (value === undefined || !(await saveCommandSettings(host, { reducedMotion: value })))
         return;
     session.config.reducedMotion = value;
     host.refreshSettings?.();
@@ -231,23 +181,18 @@ async function numberSetting(session, host, name, label) {
         host.emit({ kind: "notice", text: `${label} must be a positive integer`, tone: "error" });
         return;
     }
-    if (!(await persist(host, { [name]: value })))
+    if (!(await saveCommandSettings(host, { [name]: value })))
         return;
     session.config[name] = value;
 }
-async function persist(host, patch) {
-    try {
-        await updateSettings(patch);
-        return true;
-    }
-    catch (error) {
-        host.emit({ kind: "notice", text: `could not save settings · ${error.message}`, tone: "error" });
-        return false;
-    }
-}
 function chooser(host) {
     if (host.choose === undefined) {
         host.emit({ kind: "notice", text: "that command needs the screen", tone: "warn" });
     }
     return host.choose;
 }
+function throwIfAborted(signal) {
+    if (signal?.aborted !== true)
+        return;
+    throw signal.reason instanceof Error ? signal.reason : new Error("interrupted");
+}