@monocle.sh/cli 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-present, Julien Ripouteau
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @monocle.sh/cli
+
+CLI for Monocle - upload source maps to enable readable stack traces in your error monitoring.
+
+## Installation
+
+```bash
+npm install -g @monocle.sh/cli
+# or use npx
+npx @monocle.sh/cli sourcemaps upload ...
+```
+
+## Usage
+
+### Upload Source Maps
+
+Upload source maps after your build process:
+
+```bash
+monocle-cli sourcemaps upload \
+  --api-key=mk_live_xxx \
+  --release=v1.2.3 \
+  ./dist/**/*.map
+```
+
+With environment variable:
+
+```bash
+MONOCLE_API_KEY=mk_live_xxx monocle-cli sourcemaps upload \
+  --release=$(git rev-parse HEAD) \
+  ./dist/**/*.map
+```
+
+### Options
+
+| Option                | Description                                        | Default                  |
+| --------------------- | -------------------------------------------------- | ------------------------ |
+| `--api-key <key>`     | Monocle API key (or set `MONOCLE_API_KEY` env var) | -                        |
+| `--release <version>` | Release version (e.g., `v1.2.3` or git SHA)        | -                        |
+| `--url <url>`         | Monocle API URL                                    | `https://api.monocle.sh` |
+| `--dry-run`           | Show what would be uploaded without uploading      | `false`                  |
+
+### Release Identifier
+
+The release identifier links exceptions to their source maps. It must match the `serviceVersion` configured in your Monocle agent:
+
+```typescript
+// config/monocle.ts
+export default defineConfig({
+  serviceVersion: env.get('APP_VERSION'), // e.g., "v1.2.3" or git SHA
+})
+```
+
+Best practices:
+
+- Use git commit SHA for precise matching: `$(git rev-parse HEAD)`
+- Use semver for human-readable releases: `v1.2.3`
+- Must match exactly between upload and runtime config
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload Source Maps
+        run: |
+          npx @monocle.sh/cli sourcemaps upload \
+            --api-key=${{ secrets.MONOCLE_API_KEY }} \
+            --release=${{ github.sha }} \
+            ./dist/**/*.map
+
+      - name: Deploy
+        run: # your deploy command
+```
+
+### GitLab CI
+
+```yaml
+deploy:
+  stage: deploy
+  script:
+    - npm ci
+    - npm run build
+    - npx @monocle.sh/cli sourcemaps upload
+      --api-key=$MONOCLE_API_KEY
+      --release=$CI_COMMIT_SHA
+      ./dist/**/*.map
+    -  # your deploy command
+```
+
+### CircleCI
+
+```yaml
+version: 2.1
+
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm ci
+      - run: npm run build
+      - run:
+          name: Upload Source Maps
+          command: |
+            npx @monocle.sh/cli sourcemaps upload \
+              --api-key=$MONOCLE_API_KEY \
+              --release=$CIRCLE_SHA1 \
+              ./dist/**/*.map
+      - run: # your deploy command
+```
+
+## AdonisJS Configuration
+
+For AdonisJS projects using `tsc` and Node.js (no bundler):
+
+### 1. Enable source maps in tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "sourceMap": true,
+    "inlineSources": true,
+    "sourceRoot": "/"
+  }
+}
+```
+
+### 2. Configure Monocle agent with release version
+
+```typescript
+// config/monocle.ts
+import env from '#start/env'
+
+export default defineConfig({
+  serviceVersion: env.get('APP_VERSION'),
+})
+```
+
+### 3. Set APP_VERSION in your deployment
+
+```bash
+# In your CI/CD or .env
+APP_VERSION=$(git rev-parse HEAD)
+```
+
+### 4. Upload source maps after build
+
+```yaml
+# GitHub Actions example
+- name: Build
+  run: node ace build
+
+- name: Upload Source Maps
+  run: |
+    npx @monocle.sh/cli sourcemaps upload \
+      --api-key=${{ secrets.MONOCLE_API_KEY }} \
+      --release=${{ github.sha }} \
+      ./build/**/*.map
+
+- name: Deploy
+  run: # rsync, docker push, etc.
+```
+
+The `--release` value must match `APP_VERSION` used at runtime.
+
+### 5. (Optional) Delete source maps before deploy
+
+Source maps can expose your source code. Delete them after upload:
+
+```yaml
+- name: Upload Source Maps
+  run: npx @monocle.sh/cli sourcemaps upload ...
+
+- name: Remove source maps from build
+  run: find ./build -name "*.map" -delete
+
+- name: Deploy
+  run: # deploy without .map files
+```
+
+## Troubleshooting
+
+### No source map files found
+
+- Check that your build generates `.map` files
+- Verify your glob patterns match the output location
+- Try using `--dry-run` to see what would be matched
+
+### Authentication failed
+
+- Verify your API key is correct
+- Ensure the API key has write permissions for source maps
+- Check that `MONOCLE_API_KEY` environment variable is set correctly
+
+### Stack traces not resolving
+
+- Ensure the `--release` value matches `serviceVersion` in your Monocle agent config
+- Verify source maps were uploaded successfully
+- Check that the source map filenames match the ones referenced in your minified code

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { i as uploadSourcemaps, t as UploadError } from "./upload-DJfE9Qcx.mjs";
+import { join } from "node:path";
+import { readFileSync, readdirSync, rmSync } from "node:fs";
+import pc from "picocolors";
+import { program } from "commander";
+import { homedir } from "node:os";
+import { exec } from "node:child_process";
+//#region src/cli.ts
+const pkg = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf-8"));
+console.log();
+console.log(pc.magenta(pc.bold("  monocle.sh")), pc.dim(`v${pkg.version}`));
+console.log();
+program.name("monocle").description("Monocle CLI - upload source maps and manage your Monocle projects").version(pkg.version);
+program.command("sourcemaps").description("Manage source maps").command("upload").description("Upload source maps to Monocle").argument("<patterns...>", "Glob patterns for source map files (e.g., ./dist/**/*.map)").option("--api-key <key>", "Monocle API key (or set MONOCLE_API_KEY env var)").option("--release <version>", "Release version (e.g., v1.2.3 or git SHA)").option("--url <url>", "Monocle API URL", "https://api.monocle.sh").option("--dry-run", "Show what would be uploaded without uploading").action(async (patterns, options) => {
+	const apiKey = options.apiKey || process.env.MONOCLE_API_KEY;
+	if (!apiKey) {
+		console.error(pc.red("Error: Missing API key"));
+		console.error("Provide --api-key option or set MONOCLE_API_KEY environment variable");
+		process.exit(1);
+	}
+	if (!options.release) {
+		console.error(pc.red("Error: Missing --release option"));
+		console.error("Provide a release version (e.g., --release=v1.2.3 or --release=$(git rev-parse HEAD))");
+		process.exit(1);
+	}
+	try {
+		await uploadSourcemaps({
+			patterns,
+			apiKey,
+			release: options.release,
+			apiUrl: options.url,
+			dryRun: options.dryRun
+		});
+	} catch (error) {
+		if (error instanceof UploadError) console.error(pc.red(`Error: ${error.message}`));
+		else console.error(pc.red("Error: An unexpected error occurred"));
+		process.exit(1);
+	}
+});
+program.command("dev").description("Start local DevTools server for development observability").option("--port <port>", "Port for the DevTools server", "4200").option("--host <host>", "Host to bind to", "0.0.0.0").option("--open", "Open browser automatically").option("--clean", "Reset all stored data before starting").option("--db-path <path>", "Custom path for DuckDB database").action(async (options) => {
+	const port = Number.parseInt(options.port, 10);
+	if (options.clean) {
+		const configDir = join(homedir(), ".config", "monocle");
+		try {
+			for (const file of readdirSync(configDir)) if (file.endsWith(".db") || file.endsWith(".db-wal") || file.endsWith(".db-shm")) rmSync(join(configDir, file));
+			console.log(pc.green("Data cleared."));
+		} catch {}
+	}
+	let devtools;
+	try {
+		devtools = await import("@monocle.sh/studio");
+	} catch {
+		console.error(pc.red("Error: @monocle.sh/studio is not installed"));
+		console.error("Install it with: pnpm add -D @monocle.sh/studio");
+		process.exit(1);
+	}
+	try {
+		await devtools.startServer({
+			port,
+			host: options.host,
+			dbPath: options.dbPath
+		});
+		if (options.open) exec(`open http://localhost:${port}`);
+	} catch (error) {
+		console.error(pc.red("Failed to start DevTools server"));
+		if (error instanceof Error) console.error(error.message);
+		process.exit(1);
+	}
+});
+program.parse();
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+//#region src/upload.d.ts
+interface UploadSourcemapsOptions {
+  patterns: string[];
+  apiKey: string;
+  release: string;
+  apiUrl: string;
+  dryRun?: boolean;
+}
+interface UploadResult {
+  uploaded: Array<{
+    filename: string;
+    release: string;
+    sizeBytes: number;
+  }>;
+  count: number;
+}
+interface SourcemapFile {
+  path: string;
+  filename: string;
+  content: Buffer;
+  size: number;
+}
+/**
+ * Upload source maps to Monocle API.
+ */
+declare function uploadSourcemaps(options: UploadSourcemapsOptions): Promise<UploadResult>;
+/**
+ * Find source map files matching the given glob patterns.
+ */
+declare function findSourcemapFiles(patterns: string[]): Promise<string[]>;
+/**
+ * Load and validate a source map file. Returns the file with its content.
+ */
+declare function loadAndValidateSourcemap(filePath: string): SourcemapFile;
+/**
+ * Validate that a file is a valid source map. (Legacy function for tests)
+ */
+declare function validateSourcemap(filePath: string): {
+  valid: boolean;
+  error?: string;
+};
+/**
+ * Custom error class for upload errors. Does not expose sensitive data.
+ */
+declare class UploadError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { type SourcemapFile, UploadError, type UploadResult, type UploadSourcemapsOptions, findSourcemapFiles, loadAndValidateSourcemap, uploadSourcemaps, validateSourcemap };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as validateSourcemap, i as uploadSourcemaps, n as findSourcemapFiles, r as loadAndValidateSourcemap, t as UploadError } from "./upload-DJfE9Qcx.mjs";
+export { UploadError, findSourcemapFiles, loadAndValidateSourcemap, uploadSourcemaps, validateSourcemap };

package/dist/upload-DJfE9Qcx.mjs

@@ -0,0 +1,167 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import pc from "picocolors";
+import ora from "ora";
+import ky, { HTTPError, TimeoutError } from "ky";
+import fg from "fast-glob";
+//#region src/upload.ts
+const MAX_FILE_SIZE = 50 * 1024 * 1024;
+const UPLOAD_TIMEOUT = 12e4;
+/**
+* Upload source maps to Monocle API.
+*/
+async function uploadSourcemaps(options) {
+	const { patterns, apiKey, release, apiUrl, dryRun } = options;
+	const spinner = ora("Finding source map files...").start();
+	const filePaths = await findSourcemapFiles(patterns);
+	if (filePaths.length === 0) {
+		spinner.fail("No source map files found");
+		console.error(pc.yellow(`Searched patterns: ${patterns.join(", ")}`));
+		console.error(pc.dim("Make sure the glob patterns match .map files in your build output"));
+		throw new UploadError("No source map files found");
+	}
+	spinner.text = `Validating ${filePaths.length} source map file(s)...`;
+	const files = [];
+	for (const filePath of filePaths) {
+		const file = loadAndValidateSourcemap(filePath);
+		files.push(file);
+	}
+	spinner.succeed(`Found ${files.length} valid source map file(s)`);
+	for (const file of files) {
+		const sizeKb = (file.size / 1024).toFixed(1);
+		console.log(pc.dim(`  ${file.path} (${sizeKb} KB)`));
+	}
+	if (dryRun) {
+		console.log(pc.yellow("\nDry run mode - no files uploaded"));
+		return {
+			uploaded: [],
+			count: 0
+		};
+	}
+	spinner.start(`Uploading to ${sanitizeUrl(apiUrl)}...`);
+	const result = await uploadFiles({
+		files,
+		apiKey,
+		release,
+		apiUrl,
+		onProgress: (current, total) => {
+			spinner.text = `Uploading file ${current}/${total} to ${sanitizeUrl(apiUrl)}...`;
+		}
+	});
+	spinner.succeed(`Uploaded ${result.count} source map(s) for release ${pc.cyan(release)}`);
+	return result;
+}
+/**
+* Find source map files matching the given glob patterns.
+*/
+async function findSourcemapFiles(patterns) {
+	return (await fg(patterns, {
+		onlyFiles: true,
+		absolute: true,
+		ignore: ["**/node_modules/**"]
+	})).filter((file) => file.endsWith(".map"));
+}
+/**
+* Load and validate a source map file. Returns the file with its content.
+*/
+function loadAndValidateSourcemap(filePath) {
+	const stats = fs.statSync(filePath);
+	if (stats.size > MAX_FILE_SIZE) throw new UploadError(`File ${filePath} exceeds 50MB limit (${(stats.size / 1024 / 1024).toFixed(1)}MB)`);
+	const content = fs.readFileSync(filePath);
+	const filename = path.basename(filePath);
+	try {
+		const parsed = JSON.parse(content.toString("utf-8"));
+		if (typeof parsed.version !== "number") throw new UploadError(`Invalid source map ${filePath}: missing version field`);
+		if (!Array.isArray(parsed.sources)) throw new UploadError(`Invalid source map ${filePath}: missing sources array`);
+		if (typeof parsed.mappings !== "string") throw new UploadError(`Invalid source map ${filePath}: missing mappings field`);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new UploadError(`Invalid source map ${filePath}: invalid JSON`);
+		throw error;
+	}
+	return {
+		path: filePath,
+		filename,
+		content,
+		size: stats.size
+	};
+}
+/**
+* Validate that a file is a valid source map. (Legacy function for tests)
+*/
+function validateSourcemap(filePath) {
+	try {
+		loadAndValidateSourcemap(filePath);
+		return { valid: true };
+	} catch (error) {
+		return {
+			valid: false,
+			error: error instanceof Error ? error.message : "Unknown error"
+		};
+	}
+}
+/**
+* Upload files to the Monocle API.
+*/
+async function uploadFiles(options) {
+	const { files, apiKey, release, apiUrl, onProgress } = options;
+	const formData = new FormData();
+	formData.append("release", release);
+	let current = 0;
+	for (const file of files) {
+		current++;
+		onProgress?.(current, files.length);
+		const blob = new Blob([new Uint8Array(file.content)], { type: "application/json" });
+		formData.append("files", blob, file.filename);
+	}
+	try {
+		return (await (await ky.post(`${apiUrl}/sourcemaps`, {
+			headers: { "x-api-key": apiKey },
+			body: formData,
+			timeout: UPLOAD_TIMEOUT
+		})).json()).data;
+	} catch (error) {
+		throw handleUploadError(error);
+	}
+}
+/**
+* Custom error class for upload errors. Does not expose sensitive data.
+*/
+var UploadError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UploadError";
+	}
+};
+/**
+* Handle upload errors and return a sanitized error.
+*/
+function handleUploadError(error) {
+	if (error instanceof TimeoutError) return new UploadError("Upload timed out. Check your network connection and try again.");
+	if (error instanceof HTTPError) {
+		const status = error.response.status;
+		if (status === 401) return new UploadError("Authentication failed. Check your API key.");
+		if (status === 413) return new UploadError("Upload too large. Maximum total size is 50MB per file.");
+		if (status === 429) return new UploadError("Rate limited. Please wait and try again.");
+		if (status >= 500) return new UploadError(`Server error (${status}). Please try again later.`);
+		return new UploadError(`Upload failed with status ${status}`);
+	}
+	if (error instanceof Error) {
+		if (error.message.includes("ECONNREFUSED")) return new UploadError("Connection refused. Check the API URL and your network.");
+		if (error.message.includes("ENOTFOUND")) return new UploadError("DNS resolution failed. Check the API URL.");
+		if (error.message.includes("ETIMEDOUT")) return new UploadError("Connection timed out. Check your network connection.");
+	}
+	return new UploadError("Upload failed. Check your network connection and try again.");
+}
+/**
+* Sanitize URL to remove sensitive parts for display.
+*/
+function sanitizeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.protocol}//${parsed.host}`;
+	} catch {
+		return url;
+	}
+}
+//#endregion
+export { validateSourcemap as a, uploadSourcemaps as i, findSourcemapFiles as n, loadAndValidateSourcemap as r, UploadError as t };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@monocle.sh/cli",
+  "version": "0.1.0",
+  "description": "Monocle CLI - upload source maps and manage your Monocle projects",
+  "keywords": [
+    "cli",
+    "error-tracking",
+    "monocle",
+    "observability",
+    "sourcemaps"
+  ],
+  "license": "ISC",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "bin": {
+    "monocle": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "fast-glob": "^3.3.3",
+    "ky": "^1.14.3",
+    "ora": "^9.3.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/file-system": "^3.0.0",
+    "@japa/runner": "^5.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "release-it": "^19.2.4",
+    "@monocle.sh/studio": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsgo --noEmit",
+    "test": "node --import @poppinss/ts-exec bin/test.ts",
+    "release": "release-it --preRelease=beta"
+  }
+}