@coffer-org/server 3.3.0 → 4.0.0

package/dist/mcp-contract/tools.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { ValidationError, NotFoundError, ConnectionError } from "./client.js";
+const ok = (data) => ({
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+});
+const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+const ISSUE_HINTS = {
+    file_remote_url: 'a file field stores an uploaded file, not a remote URL',
+    file_unknown_key: 'a file entry may only carry name, mime and size',
+    file_name: 'name must be a bare filename, without a path',
+    file_not_uploaded: 'no file by that name has been uploaded',
+};
+const FILE_RECIPE = '\n\nTo put a file in a file/image/media field:\n' +
+    '1. create_upload_ticket → {token, upload_url} — upload_url is the absolute address to post to\n' +
+    '2. curl -H "Authorization: Bearer <token>" -F "file=@<local path>" <upload_url> → {"name":"<filename>"}\n' +
+    '3. write the field as {"name":"<filename>"} (or an array of those).\n' +
+    'Downloading a remote image is your side of the job: fetch it to a local file first, then upload that file. ' +
+    'mime and size are set by the server. To remove a file, drop its entry — entries cannot be edited in place.';
+async function guard(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        if (e instanceof ValidationError) {
+            const lines = e.issues.map((i) => {
+                const o = i;
+                const code = o.code ?? 'invalid';
+                const hint = ISSUE_HINTS[code];
+                return `- ${o.field ?? '?'}: ${code}${hint ? ` — ${hint}` : ''}`;
+            });
+            const fileIssue = e.issues.some((i) => (i.code ?? '').startsWith('file_'));
+            return fail(`Validation error:\n${lines.join('\n')}${fileIssue ? FILE_RECIPE : ''}`);
+        }
+        if (e instanceof NotFoundError)
+            return fail('Record or shelf not found.');
+        if (e instanceof ConnectionError)
+            return fail(e.message);
+        return fail(`Unexpected error: ${e.message}`);
+    }
+}
+export const LIST_DEFAULT_LIMIT = 25;
+export const LIST_MAX_LIMIT = 200;
+export function buildTools(client, cache) {
+    const library = z.string().describe('Library identifier, e.g. "things"');
+    const shelf = z.string().describe('Shelf identifier, e.g. "item"');
+    const id = z.coerce.number().int().describe('record id');
+    return [
+        {
+            name: 'list_libraries',
+            description: 'Lightweight index of all libraries and shelves (library, shelf, label). Starting point for exploring content.',
+            inputSchema: {},
+            handler: () => guard(() => cache.index()),
+        },
+        {
+            name: 'describe_shelf',
+            description: 'Detailed shelf schema: fields with kind/prim/required and relation/options. A collection is one entry with ' +
+                'multiple:true and its row shape in fields[]. A field with derived:true is computed by the server and rejects ' +
+                'writes — omit it when writing. Call BEFORE create_record/update_record.',
+            inputSchema: { library, shelf },
+            handler: (a) => guard(() => cache.describeShelf(a.library, a.shelf)),
+        },
+        {
+            name: 'refresh_schema',
+            description: 'Re-read the schema from the server. Call after enabling/installing a plugin (server restart required).',
+            inputSchema: {},
+            handler: async () => {
+                cache.refresh();
+                return ok({ refreshed: true });
+            },
+        },
+        {
+            name: 'list_records',
+            description: `List records of a shelf, one page at a time. q — free-text search over the shelf's text fields ` +
+                `(this is how you FIND a record by part of its name: q "minisforum" matches "Minisforum UM790"); ` +
+                `filters — exact field match; folderId — folder filter; ` +
+                `limit — page size (default ${LIST_DEFAULT_LIMIT}, max ${LIST_MAX_LIMIT}); offset — rows to skip. ` +
+                `Returns {rows, total, limit, offset}: "total" is how many records match IN FULL, so answer "how many do I have" ` +
+                `from it instead of listing everything, and never conclude a record is missing from one unfiltered page — ` +
+                `search with q first.`,
+            inputSchema: {
+                library,
+                shelf,
+                q: z.string().optional().describe('Free-text search over text fields; matches partial words'),
+                filters: z
+                    .record(z.string(), z.union([z.string(), z.number()]))
+                    .optional()
+                    .describe('Exact field=value match'),
+                folderId: z.string().optional(),
+                limit: z.number().int().positive().optional(),
+                offset: z.number().int().nonnegative().optional(),
+            },
+            handler: async (a) => guard(async () => {
+                const q = { ...a.filters };
+                if (a.folderId !== undefined)
+                    q.folderId = a.folderId;
+                if (typeof a.q === 'string' && a.q.trim())
+                    q.q = a.q.trim();
+                const limit = Math.min(typeof a.limit === 'number' ? a.limit : LIST_DEFAULT_LIMIT, LIST_MAX_LIMIT);
+                q.limit = limit;
+                const offset = typeof a.offset === 'number' ? a.offset : 0;
+                if (offset > 0)
+                    q.offset = offset;
+                const res = await client.listRecords(a.library, a.shelf, q);
+                const paged = res;
+                const rows = Array.isArray(res) ? res : Array.isArray(paged.rows) ? paged.rows : [];
+                const total = typeof paged.total === 'number' ? paged.total : rows.length;
+                return { rows, total, limit, offset };
+            }),
+        },
+        {
+            name: 'get_record',
+            description: 'A single record by id (with _extends, if any).',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.getRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'create_record',
+            description: 'Create a record. fields — an object of field values (see describe_shelf). name is required.',
+            inputSchema: { library, shelf, fields: z.record(z.string(), z.unknown()).describe('Record field values') },
+            handler: (a) => guard(() => client.createRecord(a.library, a.shelf, a.fields)),
+        },
+        {
+            name: 'update_record',
+            description: 'Partial record update. fields — only the fields to change. Read the record first, call describe_shelf first, and preserve every unmentioned field; never overwrite conflicts silently.',
+            inputSchema: { library, shelf, id, fields: z.record(z.string(), z.unknown()) },
+            handler: (a) => guard(() => client.updateRecord(a.library, a.shelf, a.id, a.fields)),
+        },
+        {
+            name: 'delete_record',
+            description: 'Move a record to the trash by id (reversible soft-delete; data remains in the database). Read the complete record first and get explicit user confirmation for a non-obvious deletion. Never blank fields to simulate deletion.',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.deleteRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'list_trash',
+            description: 'List every record currently in the trash, including its full data. Use this before restoring or permanently purging a record; normal list_records/get_record calls hide trashed records.',
+            inputSchema: {},
+            handler: () => guard(() => client.listTrash()),
+        },
+        {
+            name: 'restore_record',
+            description: 'Restore a record from the trash. Inspect it with list_trash first and confirm the target if the user did not name the exact record.',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.restoreRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'purge_record',
+            description: 'Permanently delete a record that is already in the trash. This is irreversible: inspect list_trash and require explicit user confirmation immediately before calling it.',
+            inputSchema: {
+                library,
+                shelf,
+                id,
+                confirmed: z.literal(true).describe('Must be true only after the user explicitly confirmed permanent deletion'),
+            },
+            handler: async (a) => a.confirmed === true
+                ? guard(() => client.purgeRecord(a.library, a.shelf, a.id))
+                : fail('Permanent deletion requires explicit user confirmation.'),
+        },
+    ];
+}

package/dist/mcp-local.d.ts

@@ -1,4 +1,4 @@
-import type { CofferClientApi } from '@coffer-org/mcp/client';
+import type { CofferClientApi } from './mcp-contract/client.ts';
 export declare function mapError(e: unknown): never;
 export declare function splitListQuery(raw: Record<string, unknown>): {
     query: Record<string, unknown>;

package/dist/mcp-local.js

@@ -1,5 +1,5 @@
-import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
-import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, SingleShelfError, } from "./records-api.js";
+import { ValidationError, NotFoundError } from "./mcp-contract/client.js";
+import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, SingleShelfError, FilterError, } from "./records-api.js";
 import { ValidationError as ServerValidationError } from "./mutate.js";
 import { buildClientSchema } from "./schema-api.js";
 export function mapError(e) {
@@ -9,6 +9,8 @@ export function mapError(e) {
         throw new NotFoundError('not_found');
     if (e instanceof SingleShelfError)
         throw new ValidationError([{ field: 'shelf', code: 'single_shelf', message: e.message }]);
+    if (e instanceof FilterError)
+        throw new ValidationError([{ field: 'query', code: 'bad_filter', message: e.message }]);
     throw e;
 }
 export function splitListQuery(raw) {

package/dist/mcp-tools.d.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '@mikro-orm/core';
 import { z } from 'zod';
-import { type ToolResult } from '@coffer-org/mcp';
+import { type ToolResult } from './mcp-contract/tools.ts';
 import { type AuthRole, type PluginHooks } from './plugin-hooks.ts';
 import { type Condition } from '@coffer-org/sdk/condition';
 import { type RagHit } from './rag-search.ts';
@@ -69,5 +69,16 @@ export declare function collectLibraryPurposes(reg?: {
     }[];
 }): LibraryPurpose[];
 export declare function buildDomainSections(): Promise<string[]>;
+export declare function collectStarterHints(hooks?: Record<string, PluginHooks>, emFactory?: () => EntityManager, reg?: {
+    libraries: {
+        meta: {
+            id: string;
+            starterHint?: string;
+        };
+    }[];
+}): Promise<{
+    combined: string;
+    hash: string;
+}>;
 export declare function buildMcpInstructions(sections: string[]): string;
 export {};

package/dist/mcp-tools.js

@@ -1,6 +1,7 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
-import { buildTools } from '@coffer-org/mcp';
-import { SchemaCache } from '@coffer-org/mcp/schema';
+import { buildTools } from "./mcp-contract/tools.js";
+import { SchemaCache } from "./mcp-contract/schema.js";
 import { LocalClient } from "./mcp-local.js";
 import { frontendInstructions } from "./frontend-agent.js";
 import { mintUploadTicket } from "./upload-ticket.js";
@@ -81,7 +82,7 @@ export async function collectMcpTools(opts = {}) {
                     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."),
+                            : " The server has no public URL configured (system settings publicUrl / PUBLIC_URL env), so the path is relative — resolve it against this MCP server's own origin."),
                 });
             },
         });
@@ -204,7 +205,7 @@ export async function collectMcpTools(opts = {}) {
             server: 'coffer',
             bareName: 'list_settings',
             httpName: 'list_settings',
-            description: 'List every plugin and system settings group (including "core"): each field\'s key/kind/required and the current values (secrets masked). Call before update_settings.',
+            description: "List every settings group (the instance's own `system` group and each plugin's): each field's key/kind/required and the current values (secrets masked). Call before update_settings.",
             inputSchema: {},
             scope: 'settings',
             role: 'admin',
@@ -221,13 +222,13 @@ export async function collectMcpTools(opts = {}) {
             server: 'coffer',
             bareName: 'update_settings',
             httpName: 'update_settings',
-            description: 'Update a plugin or system settings group. plugin — the plugin id (e.g. "claude-agent", "core"); fields — only the settings to change (see list_settings). Send real secret values; the masked placeholder (********) is treated as unchanged.',
-            inputSchema: { plugin: z.string(), fields: z.record(z.string(), z.unknown()) },
+            description: 'Update a plugin or system settings group. group — the settings group id (e.g. "system", "claude-agent"); fields — only the settings to change (see list_settings). Send real secret values; the masked placeholder (********) is treated as unchanged.',
+            inputSchema: { group: z.string(), fields: z.record(z.string(), z.unknown()) },
             scope: 'settings',
             role: 'admin',
             handler: async (args) => {
                 try {
-                    const row = await writePluginSettings(getEm().fork(), args.plugin, args.fields, actor);
+                    const row = await writePluginSettings(getEm().fork(), args.group, args.fields, actor);
                     return ok(row);
                 }
                 catch (e) {
@@ -239,7 +240,7 @@ export async function collectMcpTools(opts = {}) {
                         return fail(`Validation error:\n${lines.join('\n')}`);
                     }
                     if (e instanceof NotFoundError)
-                        return fail(`Plugin '${String(args.plugin)}' has no settings.`);
+                        return fail(`No settings group '${String(args.group)}'.`);
                     return fail(`Error: ${e.message}`);
                 }
             },
@@ -349,6 +350,38 @@ export async function buildDomainSections() {
         ...rules,
     ];
 }
+export async function collectStarterHints(hooks = pluginHooks, emFactory = () => getEm().fork(), reg) {
+    const parts = [];
+    for (const [id, h] of Object.entries(hooks)) {
+        const hint = h.agent?.starterHint;
+        if (hint == null)
+            continue;
+        try {
+            const text = typeof hint === 'function' ? await hint(pluginCtx(id, emFactory())) : hint;
+            if (text)
+                parts.push(`- ${id}: ${text}`);
+        }
+        catch (e) {
+            log.warn(`plugin ${id}: starterHint skipped — ${e.message}`);
+        }
+    }
+    let registry = reg;
+    if (!registry) {
+        try {
+            registry = getActiveRegistry();
+        }
+        catch {
+            registry = undefined;
+        }
+    }
+    for (const v of registry?.libraries ?? []) {
+        if (v.meta.starterHint)
+            parts.push(`- ${v.meta.id}: ${v.meta.starterHint}`);
+    }
+    const combined = parts.join('\n');
+    const hash = createHash('sha1').update(combined).digest('hex');
+    return { combined, hash };
+}
 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.",

package/dist/migrations.d.ts

@@ -1,5 +1,7 @@
 import type { EntityManager, EntitySchema } from '@mikro-orm/core';
 import type { Migration, PluginHooks, TableOps } from './plugin-hooks.ts';
+export declare function markColumnHandedOver(table: string, column: string): void;
+export declare function isColumnHandedOver(table: string, column: string): boolean;
 export declare function introspectTable(em: EntityManager, table: string): Promise<{
     exists: boolean;
     columns: Set<string>;
@@ -9,8 +11,29 @@ export declare function introspectTable(em: EntityManager, table: string): Promi
         primary: boolean;
     }[];
 }>;
-export declare function makeTable(em: EntityManager, table: string): TableOps;
+export declare function introspectAllColumns(em: EntityManager, tables: string[]): Promise<Map<string, Set<string>>>;
+export type MigrationOpCode = 'no-table' | 'no-rows' | 'no-change' | 'no-source-column' | 'target-column-exists' | 'converted-nothing';
+export declare const CONCERNING_CODES: ReadonlySet<MigrationOpCode>;
+export interface MigrationOp {
+    op: 'renameColumn' | 'fill' | 'changeType' | 'convert' | 'dropColumn';
+    table: string;
+    performed: boolean;
+    rows?: number;
+    scanned?: number;
+    emptyTargets?: string[];
+    strandedSources?: string[];
+    code?: MigrationOpCode;
+    reason?: string;
+}
+export type OpRecorder = (op: MigrationOp) => void;
+export declare function describeMigrationConcerns(plugin: string, version: number, ops: MigrationOp[]): string | null;
+export declare function makeTable(em: EntityManager, table: string, record?: OpRecorder): TableOps;
 export declare function renameSystemShelfKey(em: EntityManager): Promise<void>;
+export declare const SYSTEM_MIGRATIONS: {
+    name: string;
+    up(em: EntityManager): Promise<void>;
+}[];
+export declare function runSystemMigrations(em: EntityManager): Promise<void>;
 export declare function validateMigrations(pluginId: string, list: Migration[]): void;
 interface RunArgs {
     em: EntityManager;
@@ -19,7 +42,12 @@ interface RunArgs {
         tables?: string[];
     }[];
     hooks: Record<string, PluginHooks>;
+    onApplied?: (r: {
+        plugin: string;
+        version: number;
+        ops: MigrationOp[];
+    }) => void;
 }
-export declare function runMigrations({ em, plugins, hooks }: RunArgs): Promise<void>;
+export declare function runMigrations({ em, plugins, hooks, onApplied }: RunArgs): Promise<void>;
 export declare function assertSafeRequired(em: EntityManager, entities: EntitySchema[]): Promise<void>;
 export {};