@cyanheads/mcp-ts-core 0.9.15 → 0.9.17

package/dist/services/mirror/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Public contracts for the MirrorService — the source-agnostic
+ * machinery for a persistent, self-refreshing local mirror of a bulk upstream
+ * dataset. The framework owns the store, the sync-state machine, and the runner;
+ * each server supplies only the ingester (`sync` generator) and the schema.
+ * @module services/mirror/types
+ */
+import type { SqliteHandle, SqlValue } from './sqlite/handle.js';
+export type { SqliteHandle, SqliteStatement, SqlValue } from './sqlite/handle.js';
+/** One mirrored record — a flat object keyed by declared column name. */
+export type MirrorRow = Record<string, SqlValue>;
+/** Lifecycle state of a mirror's local dataset. */
+export type SyncStatus = 'pending' | 'in_progress' | 'complete' | 'error';
+/**
+ * Duck-typed logger consumed by the runner. A sync runs outside the MCP request
+ * pipeline (cron job or CLI script), so it has no request `Context` — any
+ * logger with these methods works (the framework `logger`, a `ctx.log`, or a
+ * console wrapper). All methods are optional.
+ */
+export interface MirrorLogger {
+    debug?(message: string, meta?: object): void;
+    error?(message: string, meta?: object): void;
+    info?(message: string, meta?: object): void;
+    notice?(message: string, meta?: object): void;
+    warning?(message: string, meta?: object): void;
+}
+/**
+ * Persisted sync state — the resume-on-interrupt checkpoint store. The two
+ * position fields are deliberately distinct:
+ *
+ * - `cursor` is the **volatile** intra-run resume position (e.g. an OAI-PMH
+ *   resumption token). It is valid only within a single run, may expire, and is
+ *   cleared on completion. The runner threads it back into `sync()` to resume an
+ *   interrupted init.
+ * - `checkpoint` is the **durable** high-water mark (e.g. the max record
+ *   datestamp). It advances monotonically and only on success, and seeds the
+ *   next incremental refresh.
+ *
+ * They cannot be merged: for a token-paged source the mid-run cursor is not a
+ * valid refresh seed, and the high-water mark is not a valid mid-run resume
+ * position.
+ */
+export interface SyncState {
+    /** Durable incremental high-water mark; advances only on success. */
+    checkpoint?: string | undefined;
+    /** ISO 8601 timestamp the last run completed successfully. Drives readiness. */
+    completedAt?: string | undefined;
+    /** Volatile intra-run resume position; cleared on completion. */
+    cursor?: string | undefined;
+    /** Message from the last failed run, set when `status === 'error'`. */
+    error?: string | undefined;
+    /** ISO 8601 timestamp the current run started. */
+    startedAt?: string | undefined;
+    status: SyncStatus;
+    /** Record count, set when a sync completes. */
+    total?: number | undefined;
+}
+/** Context passed to a server's `sync` generator on each run. */
+export interface SyncContext {
+    /** Durable high-water mark to harvest from (refresh; also init-resume recovery). */
+    checkpoint?: string | undefined;
+    /** Volatile resume position from a prior interrupted run (init only). */
+    cursor?: string | undefined;
+    /** `init` for a full harvest, `refresh` for an incremental one. */
+    mode: SyncMode;
+    /** Aborts the run; the generator should stop and the runner persists state. */
+    signal: AbortSignal;
+}
+export type SyncMode = 'init' | 'refresh';
+/**
+ * One page yielded by a server's `sync` generator. The framework upserts the
+ * records, deletes the tombstones, and persists the cursor/checkpoint — all in
+ * one transaction per page — so an interrupt resumes from the last yielded page.
+ */
+export interface SyncPage {
+    /**
+     * Updated durable high-water mark after this page. Must be lexicographically
+     * monotonic (e.g. ISO 8601) — the runner advances the stored checkpoint only
+     * when a page's value compares greater.
+     */
+    checkpoint?: string | undefined;
+    /** Updated volatile resume position after this page. */
+    cursor?: string | undefined;
+    /** Records to upsert (keyed by column name). */
+    records: MirrorRow[];
+    /** Primary-key values to delete (deleted upstream records). */
+    tombstones?: string[];
+}
+/** A server's ingester: an async generator of pages from the upstream source. */
+export type SyncGenerator = (ctx: SyncContext) => AsyncGenerator<SyncPage>;
+/** Progress hook invoked after each persisted page. */
+export type SyncProgress = (info: {
+    pages: number;
+    records: number;
+    tombstones: number;
+    cursor?: string | undefined;
+    checkpoint?: string | undefined;
+}) => void;
+/** Options for a single sync run. */
+export interface RunSyncOptions {
+    mode: SyncMode;
+    onProgress?: SyncProgress;
+}
+/** Outcome of a completed sync run. */
+export interface SyncResult {
+    pagesFetched: number;
+    recordsApplied: number;
+    tombstonesApplied: number;
+    total: number;
+}
+/** Public status of a mirror — what tools surface to agents. */
+export interface MirrorStatus {
+    checkpoint?: string | undefined;
+    completedAt?: string | undefined;
+    error?: string | undefined;
+    /**
+     * `true` once a full sync has ever completed (`completedAt != null`), NOT
+     * `status === 'complete'`. The dataset stays queryable during a refresh, so
+     * readiness keys off the durable completion marker — an in-progress or failed
+     * refresh on top of a complete mirror is still ready.
+     */
+    ready: boolean;
+    startedAt?: string | undefined;
+    status: SyncStatus;
+    total?: number | undefined;
+}
+/** Comparison operators for a {@link QueryFilter}. */
+export type FilterOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+/** A single structured filter applied as an indexed `WHERE` clause. */
+export interface QueryFilter {
+    /** Column to filter — must be a declared column. */
+    column: string;
+    op: FilterOp;
+    /** Scalar for scalar ops; array for `in`. */
+    value: SqlValue | SqlValue[];
+}
+/** Sort directive: by a declared column, or `'relevance'` (FTS bm25, requires `match`). */
+export type QuerySort = {
+    column: string;
+    direction: 'asc' | 'desc';
+} | 'relevance';
+/** Options for the generic {@link MirrorStore.query}. */
+export interface QueryOptions {
+    /** Structured filters, AND-combined. */
+    filters?: QueryFilter[];
+    limit: number;
+    /** FTS5 `MATCH` expression. The server translates its own query syntax to FTS5. */
+    match?: string | undefined;
+    offset: number;
+    /** Sort directive. Defaults to insertion order (rowid) when omitted. */
+    sort?: QuerySort | undefined;
+}
+/** Result of a {@link MirrorStore.query}. */
+export interface QueryResult {
+    rows: MirrorRow[];
+    /** Total matches before `limit`/`offset`. */
+    total: number;
+}
+/** A schema migration: bump `version` and apply `up` on open when the stored version is lower. */
+export interface Migration {
+    /** Apply the migration. Runs inside the open handle; should be idempotent. */
+    up(handle: SqliteHandle): void;
+    /** Target schema version this migration produces. */
+    version: number;
+}
+/**
+ * Pluggable backend contract — the embedded-store half of a mirror. The default
+ * implementation is `sqliteMirrorStore`; the interface leaves a clean path to
+ * other backends (DuckDB, Postgres) without re-architecting the runner. All
+ * methods lazy-open the underlying store on first call (async per the Tier-3
+ * convention) and are then backed by synchronous driver calls.
+ */
+export interface MirrorStore {
+    /** Upsert records and delete tombstoned primary keys in one transaction. */
+    applyBatch(records: MirrorRow[], tombstones: string[]): Promise<void>;
+    /** Close the underlying store. */
+    close(): Promise<void>;
+    /** Total record count. */
+    count(): Promise<number>;
+    /** Fetch records by primary-key list, preserving input order; missing keys skipped. */
+    getByIds(ids: string[]): Promise<MirrorRow[]>;
+    /** `PRAGMA integrity_check` + `quick_check`. */
+    integrityCheck(): Promise<{
+        ok: boolean;
+        results: string[];
+    }>;
+    /** Generic flat query: FTS `MATCH` + indexed filters + sort + pagination. */
+    query(options: QueryOptions): Promise<QueryResult>;
+    /**
+     * The opened runtime-agnostic handle — the escape hatch for server-specific
+     * access paths (auxiliary tables, junctions, custom indexes, bespoke queries)
+     * that the generic `query()` does not cover.
+     */
+    raw(): Promise<SqliteHandle>;
+    /** Read the persisted sync state. */
+    readState(): Promise<SyncState>;
+    /** Write the persisted sync state. Durable fields (`completedAt`/`total`) are preserved when omitted. */
+    writeState(state: SyncState): Promise<void>;
+}
+/** Definition passed to {@link defineMirror}. */
+export interface MirrorDefinition {
+    /** Logger for sync runs; defaults to the framework `logger`. */
+    logger?: MirrorLogger;
+    /** Stable name for logs and telemetry (e.g. `'arxiv-papers'`). */
+    name: string;
+    /** The backend store (e.g. from `sqliteMirrorStore({...})`). */
+    store: MirrorStore;
+    /** The ingester — the one irreducibly per-source part. */
+    sync: SyncGenerator;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/mirror/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/mirror/types.ts"],"names":[],"mappings":"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"}

package/dist/services/mirror/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public contracts for the MirrorService — the source-agnostic
+ * machinery for a persistent, self-refreshing local mirror of a bulk upstream
+ * dataset. The framework owns the store, the sync-state machine, and the runner;
+ * each server supplies only the ingester (`sync` generator) and the schema.
+ * @module services/mirror/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/mirror/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/mirror/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -79,6 +79,10 @@
       "types": "./dist/services/canvas/index.d.ts",
       "import": "./dist/services/canvas/index.js"
     },
+    "./mirror": {
+      "types": "./dist/services/mirror/index.d.ts",
+      "import": "./dist/services/mirror/index.js"
+    },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js"
@@ -171,7 +175,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@cloudflare/vitest-pool-workers": "^0.16.10",
-    "@cloudflare/workers-types": "^4.20260530.1",
+    "@cloudflare/workers-types": "4.20260531.1",
     "@duckdb/node-api": "^1.5.3-r.2",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
@@ -192,6 +196,7 @@
     "@types/validator": "^13.15.10",
     "@vitest/coverage-istanbul": "4.1.7",
     "@vitest/ui": "4.1.7",
+    "better-sqlite3": "^12.10.0",
     "bun-types": "^1.3.14",
     "chrono-node": "^2.9.1",
     "clipboardy": "^5.3.1",
@@ -292,6 +297,7 @@
     "@opentelemetry/sdk-trace-node": "^2.7.0",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@supabase/supabase-js": "^2.103.3",
+    "better-sqlite3": "^12.0.0",
     "chrono-node": "^2.9.0",
     "defuddle": "^0.18.1",
     "diff": "latest",
@@ -346,6 +352,9 @@
     "@supabase/supabase-js": {
       "optional": true
     },
+    "better-sqlite3": {
+      "optional": true
+    },
     "chrono-node": {
       "optional": true
     },

package/skills/api-mirror/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: api-mirror
+description: >
+  Stand up a persistent, self-refreshing local mirror of a bulk upstream dataset with the MirrorService (@cyanheads/mcp-ts-core/mirror). Use when a server wraps a large or slow API and should query a synced local index (embedded SQLite + FTS5) instead of paginating the live API per request.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Context
+
+The MirrorService owns the source-agnostic half of a local mirror — the embedded store, the sync-state machine, the runner — so a server supplies only the two parts that are irreducibly per-source: the **ingester** (a `sync` generator) and the **schema**. It targets the embedded-SQLite tier (~10⁴–10⁷ rows). Node/Bun only: `bun:sqlite` is built-in on Bun, `better-sqlite3` is an optional peer dependency on Node; the store is unavailable on Workers (no SQLite, no persistent filesystem).
+
+Import from `@cyanheads/mcp-ts-core/mirror`.
+
+## The shape
+
+```ts
+import { defineMirror, sqliteMirrorStore } from '@cyanheads/mcp-ts-core/mirror';
+
+const papers = defineMirror({
+  name: 'arxiv-papers',
+  store: sqliteMirrorStore({
+    path: config.mirrorPath,
+    primaryKey: 'id',
+    columns: { id: 'TEXT', title: 'TEXT', authors: 'TEXT', abstract: 'TEXT', updated: 'TEXT' },
+    fts: ['title', 'authors', 'abstract'],          // opt-in FTS5 external-content index
+    indexes: [{ columns: ['updated'] }],
+  }),
+  // The ingester — the one part that is always server-specific.
+  async *sync({ mode, cursor, checkpoint, signal }) {
+    for await (const page of harvestPages({ resumeFrom: cursor, since: checkpoint, signal })) {
+      yield {
+        records: page.rows,             // objects keyed by declared column
+        tombstones: page.deletedIds,    // primary-key values to delete
+        cursor: page.token,             // volatile resume position (see below)
+        checkpoint: page.maxStamp,      // durable high-water mark (see below)
+      };
+    }
+  },
+});
+
+await papers.runSync({ mode: 'init', signal: AbortSignal.timeout(3_600_000) }); // full; resumes on interrupt
+await papers.runSync({ mode: 'refresh' });                                       // incremental
+const { rows, total } = await papers.query({ match: 'transformers', limit: 10, offset: 0 });
+const status = await papers.status();   // { status, ready, checkpoint, total, ... }
+```
+
+## cursor vs. checkpoint — the core distinction
+
+Two resume dimensions, deliberately separate. Conflating them silently corrupts resume for token-paged sources.
+
+| | `cursor` | `checkpoint` |
+|---|---|---|
+| Meaning | Volatile intra-run resume position (e.g. an OAI-PMH resumption token, a page token) | Durable incremental high-water mark (e.g. the max record datestamp) |
+| Lifetime | One run; may expire; **cleared on completion** | Persists; **advances monotonically, only on success** |
+| Used for | Resuming an interrupted `init` | Seeding the next `refresh` |
+
+Why they can't merge: during a from-scratch init the records aren't ordered by the high-water field, so the max-so-far is not a valid resume position — only the cursor is. After a completed init the cursor is meaningless, but the high-water mark is the correct refresh seed. The framework persists both per page and threads the right one back into `sync()` per mode. **The checkpoint must be lexicographically monotonic** (ISO 8601 works); the runner advances the stored checkpoint only when a page's value compares greater.
+
+## What you own vs. what the framework owns
+
+| Framework | Server |
+|---|---|
+| Cross-runtime SQLite handle, WAL + `busy_timeout` | The `sync` generator (the ingester) |
+| `mirror_sync_state` + cursor/checkpoint state machine | Translating your query syntax → FTS5 `match` |
+| `runSync({ init \| refresh })`, per-page persist, resume | Mapping upstream records → row objects |
+| Schema gen (columns + FTS + tokenizer + triggers) | Migration *content* (the `up` functions) |
+| `schema_version` + migration *runner* | Scheduling + init/refresh bootstrap (see below) |
+| Generic `query()` + the raw-handle escape hatch | Server-specific access paths via the raw handle |
+
+## Querying
+
+`query({ match?, filters?, sort?, limit, offset })` covers the common case:
+
+- `match` — an FTS5 `MATCH` expression (only when the store declares `fts` columns). Translate your own query grammar to FTS5 before calling.
+- `filters` — `[{ column, op, value }]`, AND-combined, over declared columns. `op` ∈ `eq|ne|gt|gte|lt|lte|in` (`in` takes an array).
+- `sort` — `{ column, direction }` or `'relevance'` (FTS bm25; requires `match`). Defaults to insertion order.
+
+For access paths the generic query can't express — junction tables for index-backed multi-value filtering, denormalized counters, bespoke `bm25` weighting — use the **raw handle**: `const db = await mirror.raw();` then run prepared statements against your own auxiliary tables (declare them via a migration). Add the auxiliary DDL in a `migrations` step; maintain it from your `sync` mapping or SQL triggers.
+
+## Readiness — key off the completion marker, not live status
+
+`status().ready` is `true` once a full sync has **ever completed** (`completedAt != null`), not when `status === 'complete'`. The dataset stays transactionally queryable during a refresh, so a mirror mid-refresh — or one whose last refresh failed — is still ready and should keep serving. Gate the mirror read path on `await mirror.ready()`; fall back to the live API only when it is `false` (cold, never-completed init).
+
+## Scheduling and bootstrap (server-owned)
+
+The service owns `runSync` + state; it does not schedule. Wire "self-refreshing" yourself:
+
+- **Refresh** — register `runSync({ mode: 'refresh' })` on a cron via `schedulerService` from `@cyanheads/mcp-ts-core/utils`, inside `setup()`. Gate on transport (HTTP) when stdio operators run it out-of-band.
+- **Init** — run out-of-band (a CLI script / one-shot), never on startup: a full init can take hours and must not block the server. It is idempotent and resumable — re-running after an interrupt continues from the persisted cursor.
+
+## Checklist
+
+- [ ] `defineMirror({ name, store, sync })`; the server holds the instance (one per mirror)
+- [ ] `sqliteMirrorStore` spec declares `primaryKey`, `columns`, and (if searching) `fts`
+- [ ] `sync` yields `{ records, tombstones?, cursor?, checkpoint? }` per page; checkpoint is lexicographically monotonic
+- [ ] Read path gated on `await mirror.ready()` with a live fallback when not ready
+- [ ] `better-sqlite3` added as a peer dependency for Node deployments; mirror disabled on Workers
+- [ ] Refresh wired via `schedulerService` in `setup()`; init runs out-of-band
+- [ ] `bun run devcheck` passes