@bluefields/cli 0.2.0

package/dist/mcp-server.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Local MCP server (stdio, JSON-RPC 2.0, newline-delimited).
+ *
+ * Exposes the Bluefield local store as tools an agent can call natively:
+ * `scrape`, `log`, `diff`, `verify`, `export`, `identity`. Unlike
+ * `@bluefields/mcp-server` (a thin HTTP client to the hosted API), every tool
+ * here runs entirely LOCALLY against the on-disk store — no API key, no
+ * network beyond the fetch itself, no telemetry.
+ *
+ * The protocol surface we need (initialize, tools/list, tools/call) is small
+ * enough to implement directly, mirroring the pattern in `@bluefields/mcp-server`
+ * rather than taking an MCP-SDK dependency.
+ */
+import './quiet.js';
+import { type Bluefield } from './bluefield.js';
+interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOLS: ToolDef[];
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export declare function handleRequest(msg: JsonRpcRequest, bf: Bluefield): Promise<JsonRpcResponse | null>;
+/** Run the stdio JSON-RPC loop until stdin closes. */
+export declare function runMcpServer(): Promise<void>;
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Local MCP server (stdio, JSON-RPC 2.0, newline-delimited).
+ *
+ * Exposes the Bluefield local store as tools an agent can call natively:
+ * `scrape`, `log`, `diff`, `verify`, `export`, `identity`. Unlike
+ * `@bluefields/mcp-server` (a thin HTTP client to the hosted API), every tool
+ * here runs entirely LOCALLY against the on-disk store — no API key, no
+ * network beyond the fetch itself, no telemetry.
+ *
+ * The protocol surface we need (initialize, tools/list, tools/call) is small
+ * enough to implement directly, mirroring the pattern in `@bluefields/mcp-server`
+ * rather than taking an MCP-SDK dependency.
+ */
+import './quiet.js'; // MUST be first — silences engine logs before fetcher loads
+import process from 'node:process';
+import { openBluefield } from './bluefield.js';
+import { PROJECT_NAME, STANDARD_FULL } from './constants.js';
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = { name: `${PROJECT_NAME.toLowerCase()}-local`, version: '0.1.0' };
+export const TOOLS = [
+    {
+        name: 'scrape',
+        description: `Capture a URL into the local ${PROJECT_NAME} store: fetch, content-address on disk, and sign an offline-verifiable provenance manifest (${STANDARD_FULL}). Returns the snapshot id, content hash, and whether it changed since the last capture.`,
+        inputSchema: {
+            type: 'object',
+            required: ['url'],
+            properties: {
+                url: { type: 'string', description: 'The URL to capture.' },
+                sign: { type: 'boolean', description: 'Sign the manifest (default true).' },
+                extract: {
+                    type: 'boolean',
+                    description: 'Run structured extraction (needs ANTHROPIC_API_KEY).',
+                },
+                schema: { type: 'object', description: 'JSON schema for structured extraction.' },
+                intent: { type: 'string', description: 'One-sentence extraction hint.' },
+            },
+        },
+    },
+    {
+        name: 'log',
+        description: 'List snapshot history, newest first — all snapshots or just one URL.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Filter to this URL (optional).' },
+                limit: { type: 'number', description: 'Max rows (default 50).' },
+            },
+        },
+    },
+    {
+        name: 'diff',
+        description: 'Diff two snapshots (by id-prefix or URL). With one URL and no `to`, diffs its two most recent snapshots. Set `structured` to diff extracted data instead of raw content.',
+        inputSchema: {
+            type: 'object',
+            required: ['from'],
+            properties: {
+                from: { type: 'string', description: 'Snapshot ref A (id-prefix or URL).' },
+                to: { type: 'string', description: 'Snapshot ref B (optional).' },
+                structured: { type: 'boolean', description: 'Diff structured data (JSON Patch).' },
+            },
+        },
+    },
+    {
+        name: 'verify',
+        description: "Verify a snapshot offline: recompute its content hash and check the Ed25519 signature against a trusted key. Returns whether it's authentic and untampered.",
+        inputSchema: {
+            type: 'object',
+            required: ['ref'],
+            properties: {
+                ref: { type: 'string', description: 'Snapshot ref (id-prefix or URL).' },
+                trustEmbedded: { type: 'boolean', description: 'Trust the bundle-embedded key (TOFU).' },
+            },
+        },
+    },
+    {
+        name: 'export',
+        description: 'Export a snapshot as raw content + a portable proof bundle (manifest + signature + public key) into a directory.',
+        inputSchema: {
+            type: 'object',
+            required: ['ref'],
+            properties: {
+                ref: { type: 'string', description: 'Snapshot ref (id-prefix or URL).' },
+                out: { type: 'string', description: 'Destination directory (default cwd).' },
+            },
+        },
+    },
+    {
+        name: 'identity',
+        description: "Show this machine's public signing identity (keyId + public JWK). Safe to share.",
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+const asString = (v) => (typeof v === 'string' ? v : undefined);
+const textResult = (v) => ({
+    content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }],
+});
+/** Dispatch one tool call against the local library. */
+async function callTool(bf, name, args) {
+    switch (name) {
+        case 'scrape': {
+            const url = asString(args.url);
+            if (!url)
+                throw new Error('scrape: `url` is required');
+            return textResult(await bf.scrape(url, {
+                sign: args.sign !== false,
+                extract: args.extract === true,
+                schema: args.schema ?? null,
+                intent: asString(args.intent) ?? null,
+            }));
+        }
+        case 'log':
+            return textResult(await bf.log(asString(args.url) ?? null, {
+                limit: typeof args.limit === 'number' ? args.limit : 50,
+            }));
+        case 'diff': {
+            const from = asString(args.from);
+            if (!from)
+                throw new Error('diff: `from` is required');
+            return textResult(await bf.diff(from, asString(args.to), {
+                mode: args.structured === true ? 'structured' : 'content',
+            }));
+        }
+        case 'verify': {
+            const ref = asString(args.ref);
+            if (!ref)
+                throw new Error('verify: `ref` is required');
+            return textResult(await bf.verify(ref, { trustEmbedded: args.trustEmbedded === true }));
+        }
+        case 'export': {
+            const ref = asString(args.ref);
+            if (!ref)
+                throw new Error('export: `ref` is required');
+            return textResult(await bf.export(ref, asString(args.out) ?? '.'));
+        }
+        case 'identity':
+            return textResult(bf.publicIdentity());
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
+export async function handleRequest(msg, bf) {
+    const id = msg.id ?? null;
+    switch (msg.method) {
+        case 'initialize':
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: SERVER_INFO,
+                },
+            };
+        case 'notifications/initialized':
+            return null;
+        case 'ping':
+            return { jsonrpc: '2.0', id, result: {} };
+        case 'tools/list':
+            return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+        case 'tools/call': {
+            const name = asString(msg.params?.name) ?? '';
+            const raw = msg.params?.arguments;
+            const args = (raw && typeof raw === 'object' ? raw : {});
+            try {
+                return { jsonrpc: '2.0', id, result: await callTool(bf, name, args) };
+            }
+            catch (err) {
+                // Tool errors are returned as an error result, not a protocol error,
+                // so the agent sees the message and can recover.
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        isError: true,
+                        content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+                    },
+                };
+            }
+        }
+        default:
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `method not found: ${msg.method}` },
+            };
+    }
+}
+/** Run the stdio JSON-RPC loop until stdin closes. */
+export async function runMcpServer() {
+    const bf = await openBluefield();
+    const write = (line) => process.stdout.write(line);
+    process.stdin.setEncoding('utf8');
+    await new Promise((resolve, reject) => {
+        let buffer = '';
+        let inFlight = 0;
+        let ended = false;
+        const settleIfDone = () => {
+            if (ended && inFlight === 0 && buffer.indexOf('\n') < 0)
+                resolve();
+        };
+        const dispatch = (msg) => {
+            inFlight++;
+            handleRequest(msg, bf)
+                .catch((err) => ({
+                jsonrpc: '2.0',
+                id: msg.id ?? null,
+                error: { code: -32603, message: err instanceof Error ? err.message : String(err) },
+            }))
+                .then((res) => {
+                if (res)
+                    write(`${JSON.stringify(res)}\n`);
+            })
+                .catch(() => {
+                /* a write failure must not crash the server */
+            })
+                .finally(() => {
+                inFlight--;
+                settleIfDone();
+            });
+        };
+        const pump = () => {
+            for (;;) {
+                const nl = buffer.indexOf('\n');
+                if (nl < 0)
+                    break;
+                const line = buffer.slice(0, nl).trim();
+                buffer = buffer.slice(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    dispatch(JSON.parse(line));
+                }
+                catch {
+                    /* skip malformed frame */
+                }
+            }
+            settleIfDone();
+        };
+        process.stdin.on('data', (chunk) => {
+            buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            pump();
+        });
+        process.stdin.on('end', () => {
+            ended = true;
+            pump();
+        });
+        process.stdin.on('error', reject);
+    });
+    await bf.close();
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Store-location resolution — "where does this machine keep its snapshots?".
+ *
+ * Resolution order (git-like):
+ *   1. `$BF_HOME` if set                        → explicit override
+ *   2. nearest `.bf/` walking up from `cwd`     → repo-local project store
+ *   3. `~/.bluefield/`                          → global default store
+ *
+ * The PRIVATE signing key is deliberately NOT stored inside the resolved
+ * store root: it always lives under `~/.bluefield/keys` (the user's global
+ * identity). That keeps a project-local `.bf/` safe to commit/share/inspect —
+ * it only ever holds public material (objects, manifests, public JWKs, db).
+ */
+/** Absolute path to the user's global home store (`~/.bluefield`). */
+export declare function globalHome(): string;
+/**
+ * The signing-keys directory: `~/.bluefield/keys` by default, relocatable via
+ * `BF_KEYS_DIR`. Kept deliberately separate from the (possibly project-local)
+ * store root so the private identity never lands inside a shareable `.bf`.
+ */
+export declare function keysDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Find the nearest `.bf/` directory walking up from `startDir`. Returns null
+ * if none is found before the filesystem root.
+ */
+export declare function findLocalStore(startDir?: string): string | null;
+/**
+ * Resolve the active store root. Pure (no filesystem writes) so callers can
+ * decide whether to create it.
+ */
+export declare function resolveStoreRoot(opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/** The set of directories that make up a store. */
+export interface StorePaths {
+    root: string;
+    /** Content-addressed raw bodies: `objects/<ab>/<sha256>`. */
+    objects: string;
+    /** SignedManifest sidecars keyed by snapshot id. */
+    manifests: string;
+    /** PGlite data directory. */
+    db: string;
+    /** Extra pinned public keys the user trusts for `verify` (`*.jwk`). */
+    trusted: string;
+    /** Optional JSON config (proxy/LLM overrides, store display name). */
+    config: string;
+    /** Global keys dir — always under `~/.bluefield/keys`, never inside `root`. */
+    keys: string;
+}
+/** Compute the sub-paths of a store root (pure). */
+export declare function storePaths(root: string): StorePaths;

package/dist/paths.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Store-location resolution — "where does this machine keep its snapshots?".
+ *
+ * Resolution order (git-like):
+ *   1. `$BF_HOME` if set                        → explicit override
+ *   2. nearest `.bf/` walking up from `cwd`     → repo-local project store
+ *   3. `~/.bluefield/`                          → global default store
+ *
+ * The PRIVATE signing key is deliberately NOT stored inside the resolved
+ * store root: it always lives under `~/.bluefield/keys` (the user's global
+ * identity). That keeps a project-local `.bf/` safe to commit/share/inspect —
+ * it only ever holds public material (objects, manifests, public JWKs, db).
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { HOME_DIR_NAME, HOME_ENV, LOCAL_DIR_NAME } from './constants.js';
+/** Absolute path to the user's global home store (`~/.bluefield`). */
+export function globalHome() {
+    return join(homedir(), HOME_DIR_NAME);
+}
+/**
+ * The signing-keys directory: `~/.bluefield/keys` by default, relocatable via
+ * `BF_KEYS_DIR`. Kept deliberately separate from the (possibly project-local)
+ * store root so the private identity never lands inside a shareable `.bf`.
+ */
+export function keysDir(env = process.env) {
+    const override = env.BF_KEYS_DIR;
+    if (override?.trim())
+        return resolve(override.trim());
+    return join(globalHome(), 'keys');
+}
+/**
+ * Find the nearest `.bf/` directory walking up from `startDir`. Returns null
+ * if none is found before the filesystem root.
+ */
+export function findLocalStore(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    // Walk to the filesystem root; dirname('/') === '/' terminates the loop.
+    for (;;) {
+        const candidate = join(dir, LOCAL_DIR_NAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the active store root. Pure (no filesystem writes) so callers can
+ * decide whether to create it.
+ */
+export function resolveStoreRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const override = env[HOME_ENV];
+    if (override?.trim())
+        return resolve(override.trim());
+    const local = findLocalStore(opts.cwd);
+    if (local)
+        return local;
+    return globalHome();
+}
+/** Compute the sub-paths of a store root (pure). */
+export function storePaths(root) {
+    return {
+        root,
+        objects: join(root, 'objects'),
+        manifests: join(root, 'manifests'),
+        db: join(root, 'db'),
+        trusted: join(root, 'trusted'),
+        config: join(root, 'config.json'),
+        keys: keysDir(),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEzE,sEAAsE;AACtE,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1D,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,CAAC;IACjC,IAAI,QAAQ,EAAE,IAAI,EAAE;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,OAAO,IAAI,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IAC7D,IAAI,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,yEAAyE;IACzE,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC5C,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAkD,EAAE;IACnF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,IAAI,QAAQ,EAAE,IAAI,EAAE;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAmBD,oDAAoD;AACpD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;QAC9B,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;QAClC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;QACpB,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QACjC,IAAI,EAAE,OAAO,EAAE;KAChB,CAAC;AACJ,CAAC"}

package/dist/quiet.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Side-effect module: default the engine's structured logger to silent for the
+ * CLI so pino's JSON output never pollutes stdout — critical for `--json` and
+ * for the MCP stdio transport, where stray stdout frames corrupt the protocol.
+ *
+ * MUST be the first import in every executable entry point (`cli.ts`,
+ * `mcp-server.ts`) so it runs before `@bluefields/fetcher` builds its layer
+ * logger (which reads `LOG_LEVEL` once, at module load). Users can opt back in
+ * with `LOG_LEVEL=info` (or debug/trace) in the environment.
+ */
+export {};

package/dist/quiet.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Side-effect module: default the engine's structured logger to silent for the
+ * CLI so pino's JSON output never pollutes stdout — critical for `--json` and
+ * for the MCP stdio transport, where stray stdout frames corrupt the protocol.
+ *
+ * MUST be the first import in every executable entry point (`cli.ts`,
+ * `mcp-server.ts`) so it runs before `@bluefields/fetcher` builds its layer
+ * logger (which reads `LOG_LEVEL` once, at module load). Users can opt back in
+ * with `LOG_LEVEL=info` (or debug/trace) in the environment.
+ */
+process.env.LOG_LEVEL ??= 'silent';
+export {};
+//# sourceMappingURL=quiet.js.map

package/dist/quiet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quiet.js","sourceRoot":"","sources":["../src/quiet.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C;;;;;;;;;GASG;AAEH,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The local metadata store — an embedded Postgres (PGlite, WASM, in-process)
+ * that satisfies the `DbClient` the engine injects. NO hosted Postgres, no
+ * network, no KMS. The full Drizzle schema is applied to a file-backed PGlite
+ * data directory under `<store>/db`, so snapshot history survives across CLI
+ * invocations and `log`/`diff`/`watch`/`export` can query it with real SQL.
+ *
+ * This reuses the QA real-DB harness pattern (statement-by-statement, tolerant
+ * apply): a handful of migrations use Neon/pg_cron/pg_partman features PGlite
+ * lacks; those statements skip harmlessly while the engine tables are created
+ * from plain DDL. Two extra local adaptations then run:
+ *
+ *   1. DEFAULT partitions — `snapshots` / `cost_records` / `events` /
+ *      `audit_log` are declared `PARTITION BY RANGE`, and without pg_partman
+ *      they have no child partitions, so INSERTs would fail. We attach a
+ *      `<table>_default DEFAULT` partition to each so rows land locally.
+ *   2. A single seed `customers` row — `cost_records.customer_id` is a NOT-NULL
+ *      FK to `customers`, and the engine writes a cost row per fetch. One fixed
+ *      local customer keeps the engine's billing plumbing satisfied with zero
+ *      behavioural change.
+ */
+import { type DbClient } from '@bluefields/db';
+import { PGlite } from '@electric-sql/pglite';
+/**
+ * Fixed local identity for the single-user store. `cost_records` and
+ * `snapshots` are attributed to this synthetic customer; it never leaves the
+ * machine and carries no billing meaning.
+ */
+export declare const LOCAL_CUSTOMER_ID: "00000000-0000-4000-8000-000000000001";
+export declare const LOCAL_CUSTOMER_EMAIL: "local@bluefield.invalid";
+export declare const LOCAL_SUBSCRIPTION_ID: null;
+/** A live handle to the local store. */
+export interface Store {
+    db: DbClient;
+    client: PGlite;
+    /** How many migration statements were skipped (Neon/pg_cron/partman-only). */
+    skipped: number;
+    close(): Promise<void>;
+}
+/**
+ * Open (or create) the file-backed local store at `dbDir` and return an
+ * engine-compatible `DbClient`. Idempotent: re-opening an existing store
+ * re-applies DDL tolerantly (`IF NOT EXISTS` / already-exists skips) and
+ * re-seeds via `ON CONFLICT DO NOTHING`.
+ */
+export declare function openStore(dbDir: string): Promise<Store>;