@coffer-org/server 2.6.0 → 2.7.0

package/dist/mcp-tools.js

@@ -10,7 +10,8 @@ import { countTargetsFor, recordCounts } from "./counts.js";
 import { describeCondition } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
 import { getPluginSettings } from "./plugin-runtime.js";
-import { searchEmbeddings } from "./embeddings.js";
+import { configuredPublicUrl } from "./public-url.js";
+import { hybridSearch, buildSearchShelves } from "./rag-search.js";
 import { embedOne, embeddingFailureMessage } from "./embed-openai.js";
 import { getLogger } from "./log.js";
 import { writePluginSettings, listSettings } from "./settings-write.js";
@@ -21,7 +22,14 @@ export function formatHits(hits) {
     if (hits.length === 0)
         return 'No matching records.';
     return hits
-        .map((h) => `[${h.shelfKey}/${h.recordId}] (dist ${h.distance.toFixed(3)})\n${h.snippet}`)
+        .map((h) => {
+        const legs = [];
+        if (h.distance != null)
+            legs.push(`vector ${h.distance.toFixed(3)} #${h.vectorRank}`);
+        if (h.textRank != null)
+            legs.push(`text #${h.textRank}`);
+        return `[${h.shelfKey}/${h.recordId}] (${legs.join(' | ')})\n${h.snippet}`;
+    })
         .join('\n\n');
 }
 const ok = (data) => ({
@@ -31,7 +39,7 @@ const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
 export async function resolveRagDeps() {
     const db = (await getPluginSettings('claude-agent'));
     const enabled = db['rag_enabled'] !== false;
-    const embeddingApiKey = (process.env.OPENAI_API_KEY ?? db['openai_api_key'] ?? '');
+    const embeddingApiKey = process.env.OPENAI_API_KEY ?? db['openai_api_key'] ?? '';
     if (!enabled || !embeddingApiKey)
         return null;
     return { embeddingApiKey };
@@ -64,11 +72,16 @@ export async function collectMcpTools(opts = {}) {
             role: 'member',
             handler: async () => {
                 const { token, expiresInSec } = mintUploadTicket(actor);
+                const base = await configuredPublicUrl();
+                const uploadUrl = base ? `${base}/api/upload` : '/api/upload';
                 return ok({
                     token,
-                    upload_url: '/api/upload',
+                    upload_url: uploadUrl,
                     expires_in: expiresInSec,
-                    how_to: 'curl -H "Authorization: Bearer <token>" -F "file=@<path>" <base-url>/api/upload  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.',
+                    how_to: `curl -H "Authorization: Bearer <token>" -F "file=@<path>" ${uploadUrl}  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.` +
+                        (base
+                            ? ''
+                            : " The server has no public URL configured (core settings publicUrl / PUBLIC_URL env), so the path is relative — resolve it against this MCP server's own origin."),
                 });
             },
         });
@@ -132,18 +145,55 @@ export async function collectMcpTools(opts = {}) {
             server: 'rag',
             bareName: 'search_records',
             httpName: 'search_records',
-            description: "Semantic search over the user's coffer records. Returns the most relevant records as library/shelf/id refs with a text snippet.",
-            inputSchema: { query: z.string(), k: z.number().int().positive().optional() },
+            description: "Hybrid search over the user's coffer records: semantic similarity plus exact-token matching. " +
+                'Returns the most relevant records as library/shelf/id refs with a text snippet. Narrow it with `library` ' +
+                '(and optionally `shelf`) when you already know where the answer lives. An empty result means nothing ' +
+                'relevant is stored — say so instead of answering from a weak match. If the first call returns nothing ' +
+                'useful, retry with a rephrasing, or with the exact literal string (a model number, a name, an error code): ' +
+                'the exact-token leg finds those where a paraphrase cannot.',
+            inputSchema: {
+                query: z.string(),
+                k: z.number().int().positive().optional(),
+                library: z.string().optional(),
+                shelf: z.string().optional(),
+            },
             scope: 'rag',
             role: 'member',
             handler: async (args) => {
+                const library = args.library;
+                const shelf = args.shelf;
+                if (shelf && !library) {
+                    return fail('Error: `shelf` needs `library` (a shelf name is only unique inside its library).');
+                }
+                if (library) {
+                    const known = buildSearchShelves({ library, shelf });
+                    if (known.length === 0) {
+                        const all = buildSearchShelves();
+                        const valid = shelf
+                            ? all.filter((s) => s.key.startsWith(`${library}/`)).map((s) => s.key)
+                            : [...new Set(all.map((s) => s.key.split('/')[0]))];
+                        return fail(`Error: unknown ${shelf ? 'shelf' : 'library'}. Valid: ${valid.join(', ')}`);
+                    }
+                }
+                let vector = null;
+                try {
+                    vector = (await embedOne(args.query, embeddingApiKey)).vector;
+                }
+                catch (e) {
+                    log.warn(`embedding failed, text-only search — ${embeddingFailureMessage(e)}`);
+                }
                 try {
-                    const { vector } = await embedOne(args.query, embeddingApiKey);
-                    const hits = await searchEmbeddings(vector, args.k ?? DEFAULT_RAG_TOP_K);
+                    const hits = await hybridSearch({
+                        query: args.query,
+                        vector,
+                        k: args.k ?? DEFAULT_RAG_TOP_K,
+                        library,
+                        shelf,
+                    });
                     return { content: [{ type: 'text', text: formatHits(hits) }] };
                 }
                 catch (e) {
-                    return fail(`RAG unavailable: ${embeddingFailureMessage(e)} Use the regular coffer tools (list_records/get_record) instead.`);
+                    return fail(`Search unavailable: ${e.message} Use the regular coffer tools (list_records/get_record) instead.`);
                 }
             },
         });
@@ -214,6 +264,22 @@ export async function collectPluginInstructions(hooks = pluginHooks, emFactory =
     }
     return out;
 }
+export function collectSingleShelves(reg) {
+    let registry = reg;
+    if (!registry) {
+        try {
+            registry = getActiveRegistry();
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!registry)
+        return [];
+    return registry.shelves
+        .filter((s) => s.single && s.claude)
+        .map((s) => ({ library: s.library, shelf: s.shelf, claude: s.claude }));
+}
 export function collectLibraryPurposes(reg) {
     let registry = reg;
     if (!registry) {
@@ -259,6 +325,11 @@ export async function buildDomainSections() {
         overview =
             '## Libraries (what each holds / when to use it — pick the right one before searching)\n\n' + blocks.join('\n\n');
     }
+    const singles = collectSingleShelves();
+    const singleSection = singles.length
+        ? '## Single-record shelves (one document each — read the record, do not search the shelf)\n\n' +
+            singles.map((s) => `- ${s.library}/${s.shelf}: ${s.claude.replace(/\s*\n\s*/g, ' ')}`).join('\n')
+        : null;
     const dataModel = '## Data model\n' +
         'Library (top-level area) → shelf (a kind of record, e.g. things/item) → record (addressed library/shelf/id) → fields. ' +
         'Some field values are JSON (e.g. quantity {"value":2000,"unit":"ml"}); some are relations (hold another record\'s id); ' +
@@ -273,6 +344,7 @@ export async function buildDomainSections() {
     return [
         dataModel,
         ...(overview ? [overview] : []),
+        ...(singleSection ? [singleSection] : []),
         ...(site ? [`## web\n${site}`] : []),
         ...rules,
     ];
@@ -280,7 +352,7 @@ export async function buildDomainSections() {
 export function buildMcpInstructions(sections) {
     const base = [
         "Coffer is the user's personal database, organized into libraries (kitchen, people, finance, health, devices, home, garden, documents, travel, and more), each holding typed records.",
-        'Use the tools to read and write this data: call list_libraries to see what exists, describe_shelf before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for semantic lookup.',
+        'Use the tools to read and write this data: call list_libraries to see what exists, describe_shelf before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for lookup — it searches by meaning and by exact token at once, and takes an optional library/shelf to narrow it. State where each fact came from by citing its record as [library/shelf/id]: an answer assembled from search results without citations cannot be checked against the data.',
         'The per-library notes below name the shelves and the rules — not every field. For exact field names, types, and which are required, call describe_shelf(library, shelf) rather than guessing from the notes.',
         'Record field values may be JSON-encoded (e.g. quantity {"value":2000,"unit":"ml"}) — parse them.',
         'Action safety: read a complete record before editing or deleting it. update_record must be the smallest patch and must preserve unmentioned fields. delete_record moves the record to reversible trash; never blank fields to simulate deletion. For suspected duplicates, read both complete records, compare fields/collections/extends/attachments, identify the less complete record, and offer a field-by-field merge before moving anything to trash. Use list_trash/restore_record for recovery; purge_record is irreversible and requires explicit confirmation.',

package/dist/msg-log.d.ts

@@ -7,6 +7,8 @@ export interface MsgLogRow {
     tokensIn: number | null;
     tokensOut: number | null;
     ms: number | null;
+    agentId: string | null;
+    presetId: string | null;
 }
 export interface MsgLogDiagnosticRow {
     id: number;

package/dist/msg-log.js

@@ -1,11 +1,29 @@
 import { getEm } from "./db.js";
 export async function logMessage(row) {
-    await getEm().fork().getConnection().execute(`INSERT INTO _orch_msg_log (ts, connector, chat_id, user_id, role, text, tokens_in, tokens_out, ms)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [new Date().toISOString(), row.connector, row.chatId, row.userId, row.role, row.text, row.tokensIn, row.tokensOut, row.ms]);
+    await getEm()
+        .fork()
+        .getConnection()
+        .execute(`INSERT INTO _orch_msg_log (ts, connector, chat_id, user_id, role, text, tokens_in, tokens_out, ms, agent_id, preset_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        new Date().toISOString(),
+        row.connector,
+        row.chatId,
+        row.userId,
+        row.role,
+        row.text,
+        row.tokensIn,
+        row.tokensOut,
+        row.ms,
+        row.agentId,
+        row.presetId,
+    ]);
 }
 export async function listRecentMessageMetrics(limit = 25) {
     const bounded = Math.max(1, Math.min(100, Math.trunc(limit)));
-    const rows = (await getEm().fork().getConnection().execute(`SELECT id, ts, connector, role, tokens_in, tokens_out, ms
+    const rows = (await getEm()
+        .fork()
+        .getConnection()
+        .execute(`SELECT id, ts, connector, role, tokens_in, tokens_out, ms
        FROM _orch_msg_log
       ORDER BY id DESC
       LIMIT ?`, [bounded]));

package/dist/mutate.d.ts

@@ -1,7 +1,9 @@
 import type { EntityManager } from '@mikro-orm/core';
 import type { ShelfDef } from '@coffer-org/sdk/shelf';
+import type { LayoutEl } from '@coffer-org/sdk/fields';
 import { z } from 'zod';
-export declare function encodeJson(m: ShelfDef, data: Record<string, unknown>): Record<string, unknown>;
+export declare function encodeJsonAt(fields: LayoutEl[], data: Record<string, unknown>): Record<string, unknown>;
+export declare const encodeJson: (m: ShelfDef, data: Record<string, unknown>) => Record<string, unknown>;
 export interface MutateCtx {
     actor: string;
 }

package/dist/mutate.js

@@ -11,15 +11,16 @@ import { splitCollections, writeCollections, deleteCollections, flattenEmbedded,
 function nowIso() {
     return new Date().toISOString();
 }
-export function encodeJson(m, data) {
+export function encodeJsonAt(fields, data) {
     const out = { ...data };
-    for (const [k, f] of fieldEntries(m.fields)) {
+    for (const [k, f] of fieldEntries(fields)) {
         if (isJsonStored(f) && out[k] !== null && out[k] !== undefined && typeof out[k] === 'object') {
             out[k] = JSON.stringify(out[k]);
         }
     }
     return out;
 }
+export const encodeJson = (m, data) => encodeJsonAt(m.fields, data);
 export class ValidationError extends Error {
     issues;
     constructor(issues) {
@@ -119,10 +120,11 @@ export async function updateRecord(m, entityName, id, input, ctx, afterBase) {
         const existingFlat = decodeTemporal(m, serialize(found));
         const existing = nestEmbedded(m, existingFlat);
         const ts = nowIso();
-        const { base, collections } = splitCollections(m, { ...parsed.data });
-        const fileIssues = normalizeFileFields(m, base);
+        const patchData = parsed.data;
+        const fileIssues = normalizeFileFields(m, patchData);
         if (fileIssues.length)
             throw new ValidationError(fileIssues);
+        const { base, collections } = splitCollections(m, { ...patchData });
         const merged = { ...existing, ...base };
         const reqIssues = [];
         for (const [key, f] of fieldEntries(m.fields)) {

package/dist/oauth-api.js

@@ -3,10 +3,7 @@ import { resolveRequestUser, startPasswordSession } from "./auth-api.js";
 import { baseUrl, mcpResource } from "./public-url.js";
 import { getLogger } from "./log.js";
 const log = getLogger('oauth');
-const DEFAULT_REDIRECT_ALLOW = [
-    'https://claude.ai/api/mcp/auth_callback',
-    'https://claude.com/api/mcp/auth_callback',
-];
+const DEFAULT_REDIRECT_ALLOW = ['https://claude.ai/api/mcp/auth_callback', 'https://claude.com/api/mcp/auth_callback'];
 function redirectAllowlist() {
     const extra = (process.env['OAUTH_REDIRECT_ALLOW'] ?? '')
         .split(',')
@@ -147,7 +144,10 @@ export function registerOAuthApi(app) {
                 .code(400)
                 .send({ error: 'invalid_redirect_uri', error_description: `redirect_uri not allowed: ${bad}` });
         }
-        const client = await registerClient({ clientName: body.client_name?.slice(0, 200) || 'MCP client', redirectUris: uris });
+        const client = await registerClient({
+            clientName: body.client_name?.slice(0, 200) || 'MCP client',
+            redirectUris: uris,
+        });
         log.info(`registered client ${client.clientId} (${client.clientName})`);
         return reply.code(201).send({
             client_id: client.clientId,
@@ -160,14 +160,23 @@ export function registerOAuthApi(app) {
     });
     async function validateAuthz(p) {
         if (!p.client_id || !p.redirect_uri) {
-            return { ok: false, html: page('Invalid request', '<h1>Invalid request</h1><p>Missing client_id or redirect_uri.</p>') };
+            return {
+                ok: false,
+                html: page('Invalid request', '<h1>Invalid request</h1><p>Missing client_id or redirect_uri.</p>'),
+            };
         }
         const client = await findClient(p.client_id);
         if (!client) {
-            return { ok: false, html: page('Unknown client', '<h1>Unknown client</h1><p>This application is not registered.</p>') };
+            return {
+                ok: false,
+                html: page('Unknown client', '<h1>Unknown client</h1><p>This application is not registered.</p>'),
+            };
         }
         if (!client.redirectUris.includes(p.redirect_uri)) {
-            return { ok: false, html: page('Invalid redirect', '<h1>Invalid redirect</h1><p>redirect_uri does not match this client.</p>') };
+            return {
+                ok: false,
+                html: page('Invalid redirect', '<h1>Invalid redirect</h1><p>redirect_uri does not match this client.</p>'),
+            };
         }
         return { ok: true, clientName: client.clientName };
     }
@@ -197,12 +206,18 @@ export function registerOAuthApi(app) {
                 return reply.code(429).type('text/html').send(page('Slow down', '<h1>Too many attempts</h1>'));
             const user = await startPasswordSession(reply, String(body['login'] ?? ''), String(body['password'] ?? ''));
             if (!user)
-                return reply.code(401).type('text/html').send(loginForm(p, check.clientName, 'Wrong login or password.'));
+                return reply
+                    .code(401)
+                    .type('text/html')
+                    .send(loginForm(p, check.clientName, 'Wrong login or password.'));
             return reply.type('text/html').send(consentForm(p, check.clientName, user));
         }
         const user = await resolveRequestUser(req);
         if (!user)
-            return reply.code(401).type('text/html').send(loginForm(p, check.clientName, 'Your session expired. Sign in again.'));
+            return reply
+                .code(401)
+                .type('text/html')
+                .send(loginForm(p, check.clientName, 'Your session expired. Sign in again.'));
         if (body['action'] !== 'approve')
             return redirectWithError(reply, p, 'access_denied');
         if (!p.code_challenge)

package/dist/plugin-i18n.d.ts

@@ -0,0 +1,6 @@
+export interface PluginI18n {
+    lang: string;
+    t(key: string, fallback?: string): string;
+}
+export declare function loadPluginI18n(localesDir: URL | string, fallbackLang?: string): Promise<PluginI18n>;
+export declare function clearPluginI18nCache(): void;

package/dist/plugin-i18n.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+const cache = new Map();
+async function systemLanguage(fallback) {
+    try {
+        const { getPluginSettings } = await import("./plugin-runtime.js");
+        return (await getPluginSettings('core'))['language'] || fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function loadPluginI18n(localesDir, fallbackLang = 'uk') {
+    const lang = await systemLanguage(fallbackLang);
+    const url = new URL(`${lang}.json`, localesDir);
+    let dict = cache.get(url.href);
+    if (!dict) {
+        try {
+            dict = JSON.parse(await readFile(url, 'utf8'));
+        }
+        catch {
+            dict = {};
+        }
+        cache.set(url.href, dict);
+    }
+    const loaded = dict;
+    return {
+        lang,
+        t(key, fallback) {
+            const value = key
+                .split('.')
+                .reduce((node, part) => (node == null ? undefined : node[part]), loaded);
+            return typeof value === 'string' ? value : (fallback ?? key);
+        },
+    };
+}
+export function clearPluginI18nCache() {
+    cache.clear();
+}

package/dist/rag-search.d.ts

@@ -0,0 +1,40 @@
+import { type EmbeddingHit } from './embeddings.ts';
+import { type GlobalSearchHit, type SearchShelf } from './global-search.ts';
+export declare const RRF_K = 60;
+export declare const MAX_VECTOR_DISTANCE = 0.85;
+export declare const SEARCH_POOL = 50;
+export interface FusedEntry {
+    score: number;
+    ranks: (number | null)[];
+}
+export declare function fuseRrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): Map<string, FusedEntry>;
+export interface RagHit {
+    shelfKey: string;
+    recordId: number;
+    snippet: string;
+    distance: number | null;
+    vectorRank: number | null;
+    textRank: number | null;
+    score: number;
+}
+export interface HybridOpts {
+    query: string;
+    vector: number[] | null;
+    k: number;
+    library?: string;
+    shelf?: string;
+    maxDistance?: number;
+    rrfK?: number;
+}
+export interface HybridDeps {
+    vectorSearch?: (vec: number[], k: number, o?: {
+        shelfKeys?: Set<string>;
+    }) => Promise<EmbeddingHit[]>;
+    textSearch?: (shelves: SearchShelf[], q: string, k: number) => Promise<GlobalSearchHit[]>;
+    shelves?: SearchShelf[];
+}
+export declare function buildSearchShelves(filter?: {
+    library?: string;
+    shelf?: string;
+}): SearchShelf[];
+export declare function hybridSearch(opts: HybridOpts, deps?: HybridDeps): Promise<RagHit[]>;

package/dist/rag-search.js

@@ -0,0 +1,94 @@
+import { searchEmbeddings } from "./embeddings.js";
+import { globalSearch } from "./global-search.js";
+import { getActiveRegistry } from "./registry-context.js";
+import { shelfTableName } from "./entity-schema.js";
+import { getLogger } from "./log.js";
+const log = getLogger('rag-search');
+export const RRF_K = 60;
+export const MAX_VECTOR_DISTANCE = 0.85;
+export const SEARCH_POOL = 50;
+export function fuseRrf(lists, keyOf, k = RRF_K) {
+    const out = new Map();
+    lists.forEach((list, listIndex) => {
+        list.forEach((item, i) => {
+            const key = keyOf(item);
+            let entry = out.get(key);
+            if (!entry) {
+                entry = { score: 0, ranks: lists.map(() => null) };
+                out.set(key, entry);
+            }
+            if (entry.ranks[listIndex] !== null)
+                return;
+            entry.ranks[listIndex] = i + 1;
+            entry.score += 1 / (k + i + 1);
+        });
+    });
+    return out;
+}
+export function buildSearchShelves(filter = {}) {
+    return getActiveRegistry()
+        .shelves.filter((m) => (filter.library ? m.library === filter.library : true))
+        .filter((m) => (filter.shelf ? m.shelf === filter.shelf : true))
+        .map((m) => ({
+        key: `${m.library}/${m.shelf}`,
+        table: shelfTableName(m.library, m.shelf),
+        def: m,
+    }));
+}
+const hitKey = (shelfKey, recordId) => `${shelfKey}/${recordId}`;
+async function leg(name, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        log.warn(`${name} leg failed, degrading — ${e.message}`);
+        return [];
+    }
+}
+export async function hybridSearch(opts, deps = {}) {
+    const vectorSearch = deps.vectorSearch ?? searchEmbeddings;
+    const textSearch = deps.textSearch ?? globalSearch;
+    const narrowed = Boolean(opts.library || opts.shelf);
+    const shelves = deps.shelves
+        ? deps.shelves
+            .filter((s) => (opts.library ? s.key.startsWith(`${opts.library}/`) : true))
+            .filter((s) => (opts.shelf ? s.key.endsWith(`/${opts.shelf}`) : true))
+        : buildSearchShelves({ library: opts.library, shelf: opts.shelf });
+    const shelfKeys = narrowed ? new Set(shelves.map((s) => s.key)) : undefined;
+    const maxDistance = opts.maxDistance ?? MAX_VECTOR_DISTANCE;
+    const [vectorHits, textHits] = await Promise.all([
+        opts.vector
+            ? leg('vector', () => vectorSearch(opts.vector, SEARCH_POOL, { shelfKeys }))
+            : Promise.resolve([]),
+        leg('text', () => textSearch(shelves, opts.query, SEARCH_POOL)),
+    ]);
+    const near = vectorHits.filter((h) => h.distance <= maxDistance);
+    const keyedText = textHits.map((h) => ({
+        shelfKey: `${h.library}/${h.shelf}`,
+        recordId: Number(h.id),
+        snippet: h.snippet,
+    }));
+    const fused = fuseRrf([near, keyedText], (h) => hitKey(h.shelfKey, h.recordId), opts.rrfK);
+    const snippets = new Map();
+    for (const h of keyedText)
+        snippets.set(hitKey(h.shelfKey, h.recordId), h.snippet);
+    for (const h of near)
+        snippets.set(hitKey(h.shelfKey, h.recordId), h.snippet);
+    const distances = new Map(near.map((h) => [hitKey(h.shelfKey, h.recordId), h.distance]));
+    return [...fused.entries()]
+        .map(([key, entry]) => {
+        const slash = key.lastIndexOf('/');
+        const shelfKey = key.slice(0, slash);
+        return {
+            shelfKey,
+            recordId: Number(key.slice(slash + 1)),
+            snippet: snippets.get(key) ?? '',
+            distance: distances.get(key) ?? null,
+            vectorRank: entry.ranks[0] ?? null,
+            textRank: entry.ranks[1] ?? null,
+            score: entry.score,
+        };
+    })
+        .sort((a, b) => b.score - a.score || hitKey(a.shelfKey, a.recordId).localeCompare(hitKey(b.shelfKey, b.recordId)))
+        .slice(0, opts.k);
+}

package/dist/records-api.d.ts

@@ -1,6 +1,9 @@
 import type { ShelfDef } from '@coffer-org/sdk/shelf';
 export declare class UnknownShelfError extends Error {
 }
+export declare class SingleShelfError extends Error {
+    constructor(message: string);
+}
 export type RecordListQuery = {
     q?: string;
     id?: string;
@@ -33,6 +36,7 @@ export declare function recordGet(library: string, shelf: string, id: number, op
     includeDeleted?: boolean;
 }): Promise<Record<string, unknown> | null>;
 export declare function recordCreate(library: string, shelf: string, body: unknown, actor?: string): Promise<Record<string, unknown>>;
+export declare function ensureSingle(library: string, shelf: string): Promise<Record<string, unknown>>;
 export declare function recordUpdate(library: string, shelf: string, id: number, body: unknown, actor?: string): Promise<Record<string, unknown>>;
 export declare function recordDelete(library: string, shelf: string, id: number, actor?: string): Promise<void>;
 export declare function recordRestore(library: string, shelf: string, id: number, actor?: string): Promise<void>;

package/dist/records-api.js

@@ -11,6 +11,12 @@ import { createRecord, updateRecord, getRecord, deleteRecord, restoreRecord, pur
 import { deleteRecordActivity } from "./record-activity.js";
 export class UnknownShelfError extends Error {
 }
+export class SingleShelfError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SingleShelfError';
+    }
+}
 export const MAX_PAGE = 500;
 function pickCols(row, cols) {
     const out = {};
@@ -110,9 +116,11 @@ export async function recordCount(library, shelf, query = {}, opts = {}) {
         where.deleted_at = { $ne: null };
     if (m.standalone === false && Object.keys(filterParams).length === 0)
         return 0;
-    return getEm().fork().count(ename, where);
+    return getEm()
+        .fork()
+        .count(ename, where);
 }
-export async function recordList(library, shelf, query = {}, opts = {}) {
+async function listRecords(library, shelf, query = {}, opts = {}) {
     const { view = 'full', extends: withExt = true, deleted = 'active' } = opts;
     const { m, ename } = resolve(library, shelf);
     const { q, ...filterParams } = query;
@@ -147,6 +155,12 @@ export async function recordList(library, shelf, query = {}, opts = {}) {
         return decoded;
     return withExtendsMany(decoded, library, shelf);
 }
+export async function recordList(library, shelf, query = {}, opts = {}) {
+    const { m } = resolve(library, shelf);
+    if (m.single)
+        await ensureSingle(library, shelf);
+    return listRecords(library, shelf, query, opts);
+}
 export function isPagedRequest(limit, offset) {
     return [limit, offset].some((v) => v !== undefined && v.trim() !== '' && Number.isFinite(Number(v)));
 }
@@ -179,7 +193,7 @@ export async function recordGet(library, shelf, id, opts = {}) {
         return null;
     return withExtends(row, library, shelf);
 }
-export async function recordCreate(library, shelf, body, actor = 'gui') {
+async function createOne(library, shelf, body, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
     const { base, extData } = splitBody(body);
     validateExtends(library, shelf, extData);
@@ -189,6 +203,37 @@ export async function recordCreate(library, shelf, body, actor = 'gui') {
     });
     return withExtends(row, library, shelf);
 }
+export async function recordCreate(library, shelf, body, actor = 'gui') {
+    const { m } = resolve(library, shelf);
+    if (m.single) {
+        await ensureSingle(library, shelf);
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record already exists — update it instead`);
+    }
+    return createOne(library, shelf, body, actor);
+}
+const singleInFlight = new Map();
+export async function ensureSingle(library, shelf) {
+    const { m } = resolve(library, shelf);
+    if (!m.single)
+        throw new Error(`not a single shelf: ${library}/${shelf}`);
+    const key = `${library}/${shelf}`;
+    const pending = singleInFlight.get(key);
+    if (pending)
+        return pending;
+    const task = (async () => {
+        const rows = await listRecords(library, shelf, {}, { limit: 1, orderBy: { id: 'ASC' } });
+        if (rows[0])
+            return rows[0];
+        return createOne(library, shelf, {}, 'system');
+    })();
+    singleInFlight.set(key, task);
+    try {
+        return await task;
+    }
+    finally {
+        singleInFlight.delete(key);
+    }
+}
 export async function recordUpdate(library, shelf, id, body, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
     const { base, extData } = splitBody(body);
@@ -201,6 +246,8 @@ export async function recordUpdate(library, shelf, id, body, actor = 'gui') {
 }
 export async function recordDelete(library, shelf, id, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
+    if (m.single)
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record cannot be deleted — clear its fields instead`);
     await deleteRecord(m, ename, id, { actor });
 }
 export async function recordRestore(library, shelf, id, actor = 'gui') {
@@ -209,6 +256,8 @@ export async function recordRestore(library, shelf, id, actor = 'gui') {
 }
 export async function recordPurge(library, shelf, id, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
+    if (m.single)
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record cannot be deleted — clear its fields instead`);
     await purgeRecord(m, ename, id, { actor }, (tx, recordId) => deleteExtends(tx, library, shelf, recordId));
     await deleteRecordActivity(library, shelf, id);
 }
@@ -216,7 +265,7 @@ export async function recordTrashList() {
     const shelves = getActiveRegistry().shelves.filter((s) => s.standalone !== false);
     const out = [];
     for (const m of shelves) {
-        const rows = await recordList(m.library, m.shelf, {}, { view: 'full', extends: true, deleted: 'deleted' });
+        const rows = await listRecords(m.library, m.shelf, {}, { view: 'full', extends: true, deleted: 'deleted' });
         for (const record of rows)
             out.push({ library: m.library, shelf: m.shelf, label: m.label, record });
     }

package/dist/search-index.js

@@ -57,11 +57,7 @@ export async function upsertSearchRow(shelf, recordId, folded) {
     await conn.execute('DELETE FROM "_search" WHERE shelf = ? AND record_id = ?', [shelf, recordId]);
     if (!folded)
         return;
-    await conn.execute('INSERT INTO "_search" (shelf, record_id, folded) VALUES (?, ?, ?)', [
-        shelf,
-        recordId,
-        folded,
-    ]);
+    await conn.execute('INSERT INTO "_search" (shelf, record_id, folded) VALUES (?, ?, ?)', [shelf, recordId, folded]);
 }
 export async function deleteSearchRow(shelf, recordId) {
     if (!ftsAvailable())
@@ -81,9 +77,7 @@ export async function ftsCandidates(tokens) {
         const rows = (await getEm()
             .fork()
             .getConnection()
-            .execute('SELECT shelf, record_id FROM "_search" WHERE "_search" MATCH ?', [
-            buildFtsMatchQuery(tokens),
-        ]));
+            .execute('SELECT shelf, record_id FROM "_search" WHERE "_search" MATCH ?', [buildFtsMatchQuery(tokens)]));
         for (const r of rows) {
             const list = out.get(r.shelf);
             if (list)