@frontend-monitor/upload-sourcemaps 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @frontend-monitor/upload-sourcemaps
+
+将构建产物中的 Source Map 文件批量上传到前端监控平台 API，便于错误堆栈还原。适用于 CI/CD 流水线。
+
+## 要求
+
+- Node.js >= 18（使用原生 `fetch`、`FormData`）
+- 监控平台 API 已部署，并已创建项目（获得 Project ID 与 Secret Key）
+
+## 安装
+
+```bash
+# 安装为项目依赖（推荐在 CI 中与 npx 二选一）
+npm install @frontend-monitor/upload-sourcemaps
+
+# 全局安装（可选，便于直接使用命令）
+npm install -g @frontend-monitor/upload-sourcemaps
+
+# 或仅用 npx 运行，无需安装
+npx @frontend-monitor/upload-sourcemaps --project-id xxx --secret-key yyy --endpoint https://api.example.com
+```
+
+## 用法
+
+### 参数（环境变量或命令行）
+
+| 参数 | 环境变量 | 说明 | 必填 |
+|------|----------|------|------|
+| `--project-id` | `PROJECT_ID` | 项目 ID | 是 |
+| `--secret-key` | `SECRET_KEY` | 项目密钥 | 是 |
+| `--endpoint` | `ENDPOINT` | API 根地址，如 `https://api.example.com` | 是 |
+| `--release` | `RELEASE` | 版本号，需与前端 SDK `init({ release })` 一致 | 否，默认 `default` |
+| `--dir` | `DIR` | 包含 `.map` 文件的目录 | 否，默认当前目录 |
+
+### 示例
+
+```bash
+# 使用命令行参数
+npx @frontend-monitor/upload-sourcemaps \
+  --project-id p_xxx \
+  --secret-key your_secret_key \
+  --endpoint https://api.example.com \
+  --release 1.0.0 \
+  --dir ./dist
+
+# 使用环境变量（适合 CI）
+export PROJECT_ID=p_xxx
+export SECRET_KEY=your_secret_key
+export ENDPOINT=https://api.example.com
+export RELEASE=1.0.0
+export DIR=./dist
+npx @frontend-monitor/upload-sourcemaps
+```
+
+### 在 CI 中使用
+
+**GitHub Actions 示例：**
+
+```yaml
+- name: Upload Source Maps
+  env:
+    PROJECT_ID: ${{ secrets.MONITOR_PROJECT_ID }}
+    SECRET_KEY: ${{ secrets.MONITOR_SECRET_KEY }}
+    ENDPOINT: https://api.your-company.com
+    RELEASE: ${{ github.ref_name }}
+    DIR: ./dist
+  run: npx @frontend-monitor/upload-sourcemaps
+```
+
+**在代码中调用（Node.js）：**
+
+```js
+import { uploadAll } from '@frontend-monitor/upload-sourcemaps';
+
+const { ok, fail } = await uploadAll({
+  endpoint: 'https://api.example.com',
+  projectId: 'p_xxx',
+  secretKey: 'your_secret_key',
+  release: '1.0.0',
+  dir: './dist',
+});
+console.log(`Uploaded ${ok} files, ${fail} failed`);
+```
+
+## 行为说明
+
+- 递归扫描 `--dir` 下所有 `.map` 文件并逐个上传。
+- 请求地址为 `{ENDPOINT}/sourcemaps/upload`，鉴权方式与监控平台 ingest 一致（Project ID + Secret Key）。
+- 若有文件上传失败，会打印错误并以退出码 `1` 结束，便于 CI 失败感知。
+
+## 发布到 npm
+
+本包为 **scoped 包**（`@frontend-monitor/upload-sourcemaps`），首次发布需带 `--access public`。
+
+### 发布脚本说明
+
+| 脚本 | 说明 |
+|------|------|
+| `prepublishOnly` | 发布前自动执行：检查 `bin`、`lib` 是否存在，避免漏文件 |
+| `npm run publish:dry` | 仅做发布预检（不实际上传）：先跑 prepublishOnly，再 `npm publish --dry-run` |
+| `npm run publish:public` | 执行发布并设为公开：prepublishOnly + `npm publish --access public` |
+
+### 发布步骤
+
+```bash
+cd packages/upload-sourcemaps
+
+# 1. 确认将要发布的文件列表（推荐先执行）
+npm run publish:dry
+
+# 2. 登录 npm（未登录时）
+npm login
+
+# 3. 发布（scoped 包需加 --access public）
+npm run publish:public
+```
+
+若已配置 `npm config set access public`，也可直接执行 `npm publish`。
+
+## License
+
+MIT

package/bin/upload-sourcemaps.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * frontend-monitor-upload-sourcemaps CLI
+ *
+ * 环境变量或参数：
+ *   PROJECT_ID / --project-id    项目 ID（必填）
+ *   SECRET_KEY / --secret-key    项目密钥（必填）
+ *   ENDPOINT   / --endpoint      API 地址（必填）
+ *   RELEASE    / --release       release 版本（默认 default）
+ *   DIR        / --dir           要上传的目录（默认当前目录）
+ *
+ * 示例：
+ *   npx frontend-monitor-upload-sourcemaps --project-id xxx --secret-key yyy --endpoint https://api.com
+ *   PROJECT_ID=xxx SECRET_KEY=yyy ENDPOINT=https://api.com RELEASE=1.0.0 DIR=./dist upload-sourcemaps
+ */
+import { uploadAll } from '../lib/upload.js';
+
+function getArg(name, envName) {
+  const env = process.env[envName];
+  if (env) return env;
+  const i = process.argv.indexOf(name);
+  if (i !== -1 && process.argv[i + 1]) return process.argv[i + 1];
+  return null;
+}
+
+const projectId = getArg('--project-id', 'PROJECT_ID');
+const secretKey = getArg('--secret-key', 'SECRET_KEY');
+const endpoint = getArg('--endpoint', 'ENDPOINT') || '';
+const release = getArg('--release', 'RELEASE') || 'default';
+const dir = getArg('--dir', 'DIR') || process.cwd();
+
+if (!projectId || !secretKey || !endpoint) {
+  console.error('Usage: PROJECT_ID, SECRET_KEY and ENDPOINT are required.');
+  console.error('');
+  console.error('  Environment:');
+  console.error('    PROJECT_ID=xxx SECRET_KEY=yyy ENDPOINT=https://api.com [RELEASE=1.0.0] [DIR=./dist]');
+  console.error('');
+  console.error('  Arguments:');
+  console.error('    --project-id <id>   Project ID');
+  console.error('    --secret-key <key> Secret Key');
+  console.error('    --endpoint <url>   API base URL');
+  console.error('    --release <tag>    Release version (default: default)');
+  console.error('    --dir <path>       Directory containing .map files (default: cwd)');
+  console.error('');
+  console.error('  Example:');
+  console.error('    npx @frontend-monitor/upload-sourcemaps --project-id p_xxx --secret-key sk_yyy --endpoint https://api.example.com --release 1.0.0 --dir ./dist');
+  process.exit(1);
+}
+
+const { ok, fail } = await uploadAll(
+  { endpoint, projectId, secretKey, release, dir },
+  console
+);
+
+if (fail > 0) {
+  process.exit(1);
+}

package/lib/upload.js

@@ -0,0 +1,79 @@
+import { readdir, readFile } from 'fs/promises';
+import { join, basename } from 'path';
+
+/**
+ * 递归收集目录下所有 .map 文件
+ */
+export async function findMapFiles(dirPath, list = []) {
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dirPath, e.name);
+    if (e.isDirectory()) {
+      await findMapFiles(full, list);
+    } else if (e.name.endsWith('.map')) {
+      list.push(full);
+    }
+  }
+  return list;
+}
+
+/**
+ * 上传单个 .map 文件到监控 API
+ * @param {object} opts - { endpoint, projectId, secretKey, release, filePath }
+ * @returns {Promise<object>} API 返回结果
+ */
+export async function uploadOne(opts) {
+  const { endpoint, projectId, secretKey, release, filePath } = opts;
+  const base = basename(filePath, '.map');
+  const buf = await readFile(filePath);
+  const url = endpoint.replace(/\/$/, '') + '/sourcemaps/upload';
+  const form = new FormData();
+  form.append('projectId', projectId);
+  form.append('secretKey', secretKey);
+  form.append('release', release);
+  form.append('filename', base);
+  form.append('file', new Blob([buf]), basename(filePath));
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'X-Project-Id': projectId,
+      'X-Secret-Key': secretKey,
+    },
+    body: form,
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`${res.status} ${text}`);
+  }
+  return JSON.parse(text || '{}');
+}
+
+/**
+ * 批量上传目录下所有 .map 文件
+ * @param {object} opts - { endpoint, projectId, secretKey, release, dir }
+ * @param {object} [logger] - { log, error } 默认 console
+ * @returns {Promise<{ ok: number, fail: number }>}
+ */
+export async function uploadAll(opts, logger = console) {
+  const { dir, endpoint, projectId, secretKey, release } = opts;
+  const files = await findMapFiles(dir);
+  if (files.length === 0) {
+    logger.log('No .map files found in', dir);
+    return { ok: 0, fail: 0 };
+  }
+  logger.log('Uploading', files.length, 'source map(s) to', endpoint, 'release=', release);
+  let ok = 0;
+  let fail = 0;
+  for (const f of files) {
+    try {
+      await uploadOne({ endpoint, projectId, secretKey, release, filePath: f });
+      logger.log('  OK', basename(f));
+      ok++;
+    } catch (err) {
+      logger.error('  FAIL', f, err.message);
+      fail++;
+    }
+  }
+  return { ok, fail };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@frontend-monitor/upload-sourcemaps",
+  "version": "1.0.0",
+  "description": "CLI to upload Source Map files to frontend-monitor API (for CI/CD)",
+  "type": "module",
+  "main": "lib/upload.js",
+  "bin": {
+    "upload-sourcemaps": "./bin/upload-sourcemaps.js"
+  },
+  "scripts": {
+    "prepublishOnly": "node -e \"require('fs').accessSync('bin/upload-sourcemaps.js'); require('fs').accessSync('lib/upload.js'); console.log('publish check ok');\"",
+    "publish:dry": "npm run prepublishOnly && npm publish --dry-run",
+    "publish:public": "npm run prepublishOnly && npm publish --access public"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "sourcemap",
+    "source-map",
+    "frontend",
+    "monitoring",
+    "cli",
+    "upload",
+    "ci"
+  ],
+  "author": "mishuxing",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}