@sansynx/erroratlas 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# ErrorAtlas
+
+ErrorAtlas is hosted debugging memory for coding agents.
+
+Developers do not clone this repo, create Supabase projects, deploy Workers, or manage ErrorAtlas infrastructure. They install the npm MCP client, generate one hosted MCP key, run Supermemory locally, and let their coding agent search and publish verified fixes.
+
+## End-user flow
+
+1. Open the hosted dashboard:
+
+```txt
+https://erroratlas.sansynx.workers.dev/dashboard
+```
+
+2. Sign in and click `Generate secret`.
+
+Copy the MCP secret immediately. Existing raw secrets cannot be recovered later.
+
+3. Install ErrorAtlas in the project where the coding agent works:
+
+```bash
+npm install -D @sansynx/erroratlas
+npx erroratlas init
+```
+
+4. Run Supermemory local:
+
+```bash
+OPENAI_API_KEY=your_model_provider_key
+npx supermemory local --port 6767
+```
+
+Windows/WSL fallback:
+
+```bash
+export OPENAI_API_KEY=your_model_provider_key
+PORT=6767 ~/.supermemory/bin/supermemory-server
+```
+
+5. Add the MCP server to the agent client:
+
+```json
+{
+  "mcpServers": {
+    "erroratlas": {
+      "command": "npx",
+      "args": ["-y", "--package", "@sansynx/erroratlas", "erroratlas", "mcp"],
+      "env": {
+        "ERRORATLAS_API_URL": "https://erroratlas.sansynx.workers.dev",
+        "ERRORATLAS_API_KEY": "ea_live_from_dashboard",
+        "SUPERMEMORY_URL": "http://localhost:6767"
+      }
+    }
+  }
+}
+```
+
+If Supermemory local prints an API key, also add:
+
+```txt
+SUPERMEMORY_API_KEY=optional_local_supermemory_key
+```
+
+## What the CLI creates
+
+`npx erroratlas init` creates only an `.erroratlas` folder in the developer project:
+
+```txt
+.erroratlas/config.json
+.erroratlas/instructions.md
+.erroratlas/mcp.json.example
+```
+
+It does not edit `AGENTS.md`, `CLAUDE.md`, Cursor rules, Windsurf rules, or existing project instruction files.
+
+## MCP tools
+
+```txt
+erroratlas.search_error
+erroratlas.capture_error_signal
+erroratlas.record_incident
+erroratlas.publish_resolution
+erroratlas.get_playbook
+```
+
+## Storage model
+
+- Supermemory local stores private project memory on the developer machine.
+- ErrorAtlas remote stores sanitized searchable incidents and playbooks.
+- Agent keys are shown once and stored remotely only as hashes.
+- Sensitive incident payload snapshots are encrypted before database insert.
+
+## Operator setup
+
+This section is only for the ErrorAtlas service owner.
+
+```bash
+cp .dev.vars.example .dev.vars
+npm install
+npm run dev
+```
+
+Apply the database schema from:
+
+```txt
+supabase/schema.sql
+```
+
+Set production Worker secrets:
+
+```bash
+npx wrangler secret put PUBLIC_SUPABASE_URL
+npx wrangler secret put PUBLIC_SUPABASE_ANON_KEY
+npx wrangler secret put SUPABASE_SERVICE_ROLE_KEY
+npx wrangler secret put FIELD_ENCRYPTION_KEY
+```
+
+Deploy:
+
+```bash
+npm run deploy
+```
+
+Publish the npm package from an npm account or organization you control:
+
+```bash
+npm login
+npm publish --access public
+```
+
+The package name is `@sansynx/erroratlas` because the unscoped npm name `erroratlas` is already owned by another package. The CLI command remains `erroratlas`.
+
+## Project structure
+
+```txt
+src/worker      Cloudflare Worker UI and API
+src/mcp         local MCP server for coding agents
+src/cli         npm package CLI for init and MCP startup
+src/shared      redaction and playbook utilities
+supabase        service-owner database schema
+templates       files copied by npx erroratlas init
+public          Worker-served public assets
+scripts         maintainer build and smoke-test scripts
+```
+
+## Important routes
+
+```txt
+GET  /                         landing page
+GET  /setup                    public setup guide
+GET  /dashboard                protected MCP key console
+GET  /llms.txt                 machine-readable agent guide
+GET  /api/health               service health
+POST /api/search               search approved fixes
+POST /api/agent-keys           create or rotate MCP key
+POST /api/incidents            capture sanitized error signal
+POST /api/resolutions          publish verified resolution
+```

package/dist/cli/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = process.cwd();
+const command = process.argv[2] || "help";
+if (command === "init") {
+    init();
+}
+else if (command === "mcp") {
+    await import("../mcp/server.js");
+}
+else {
+    printHelp();
+}
+function printHelp() {
+    console.log(`ErrorAtlas
+
+Commands:
+  init    create .erroratlas config and MCP template files
+  mcp     start the ErrorAtlas MCP server over stdio
+`);
+}
+function init() {
+    const files = [
+        [".erroratlas/config.json", template("config.json.example")],
+        [".erroratlas/instructions.md", template("instructions.md")],
+        [".erroratlas/mcp.json.example", template("mcp.json.example")]
+    ];
+    for (const [target, body] of files) {
+        writeIfMissing(join(root, target), body);
+    }
+    console.log(`Created ErrorAtlas project files:
+- .erroratlas/config.json
+- .erroratlas/instructions.md
+- .erroratlas/mcp.json.example
+
+No existing agent instruction file was modified.`);
+}
+function template(name) {
+    const projectTemplate = join(root, "templates", name);
+    const packageTemplate = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates", name);
+    if (existsSync(projectTemplate))
+        return readFileSync(projectTemplate, "utf8");
+    return readFileSync(packageTemplate, "utf8");
+}
+function writeIfMissing(path, body) {
+    if (existsSync(path))
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body);
+}

package/dist/mcp/server.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { buildPlaybookMarkdown, errorSignature, redactText, titleFromError } from "../shared/redaction.js";
+function localConfig() {
+    const path = join(process.cwd(), ".erroratlas", "config.json");
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+const config = localConfig();
+const apiUrl = (process.env.ERRORATLAS_API_URL || config.apiUrl || "http://localhost:8787").replace(/\/$/, "");
+const agentKey = process.env.ERRORATLAS_API_KEY || "";
+const supermemoryUrl = (process.env.SUPERMEMORY_URL || config.supermemoryUrl || "http://localhost:6767").replace(/\/$/, "");
+const supermemoryKey = process.env.SUPERMEMORY_API_KEY || "";
+const server = new McpServer({
+    name: "erroratlas",
+    version: "0.1.0"
+});
+server.tool("search_error", {
+    error: z.string(),
+    stack: z.string().optional(),
+    command: z.string().optional(),
+    exitCode: z.number().optional(),
+    language: z.string().optional(),
+    framework: z.string().optional(),
+    packageManager: z.string().optional(),
+    dependencyVersions: z.record(z.string()).optional(),
+    limit: z.number().optional()
+}, async (input) => {
+    const local = await searchSupermemory(input);
+    const remote = await callApi("/api/search", input);
+    return respond({ local, remote });
+});
+server.tool("capture_error_signal", {
+    error: z.string(),
+    context: z.string().optional(),
+    stack: z.string().optional(),
+    attemptedFixes: z.array(z.string()).optional(),
+    command: z.string().optional(),
+    exitCode: z.number().optional(),
+    language: z.string().optional(),
+    framework: z.string().optional(),
+    packageManager: z.string().optional(),
+    dependencyVersions: z.record(z.string()).optional(),
+    signalType: z.enum(["error", "failed_fix", "verification", "note"]).optional(),
+    visibility: z.enum(["private", "team", "public"]).optional()
+}, async (input) => {
+    const memory = await writeSupermemory({
+        kind: "incident",
+        title: titleFromError(input.error),
+        error_signature: errorSignature(input.error),
+        ...input
+    });
+    const remote = await callApi("/api/incidents", input);
+    return respond({ memory, remote });
+});
+server.tool("record_incident", {
+    error: z.string(),
+    context: z.string().optional(),
+    stack: z.string().optional(),
+    attemptedFixes: z.array(z.string()).optional(),
+    command: z.string().optional(),
+    exitCode: z.number().optional(),
+    language: z.string().optional(),
+    framework: z.string().optional(),
+    packageManager: z.string().optional(),
+    dependencyVersions: z.record(z.string()).optional(),
+    signalType: z.enum(["error", "failed_fix", "verification", "note"]).optional(),
+    visibility: z.enum(["private", "team", "public"]).optional()
+}, async (input) => {
+    const memory = await writeSupermemory({
+        kind: "incident",
+        title: titleFromError(input.error),
+        error_signature: errorSignature(input.error),
+        ...input
+    });
+    const remote = await callApi("/api/incidents", input);
+    return respond({ memory, remote });
+});
+server.tool("publish_resolution", {
+    error: z.string(),
+    rootCause: z.string(),
+    finalFix: z.string(),
+    failedAttempts: z.array(z.string()).optional(),
+    verification: z.string().optional(),
+    language: z.string().optional(),
+    framework: z.string().optional(),
+    packageManager: z.string().optional(),
+    visibility: z.enum(["private", "team", "public"]).optional(),
+    risk: z.enum(["low", "medium", "high"]).optional(),
+    confidence: z.enum(["low", "medium", "high"]).optional()
+}, async (input) => {
+    const title = titleFromError(input.error);
+    const playbookInput = {
+        title,
+        error: input.error,
+        rootCause: input.rootCause,
+        finalFix: input.finalFix
+    };
+    if (input.failedAttempts)
+        playbookInput.failedAttempts = input.failedAttempts;
+    if (input.verification)
+        playbookInput.verification = input.verification;
+    if (input.framework)
+        playbookInput.framework = input.framework;
+    if (input.language)
+        playbookInput.language = input.language;
+    if (input.risk)
+        playbookInput.risk = input.risk;
+    if (input.confidence)
+        playbookInput.confidence = input.confidence;
+    const playbook = buildPlaybookMarkdown(playbookInput);
+    const memory = await writeSupermemory({
+        kind: "resolution",
+        title,
+        error_signature: errorSignature(input.error),
+        playbook,
+        ...input
+    });
+    const remote = await callApi("/api/resolutions", {
+        ...input,
+        visibility: input.visibility || config.defaultVisibility || "team"
+    });
+    return respond({ memory, remote, playbook });
+});
+server.tool("get_playbook", {
+    id: z.string()
+}, async (input) => {
+    const response = await fetch(`${apiUrl}/api/playbooks/${encodeURIComponent(input.id)}`, {
+        headers: authHeaders()
+    });
+    return respond(await response.json());
+});
+async function callApi(path, body) {
+    if (!agentKey) {
+        return { skipped: true, reason: "ERRORATLAS_API_KEY is not set" };
+    }
+    const response = await fetch(`${apiUrl}${path}`, {
+        method: "POST",
+        headers: {
+            ...authHeaders(),
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(sanitizeForRemote(body))
+    });
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { status: response.status, body: text };
+    }
+}
+function authHeaders() {
+    return agentKey ? { "X-ErrorAtlas-Key": agentKey } : {};
+}
+async function searchSupermemory(input) {
+    try {
+        const query = redactText(input);
+        const response = await fetch(`${supermemoryUrl}/v3/search`, {
+            method: "POST",
+            headers: supermemoryHeaders(),
+            body: JSON.stringify({ q: query, limit: 5 })
+        });
+        if (!response.ok)
+            return { skipped: true, status: response.status };
+        return response.json();
+    }
+    catch (error) {
+        return { skipped: true, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function writeSupermemory(payload) {
+    try {
+        const response = await fetch(`${supermemoryUrl}/v3/documents`, {
+            method: "POST",
+            headers: supermemoryHeaders(),
+            body: JSON.stringify({
+                content: localMemoryContent(payload),
+                metadata: { source: "erroratlas" }
+            })
+        });
+        if (!response.ok)
+            return { skipped: true, status: response.status };
+        return response.json();
+    }
+    catch (error) {
+        return { skipped: true, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+function supermemoryHeaders() {
+    return {
+        "Content-Type": "application/json",
+        ...(supermemoryKey ? { Authorization: `Bearer ${supermemoryKey}` } : {})
+    };
+}
+function localMemoryContent(payload) {
+    const content = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+    return content.slice(0, 20000);
+}
+function sanitizeForRemote(value) {
+    if (typeof value === "string")
+        return redactText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeForRemote);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [redactText(key), sanitizeForRemote(entry)]));
+}
+function respond(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2)
+            }
+        ]
+    };
+}
+await server.connect(new StdioServerTransport());

package/dist/shared/redaction.js

@@ -0,0 +1,56 @@
+const TOKEN_PATTERNS = [
+    [/-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g, "[redacted-private-key]"],
+    [/\b(?:sk|pk|ghp|github_pat|xoxb|xoxp|ea_live|ea_test)_[A-Za-z0-9_\-=]{12,}\b/g, "[redacted-token]"],
+    [/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, "[redacted-jwt]"],
+    [/\b[A-Fa-f0-9]{32,}\b/g, "[redacted-hex-secret]"],
+    [/[A-Z]:\\Users\\[^\\\s]+/gi, "C:\\Users\\[user]"],
+    [/\/Users\/[^/\s]+/g, "/Users/[user]"],
+    [/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted-email]"],
+    [/https?:\/\/[^\s"'<>)]*/gi, "[redacted-url]"],
+    [/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "[redacted-ip]"]
+];
+export function redactText(value) {
+    const input = typeof value === "string" ? value : JSON.stringify(value ?? "");
+    return TOKEN_PATTERNS.reduce((text, [pattern, replacement]) => text.replace(pattern, replacement), input).slice(0, 12000);
+}
+export function errorSignature(error) {
+    return redactText(error)
+        .replace(/\b0x[a-f0-9]+\b/gi, "0xADDR")
+        .replace(/\b\d{4,}\b/g, "N")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 240);
+}
+export function titleFromError(error) {
+    const firstLine = redactText(error).split(/\r?\n/).find(Boolean) ?? "Untitled incident";
+    return firstLine.replace(/\s+/g, " ").trim().slice(0, 96);
+}
+export function buildPlaybookMarkdown(input) {
+    const failed = input.failedAttempts?.length
+        ? input.failedAttempts.map((attempt) => `- ${redactText(attempt)}`).join("\n")
+        : "- None recorded";
+    return [
+        `# ${redactText(input.title)}`,
+        "",
+        "## Error",
+        redactText(input.error),
+        "",
+        "## Root Cause",
+        redactText(input.rootCause),
+        "",
+        "## Fix",
+        redactText(input.finalFix),
+        "",
+        "## Failed Attempts",
+        failed,
+        "",
+        "## Verification",
+        redactText(input.verification || "Not recorded"),
+        "",
+        "## Context",
+        `Language: ${redactText(input.language || "unknown")}`,
+        `Framework: ${redactText(input.framework || "unknown")}`,
+        `Risk: ${redactText(input.risk || "medium")}`,
+        `Confidence: ${redactText(input.confidence || "medium")}`
+    ].join("\n");
+}

package/dist/worker/assets.js

@@ -0,0 +1 @@
+export const faviconSvg = "<svg width=\"64\" height=\"64\" viewBox=\"0 0 64 64\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n  <rect width=\"64\" height=\"64\" rx=\"16\" fill=\"#0F0F0E\"/>\n  <path d=\"M18 42V20H47\" stroke=\"#F4EEE7\" stroke-width=\"5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n  <path d=\"M18 42H46\" stroke=\"#FF5A1F\" stroke-width=\"5\" stroke-linecap=\"round\"/>\n  <path d=\"M28 31H43\" stroke=\"#F4EEE7\" stroke-width=\"5\" stroke-linecap=\"round\"/>\n</svg>";

package/dist/worker/crypto.js

@@ -0,0 +1,36 @@
+import { HttpError } from "./http";
+import { redactText } from "../shared/redaction";
+function decodeKey(value) {
+    const trimmed = value.trim();
+    if (/^[a-f0-9]{64}$/i.test(trimmed)) {
+        return new Uint8Array(trimmed.match(/.{2}/g)?.map((part) => Number.parseInt(part, 16)) || []);
+    }
+    const normalized = trimmed.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    const binary = atob(padded);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+async function importEncryptionKey(env) {
+    if (!env.FIELD_ENCRYPTION_KEY) {
+        throw new HttpError(503, "encryption_not_configured", "FIELD_ENCRYPTION_KEY is required before storing incident or resolution payloads.");
+    }
+    const raw = decodeKey(env.FIELD_ENCRYPTION_KEY);
+    if (raw.byteLength !== 32) {
+        throw new HttpError(503, "invalid_encryption_key", "FIELD_ENCRYPTION_KEY must decode to 32 bytes.");
+    }
+    const keyData = raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength);
+    return crypto.subtle.importKey("raw", keyData, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+function base64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+export async function encryptSensitivePayload(env, value) {
+    const key = await importEncryptionKey(env);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const plaintext = new TextEncoder().encode(redactText(value));
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, plaintext));
+    return `v1:${base64(iv)}:${base64(ciphertext)}`;
+}

package/dist/worker/http.js

@@ -0,0 +1,84 @@
+export class HttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const corsHeaders = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type,Authorization,X-ErrorAtlas-Key"
+};
+export function json(data, status = 200, headers = {}) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "no-store",
+            ...corsHeaders,
+            ...headers
+        }
+    });
+}
+export function html(data, status = 200) {
+    return new Response(data, {
+        status,
+        headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store"
+        }
+    });
+}
+export function text(data, status = 200, contentType = "text/plain; charset=utf-8") {
+    return new Response(data, {
+        status,
+        headers: {
+            "Content-Type": contentType,
+            "Cache-Control": "public, max-age=300",
+            ...corsHeaders
+        }
+    });
+}
+export function options() {
+    return new Response(null, { status: 204, headers: corsHeaders });
+}
+export async function readJson(request) {
+    try {
+        return (await request.json());
+    }
+    catch {
+        throw new HttpError(400, "invalid_json", "Request body must be valid JSON.");
+    }
+}
+export function bearerToken(request) {
+    const value = request.headers.get("Authorization");
+    if (!value?.startsWith("Bearer "))
+        return null;
+    return value.slice("Bearer ".length).trim();
+}
+export async function sha256Hex(value) {
+    const bytes = new TextEncoder().encode(value);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function randomToken(prefix = "ea_live") {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const body = btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+    return `${prefix}_${body}`;
+}
+export function clampLimit(value, fallback = 8) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(1, Math.min(20, Math.trunc(parsed)));
+}
+export function handleError(error) {
+    if (error instanceof HttpError) {
+        return json({ error: error.code, message: error.message }, error.status);
+    }
+    return json({ error: "internal_error", message: "Unexpected server error." }, 500);
+}