@aragon-agent/cli 0.6.35 → 0.6.37

package/dist/prompts/search.js

@@ -0,0 +1,146 @@
+/**
+ * Filtering and view ordering for the picker (quick-prompt-library D-9 / D-10).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * SUBSEQUENCE MATCHING, NOT SUBSTRING MATCHING. `clr` should find `clean code
+ * review`, and Chinese titles make the same demand in a different shape: the
+ * characters a user remembers are rarely contiguous. The query is matched
+ * case-insensitively against the title, then the tags, then the description, and
+ * the FIELD a match landed in is a stronger signal than how good the match was.
+ *
+ * NO CHARACTER HIGHLIGHTING (D-10). Colouring the matched characters would mean
+ * splitting a row into styled runs, and every row in this package is one
+ * `wrap="truncate"` `<Text>` precisely so its height is exactly one row. The
+ * detail block answers "why did this match" instead.
+ */
+/** How much worse a match in tags, or in the description, is than in the title. */
+const TAG_PENALTY = 1_000;
+const DESCRIPTION_PENALTY = 2_000;
+/**
+ * Greedy subsequence match; `null` when `query` is not a subsequence of `text`.
+ *
+ * The score is LOWER-is-better and is built from what a reader would actually
+ * call a good match: how early the first hit is, how tightly the hits cluster,
+ * and how many characters had to be skipped between them.
+ */
+export function subsequenceScore(text, query) {
+    if (query.length === 0)
+        return 0;
+    const haystack = text.toLowerCase();
+    const needle = query.toLowerCase();
+    let at = 0;
+    let first = -1;
+    let last = -1;
+    let gaps = 0;
+    for (const char of needle) {
+        const hit = haystack.indexOf(char, at);
+        if (hit === -1)
+            return null;
+        if (first === -1)
+            first = hit;
+        else if (hit > last + 1)
+            gaps += hit - last - 1;
+        last = hit;
+        at = hit + 1;
+    }
+    const span = last - first + 1;
+    return first * 4 + gaps * 2 + (span - needle.length);
+}
+function fieldScore(prompt, query) {
+    const title = subsequenceScore(prompt.title, query);
+    if (title !== null)
+        return title;
+    let best = null;
+    for (const tag of prompt.tags ?? []) {
+        const score = subsequenceScore(tag, query);
+        if (score !== null && (best === null || score < best))
+            best = score;
+    }
+    if (best !== null)
+        return TAG_PENALTY + best;
+    const description = prompt.description;
+    if (description === undefined)
+        return null;
+    const score = subsequenceScore(description, query);
+    return score === null ? null : DESCRIPTION_PENALTY + score;
+}
+/**
+ * Filter, but NEVER REORDER BEYOND WHAT THE QUERY EARNS.
+ *
+ * Ties keep the library's own order, because a filter that reshuffles entries with
+ * equal scores makes the list move under the user's arrow keys while they type.
+ * Favourites win ties, which is the only preference the picker states.
+ */
+export function searchPrompts(prompts, query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return prompts.map((prompt) => ({ prompt, score: 0 }));
+    const hits = [];
+    for (let at = 0; at < prompts.length; at += 1) {
+        const prompt = prompts[at];
+        const score = fieldScore(prompt, trimmed);
+        if (score !== null)
+            hits.push({ prompt, score, at });
+    }
+    hits.sort((a, b) => {
+        const favourite = (b.prompt.favorite === true ? 1 : 0) - (a.prompt.favorite === true ? 1 : 0);
+        if (favourite !== 0)
+            return favourite;
+        if (a.score !== b.score)
+            return a.score - b.score;
+        return a.at - b.at;
+    });
+    return hits.map(({ prompt, score }) => ({ prompt, score }));
+}
+/**
+ * The three presentations (D-9).
+ *
+ * `manual` is the only persisted order; the other two are VANISHING views. The one
+ * that rearranges is `favorite` - `recent` sorts by `lastUsedAt` only, so an entry
+ * that has never been used keeps its place at the tail instead of jumping around
+ * while the user watches.
+ */
+export function viewOrder(prompts, view) {
+    if (view === 'manual')
+        return [...prompts];
+    const indexed = prompts.map((prompt, at) => ({ prompt, at }));
+    if (view === 'favorite') {
+        indexed.sort((a, b) => {
+            const favourite = (b.prompt.favorite === true ? 1 : 0) - (a.prompt.favorite === true ? 1 : 0);
+            return favourite !== 0 ? favourite : a.at - b.at;
+        });
+        return indexed.map(({ prompt }) => prompt);
+    }
+    indexed.sort((a, b) => {
+        const recent = (b.prompt.lastUsedAt ?? 0) - (a.prompt.lastUsedAt ?? 0);
+        return recent !== 0 ? recent : a.at - b.at;
+    });
+    return indexed.map(({ prompt }) => prompt);
+}
+/** The next view in the `Ctrl+S` cycle (manual -> recent -> favorite -> manual). */
+export function nextView(view) {
+    if (view === 'manual')
+        return 'recent';
+    if (view === 'recent')
+        return 'favorite';
+    return 'manual';
+}
+/**
+ * Title order, for the `/prompts sort name` write.
+ *
+ * A TOTAL order (title, then id): a sort the user asked for has to be reproducible, and
+ * two entries sharing a title would otherwise swap places between runs - a "sorted"
+ * library that reorders itself on every read is worse than an unsorted one. Code-unit
+ * comparison rather than `localeCompare`, because the file is written on one machine and
+ * read on the next, and a locale-dependent order would silently rewrite the user's
+ * sequence on a different machine for no reason they could see.
+ */
+export function sortedPromptTitleOrder(prompts) {
+    const compare = (a, b) => {
+        if (a.title !== b.title)
+            return a.title < b.title ? -1 : 1;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    };
+    return [...prompts].sort(compare);
+}

package/dist/prompts/store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The quick-prompt library's ONLY read/write authority (quick-prompt-library D-3,
+ * D-4, D-14, I-6).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * EVERY MUTATION IS: read the current file, apply ONE pure change, write the whole
+ * library atomically. No lock (D-14) - this is the strategy `ui-state.ts` and
+ * `prompt-history.ts` already use, and a stale lock is a worse failure than two
+ * concurrent TUIs overwriting each other's order once.
+ *
+ * NOTHING HERE THROWS (D-4). A corrupt file becomes a `.bak` copy plus an empty
+ * library; an unwritable file becomes `write_failed` while the new value STAYS IN
+ * MEMORY, because rolling back would make the prompt the user just typed vanish
+ * from the screen it was typed on.
+ *
+ * THE SNAPSHOT IS THE RESULT. Every mutation returns the new `PromptLibrary`, and
+ * that is what `App` renders. A component that computed its own optimistic library
+ * would be a second truth (I-6).
+ */
+import type { PromptDraftInput, PromptDraftVerdict, PromptLibrary, PromptMutationResult, PromptSortKey } from './types.js';
+/**
+ * What the last read had to repair.
+ *
+ * `'entries'` is not a repair of the FILE: it counts entries that were dropped while the
+ * file itself was readable. The caller says something different for it ("N records were
+ * skipped" rather than "the file was backed up"), and folding the two together would
+ * promise a `.bak` that does not exist.
+ */
+type PromptRepair = {
+    dropped: number;
+    repaired: 'schema' | 'parse' | 'entries';
+};
+/**
+ * Validate one draft, at the boundary where a draft becomes data (I-5).
+ *
+ * The editor calls this too, so the code that decides "that title is too long" and
+ * the code that decides which ROW owns the error cannot disagree - which is why it
+ * lives here rather than in the view model.
+ */
+export declare function validatePromptDraft(input: PromptDraftInput): PromptDraftVerdict;
+/** Parsed tags from the editor's raw comma/space separated field. Never throws. */
+export declare function parsePromptTags(raw: string): string[];
+/** Read the cached snapshot, loading it once per process. Never throws. */
+export declare function loadPromptLibrary(): PromptLibrary;
+/**
+ * One-shot report of a repair or of dropped entries (§8).
+ *
+ * READ, AND CLEARED: the caller shows it once and the next caller gets `null`. A
+ * standing flag would make every later render believe the file is still broken.
+ */
+export declare function takePromptRepairNotice(): PromptRepair | null;
+/** Monotonic count of successful writes (I-3). Tests assert "one change, one write". */
+export declare function getPromptLibraryRevision(): number;
+export declare function createPrompt(input: PromptDraftInput, now?: number): PromptMutationResult;
+export declare function updatePrompt(id: string, patch: Partial<PromptDraftInput>, now?: number): PromptMutationResult;
+export declare function deletePrompt(id: string): PromptMutationResult;
+/** Swap one entry with its neighbour. A no-op at either end is a refusal, not a write. */
+export declare function movePrompt(id: string, delta: -1 | 1): PromptMutationResult;
+/** Move one entry to a 0-based absolute position (`/prompts move <ref> <to>`). */
+export declare function reorderPrompt(fromIndex: number, toIndex: number): PromptMutationResult;
+/**
+ * Replace the whole manual order in ONE write (`/prompts sort`).
+ *
+ * A sibling of `reorderPrompt` rather than a loop over it, because a sort touches
+ * every position: calling the single-move function N times would rewrite the whole
+ * library N times, which is the write amplification R-2 exists to bound.
+ */
+export declare function reorderPrompts(ids: readonly string[]): PromptMutationResult;
+/**
+ * The ids `/prompts sort <key>` should write, in the order it should write them.
+ *
+ * `name` is title order, `recent` and `favorite` are the two views promoted to a
+ * persistent order. It returns IDS rather than a library so the caller can hand them
+ * straight to `reorderPrompts`, which is the one function that writes a whole order in a
+ * single pass (R-2).
+ */
+export declare function sortPromptIds(library: PromptLibrary, key: PromptSortKey): string[];
+export declare function setPromptFavorite(id: string, favorite: boolean, now?: number): PromptMutationResult;
+/** In-memory usage bump; the write is debounced (D-7). */
+export declare function recordPromptUse(id: string, now?: number): void;
+/** Write pending counters now. Idempotent: a clean library writes nothing. */
+export declare function flushPromptStats(now?: number): void;
+/** Test-only: forget the cache, the counters and the revision. */
+export declare function resetPromptLibraryForTests(): void;
+export {};

package/dist/prompts/store.js

@@ -0,0 +1,453 @@
+/**
+ * The quick-prompt library's ONLY read/write authority (quick-prompt-library D-3,
+ * D-4, D-14, I-6).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * EVERY MUTATION IS: read the current file, apply ONE pure change, write the whole
+ * library atomically. No lock (D-14) - this is the strategy `ui-state.ts` and
+ * `prompt-history.ts` already use, and a stale lock is a worse failure than two
+ * concurrent TUIs overwriting each other's order once.
+ *
+ * NOTHING HERE THROWS (D-4). A corrupt file becomes a `.bak` copy plus an empty
+ * library; an unwritable file becomes `write_failed` while the new value STAYS IN
+ * MEMORY, because rolling back would make the prompt the user just typed vanish
+ * from the screen it was typed on.
+ *
+ * THE SNAPSHOT IS THE RESULT. Every mutation returns the new `PromptLibrary`, and
+ * that is what `App` renders. A component that computed its own optimistic library
+ * would be a second truth (I-6).
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import process from 'node:process';
+import { getHomeRoot, getQuickPromptsPath } from '../config/app-paths.js';
+import { PROMPT_LIMITS } from './limits.js';
+import { emptyPromptLibrary, normalizePromptLibrary } from './normalize.js';
+import { promptIndexOf } from './resolve.js';
+import { sortedPromptTitleOrder, viewOrder } from './search.js';
+/** How long usage counters may sit in memory before they are written (D-7). */
+const STATS_FLUSH_MS = 1000;
+/** Same suffix as `ui-state.ts`: one writer per pid, never a stale temp file. */
+const TMP_SUFFIX = 'tmp';
+let memory = null;
+let revision = 0;
+let statsDirty = false;
+let flushTimer = null;
+let pendingRepair = null;
+function codePoints(text) {
+    return [...text].length;
+}
+/**
+ * Validate one draft, at the boundary where a draft becomes data (I-5).
+ *
+ * The editor calls this too, so the code that decides "that title is too long" and
+ * the code that decides which ROW owns the error cannot disagree - which is why it
+ * lives here rather than in the view model.
+ */
+export function validatePromptDraft(input) {
+    const title = input.title.trim();
+    const content = input.content;
+    if (title.length === 0)
+        return { ok: false, code: 'title_required', field: 'title' };
+    if (codePoints(title) > PROMPT_LIMITS.titleMaxChars) {
+        return { ok: false, code: 'title_too_long', field: 'title' };
+    }
+    if (content.trim().length === 0)
+        return { ok: false, code: 'content_required', field: 'content' };
+    if (codePoints(content) > PROMPT_LIMITS.contentMaxChars) {
+        return { ok: false, code: 'content_too_long', field: 'content' };
+    }
+    const description = (input.description ?? '').trim();
+    if (codePoints(description) > PROMPT_LIMITS.descriptionMaxChars) {
+        return { ok: false, code: 'description_too_long', field: 'description' };
+    }
+    const tags = input.tags ?? [];
+    if (tags.length > PROMPT_LIMITS.maxTags) {
+        return { ok: false, code: 'too_many_tags', field: 'tags' };
+    }
+    if (tags.some((tag) => codePoints(tag) > PROMPT_LIMITS.tagMaxChars)) {
+        return { ok: false, code: 'tag_too_long', field: 'tags' };
+    }
+    const verdict = { title, content };
+    if (description.length > 0)
+        verdict.description = description;
+    if (tags.length > 0)
+        verdict.tags = [...tags];
+    if (input.favorite === true)
+        verdict.favorite = true;
+    return { ok: true, input: verdict };
+}
+/** Parsed tags from the editor's raw comma/space separated field. Never throws. */
+export function parsePromptTags(raw) {
+    const seen = new Set();
+    const tags = [];
+    for (const part of raw.split(/[,;\s]+/)) {
+        const tag = part.trim();
+        if (tag.length === 0 || seen.has(tag))
+            continue;
+        seen.add(tag);
+        tags.push(tag);
+        if (tags.length >= PROMPT_LIMITS.maxTags)
+            break;
+    }
+    return tags;
+}
+/** Copy the unreadable file aside once. Best effort: a failure here is not fatal. */
+function backupBrokenFile() {
+    const path = getQuickPromptsPath();
+    try {
+        copyFileSync(path, `${path}.bak`);
+    }
+    catch {
+        // A read-only directory is the same class of problem as the write failure
+        // below: report the empty library, keep the original file, do not throw.
+    }
+}
+/**
+ * Atomic replace, copied from `ui-state.ts:179-194`.
+ *
+ * `mkdirSync` first because `<home>` is not guaranteed to exist, and `chmodSync`
+ * after the rename because rename does not preserve the mode on every platform.
+ */
+function writeToDisk(library) {
+    const path = getQuickPromptsPath();
+    const tmp = `${path}.${TMP_SUFFIX}-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(library, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the value stays in memory (D-4).
+        }
+        return false;
+    }
+}
+function readFromDisk() {
+    const path = getQuickPromptsPath();
+    // THE FILE IS NOT CREATED ON READ (D-3): a user who never adds a prompt has no
+    // library file, and an empty list is the honest representation of that.
+    if (!existsSync(path))
+        return emptyPromptLibrary();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        backupBrokenFile();
+        pendingRepair = { dropped: 0, repaired: 'parse' };
+        return emptyPromptLibrary();
+    }
+    const result = normalizePromptLibrary(parsed);
+    if (result.repaired !== 'none') {
+        backupBrokenFile();
+        pendingRepair = { dropped: result.dropped, repaired: result.repaired };
+    }
+    else if (result.dropped > 0) {
+        // Readable file, unusable records: no `.bak` is written, because there is nothing
+        // wrong with the file to preserve - but the user still has to be told.
+        pendingRepair = { dropped: result.dropped, repaired: 'entries' };
+    }
+    return result.library;
+}
+/** Read the cached snapshot, loading it once per process. Never throws. */
+export function loadPromptLibrary() {
+    if (memory === null)
+        memory = readFromDisk();
+    return memory;
+}
+/**
+ * One-shot report of a repair or of dropped entries (§8).
+ *
+ * READ, AND CLEARED: the caller shows it once and the next caller gets `null`. A
+ * standing flag would make every later render believe the file is still broken.
+ */
+export function takePromptRepairNotice() {
+    const notice = pendingRepair;
+    pendingRepair = null;
+    return notice;
+}
+/** Monotonic count of successful writes (I-3). Tests assert "one change, one write". */
+export function getPromptLibraryRevision() {
+    return revision;
+}
+function stamp(library, now) {
+    return { ...library, updatedAt: Math.max(now, library.updatedAt + 1) };
+}
+function refuse(code, library) {
+    return { ok: false, code, library };
+}
+/**
+ * The single write path. `fn` must be pure: it may return a new library or a
+ * refusal, and it never touches the filesystem itself.
+ */
+function mutate(fn, now = Date.now()) {
+    // PENDING STATISTICS GO FIRST, or the fresh read below would drop the usage
+    // counts this process has already shown the user.
+    if (statsDirty)
+        flushPromptStats(now);
+    const current = readFromDisk();
+    const outcome = fn(current);
+    if (!outcome.ok) {
+        memory = current;
+        return refuse(outcome.code, current);
+    }
+    const next = stamp(outcome.library, now);
+    const written = writeToDisk(next);
+    memory = next;
+    // A FAILED WRITE IS STILL AN APPLIED CHANGE (D-4): `memory` already holds it, so
+    // rolling back would make the prompt the user just typed vanish from the screen it was
+    // typed on. Only `revision` - "how many times the DISK changed" - moves on success,
+    // which is exactly what the "one change, one write" assertions count.
+    if (!written)
+        return refuse('write_failed', next);
+    revision += 1;
+    return outcome.id === undefined
+        ? { ok: true, library: next }
+        : { ok: true, library: next, id: outcome.id };
+}
+function withPrompts(library, prompts) {
+    return { ...library, prompts };
+}
+function findEntry(library, id) {
+    return library.prompts.find((prompt) => prompt.id === id);
+}
+/** Apply a validated draft onto an existing entry, dropping the optional fields. */
+function applyDraft(entry, input, now) {
+    const next = {
+        ...entry,
+        title: input.title,
+        content: input.content,
+        updatedAt: Math.max(now, entry.updatedAt + 1),
+    };
+    if (input.description !== undefined)
+        next.description = input.description;
+    else
+        delete next.description;
+    if (input.tags !== undefined)
+        next.tags = [...input.tags];
+    else
+        delete next.tags;
+    if (input.favorite === true)
+        next.favorite = true;
+    else
+        delete next.favorite;
+    return next;
+}
+export function createPrompt(input, now = Date.now()) {
+    const verdict = validatePromptDraft(input);
+    if (!verdict.ok)
+        return refuse(verdict.code, loadPromptLibrary());
+    return mutate((current) => {
+        if (current.prompts.length >= PROMPT_LIMITS.maxPrompts) {
+            return { ok: false, code: 'too_many_prompts' };
+        }
+        const entry = {
+            id: randomUUID(),
+            title: verdict.input.title,
+            content: verdict.input.content,
+            useCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        if (verdict.input.description !== undefined)
+            entry.description = verdict.input.description;
+        if (verdict.input.tags !== undefined)
+            entry.tags = [...verdict.input.tags];
+        if (verdict.input.favorite === true)
+            entry.favorite = true;
+        return {
+            ok: true,
+            library: withPrompts(current, [...current.prompts, entry]),
+            id: entry.id,
+        };
+    }, now);
+}
+export function updatePrompt(id, patch, now = Date.now()) {
+    return mutate((current) => {
+        const entry = findEntry(current, id);
+        if (!entry)
+            return { ok: false, code: 'not_found' };
+        // A PARTIAL PATCH, merged over the stored entry BEFORE validation: `/prompts edit`
+        // sends whole drafts, but the store's own contract (and every test) may send one
+        // field, and validating `{ title }` alone would answer `content_required`.
+        const merged = {
+            title: patch.title ?? entry.title,
+            content: patch.content ?? entry.content,
+        };
+        const description = patch.description ?? entry.description;
+        if (description !== undefined)
+            merged.description = description;
+        const tags = patch.tags ?? entry.tags;
+        if (tags !== undefined)
+            merged.tags = [...tags];
+        const favorite = patch.favorite ?? entry.favorite;
+        if (favorite !== undefined)
+            merged.favorite = favorite;
+        const verdict = validatePromptDraft(merged);
+        if (!verdict.ok)
+            return { ok: false, code: verdict.code };
+        return {
+            ok: true,
+            library: withPrompts(current, current.prompts.map((prompt) => prompt.id === id ? applyDraft(entry, verdict.input, now) : prompt)),
+            id,
+        };
+    }, now);
+}
+export function deletePrompt(id) {
+    return mutate((current) => {
+        if (!findEntry(current, id))
+            return { ok: false, code: 'not_found' };
+        return {
+            ok: true,
+            library: withPrompts(current, current.prompts.filter((prompt) => prompt.id !== id)),
+            id,
+        };
+    });
+}
+/** Swap one entry with its neighbour. A no-op at either end is a refusal, not a write. */
+export function movePrompt(id, delta) {
+    return mutate((current) => {
+        const at = promptIndexOf(current, id);
+        if (at < 0)
+            return { ok: false, code: 'not_found' };
+        const to = at + delta;
+        if (to < 0 || to >= current.prompts.length) {
+            return { ok: false, code: 'not_found' };
+        }
+        const prompts = [...current.prompts];
+        const [entry] = prompts.splice(at, 1);
+        prompts.splice(to, 0, entry);
+        return { ok: true, library: withPrompts(current, prompts), id };
+    });
+}
+/** Move one entry to a 0-based absolute position (`/prompts move <ref> <to>`). */
+export function reorderPrompt(fromIndex, toIndex) {
+    return mutate((current) => {
+        if (fromIndex < 0 || fromIndex >= current.prompts.length) {
+            return { ok: false, code: 'not_found' };
+        }
+        if (toIndex < 0 || toIndex >= current.prompts.length) {
+            return { ok: false, code: 'not_found' };
+        }
+        const moving = current.prompts[fromIndex];
+        if (fromIndex === toIndex) {
+            return { ok: true, library: current, id: moving.id };
+        }
+        const prompts = [...current.prompts];
+        const [entry] = prompts.splice(fromIndex, 1);
+        prompts.splice(toIndex, 0, entry);
+        return { ok: true, library: withPrompts(current, prompts), id: moving.id };
+    });
+}
+/**
+ * Replace the whole manual order in ONE write (`/prompts sort`).
+ *
+ * A sibling of `reorderPrompt` rather than a loop over it, because a sort touches
+ * every position: calling the single-move function N times would rewrite the whole
+ * library N times, which is the write amplification R-2 exists to bound.
+ */
+export function reorderPrompts(ids) {
+    return mutate((current) => {
+        const byId = new Map(current.prompts.map((prompt) => [prompt.id, prompt]));
+        const prompts = [];
+        for (const id of ids) {
+            const entry = byId.get(id);
+            if (!entry)
+                continue;
+            prompts.push(entry);
+            byId.delete(id);
+        }
+        // Anything the caller did not name keeps its relative position at the tail
+        // rather than being dropped: a lost entry is data loss, a tail position is a
+        // cosmetic surprise.
+        for (const entry of current.prompts)
+            if (byId.has(entry.id))
+                prompts.push(entry);
+        return { ok: true, library: withPrompts(current, prompts) };
+    });
+}
+/**
+ * The ids `/prompts sort <key>` should write, in the order it should write them.
+ *
+ * `name` is title order, `recent` and `favorite` are the two views promoted to a
+ * persistent order. It returns IDS rather than a library so the caller can hand them
+ * straight to `reorderPrompts`, which is the one function that writes a whole order in a
+ * single pass (R-2).
+ */
+export function sortPromptIds(library, key) {
+    const ordered = key === 'name'
+        ? sortedPromptTitleOrder(library.prompts)
+        : viewOrder(library.prompts, key);
+    return ordered.map((prompt) => prompt.id);
+}
+export function setPromptFavorite(id, favorite, now = Date.now()) {
+    return mutate((current) => {
+        const entry = findEntry(current, id);
+        if (!entry)
+            return { ok: false, code: 'not_found' };
+        const replacement = { ...entry, updatedAt: Math.max(now, entry.updatedAt + 1) };
+        if (favorite)
+            replacement.favorite = true;
+        else
+            delete replacement.favorite;
+        return {
+            ok: true,
+            library: withPrompts(current, current.prompts.map((prompt) => (prompt.id === id ? replacement : prompt))),
+            id,
+        };
+    }, now);
+}
+/** In-memory usage bump; the write is debounced (D-7). */
+export function recordPromptUse(id, now = Date.now()) {
+    const current = loadPromptLibrary();
+    const at = promptIndexOf(current, id);
+    if (at < 0)
+        return;
+    const entry = current.prompts[at];
+    const prompts = [...current.prompts];
+    prompts[at] = { ...entry, useCount: entry.useCount + 1, lastUsedAt: now };
+    memory = withPrompts(current, prompts);
+    statsDirty = true;
+    if (flushTimer)
+        return;
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flushPromptStats();
+    }, STATS_FLUSH_MS);
+    flushTimer.unref?.();
+}
+/** Write pending counters now. Idempotent: a clean library writes nothing. */
+export function flushPromptStats(now = Date.now()) {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    if (!statsDirty || memory === null)
+        return;
+    const next = stamp(memory, now);
+    const written = writeToDisk(next);
+    memory = next;
+    statsDirty = false;
+    if (written)
+        revision += 1;
+}
+/** Test-only: forget the cache, the counters and the revision. */
+export function resetPromptLibraryForTests() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    memory = null;
+    revision = 0;
+    statsDirty = false;
+    pendingRepair = null;
+}