locker-mcp-server 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,19 @@
+import { LockerConfig } from "./config";
+export interface KeyResponse {
+    service: string;
+    key: string;
+}
+export interface ServiceListItem {
+    service: string;
+    createdAt: string;
+    lastUsed: string | null;
+}
+/**
+ * Retrieves a decrypted API key from the Locker API.
+ * Sends the agent identifier for audit logging.
+ */
+export declare function getKey(config: LockerConfig, service: string, agentIdentifier?: string): Promise<KeyResponse>;
+/**
+ * Lists all stored service names (not key values).
+ */
+export declare function listServices(config: LockerConfig): Promise<ServiceListItem[]>;

package/dist/api.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKey = getKey;
+exports.listServices = listServices;
+/**
+ * Retrieves a decrypted API key from the Locker API.
+ * Sends the agent identifier for audit logging.
+ */
+async function getKey(config, service, agentIdentifier = "mcp-server") {
+    const url = `${config.apiUrl}/keys/${encodeURIComponent(service)}`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${config.token}`,
+            "Content-Type": "application/json",
+            "X-Agent-Identifier": agentIdentifier,
+        },
+    });
+    if (res.status === 401) {
+        throw new Error("Session expired. Run `locker login` to re-authenticate.");
+    }
+    if (res.status === 404) {
+        throw new Error(`No key found for service: ${service}. Store one with: locker set ${service} <key>`);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error || `API error: ${res.status}`);
+    }
+    return (await res.json());
+}
+/**
+ * Lists all stored service names (not key values).
+ */
+async function listServices(config) {
+    const url = `${config.apiUrl}/keys`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${config.token}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (res.status === 401) {
+        throw new Error("Session expired. Run `locker login` to re-authenticate.");
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(body.error || `API error: ${res.status}`);
+    }
+    const data = (await res.json());
+    return data.services;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";;AAiBA,wBA6BC;AAKD,oCAuBC;AA7DD;;;GAGG;AACI,KAAK,UAAU,MAAM,CAC1B,MAAoB,EACpB,OAAe,EACf,kBAA0B,YAAY;IAEtC,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,SAAS,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE;YACvC,cAAc,EAAE,kBAAkB;YAClC,oBAAoB,EAAE,eAAe;SACtC;KACF,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,gCAAgC,OAAO,QAAQ,CAAC,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAA6B,CAAA,CAA2B,CAAC;QACpG,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,cAAc,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgB,CAAC;AAC3C,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,YAAY,CAChC,MAAoB;IAEpB,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,OAAO,CAAC;IACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE;YACvC,cAAc,EAAE,kBAAkB;SACnC;KACF,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAA6B,CAAA,CAA2B,CAAC;QACpG,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,cAAc,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAoC,CAAC;IACnE,OAAO,IAAI,CAAC,QAAQ,CAAC;AACvB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface LockerConfig {
+    token: string;
+    email: string;
+    apiUrl: string;
+}
+/**
+ * Reads the Locker CLI config from ~/.locker/config.
+ * This is the same file the CLI writes after `locker login`.
+ * Returns null if not found or invalid.
+ */
+export declare function readConfig(): LockerConfig | null;
+/**
+ * Returns config or throws with a helpful message.
+ */
+export declare function requireConfig(): LockerConfig;

package/dist/config.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConfig = readConfig;
+exports.requireConfig = requireConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const CONFIG_FILE = node_path_1.default.join(node_os_1.default.homedir(), ".locker", "config");
+/**
+ * Reads the Locker CLI config from ~/.locker/config.
+ * This is the same file the CLI writes after `locker login`.
+ * Returns null if not found or invalid.
+ */
+function readConfig() {
+    try {
+        if (!node_fs_1.default.existsSync(CONFIG_FILE))
+            return null;
+        const raw = node_fs_1.default.readFileSync(CONFIG_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || !parsed.email || !parsed.apiUrl)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns config or throws with a helpful message.
+ */
+function requireConfig() {
+    const config = readConfig();
+    if (!config) {
+        throw new Error("Not logged in to Locker. Run `locker login` first to authenticate.");
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;AAiBA,gCAUC;AAKD,sCAQC;AAxCD,sDAAyB;AACzB,0DAA6B;AAC7B,sDAAyB;AAEzB,MAAM,WAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,iBAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAQjE;;;;GAIG;AACH,SAAgB,UAAU;IACxB,IAAI,CAAC;QACH,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7C,MAAM,GAAG,GAAG,iBAAE,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAClE,OAAO,MAAsB,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,oEAAoE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const config_1 = require("./config");
+const api_1 = require("./api");
+const server = new mcp_js_1.McpServer({
+    name: "locker",
+    version: "0.1.0",
+});
+// ── Tool: locker_get ──
+// Retrieves a decrypted API key for a given service.
+server.tool("locker_get", "Retrieve an API key from Locker. Returns the decrypted key for the specified service. The retrieval is logged in the audit trail.", {
+    service: zod_1.z.string().describe("The service name (e.g. 'openai', 'resend', 'stripe')"),
+    agent: zod_1.z.string().optional().describe("Agent identifier for the audit log (defaults to 'mcp-server')"),
+}, async ({ service, agent }) => {
+    try {
+        const config = (0, config_1.requireConfig)();
+        const result = await (0, api_1.getKey)(config, service, agent || "mcp-server");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.key,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ── Tool: locker_list ──
+// Lists all stored service names (never exposes key values).
+server.tool("locker_list", "List all services that have API keys stored in Locker. Returns service names only — never the actual key values.", {}, async () => {
+    try {
+        const config = (0, config_1.requireConfig)();
+        const services = await (0, api_1.listServices)(config);
+        if (services.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No keys stored in Locker. Store one with: locker set <service> <key>",
+                    },
+                ],
+            };
+        }
+        const lines = services.map((s) => {
+            const lastUsed = s.lastUsed
+                ? `last used ${new Date(s.lastUsed).toLocaleDateString()}`
+                : "never used";
+            return `  ${s.service} (${lastUsed})`;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${services.length} key${services.length === 1 ? "" : "s"} stored:\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ── Start server ──
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "locker-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Locker — lets AI agents retrieve API keys securely",
+  "main": "dist/index.js",
+  "bin": {
+    "locker-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/api.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getKey, listServices } from "./api";
+
+const mockConfig = {
+  token: "jwt-test-token",
+  email: "test@example.com",
+  apiUrl: "http://localhost:3001",
+};
+
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.stubGlobal("fetch", mockFetch);
+});
+
+describe("getKey", () => {
+  it("sends authenticated request with agent identifier", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ service: "openai", key: "sk-abc123" }),
+    });
+
+    const result = await getKey(mockConfig, "openai", "claude-code");
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "http://localhost:3001/keys/openai",
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          Authorization: "Bearer jwt-test-token",
+          "X-Agent-Identifier": "claude-code",
+        }),
+      })
+    );
+    expect(result.key).toBe("sk-abc123");
+  });
+
+  it("throws on 401 (expired token)", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      json: async () => ({ error: "Invalid token" }),
+    });
+
+    await expect(getKey(mockConfig, "openai")).rejects.toThrow("Session expired");
+  });
+
+  it("throws on 404 (service not found)", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 404,
+      json: async () => ({ error: "Not found" }),
+    });
+
+    await expect(getKey(mockConfig, "unknown")).rejects.toThrow("No key found");
+  });
+
+  it("defaults agent identifier to mcp-server", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ service: "stripe", key: "sk-stripe-123" }),
+    });
+
+    await getKey(mockConfig, "stripe");
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          "X-Agent-Identifier": "mcp-server",
+        }),
+      })
+    );
+  });
+});
+
+describe("listServices", () => {
+  it("returns service list", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        services: [
+          { service: "openai", createdAt: "2026-01-01", lastUsed: null },
+          { service: "resend", createdAt: "2026-01-02", lastUsed: "2026-01-03" },
+        ],
+      }),
+    });
+
+    const result = await listServices(mockConfig);
+    expect(result).toHaveLength(2);
+    expect(result[0].service).toBe("openai");
+    expect(result[1].service).toBe("resend");
+  });
+
+  it("throws on 401", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      json: async () => ({}),
+    });
+
+    await expect(listServices(mockConfig)).rejects.toThrow("Session expired");
+  });
+});

package/src/api.ts

@@ -0,0 +1,75 @@
+import { LockerConfig } from "./config";
+
+export interface KeyResponse {
+  service: string;
+  key: string;
+}
+
+export interface ServiceListItem {
+  service: string;
+  createdAt: string;
+  lastUsed: string | null;
+}
+
+/**
+ * Retrieves a decrypted API key from the Locker API.
+ * Sends the agent identifier for audit logging.
+ */
+export async function getKey(
+  config: LockerConfig,
+  service: string,
+  agentIdentifier: string = "mcp-server"
+): Promise<KeyResponse> {
+  const url = `${config.apiUrl}/keys/${encodeURIComponent(service)}`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      "Content-Type": "application/json",
+      "X-Agent-Identifier": agentIdentifier,
+    },
+  });
+
+  if (res.status === 401) {
+    throw new Error("Session expired. Run `locker login` to re-authenticate.");
+  }
+
+  if (res.status === 404) {
+    throw new Error(`No key found for service: ${service}. Store one with: locker set ${service} <key>`);
+  }
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({} as Record<string, string>)) as Record<string, string>;
+    throw new Error(body.error || `API error: ${res.status}`);
+  }
+
+  return (await res.json()) as KeyResponse;
+}
+
+/**
+ * Lists all stored service names (not key values).
+ */
+export async function listServices(
+  config: LockerConfig
+): Promise<ServiceListItem[]> {
+  const url = `${config.apiUrl}/keys`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      "Content-Type": "application/json",
+    },
+  });
+
+  if (res.status === 401) {
+    throw new Error("Session expired. Run `locker login` to re-authenticate.");
+  }
+
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({} as Record<string, string>)) as Record<string, string>;
+    throw new Error(body.error || `API error: ${res.status}`);
+  }
+
+  const data = (await res.json()) as { services: ServiceListItem[] };
+  return data.services;
+}

package/src/config.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+
+describe("config", () => {
+  it("LockerConfig interface has required fields", () => {
+    // Type-level test — if this compiles, the interface is correct
+    const config = {
+      token: "jwt-123",
+      email: "test@example.com",
+      apiUrl: "http://localhost:3001",
+    };
+    expect(config.token).toBe("jwt-123");
+    expect(config.email).toBe("test@example.com");
+    expect(config.apiUrl).toBe("http://localhost:3001");
+  });
+});

package/src/config.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const CONFIG_FILE = path.join(os.homedir(), ".locker", "config");
+
+export interface LockerConfig {
+  token: string;
+  email: string;
+  apiUrl: string;
+}
+
+/**
+ * Reads the Locker CLI config from ~/.locker/config.
+ * This is the same file the CLI writes after `locker login`.
+ * Returns null if not found or invalid.
+ */
+export function readConfig(): LockerConfig | null {
+  try {
+    if (!fs.existsSync(CONFIG_FILE)) return null;
+    const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.token || !parsed.email || !parsed.apiUrl) return null;
+    return parsed as LockerConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns config or throws with a helpful message.
+ */
+export function requireConfig(): LockerConfig {
+  const config = readConfig();
+  if (!config) {
+    throw new Error(
+      "Not logged in to Locker. Run `locker login` first to authenticate."
+    );
+  }
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { requireConfig } from "./config";
+import { getKey, listServices } from "./api";
+
+const server = new McpServer({
+  name: "locker",
+  version: "0.1.0",
+});
+
+// ── Tool: locker_get ──
+// Retrieves a decrypted API key for a given service.
+server.tool(
+  "locker_get",
+  "Retrieve an API key from Locker. Returns the decrypted key for the specified service. The retrieval is logged in the audit trail.",
+  {
+    service: z.string().describe("The service name (e.g. 'openai', 'resend', 'stripe')"),
+    agent: z.string().optional().describe("Agent identifier for the audit log (defaults to 'mcp-server')"),
+  },
+  async ({ service, agent }) => {
+    try {
+      const config = requireConfig();
+      const result = await getKey(config, service, agent || "mcp-server");
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: result.key,
+          },
+        ],
+      };
+    } catch (err: any) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ── Tool: locker_list ──
+// Lists all stored service names (never exposes key values).
+server.tool(
+  "locker_list",
+  "List all services that have API keys stored in Locker. Returns service names only — never the actual key values.",
+  {},
+  async () => {
+    try {
+      const config = requireConfig();
+      const services = await listServices(config);
+
+      if (services.length === 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "No keys stored in Locker. Store one with: locker set <service> <key>",
+            },
+          ],
+        };
+      }
+
+      const lines = services.map((s) => {
+        const lastUsed = s.lastUsed
+          ? `last used ${new Date(s.lastUsed).toLocaleDateString()}`
+          : "never used";
+        return `  ${s.service} (${lastUsed})`;
+      });
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `${services.length} key${services.length === 1 ? "" : "s"} stored:\n${lines.join("\n")}`,
+          },
+        ],
+      };
+    } catch (err: any) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ── Start server ──
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP server failed to start:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+  },
+});