@retrace-dev/cli 0.1.0

package/dist/remote-store.js

@@ -0,0 +1,75 @@
+/** Consistent headers for CLI-originated requests, including runtimes that require an explicit user agent. */
+export function retraceHeaders(token) {
+    return {
+        accept: "application/json",
+        "content-type": "application/json",
+        "user-agent": "@retrace-dev/cli/0.1.0",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+    };
+}
+export class RemoteStore {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async req(method, path, body) {
+        const res = await fetch(this.baseUrl + path, {
+            method,
+            headers: retraceHeaders(this.token),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok)
+            throw new Error(`Retrace API ${method} ${path} → ${res.status}: ${await res.text()}`);
+        return (await res.json());
+    }
+    /** Remote appends server-side (chain sealing must happen where the head lives). */
+    async append(input) {
+        return this.req("POST", "/events", input);
+    }
+    async verify(project) {
+        return this.req("GET", `/projects/${encodeURIComponent(project)}/verify`);
+    }
+    async status(project) {
+        return this.req("GET", `/projects/${encodeURIComponent(project)}/status`);
+    }
+    async createShare() { throw new Error("use share()"); }
+    async getShare(id) { return this.req("GET", `/s/${encodeURIComponent(id)}/meta`); }
+    /** Server-side share creation; returns share + url. */
+    async share(body) {
+        return this.req("POST", `/projects/${encodeURIComponent(body.project)}/share`, body);
+    }
+    async export(scope) {
+        const p = new URLSearchParams();
+        if (scope.artifact_id)
+            p.set("artifact_id", scope.artifact_id);
+        return this.req("GET", `/projects/${encodeURIComponent(scope.project)}/export?${p}`);
+    }
+    async head(project) {
+        return this.req("GET", `/projects/${encodeURIComponent(project)}/head`);
+    }
+    async insert() {
+        throw new Error("RemoteStore.insert is not supported; use append()");
+    }
+    async byIdempotencyKey() {
+        return null;
+    }
+    async get(id) {
+        return this.req("GET", `/events/${encodeURIComponent(id)}`);
+    }
+    async all(project) {
+        return this.req("GET", `/projects/${encodeURIComponent(project)}/events?limit=100000`);
+    }
+    async projects() {
+        return this.req("GET", `/projects`);
+    }
+    async history(q) {
+        const p = new URLSearchParams();
+        for (const [k, v] of Object.entries(q))
+            if (v !== undefined && k !== "project")
+                p.set(k, String(v));
+        return this.req("GET", `/projects/${encodeURIComponent(q.project)}/events?${p}`);
+    }
+}

package/dist/serve.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Local Retrace server: serves the timeline UI + REST API from the same SQLite file the MCP server writes to.
+ *   retrace-serve            → http://localhost:7777
+ * Env: RETRACE_DB, RETRACE_PORT (7777), RETRACE_TOKEN (optional bearer/query token), RETRACE_CREDENTIALS (per-actor tokens, JSON),
+ *      RETRACE_SIGNING_KEY (JWK; else ~/.retrace/signing-key.json, auto-created), RETRACE_ISSUER, RETRACE_PUBLIC_URL,
+ *      RETRACE_GITHUB_SECRET (enables POST /hooks/github), RETRACE_GITHUB_PUSH=1 (also log push commits),
+ *      RETRACE_OWNER (who holds RETRACE_TOKEN; DELETE /projects/:p audit events are attributed to this human)
+ */
+import { IncomingMessage } from "node:http";
+export declare function startServer(port?: number): import("http").Server<typeof IncomingMessage, typeof import("http").ServerResponse>;

package/dist/serve.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Local Retrace server: serves the timeline UI + REST API from the same SQLite file the MCP server writes to.
+ *   retrace-serve            → http://localhost:7777
+ * Env: RETRACE_DB, RETRACE_PORT (7777), RETRACE_TOKEN (optional bearer/query token), RETRACE_CREDENTIALS (per-actor tokens, JSON),
+ *      RETRACE_SIGNING_KEY (JWK; else ~/.retrace/signing-key.json, auto-created), RETRACE_ISSUER, RETRACE_PUBLIC_URL,
+ *      RETRACE_GITHUB_SECRET (enables POST /hooks/github), RETRACE_GITHUB_PUSH=1 (also log push commits),
+ *      RETRACE_OWNER (who holds RETRACE_TOKEN; DELETE /projects/:p audit events are attributed to this human)
+ */
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { createHandler, parseCredentials, parseSigningKey } from "@retrace-dev/core";
+import { loadSigningKey } from "./keys.js";
+import { makeStore } from "./index.js";
+import { isMainModule } from "./is-main.js";
+function toRequest(req) {
+    const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers))
+        if (typeof v === "string")
+            headers.set(k, v);
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    return new Request(url, { method: req.method, headers, body: hasBody ? Readable.toWeb(req) : undefined, ...(hasBody ? { duplex: "half" } : {}) });
+}
+export function startServer(port = Number(process.env.RETRACE_PORT ?? 7777)) {
+    const handle = createHandler(makeStore(), {
+        token: process.env.RETRACE_TOKEN,
+        credentials: parseCredentials(process.env.RETRACE_CREDENTIALS),
+        signingKey: parseSigningKey(process.env.RETRACE_SIGNING_KEY) ?? loadSigningKey(),
+        issuerName: process.env.RETRACE_ISSUER,
+        publicUrl: process.env.RETRACE_PUBLIC_URL,
+        githubSecret: process.env.RETRACE_GITHUB_SECRET,
+        githubIncludePush: process.env.RETRACE_GITHUB_PUSH === "1",
+        ownerActor: process.env.RETRACE_OWNER ? { type: "human", id: process.env.RETRACE_OWNER } : undefined,
+    });
+    const server = createServer(async (req, res) => {
+        try {
+            const out = await handle(toRequest(req));
+            const hdrs = {};
+            out.headers.forEach((v, k) => (hdrs[k] = v));
+            res.writeHead(out.status, hdrs);
+            res.end(Buffer.from(await out.arrayBuffer()));
+        }
+        catch (e) {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: String(e?.message ?? e) }));
+        }
+    });
+    server.listen(port, () => console.error(`Retrace UI + API → http://localhost:${port}`));
+    return server;
+}
+if (isMainModule(import.meta.url))
+    startServer();

package/dist/sqlite-store.d.ts

@@ -0,0 +1,246 @@
+import { ChainHead, Event, EventStore, HistoryQuery, Share } from "@retrace-dev/core";
+export declare class SqliteStore implements EventStore {
+    private db;
+    constructor(path: string);
+    private headSync;
+    head(project: string): Promise<ChainHead | null>;
+    /** Raw row writes for one event — caller owns the transaction. */
+    private insertRows;
+    insert(e: Event): Promise<void>;
+    /** Deletes + audit insert in one transaction (B3); the local server's DELETE /projects/:p needs this. The head
+     *  check runs inside the same transaction, so the audit can only ever commit against the head it describes. */
+    deleteProject(project: string, audit: Event, expectedHead: ChainHead): Promise<{
+        [k: string]: number;
+    }>;
+    createShare(s: Share): Promise<void>;
+    getShare(id: string): Promise<Share | null>;
+    byIdempotencyKey(project: string, key: string): Promise<{
+        id: string;
+        project: string;
+        actor: {
+            type: "human" | "agent" | "system";
+            id: string;
+            display_name?: string | undefined;
+            model?: string | undefined;
+            version?: string | undefined;
+            on_behalf_of?: string | undefined;
+        };
+        action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+        artifacts: {
+            id: string;
+            kind?: string | undefined;
+            label?: string | undefined;
+            derived_from?: string[] | undefined;
+            role?: "used" | "generated" | "both" | undefined;
+        }[];
+        timestamp: string;
+        seq: number;
+        prev_hash: string;
+        hash: string;
+        received_at: string;
+        action_detail?: string | undefined;
+        change?: {
+            before_hash?: string | undefined;
+            after_hash?: string | undefined;
+            diff?: string | undefined;
+            summary?: string | undefined;
+        } | undefined;
+        duration_ms?: number | undefined;
+        location?: {
+            system?: string | undefined;
+            path?: string | undefined;
+            url?: string | undefined;
+            environment?: string | undefined;
+            device?: string | undefined;
+            session?: string | undefined;
+            client?: string | undefined;
+            ide?: string | undefined;
+            workspace?: string | undefined;
+            surface?: "agent" | "tty" | undefined;
+        } | undefined;
+        intent?: string | undefined;
+        caused_by?: string | undefined;
+        method?: {
+            params?: Record<string, unknown> | undefined;
+            tool?: string | undefined;
+            instruction?: string | undefined;
+            automated?: boolean | undefined;
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
+        idempotency_key?: string | undefined;
+        tags?: string[] | undefined;
+    } | null>;
+    get(id: string): Promise<{
+        id: string;
+        project: string;
+        actor: {
+            type: "human" | "agent" | "system";
+            id: string;
+            display_name?: string | undefined;
+            model?: string | undefined;
+            version?: string | undefined;
+            on_behalf_of?: string | undefined;
+        };
+        action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+        artifacts: {
+            id: string;
+            kind?: string | undefined;
+            label?: string | undefined;
+            derived_from?: string[] | undefined;
+            role?: "used" | "generated" | "both" | undefined;
+        }[];
+        timestamp: string;
+        seq: number;
+        prev_hash: string;
+        hash: string;
+        received_at: string;
+        action_detail?: string | undefined;
+        change?: {
+            before_hash?: string | undefined;
+            after_hash?: string | undefined;
+            diff?: string | undefined;
+            summary?: string | undefined;
+        } | undefined;
+        duration_ms?: number | undefined;
+        location?: {
+            system?: string | undefined;
+            path?: string | undefined;
+            url?: string | undefined;
+            environment?: string | undefined;
+            device?: string | undefined;
+            session?: string | undefined;
+            client?: string | undefined;
+            ide?: string | undefined;
+            workspace?: string | undefined;
+            surface?: "agent" | "tty" | undefined;
+        } | undefined;
+        intent?: string | undefined;
+        caused_by?: string | undefined;
+        method?: {
+            params?: Record<string, unknown> | undefined;
+            tool?: string | undefined;
+            instruction?: string | undefined;
+            automated?: boolean | undefined;
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
+        idempotency_key?: string | undefined;
+        tags?: string[] | undefined;
+    } | null>;
+    all(project: string): Promise<{
+        id: string;
+        project: string;
+        actor: {
+            type: "human" | "agent" | "system";
+            id: string;
+            display_name?: string | undefined;
+            model?: string | undefined;
+            version?: string | undefined;
+            on_behalf_of?: string | undefined;
+        };
+        action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+        artifacts: {
+            id: string;
+            kind?: string | undefined;
+            label?: string | undefined;
+            derived_from?: string[] | undefined;
+            role?: "used" | "generated" | "both" | undefined;
+        }[];
+        timestamp: string;
+        seq: number;
+        prev_hash: string;
+        hash: string;
+        received_at: string;
+        action_detail?: string | undefined;
+        change?: {
+            before_hash?: string | undefined;
+            after_hash?: string | undefined;
+            diff?: string | undefined;
+            summary?: string | undefined;
+        } | undefined;
+        duration_ms?: number | undefined;
+        location?: {
+            system?: string | undefined;
+            path?: string | undefined;
+            url?: string | undefined;
+            environment?: string | undefined;
+            device?: string | undefined;
+            session?: string | undefined;
+            client?: string | undefined;
+            ide?: string | undefined;
+            workspace?: string | undefined;
+            surface?: "agent" | "tty" | undefined;
+        } | undefined;
+        intent?: string | undefined;
+        caused_by?: string | undefined;
+        method?: {
+            params?: Record<string, unknown> | undefined;
+            tool?: string | undefined;
+            instruction?: string | undefined;
+            automated?: boolean | undefined;
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
+        idempotency_key?: string | undefined;
+        tags?: string[] | undefined;
+    }[]>;
+    projects(): Promise<string[]>;
+    history(q: HistoryQuery): Promise<{
+        id: string;
+        project: string;
+        actor: {
+            type: "human" | "agent" | "system";
+            id: string;
+            display_name?: string | undefined;
+            model?: string | undefined;
+            version?: string | undefined;
+            on_behalf_of?: string | undefined;
+        };
+        action: "received" | "created" | "edited" | "deleted" | "read" | "executed" | "approved" | "rejected" | "sent" | "moved" | "renamed" | "instructed" | "committed" | "merged" | "other";
+        artifacts: {
+            id: string;
+            kind?: string | undefined;
+            label?: string | undefined;
+            derived_from?: string[] | undefined;
+            role?: "used" | "generated" | "both" | undefined;
+        }[];
+        timestamp: string;
+        seq: number;
+        prev_hash: string;
+        hash: string;
+        received_at: string;
+        action_detail?: string | undefined;
+        change?: {
+            before_hash?: string | undefined;
+            after_hash?: string | undefined;
+            diff?: string | undefined;
+            summary?: string | undefined;
+        } | undefined;
+        duration_ms?: number | undefined;
+        location?: {
+            system?: string | undefined;
+            path?: string | undefined;
+            url?: string | undefined;
+            environment?: string | undefined;
+            device?: string | undefined;
+            session?: string | undefined;
+            client?: string | undefined;
+            ide?: string | undefined;
+            workspace?: string | undefined;
+            surface?: "agent" | "tty" | undefined;
+        } | undefined;
+        intent?: string | undefined;
+        caused_by?: string | undefined;
+        method?: {
+            params?: Record<string, unknown> | undefined;
+            tool?: string | undefined;
+            instruction?: string | undefined;
+            automated?: boolean | undefined;
+            tokens?: number | undefined;
+            cost_usd?: number | undefined;
+        } | undefined;
+        idempotency_key?: string | undefined;
+        tags?: string[] | undefined;
+    }[]>;
+}

package/dist/sqlite-store.js

@@ -0,0 +1,121 @@
+/** Local SQLite store using Node's built-in node:sqlite (Node >= 22.13). No native deps. */
+import { DatabaseSync } from "node:sqlite";
+import { HeadMovedError, SCHEMA_SQL } from "@retrace-dev/core";
+export class SqliteStore {
+    db;
+    constructor(path) {
+        this.db = new DatabaseSync(path);
+        this.db.exec("PRAGMA journal_mode = WAL;");
+        this.db.exec(SCHEMA_SQL);
+    }
+    headSync(project) {
+        const row = this.db.prepare("SELECT seq, hash FROM events WHERE project = ? ORDER BY seq DESC LIMIT 1").get(project);
+        return row ?? null;
+    }
+    async head(project) {
+        return this.headSync(project);
+    }
+    /** Raw row writes for one event — caller owns the transaction. */
+    insertRows(e) {
+        const ins = this.db.prepare(`INSERT INTO events (id, project, seq, timestamp, received_at, actor_type, actor_id, action, caused_by, idempotency_key, prev_hash, hash, body)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        const insArt = this.db.prepare("INSERT OR IGNORE INTO event_artifacts (event_id, project, artifact_id) VALUES (?, ?, ?)");
+        ins.run(e.id, e.project, e.seq, e.timestamp, e.received_at, e.actor.type, e.actor.id, e.action, e.caused_by ?? null, e.idempotency_key ?? null, e.prev_hash, e.hash, JSON.stringify(e));
+        for (const a of e.artifacts)
+            insArt.run(e.id, e.project, a.id);
+    }
+    async insert(e) {
+        this.db.exec("BEGIN");
+        try {
+            this.insertRows(e);
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    /** Deletes + audit insert in one transaction (B3); the local server's DELETE /projects/:p needs this. The head
+     *  check runs inside the same transaction, so the audit can only ever commit against the head it describes. */
+    async deleteProject(project, audit, expectedHead) {
+        const tables = ["events", "event_artifacts", "shares"];
+        this.db.exec("BEGIN");
+        try {
+            const head = this.headSync(project); // synchronous: the transaction never yields between check and deletes
+            if (!head || head.seq !== expectedHead.seq || head.hash !== expectedHead.hash)
+                throw new HeadMovedError(project, expectedHead);
+            const counts = Object.fromEntries(tables.map((t) => [t, Number(this.db.prepare(`DELETE FROM ${t} WHERE project = ?`).run(project).changes)]));
+            this.insertRows(audit);
+            this.db.exec("COMMIT");
+            return counts;
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    async createShare(s) {
+        this.db.prepare("INSERT INTO shares (id, project, artifact_id, label, created_at, expires_at, created_by) VALUES (?, ?, ?, ?, ?, ?, ?)")
+            .run(s.id, s.project, s.artifact_id ?? null, s.label ?? null, s.created_at, s.expires_at ?? null, s.created_by ?? null);
+    }
+    async getShare(id) {
+        const r = this.db.prepare("SELECT * FROM shares WHERE id = ?").get(id);
+        if (!r)
+            return null;
+        return { id: r.id, project: r.project, artifact_id: r.artifact_id ?? undefined, label: r.label ?? undefined, created_at: r.created_at, expires_at: r.expires_at ?? undefined, created_by: r.created_by ?? undefined };
+    }
+    async byIdempotencyKey(project, key) {
+        const row = this.db.prepare("SELECT body FROM events WHERE project = ? AND idempotency_key = ? LIMIT 1").get(project, key);
+        return row ? JSON.parse(row.body) : null;
+    }
+    async get(id) {
+        const row = this.db.prepare("SELECT body FROM events WHERE id = ?").get(id);
+        return row ? JSON.parse(row.body) : null;
+    }
+    async all(project) {
+        const rows = this.db.prepare("SELECT body FROM events WHERE project = ? ORDER BY seq ASC").all(project);
+        return rows.map((r) => JSON.parse(r.body));
+    }
+    async projects() {
+        const rows = this.db.prepare("SELECT DISTINCT project FROM events ORDER BY project").all();
+        return rows.map((r) => r.project);
+    }
+    async history(q) {
+        const where = ["e.project = ?"];
+        const params = [q.project];
+        let join = "";
+        if (q.artifact_id) {
+            join = "JOIN event_artifacts ea ON ea.event_id = e.id";
+            where.push("ea.artifact_id = ?");
+            params.push(q.artifact_id);
+        }
+        if (q.actor_id) {
+            where.push("e.actor_id = ?");
+            params.push(q.actor_id);
+        }
+        if (q.actor_type) {
+            where.push("e.actor_type = ?");
+            params.push(q.actor_type);
+        }
+        if (q.action) {
+            where.push("e.action = ?");
+            params.push(q.action);
+        }
+        if (q.since) {
+            where.push("e.timestamp >= ?");
+            params.push(q.since);
+        }
+        if (q.until) {
+            where.push("e.timestamp <= ?");
+            params.push(q.until);
+        }
+        if (q.text) {
+            where.push("e.body LIKE ?");
+            params.push(`%${q.text}%`);
+        }
+        const limit = Math.min(q.limit ?? 100, 1000);
+        const sql = `SELECT DISTINCT e.body, e.seq FROM events e ${join} WHERE ${where.join(" AND ")} ORDER BY e.seq ASC LIMIT ${limit}`;
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => JSON.parse(r.body));
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@retrace-dev/cli",
+  "version": "0.1.0",
+  "description": "CLI, MCP server, Git adapter, and local UI for verifiable AI-assisted development provenance",
+  "type": "module",
+  "bin": {
+    "retrace-mcp": "dist/index.js",
+    "retrace-serve": "dist/serve.js",
+    "retrace-git": "dist/git-hook.js",
+    "retrace": "dist/doctor.js",
+    "retrace-export": "dist/export-cli.js",
+    "retrace-github": "dist/github-cli.js",
+    "retrace-gdrive": "dist/gdrive-cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "!dist/*.test.js", "!dist/*.test.d.ts", "README.md"],
+  "engines": { "node": ">=22" },
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/jordandru/retrace.git", "directory": "packages/mcp-server" },
+  "homepage": "https://github.com/jordandru/retrace#readme",
+  "bugs": { "url": "https://github.com/jordandru/retrace/issues" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node --test dist/*.test.js",
+    "start": "node dist/index.js",
+    "serve": "node dist/serve.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@retrace-dev/core": "0.1.0",
+    "zod": "^3.23.8"
+  }
+}