@aragon-agent/cli 0.6.35 → 0.6.37

package/dist/prompts/fill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * How a prompt lands in the composer (quick-prompt-library D-6 / §4.6).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * PURE, AND IT KNOWS NOTHING ABOUT THE DRAFT'S REAL SHAPE. It is handed the current
+ * buffer and caret, and it answers "what should be inserted, or what should the new
+ * buffer be". It deliberately does NOT return the resulting buffer: a draft may
+ * hold paste-collapse TOKENS (`[Pasted text #1 +8 lines]` plus a payload map), so
+ * "the buffer after applying this plan" is a fact only `editorReducer` can compute.
+ * Recomputing it here would be a second authority, and the two would drift exactly
+ * on the drafts this feature exists to append to.
+ *
+ * WHY `insert` IS THE DEFAULT (and why the decision lives here rather than in
+ * `App`): the only place that knows what the draft currently holds is the editor
+ * (the host has no copy of the text), and silently discarding what someone has
+ * already typed is the one thing a "fill" gesture must never do.
+ */
+export interface PromptFillInput {
+    /** The current draft buffer. */
+    draft: string;
+    /** Caret offset into `draft`, in UTF-16 units. */
+    cursor: number;
+    /** The prompt body. */
+    content: string;
+    /** `insert` unless the user configured `prompts.insertMode = 'replace'` (D-19). */
+    mode?: 'insert' | 'replace';
+}
+export interface PromptFillPlan {
+    mode: 'replace' | 'insert';
+    /**
+     * `replace`: the new buffer in full.
+     * `insert`: only the fragment to insert, separators included.
+     */
+    text: string;
+    /**
+     * `replace`: where the caret goes afterwards (past the body).
+     * `insert`: ignored - the reducer owns the caret and the token snapping.
+     */
+    cursor: number;
+}
+/**
+ * Decide between replacing and inserting, and build the fragment.
+ *
+ * A blank draft is replaced even in `insert` mode: "insert at the caret" into an
+ * empty buffer and "replace the empty buffer" are the same edit, and saying so
+ * keeps the caller from having to special-case it.
+ */
+export declare function planPromptFill(input: PromptFillInput): PromptFillPlan;
+/** Lines a body occupies, for the "8 lines, editable" acknowledgement. */
+export declare function promptLineCount(content: string): number;

package/dist/prompts/fill.js

@@ -0,0 +1,46 @@
+/**
+ * How a prompt lands in the composer (quick-prompt-library D-6 / §4.6).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * PURE, AND IT KNOWS NOTHING ABOUT THE DRAFT'S REAL SHAPE. It is handed the current
+ * buffer and caret, and it answers "what should be inserted, or what should the new
+ * buffer be". It deliberately does NOT return the resulting buffer: a draft may
+ * hold paste-collapse TOKENS (`[Pasted text #1 +8 lines]` plus a payload map), so
+ * "the buffer after applying this plan" is a fact only `editorReducer` can compute.
+ * Recomputing it here would be a second authority, and the two would drift exactly
+ * on the drafts this feature exists to append to.
+ *
+ * WHY `insert` IS THE DEFAULT (and why the decision lives here rather than in
+ * `App`): the only place that knows what the draft currently holds is the editor
+ * (the host has no copy of the text), and silently discarding what someone has
+ * already typed is the one thing a "fill" gesture must never do.
+ */
+/** Two newlines, so the typed text and the prompt read as two paragraphs. */
+const SEPARATOR = '\n\n';
+/**
+ * Decide between replacing and inserting, and build the fragment.
+ *
+ * A blank draft is replaced even in `insert` mode: "insert at the caret" into an
+ * empty buffer and "replace the empty buffer" are the same edit, and saying so
+ * keeps the caller from having to special-case it.
+ */
+export function planPromptFill(input) {
+    const cursor = Math.max(0, Math.min(input.draft.length, Math.floor(input.cursor)));
+    const blank = input.draft.trim().length === 0;
+    if (input.mode === 'replace' || blank) {
+        return { mode: 'replace', text: input.content, cursor: input.content.length };
+    }
+    const before = input.draft.slice(0, cursor);
+    const after = input.draft.slice(cursor);
+    // A SEPARATOR IS ADDED ONLY WHERE ONE IS MISSING, which is what keeps the plan
+    // from producing three newlines when the caret already sits on a blank line.
+    const lead = before.length > 0 && !before.endsWith(SEPARATOR) ? SEPARATOR : '';
+    const trail = after.length > 0 && !after.startsWith(SEPARATOR) ? SEPARATOR : '';
+    const text = `${lead}${input.content}${trail}`;
+    return { mode: 'insert', text, cursor: cursor + lead.length };
+}
+/** Lines a body occupies, for the "8 lines, editable" acknowledgement. */
+export function promptLineCount(content) {
+    return content.split('\n').length;
+}

package/dist/prompts/limits.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Structural bounds for the quick-prompt library (quick-prompt-library §5.1).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY (index.md:52-56). Nothing here is user-tunable: these are
+ * what an entry, the library and the picker's query can physically carry. The
+ * three keys a user may actually change (`prompts.enabled`, `insertMode`, `hint`)
+ * live in `config/schema.ts`, are clamped there, and are persisted there. Mixing
+ * the two is how a "temporary" ceiling becomes a setting nobody clamps.
+ *
+ * EVERY NUMBER IS A CODE-POINT COUNT, not a byte count and not a UTF-16 length.
+ * Titles and bodies are typed in Chinese by the users this feature exists for, so
+ * a byte-based ceiling would silently allow a third of the characters a
+ * Latin-alphabet user gets. `[...text].length` is the measurement everywhere in
+ * this tree.
+ */
+export declare const PROMPT_LIMITS: {
+    /** Entries one library may hold. The 201st create is REFUSED, never truncated. */
+    readonly maxPrompts: 200;
+    /** Title, without surrounding whitespace. */
+    readonly titleMaxChars: 80;
+    /** Body. Large enough for a 40-line procedure, small enough to rewrite cheaply. */
+    readonly contentMaxChars: 8000;
+    /** Optional one-line note under the title. */
+    readonly descriptionMaxChars: 200;
+    /** Tags per entry. */
+    readonly maxTags: 6;
+    /** Characters per tag. */
+    readonly tagMaxChars: 24;
+    /** Body preview lines the list page's detail block may spend (read-only). */
+    readonly detailPreviewLines: 3;
+    /** Rows the list page's detail block may occupy, preview lines included. */
+    readonly detailMaxLines: 6;
+    /** Characters of a body shown on ONE preview line. */
+    readonly previewLineChars: 72;
+};
+/**
+ * The picker's own structural bounds.
+ *
+ * A SEPARATE OBJECT because the picker is a separate surface with a separate
+ * budget: its rows carry an index and a title and nothing else, and its query is
+ * a filter rather than content. Sharing one object would tie a future change to
+ * the library's row height.
+ */
+export declare const PROMPT_PICKER_LIMITS: {
+    /** Longest query the filter accepts; further typing is ignored. */
+    readonly queryMaxChars: 64;
+    /** `1`-`9` pick directly, so nine. */
+    readonly quickDigits: 9;
+    /** Rows the picker's detail block may occupy. */
+    readonly detailMaxLines: 4;
+};

package/dist/prompts/limits.js

@@ -0,0 +1,53 @@
+/**
+ * Structural bounds for the quick-prompt library (quick-prompt-library §5.1).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY (index.md:52-56). Nothing here is user-tunable: these are
+ * what an entry, the library and the picker's query can physically carry. The
+ * three keys a user may actually change (`prompts.enabled`, `insertMode`, `hint`)
+ * live in `config/schema.ts`, are clamped there, and are persisted there. Mixing
+ * the two is how a "temporary" ceiling becomes a setting nobody clamps.
+ *
+ * EVERY NUMBER IS A CODE-POINT COUNT, not a byte count and not a UTF-16 length.
+ * Titles and bodies are typed in Chinese by the users this feature exists for, so
+ * a byte-based ceiling would silently allow a third of the characters a
+ * Latin-alphabet user gets. `[...text].length` is the measurement everywhere in
+ * this tree.
+ */
+export const PROMPT_LIMITS = {
+    /** Entries one library may hold. The 201st create is REFUSED, never truncated. */
+    maxPrompts: 200,
+    /** Title, without surrounding whitespace. */
+    titleMaxChars: 80,
+    /** Body. Large enough for a 40-line procedure, small enough to rewrite cheaply. */
+    contentMaxChars: 8000,
+    /** Optional one-line note under the title. */
+    descriptionMaxChars: 200,
+    /** Tags per entry. */
+    maxTags: 6,
+    /** Characters per tag. */
+    tagMaxChars: 24,
+    /** Body preview lines the list page's detail block may spend (read-only). */
+    detailPreviewLines: 3,
+    /** Rows the list page's detail block may occupy, preview lines included. */
+    detailMaxLines: 6,
+    /** Characters of a body shown on ONE preview line. */
+    previewLineChars: 72,
+};
+/**
+ * The picker's own structural bounds.
+ *
+ * A SEPARATE OBJECT because the picker is a separate surface with a separate
+ * budget: its rows carry an index and a title and nothing else, and its query is
+ * a filter rather than content. Sharing one object would tie a future change to
+ * the library's row height.
+ */
+export const PROMPT_PICKER_LIMITS = {
+    /** Longest query the filter accepts; further typing is ignored. */
+    queryMaxChars: 64,
+    /** `1`-`9` pick directly, so nine. */
+    quickDigits: 9,
+    /** Rows the picker's detail block may occupy. */
+    detailMaxLines: 4,
+};

package/dist/prompts/normalize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Reading the library off disk without trusting it (quick-prompt-library D-4).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE FIELD'S NONSENSE MUST NOT TAKE ANOTHER ENTRY WITH IT. `config/ui-state.ts`
+ * wrote that rule for a two-field file; this is the same rule one level up, for a
+ * file the user may hand-edit and one bad character in which would otherwise cost
+ * them two hundred prompts. So every entry is normalised on its own, an entry that
+ * is structurally unusable is DROPPED AND COUNTED, and the top-level file is only
+ * discarded when its shape is unknown (a parse failure or a `schema` that is not
+ * `1`).
+ *
+ * LENGTH IS CLAMPED HERE, NOT ENFORCED. The write path refuses an over-long title
+ * (`PromptWriteError`) because the user can still fix it; the read path clamps,
+ * because by then the text is the only copy and dropping the entry to protect a
+ * ceiling would delete the user's work to keep a number tidy.
+ */
+import type { PromptLibrary, QuickPrompt } from './types.js';
+/**
+ * One entry, or `null` when it cannot be salvaged.
+ *
+ * `id` IS REPAIRED, NOT TRUSTED. A duplicate id would make `{kind:'edit', id}`
+ * ambiguous and `deletePrompt(id)` delete two entries, so the caller passes the
+ * ids it has already claimed and an unrepairable one is replaced here.
+ */
+export declare function normalizePrompt(raw: unknown, now?: number): QuickPrompt | null;
+export interface NormalisedLibrary {
+    library: PromptLibrary;
+    /** Entries that could not be salvaged, for the one-shot notice (§8). */
+    dropped: number;
+    /** Why the whole file was discarded. `'none'` means it was usable. */
+    repaired: 'none' | 'schema' | 'parse';
+}
+/**
+ * The whole file, with per-entry tolerance and one repair verdict.
+ *
+ * `repaired` is what the store uses to decide whether to write the `.bak` copy;
+ * keeping the verdict in the return value rather than in the store means the pure
+ * function stays pure and the decision stays testable.
+ */
+export declare function normalizePromptLibrary(raw: unknown, now?: number): NormalisedLibrary;
+/**
+ * The canonical "most useful first" comparison (`/prompts sort favorite`).
+ *
+ * Favourite, then most used, then most recent, then title, then id. The last two
+ * are not decoration: without a total order two entries with identical counters
+ * would swap places between calls, and a "sorted" library that reorders itself on
+ * every read is worse than an unsorted one.
+ */
+export declare function comparePrompts(a: QuickPrompt, b: QuickPrompt): number;
+/** Test seam: `normalize.ts` owns no state, but the name keeps the call sites honest. */
+export declare function emptyPromptLibrary(): PromptLibrary;

package/dist/prompts/normalize.js

@@ -0,0 +1,190 @@
+/**
+ * Reading the library off disk without trusting it (quick-prompt-library D-4).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE FIELD'S NONSENSE MUST NOT TAKE ANOTHER ENTRY WITH IT. `config/ui-state.ts`
+ * wrote that rule for a two-field file; this is the same rule one level up, for a
+ * file the user may hand-edit and one bad character in which would otherwise cost
+ * them two hundred prompts. So every entry is normalised on its own, an entry that
+ * is structurally unusable is DROPPED AND COUNTED, and the top-level file is only
+ * discarded when its shape is unknown (a parse failure or a `schema` that is not
+ * `1`).
+ *
+ * LENGTH IS CLAMPED HERE, NOT ENFORCED. The write path refuses an over-long title
+ * (`PromptWriteError`) because the user can still fix it; the read path clamps,
+ * because by then the text is the only copy and dropping the entry to protect a
+ * ceiling would delete the user's work to keep a number tidy.
+ */
+import { randomUUID } from 'node:crypto';
+import { PROMPT_LIMITS } from './limits.js';
+/** First `max` code points. */
+function clampText(text, max) {
+    const points = [...text];
+    return points.length <= max ? text : points.slice(0, max).join('');
+}
+/**
+ * Control characters except `\n` and `\t`, and `\r` folded into `\n`.
+ *
+ * A `\r` that survives reaches the renderer as a carriage return, which moves the
+ * caret to column 0 and overwrites the row it is on; a stray `\u0000` is a frame
+ * marker in this codebase and must never appear inside stored content.
+ */
+function sanitiseText(text) {
+    return text
+        .replace(/\r\n?/g, '\n')
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '');
+}
+function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function asCount(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+        return fallback;
+    return Math.floor(value);
+}
+function asTimestamp(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+/** Whitespace-folded, deduplicated, clamped, bounded. Order is preserved. */
+function normaliseTags(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const tags = [];
+    for (const raw of value) {
+        const text = asString(raw);
+        if (text === null)
+            continue;
+        const tag = clampText(text.trim().replace(/\s+/g, ' '), PROMPT_LIMITS.tagMaxChars);
+        if (tag.length === 0 || seen.has(tag))
+            continue;
+        seen.add(tag);
+        tags.push(tag);
+        if (tags.length >= PROMPT_LIMITS.maxTags)
+            break;
+    }
+    return tags;
+}
+/**
+ * One entry, or `null` when it cannot be salvaged.
+ *
+ * `id` IS REPAIRED, NOT TRUSTED. A duplicate id would make `{kind:'edit', id}`
+ * ambiguous and `deletePrompt(id)` delete two entries, so the caller passes the
+ * ids it has already claimed and an unrepairable one is replaced here.
+ */
+export function normalizePrompt(raw, now = Date.now()) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const src = raw;
+    const titleRaw = asString(src.title);
+    const contentRaw = asString(src.content);
+    if (titleRaw === null || contentRaw === null)
+        return null;
+    const title = clampText(sanitiseText(titleRaw).trim(), PROMPT_LIMITS.titleMaxChars);
+    const content = clampText(sanitiseText(contentRaw), PROMPT_LIMITS.contentMaxChars);
+    // I-5: neither field is ever the empty string, so an entry with no body left
+    // after sanitising is not an entry.
+    if (title.length === 0 || content.trim().length === 0)
+        return null;
+    const id = asString(src.id);
+    const description = clampText(sanitiseText(asString(src.description) ?? '').trim(), PROMPT_LIMITS.descriptionMaxChars);
+    const createdAt = asTimestamp(src.createdAt, now);
+    const updatedAt = asTimestamp(src.updatedAt, createdAt);
+    const entry = {
+        id: id !== null && id.trim().length > 0 ? id : randomUUID(),
+        title,
+        content,
+        useCount: asCount(src.useCount, 0),
+        createdAt,
+        updatedAt: Math.max(createdAt, updatedAt),
+    };
+    if (description.length > 0)
+        entry.description = description;
+    const tags = normaliseTags(src.tags);
+    if (tags.length > 0)
+        entry.tags = tags;
+    if (src.favorite === true)
+        entry.favorite = true;
+    const lastUsedAt = asTimestamp(src.lastUsedAt, 0);
+    if (lastUsedAt > 0)
+        entry.lastUsedAt = lastUsedAt;
+    return entry;
+}
+/**
+ * The whole file, with per-entry tolerance and one repair verdict.
+ *
+ * `repaired` is what the store uses to decide whether to write the `.bak` copy;
+ * keeping the verdict in the return value rather than in the store means the pure
+ * function stays pure and the decision stays testable.
+ */
+export function normalizePromptLibrary(raw, now = Date.now()) {
+    const empty = (repaired) => ({
+        library: { schema: 1, prompts: [], updatedAt: 0 },
+        dropped: 0,
+        repaired,
+    });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return empty('parse');
+    const src = raw;
+    // A `schema` mismatch DISCARDS NOTHING on disk: the store copies the file to
+    // `<name>.bak` first (D-4). Reporting an empty library here is about the shape
+    // this process can read, not about what the user is allowed to get back.
+    if (src.schema !== 1)
+        return empty('schema');
+    if (!Array.isArray(src.prompts))
+        return empty('parse');
+    const entries = src.prompts;
+    const prompts = [];
+    const claimed = new Set();
+    let dropped = 0;
+    for (let at = 0; at < entries.length; at += 1) {
+        if (prompts.length >= PROMPT_LIMITS.maxPrompts) {
+            // THE CEILING APPLIES ON READ TOO, and the leftovers are COUNTED rather than
+            // silently forgotten: a hand-edited 300-entry file would lose 100 entries on
+            // the next write, so the user has to be told that this happened.
+            dropped += entries.length - at;
+            break;
+        }
+        const entry = normalizePrompt(entries[at], now);
+        if (!entry) {
+            dropped += 1;
+            continue;
+        }
+        if (claimed.has(entry.id))
+            entry.id = randomUUID();
+        claimed.add(entry.id);
+        prompts.push(entry);
+    }
+    return {
+        library: { schema: 1, prompts, updatedAt: asTimestamp(src.updatedAt, 0) },
+        dropped,
+        repaired: 'none',
+    };
+}
+/**
+ * The canonical "most useful first" comparison (`/prompts sort favorite`).
+ *
+ * Favourite, then most used, then most recent, then title, then id. The last two
+ * are not decoration: without a total order two entries with identical counters
+ * would swap places between calls, and a "sorted" library that reorders itself on
+ * every read is worse than an unsorted one.
+ */
+export function comparePrompts(a, b) {
+    if ((a.favorite === true) !== (b.favorite === true))
+        return a.favorite === true ? -1 : 1;
+    if (a.useCount !== b.useCount)
+        return b.useCount - a.useCount;
+    const recent = (b.lastUsedAt ?? 0) - (a.lastUsedAt ?? 0);
+    if (recent !== 0)
+        return recent;
+    if (a.title !== b.title)
+        return a.title < b.title ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Test seam: `normalize.ts` owns no state, but the name keeps the call sites honest. */
+export function emptyPromptLibrary() {
+    return { schema: 1, prompts: [], updatedAt: 0 };
+}

package/dist/prompts/resolve.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<n|title>` -> one entry (quick-prompt-library D-22).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * TITLES MAY REPEAT (I-2), so this function has exactly one job the command layer
+ * cannot do for itself: turn a possibly-ambiguous reference into either one entry
+ * or a NAMED failure with candidates. It never picks the first of several.
+ *
+ * WHY THAT IS NOT PEDANTRY: `/prompts rm <title>` has no recycle bin (D-13), so
+ * "the first of the two entries with that title" is a one-keystroke way to delete
+ * the wrong prompt - and the user would have no way to tell which one they had
+ * been talking to. A refusal that PRINTS the candidates costs one more command and
+ * keeps the data.
+ */
+import type { PromptLibrary, PromptRefResolution } from './types.js';
+/**
+ * Resolve a reference, in this fixed order:
+ *
+ *   1. a pure decimal number is a 1-based INDEX (never a title), because a script
+ *      that says `2` must never depend on what the second prompt is called;
+ *   2. an exact title (case-sensitive, surrounding whitespace removed);
+ *   3. a unique title PREFIX, so `clean` finds `clean code review`.
+ *
+ * A number that is out of range is `not_found` rather than falling through to the
+ * title rules: `0` and `999` are index mistakes, and treating them as titles would
+ * silently match a prompt literally named "999".
+ */
+export declare function resolvePromptRef(library: PromptLibrary, ref: string): PromptRefResolution;
+/** The index a resolved entry sits at, for the "3 days ago" style detail lines. */
+export declare function promptIndexOf(library: PromptLibrary, id: string): number;

package/dist/prompts/resolve.js

@@ -0,0 +1,60 @@
+/**
+ * `<n|title>` -> one entry (quick-prompt-library D-22).
+ *
+ * ASCII ONLY - `src/prompts/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * TITLES MAY REPEAT (I-2), so this function has exactly one job the command layer
+ * cannot do for itself: turn a possibly-ambiguous reference into either one entry
+ * or a NAMED failure with candidates. It never picks the first of several.
+ *
+ * WHY THAT IS NOT PEDANTRY: `/prompts rm <title>` has no recycle bin (D-13), so
+ * "the first of the two entries with that title" is a one-keystroke way to delete
+ * the wrong prompt - and the user would have no way to tell which one they had
+ * been talking to. A refusal that PRINTS the candidates costs one more command and
+ * keeps the data.
+ */
+/** How many candidates a refusal names. Five is what a terminal row shows. */
+const MAX_CANDIDATES = 5;
+function exactTitle(prompts, ref) {
+    return prompts.filter((prompt) => prompt.title === ref);
+}
+function prefixTitle(prompts, ref) {
+    return prompts.filter((prompt) => prompt.title.startsWith(ref));
+}
+function decide(matches) {
+    if (matches.length === 1)
+        return { ok: true, prompt: matches[0] };
+    if (matches.length === 0)
+        return { ok: false, code: 'not_found' };
+    return { ok: false, code: 'ambiguous', candidates: matches.slice(0, MAX_CANDIDATES) };
+}
+/**
+ * Resolve a reference, in this fixed order:
+ *
+ *   1. a pure decimal number is a 1-based INDEX (never a title), because a script
+ *      that says `2` must never depend on what the second prompt is called;
+ *   2. an exact title (case-sensitive, surrounding whitespace removed);
+ *   3. a unique title PREFIX, so `clean` finds `clean code review`.
+ *
+ * A number that is out of range is `not_found` rather than falling through to the
+ * title rules: `0` and `999` are index mistakes, and treating them as titles would
+ * silently match a prompt literally named "999".
+ */
+export function resolvePromptRef(library, ref) {
+    const trimmed = ref.trim();
+    if (trimmed.length === 0)
+        return { ok: false, code: 'not_found' };
+    if (/^\d+$/.test(trimmed)) {
+        const at = Number.parseInt(trimmed, 10) - 1;
+        const prompt = library.prompts[at];
+        return prompt ? { ok: true, prompt } : { ok: false, code: 'not_found' };
+    }
+    const exact = exactTitle(library.prompts, trimmed);
+    if (exact.length > 0)
+        return decide(exact);
+    return decide(prefixTitle(library.prompts, trimmed));
+}
+/** The index a resolved entry sits at, for the "3 days ago" style detail lines. */
+export function promptIndexOf(library, id) {
+    return library.prompts.findIndex((prompt) => prompt.id === id);
+}

package/dist/prompts/search.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+import type { QuickPrompt, PromptSortView } from './types.js';
+/**
+ * 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 declare function subsequenceScore(text: string, query: string): number | null;
+/**
+ * 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 declare function searchPrompts(prompts: readonly QuickPrompt[], query: string): {
+    prompt: QuickPrompt;
+    score: number;
+}[];
+/**
+ * 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 declare function viewOrder(prompts: readonly QuickPrompt[], view: PromptSortView): QuickPrompt[];
+/** The next view in the `Ctrl+S` cycle (manual -> recent -> favorite -> manual). */
+export declare function nextView(view: PromptSortView): PromptSortView;
+/**
+ * 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 declare function sortedPromptTitleOrder(prompts: readonly QuickPrompt[]): QuickPrompt[];