error-mom 0.6.0 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ken Kai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,104 @@
 # error-mom
 
-Agent-first CLI and MCP tools for a self-hosted Error Mom incident desk.
+Agent-first CLI and MCP tools for a self-hosted [Error Mom](https://github.com/KenKaiii/error-mom) deployment.
+
+## Install and authenticate
 
 ```bash
 npm install --global error-mom
 error-mom login https://errors.example.com --token "$ERROR_MOM_ADMIN_TOKEN"
+```
+
+Login stores the server URL and private admin token in `~/.error-mom/config.json` with private file permissions. You can instead set `ERROR_MOM_SERVER` and `ERROR_MOM_ADMIN_TOKEN`.
+
+## Connect an app
+
+Run this from the app you want to monitor:
+
+```bash
+error-mom init
+```
+
+`init` creates or reuses a project, installs `@kenkaiiii/error-mom`, generates a setup file, detects the framework, and returns exact wiring instructions. For a pnpm or Yarn workspace, use `error-mom init --skip-install` and install the SDK with the workspace package manager.
+
+The generated project key is write-only and safe to commit or ship. It can submit events but cannot read issues, manage projects, or upload source maps. Keep the admin token private.
+
+Verify health and ingestion with the exact `error-mom doctor --project-key ...` command printed by `init`. Synthetic doctor events are validated but never stored as issues.
+
+## Work with projects and issues
+
+```bash
 error-mom projects
 error-mom issues
+error-mom issues --project <project-id>
 error-mom inspect <issue-id>
+error-mom inspect <issue-id> --samples 5
 error-mom resolve <issue-id> --release 1.4.2
 ```
 
-Run `error-mom mcp` as a stdio MCP server. It exposes `list_projects`, `list_issues`, `get_issue`, and `resolve_issue`.
+Resolved issues stay hidden by default. If the same issue returns in the fixed release or a newer release, Error Mom marks it as regressed.
+
+Permanently deleting a project also deletes its issues, samples, ingest keys, and receipts:
+
+```bash
+error-mom delete-project <project-id>
+```
+
+## Source maps
+
+Upload source maps immediately after a production build. The release must exactly match the release reported by the SDK.
+
+```bash
+error-mom sourcemaps <build-directory> \
+  --release <app-version> \
+  --project <project-slug>
+```
+
+The command discovers JavaScript/source-map pairs and warns about missing `sourcesContent` or release mismatches. Uploads require the admin token; project ingest keys are rejected.
+
+Test symbolication without storing an event or map:
+
+```bash
+error-mom doctor --symbolication
+```
+
+## MCP server
+
+Run `error-mom mcp` as a stdio MCP server. It exposes:
+
+- `list_projects`
+- `list_issues`
+- `get_issue`
+- `resolve_issue`
+- `check_symbolication`
+- `delete_project`
+
+Example client configuration:
+
+```json
+{
+  "mcpServers": {
+    "error-mom": {
+      "command": "error-mom",
+      "args": ["mcp"],
+      "env": {
+        "ERROR_MOM_SERVER": "https://errors.example.com",
+        "ERROR_MOM_ADMIN_TOKEN": "set-this-in-your-secret-store"
+      }
+    }
+  }
+}
+```
+
+Prefer your MCP client's secure environment or secret configuration instead of committing the admin token.
+
+## Command help
+
+```bash
+error-mom --help
+error-mom <command> --help
+```
+
+Operational commands write machine-readable JSON to stdout, making the CLI suitable for coding agents and automation.
+
+See the [repository README](https://github.com/KenKaiii/error-mom#readme) for deployment, SDK, framework, dashboard, and security instructions.

package/dist/cli.js

@@ -2,17 +2,73 @@
 
 // src/cli.ts
 import { execFileSync } from "child_process";
-import { chmod, mkdir, readFile, readdir, stat, writeFile } from "fs/promises";
+import { chmod, mkdir, readFile as readFile2, stat, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir } from "os";
-import { basename, join } from "path";
+import { basename as basename2, join as join2 } from "path";
 import { Command } from "commander";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-var VERSION = "0.6.0";
-var CONFIG_DIR = join(homedir(), ".error-mom");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+// src/sourcemap-files.ts
+import { readFile, readdir } from "fs/promises";
+import { basename, dirname, join } from "path";
+async function associateMaps(dir) {
+  const { jsFiles, mapFiles } = await findBuildFiles(dir);
+  const associations = /* @__PURE__ */ new Map();
+  const referencedMaps = /* @__PURE__ */ new Set();
+  for (const jsFile of jsFiles) {
+    const contents = await readFile(jsFile, "utf8");
+    const matches = [...contents.matchAll(/\/\/[#@] sourceMappingURL=([^\s'"]+)/g)];
+    const reference = matches[matches.length - 1]?.[1];
+    if (!reference || reference.startsWith("data:")) continue;
+    const mapFile = join(dirname(jsFile), decodeURIComponent(reference));
+    if (!mapFiles.includes(mapFile)) continue;
+    const fileName = basename(jsFile);
+    referencedMaps.add(mapFile);
+    associations.set(`${mapFile}\0${fileName}`, { mapFile, fileName });
+  }
+  for (const mapFile of mapFiles) {
+    if (referencedMaps.has(mapFile)) continue;
+    associations.set(`${mapFile}\0`, {
+      mapFile,
+      fileName: basename(mapFile).replace(/\.map$/, "")
+    });
+  }
+  return [...associations.values()].sort((a, b) => a.fileName.localeCompare(b.fileName));
+}
+async function findBuildFiles(dir) {
+  const jsFiles = [];
+  const mapFiles = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    throw new Error(`Cannot read directory ${dir}.`);
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== "node_modules") {
+      const nested = await findBuildFiles(fullPath);
+      jsFiles.push(...nested.jsFiles);
+      mapFiles.push(...nested.mapFiles);
+    } else if (entry.isFile() && entry.name.endsWith(".map")) {
+      mapFiles.push(fullPath);
+    } else if (entry.isFile() && /\.(js|mjs|cjs)$/.test(entry.name)) {
+      jsFiles.push(fullPath);
+    }
+  }
+  return { jsFiles: jsFiles.sort(), mapFiles: mapFiles.sort() };
+}
+
+// src/cli.ts
+var VERSION = "0.7.1";
+var CONFIG_DIR = join2(homedir(), ".error-mom");
+var CONFIG_FILE = join2(CONFIG_DIR, "config.json");
+function slugifyName(value) {
+  return value.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 64);
+}
 var program = new Command().name("error-mom").description("Query and operate a self-hosted Error Mom incident desk").version(VERSION);
 program.command("login").description("Save the URL and private admin token for one Error Mom deployment").argument("<server>", "Error Mom server URL").requiredOption("--token <token>", "ERROR_MOM_ADMIN_TOKEN value").action(async (server, options) => {
   const normalized = normalizeServer(server);
@@ -120,14 +176,14 @@ program.command("doctor").description("Verify collector health, credentials, and
 program.command("init").description("Create/select a project, install the SDK, and generate framework-aware setup").option("--name <name>", "Project name").option("--project <slug>", "Use an existing project slug").option("--skip-install", "Generate setup without invoking the package manager").action(async (options) => {
   const config = await loadConfig();
   const packageJson = await readPackageJson(process.cwd());
-  const name = options.name ?? (typeof packageJson.name === "string" ? packageJson.name : basename(process.cwd()));
+  const name = options.name ?? (typeof packageJson.name === "string" ? packageJson.name : basename2(process.cwd()));
   const projectResponse = await request(
     config.server,
     config.adminToken,
     "/api/v1/projects"
   );
   let project = options.project ? projectResponse.projects.find((candidate) => candidate.slug === options.project) : projectResponse.projects.find(
-    (candidate) => candidate.name.toLowerCase() === name.toLowerCase()
+    (candidate) => candidate.name.toLowerCase() === name.toLowerCase() || candidate.slug === slugifyName(name)
   );
   if (!project) {
     const created = await request(config.server, config.adminToken, "/api/v1/projects", {
@@ -160,14 +216,14 @@ program.command("init").description("Create/select a project, install the SDK, a
 });
 program.command("sourcemaps").description("Upload production source maps so minified stacks symbolicate on ingest").argument("<dir>", "Build output directory containing *.map files (e.g. dist)").requiredOption("--release <release>", "Release the maps belong to (must match the SDK release)").requiredOption("--project <id-or-slug>", "Project id or slug").action(async (dir, options) => {
   const config = await loadConfig();
-  const mapFiles = await findMapFiles(dir);
-  if (mapFiles.length === 0) {
+  const associations = await associateMaps(dir);
+  if (associations.length === 0) {
     throw new Error(`No .map files found under ${dir}. Build with source maps enabled first.`);
   }
   const uploaded = [];
   const skipped = [];
   const warnings = [];
-  for (const mapFile of mapFiles) {
+  for (const { mapFile, fileName } of associations) {
     const info = await stat(mapFile);
     if (info.size > 20 * 1024 * 1024) {
       skipped.push({ file: mapFile, reason: "larger than 20 MB" });
@@ -175,12 +231,11 @@ program.command("sourcemaps").description("Upload production source maps so mini
     }
     let map;
     try {
-      map = JSON.parse(await readFile(mapFile, "utf8"));
+      map = JSON.parse(await readFile2(mapFile, "utf8"));
     } catch {
       skipped.push({ file: mapFile, reason: "not valid JSON" });
       continue;
     }
-    const fileName = basename(mapFile).replace(/\.map$/, "");
     const sourcesContent = map.sourcesContent;
     if (!Array.isArray(sourcesContent) || sourcesContent.every((entry) => entry == null)) {
       warnings.push(
@@ -318,7 +373,7 @@ async function loadConfig() {
     };
   }
   try {
-    const config = JSON.parse(await readFile(CONFIG_FILE, "utf8"));
+    const config = JSON.parse(await readFile2(CONFIG_FILE, "utf8"));
     if (!config.server || !config.adminToken) throw new Error("Incomplete config");
     return { server: normalizeServer(config.server), adminToken: config.adminToken };
   } catch {
@@ -344,7 +399,7 @@ async function request(server, token, path, options = {}) {
 }
 async function readPackageJson(cwd) {
   try {
-    return JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    return JSON.parse(await readFile2(join2(cwd, "package.json"), "utf8"));
   } catch {
     throw new Error(
       "Run error-mom init from a JavaScript or TypeScript project containing package.json."
@@ -472,8 +527,8 @@ function detectFramework(packageJson) {
   };
 }
 function detectPackageManager(cwd) {
-  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(join2(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join2(cwd, "yarn.lock"))) return "yarn";
   return "npm";
 }
 function installSdk(packageManager) {
@@ -488,8 +543,8 @@ function installSdk(packageManager) {
   });
 }
 async function writeSetup(framework, server, ingestKey) {
-  const sourceDirectory = existsSync(join(process.cwd(), "src")) ? "src" : ".";
-  const relativePath = join(sourceDirectory, "error-mom.ts");
+  const sourceDirectory = existsSync(join2(process.cwd(), "src")) ? "src" : ".";
+  const relativePath = join2(sourceDirectory, "error-mom.ts");
   if (framework.id === "next") await writeNextInstrumentation(sourceDirectory, server, ingestKey);
   const environment = framework.envStyle === "next" ? "process.env.NEXT_PUBLIC_" : framework.envStyle === "vite" ? "import.meta.env.VITE_" : "process.env.";
   const moduleName = framework.envStyle === "node" ? "@kenkaiiii/error-mom/node" : "@kenkaiiii/error-mom";
@@ -508,11 +563,11 @@ export const errorMom = initErrorMom({
   ...(release ? { release } : {}),
 });
 `;
-  await writeFile(join(process.cwd(), relativePath), contents);
+  await writeFile(join2(process.cwd(), relativePath), contents);
   return relativePath;
 }
 async function writeNextInstrumentation(sourceDirectory, configuredServer, ingestKey) {
-  const file = join(process.cwd(), sourceDirectory, "instrumentation.ts");
+  const file = join2(process.cwd(), sourceDirectory, "instrumentation.ts");
   if (existsSync(file)) return;
   const contents = `import type { Instrumentation } from "next";
 
@@ -585,24 +640,6 @@ async function releaseMismatchWarning(config, projectIdOrSlug, release) {
     return [];
   }
 }
-async function findMapFiles(dir) {
-  const found = [];
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    throw new Error(`Cannot read directory ${dir}.`);
-  }
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory() && entry.name !== "node_modules") {
-      found.push(...await findMapFiles(fullPath));
-    } else if (entry.isFile() && entry.name.endsWith(".map")) {
-      found.push(fullPath);
-    }
-  }
-  return found.sort();
-}
 function normalizeServer(server) {
   return server.replace(/\/$/, "");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "error-mom",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Agent-first CLI and MCP tools for self-hosted Error Mom",
   "type": "module",
   "bin": {
@@ -11,11 +11,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup src/cli.ts --format esm --dts --clean",
-    "check": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
@@ -28,5 +23,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean",
+    "check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}