// storage.js - what the composer keeps between runs. // // The store is injected: `store = { get(key): unknown, set(key, value): void }`. // The view (Task 8) hands it `{ get: shared, set: setShared }` from the // `herdr` module. `shared()` is app-wide and persisted in // ~/.config/herdr-app/shared.json, so the history is the same in every pane // and outlives the app. `localStorage` would be per mod copy - per pane - and // would not outlive a restart. // // The queue has to outlive a crash in the middle of a send: Task 5's `drain` // marks the entry `sending` BEFORE the send goes on the wire and hands the // state to the caller through `ctx.onState`, so the caller writes it down at // once. After a restart the composer loads the queue and turns `sending` into // `uncertain` (the `restart` action of state.js) - the message may have // reached the agent, so it is never sent again on its own. // // Reading never throws: a key that was never written, a value that is not a // list, a store that is not there - the composer always gets a list to show. // Writing rubbish does not throw either, but it does not write: the stored // list stays as it was, so a bug in the caller cannot wipe the history. A // store that cannot be written to at all throws - the queue on disk is what // keeps a crash from sending a message twice, so that must not pass quietly. // // What comes back is checked: an entry that lost a field on the way to the // disk is dropped, not handed to the view. A queue entry without a moment // (`createdAt`) would make state.js throw, and one with a state it does not // know would wait for ever - and a cut entry that came back would be sent // again. /** * @typedef {object} Store * @property {(key:string) => unknown} get * @property {(key:string, value:unknown) => unknown} set * * @typedef {object} HistoryEntry * @property {string} id * @property {string} text * @property {number} at * @property {string} agent * @property {string} space * @property {string} spaceName * @property {string} tab * @property {string} pane * @property {string|null} machine * @property {string[]} attachments * @property {"sent"|"queued"|"failed"} outcome * * @typedef {object} FavoriteEntry * @property {string} id * @property {string} text * @property {number} at * @property {string} agent * @property {"history"|"manual"} source * * @typedef {object} QueueEntry * @property {string} id * @property {string} text * @property {"queued"|"sending"|"held"|"uncertain"} state * @property {number} createdAt * @property {string} [reason] */ /** The states a queue entry may be in (the ones state.js knows). */ const QUEUE_STATES = new Set(["queued", "sending", "held", "uncertain"]); /** The keys the composer writes into the shared store. */ export const KEYS = { history: "ovis-composer.history", favorites: "ovis-composer.favorites", usage: "ovis-composer.usage", /** The queue is per agent: `ovis-composer.queue:`. */ queue: "ovis-composer.queue", /** The draft is per agent: `ovis-composer.draft:`. */ draft: "ovis-composer.draft", }; /** How many entries the history keeps. */ export const HISTORY_LIMIT = 500; /** How many entries the favourites keep. */ export const FAVORITES_LIMIT = 100; /** * The key of one agent's queue. * * @param {string} agent * @returns {string} */ export function queueKey(agent) { return `${KEYS.queue}:${agent}`; } /** * The history of the sent messages. * * The list is chronological - the oldest entry first, the newest last - and * the oldest entries drop out when the list grows over the limit. * * @param {Store} store * @returns {HistoryEntry[]} */ export function loadHistory(store) { return readList(store, KEYS.history, HISTORY_LIMIT, isTextEntry); } /** * @param {Store} store * @param {HistoryEntry[]} items * @returns {void} */ export function saveHistory(store, items) { writeList(store, KEYS.history, items, HISTORY_LIMIT, isTextEntry); } /** * The favourites - the texts the person marked, kept apart from the history * so they outlive a cleared history. * * @param {Store} store * @returns {FavoriteEntry[]} */ export function loadFavorites(store) { return readList(store, KEYS.favorites, FAVORITES_LIMIT, isTextEntry); } /** * @param {Store} store * @param {FavoriteEntry[]} items * @returns {void} */ export function saveFavorites(store, items) { writeList(store, KEYS.favorites, items, FAVORITES_LIMIT, isTextEntry); } /** * The queue of one agent - the messages that wait for their turn. * * The state is what it was when it was written: an entry that was on the wire * (`sending`) is still `sending` here after a restart, and the composer * turns it into `uncertain` (state.js, the `restart` action). The queue is * never sent again on its own. * * @param {Store} store * @param {string} agent * @returns {QueueEntry[]} */ export function loadQueue(store, agent) { return readList(store, queueKey(agent), 0, isQueueEntry); } /** * @param {Store} store * @param {string} agent * @param {QueueEntry[]} items * @returns {void} */ export function saveQueue(store, agent, items) { if (typeof agent !== "string" || agent === "") return; writeList(store, queueKey(agent), items, 0, isQueueEntry); } /** * The key of one agent's draft. * * @param {string} agent * @returns {string} */ export function draftKey(agent) { return `${KEYS.draft}:${agent}`; } /** * @typedef {object} DraftIdentity * @property {number|null} created_ms - when the terminal was created (`hc get`) * @property {string|null} app * * @typedef {object} Draft * @property {string} text * @property {number} caret * @property {object[]} attachments * @property {DraftIdentity} identity - who the draft was written for: the * address can be reused by another terminal after a restart * @property {number} savedAt */ /** * The draft of one agent, or nothing when there is none (or it is rubbish). * * The text is kept whole: the limit of 20 000 characters is a limit of the * send, not of the draft - a long text must survive a restart. * * @param {Store} store * @param {string} agent * @returns {Draft|null} */ export function loadDraft(store, agent) { if (typeof agent !== "string" || agent === "") return null; return toDraft(read(store, draftKey(agent))); } /** * Write the draft of one agent. An empty draft is written too - it replaces * the one that was sent. What is not a draft is not written. * * @param {Store} store * @param {string} agent * @param {Draft} draft * @returns {void} */ export function saveDraft(store, agent, draft) { if (typeof agent !== "string" || agent === "") return; const clean = toDraft(draft); if (!clean) return; // A terminal whose start time could not be read must not wipe the start // time that is already on the disk: the next restart compares against it. if (clean.identity.created_ms === null) { const stored = toDraft(read(store, draftKey(agent))); if (stored && stored.identity.created_ms !== null) clean.identity = stored.identity; } write(store, draftKey(agent), clean); } /** * A draft in the shape the composer insists on, or null. * * @param {unknown} value * @returns {Draft|null} */ function toDraft(value) { if (!value || typeof value !== "object" || Array.isArray(value)) return null; const raw = /** @type {Record} */ (value); if (typeof raw.text !== "string") return null; const caret = isTime(raw.caret) ? Math.max(0, Math.min(Math.trunc(raw.caret), raw.text.length)) : raw.text.length; const attachments = Array.isArray(raw.attachments) ? raw.attachments.filter( (file) => file && typeof file === "object" && isText(file.id) && isText(file.name) && isText(file.path), ) : []; const id = raw.identity && typeof raw.identity === "object" ? raw.identity : {}; return { text: raw.text, caret, attachments, identity: { created_ms: isTime(id.created_ms) ? id.created_ms : null, app: typeof id.app === "string" ? id.app : null, }, savedAt: isTime(raw.savedAt) ? raw.savedAt : 0, }; } /** * How often each command was used - the numbers the ranking of the * suggestions breaks its ties with (`suggest.rank` reads `item.uses`). * * The key is the key of the catalog (`catalog.js`): the name of the command * without the slash - "review", not "/review" - because that is the name * `suggest.rank` compares. * * @param {Store} store * @returns {Record} */ export function loadUsage(store) { const raw = read(store, KEYS.usage); if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {}; const counts = {}; for (const [key, value] of Object.entries(raw)) { if (typeof value === "number" && Number.isFinite(value) && value >= 0) counts[key] = value; } return counts; } /** * @param {Store} store * @param {Record} counts - the key of the catalog, without * the slash: "review", not "/review" * @returns {void} */ export function saveUsage(store, counts) { if (!counts || typeof counts !== "object" || Array.isArray(counts)) return; const clean = {}; for (const [key, value] of Object.entries(counts)) { if (typeof value === "number" && Number.isFinite(value) && value >= 0) clean[key] = value; } // Counts that are not counts are rubbish - they do not wipe the counters // that are there. An empty map on purpose still clears them. if (Object.keys(counts).length > 0 && Object.keys(clean).length === 0) return; write(store, KEYS.usage, clean); } /** * Read a list, dropping what is not a list, what is not an entry and what the * limit leaves out. The oldest entries drop out - the list is chronological. * * @param {Store} store * @param {string} key * @param {number} limit - 0 for a list without a limit * @param {(entry:Record) => boolean} isValid * @returns {any[]} */ function readList(store, key, limit, isValid) { const list = toList(read(store, key), isValid); if (!list) return []; return limit > 0 ? list.slice(-limit) : list; } /** * Write a list, dropping what is not an entry and what the limit leaves out. * * @param {Store} store * @param {string} key * @param {unknown} items * @param {number} limit - 0 for a list without a limit * @param {(entry:Record) => boolean} isValid * @returns {void} */ function writeList(store, key, items, limit, isValid) { const source = listSource(items); // Rubbish in - nothing is written, so the stored list stays as it was. if (!source) return; const list = toList(source, isValid) ?? []; // A list that lost every entry is rubbish, not an empty list - writing it // would wipe what is there. if (source.length > 0 && list.length === 0) return; write(store, key, limit > 0 ? list.slice(-limit) : list); } /** * The list in a value, or nothing when the value is not a list. The entries * that are not entries of this kind are rubbish and go. * * The entries keep the shape the caller wrote - what a history entry and what * a queue entry look like is the caller's business, not the store's. * * @param {unknown} value * @param {(entry:Record) => boolean} isValid * @returns {any[]|null} */ function toList(value, isValid) { const source = listSource(value); if (!source) return null; return source.filter((entry) => isEntry(entry, isValid)); } /** * Is this an entry of the kind the list holds? An entry that lost a field on * the way to the disk does not come back - the view and the state model would * have to guess what is missing. * * @param {unknown} entry * @param {(entry:Record) => boolean} isValid * @returns {boolean} */ function isEntry(entry, isValid) { if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false; return isValid(/** @type {Record} */ (entry)); } /** * An entry the view can show - a history entry and a favourite have the same * shape: a text and a moment. * * @param {Record} entry * @returns {boolean} */ function isTextEntry(entry) { return isText(entry.id) && isText(entry.text) && isTime(entry.at); } /** * A queue entry the state model can take. * * `createdAt` is what state.js insists on - without it the model throws - and * the state has to be one it knows: an entry with a state of its own would * wait for ever, and one that lost its state could be sent a second time. * * @param {Record} entry * @returns {boolean} */ function isQueueEntry(entry) { return ( isText(entry.id) && isText(entry.text) && isTime(entry.createdAt) && QUEUE_STATES.has(entry.state) ); } /** Is this a text? */ function isText(value) { return typeof value === "string"; } /** Is this a moment in time (epoch ms)? */ function isTime(value) { return typeof value === "number" && Number.isFinite(value); } /** * The list a value holds: the value itself, or the `items` of the envelope * the design wrote down (`{ items: [ … ] }`). * * @param {unknown} value * @returns {unknown[]|null} */ function listSource(value) { if (Array.isArray(value)) return value; if (!value || typeof value !== "object") return null; const envelope = /** @type {{items?: unknown}} */ (value); return Array.isArray(envelope.items) ? envelope.items : null; } /** * Read a value from the store. A store that fails gives nothing. * * @param {Store} store * @param {string} key * @returns {unknown} */ function read(store, key) { try { if (!store || typeof store.get !== "function") return null; const value = store.get(key); return value ?? null; } catch { return null; } } /** * Write a value into the store. A store that cannot be written to throws - * the queue on disk is what keeps a crash from sending a message twice. * * @param {Store} store * @param {string} key * @param {unknown} value * @returns {void} */ function write(store, key, value) { if (!store || typeof store.set !== "function") { throw new TypeError(`brak magazynu dla klucza ${key}`); } store.set(key, value); }