@migor/cli 0.5.0 → 0.6.1

package/dist/npm-bin.js

@@ -1,7 +1,44 @@
 /**
- * Windows 上 npm / npx 是 .cmd shim：不带 shell 的 spawn / spawnSync 无法直接执行
- * （ENOENT）。统一在这里按平台点名 —— 保持 CLI 零依赖（不引 cross-spawn）。
+ * Windows 上 npm / npx 是 .cmd shim：Node 修补 CVE-2024-27980（18.20.2 / 20.12.2 / 21.7.3+）后，
+ * 不带 shell 直接 spawn .cmd 会 EINVAL。统一在这里产出 spawn 描述（cross-spawn 同思路，
+ * 保持零依赖）：win32 走 cmd.exe 包装 + 逐参数脱敏，其余平台原样直 spawn。
+ *
+ * 为什么不用 options.shell:true —— shell:true 时 Node 把「命令 + 参数」用空格 join 后
+ * 整体塞给 cmd.exe，参数**不做任何转义**；而 add 的参数是用户输入的包名/本地路径，
+ * 含 `&` / `|` / `%` 即成命令注入。所以这里走 cmd.exe 包装并逐参数脱敏
+ * （算法取自 cross-spawn lib/util/escape.js，https://qntm.org/cmd）。
  */
-export function npmBin(bin, platform = process.platform) {
-    return platform === 'win32' ? `${bin}.cmd` : bin;
+// cmd.exe 元字符（见 http://www.robvanderwoude.com/escapechars.php）
+const CMD_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+/** 命令名脱敏（npm.cmd 本身）：不加引号，只 ^ 脱敏元字符 */
+function escapeCmdCommand(command) {
+    return command.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * 参数脱敏：反斜杠+引号序列按 CreateProcess 规则翻倍转义，整体加双引号，
+ * 再对 cmd 元字符加 ^（`^` 落在引号外才生效，所以先加引号后脱敏）。
+ */
+function escapeCmdArg(arg) {
+    let out = arg
+        // 反斜杠序列 + 引号：反斜杠翻倍，引号加反斜杠
+        .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
+        // 末尾反斜杠序列翻倍（随后会拼上收尾引号）
+        .replace(/(?=(\\+?)?)\1$/, '$1$1');
+    out = `"${out}"`;
+    return out.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * npm / npx 的 spawn 描述：win32 返回 cmd.exe 包装（参数已脱敏，
+ * 全局安装的 npm.cmd 非 node_modules/.bin 代理 shim，单层 ^ 脱敏即可）；
+ * 其余平台原样返回（直接 spawn 可执行文件）。
+ */
+export function npmSpawn(bin, args, platform = process.platform, comspec = process.env.comspec) {
+    if (platform !== 'win32')
+        return { command: bin, args, options: {} };
+    const shellCommand = [escapeCmdCommand(`${bin}.cmd`), ...args.map(escapeCmdArg)].join(' ');
+    return {
+        command: comspec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${shellCommand}"`],
+        options: { windowsVerbatimArguments: true },
+    };
 }

package/dist/report.js

@@ -30,12 +30,14 @@ export function extractTrace(v) {
     return null;
 }
 /** 打印一张按总耗时降序的能力排行（跨多行记录时按能力合并） */
+/** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
+export const USAGE = '用法：agentia report <trace.jsonl>';
 export async function reportCommand(args) {
     const file = args[0];
     // 失败一律**抛错**（而不是就地设 process.exitCode）—— 本命令是异步的，
     // 就地设的 exitCode 会被 cli.ts 末尾那句 `process.exitCode = main(...)` 覆盖成 0。
     if (file === undefined || args.length > 1) {
-        throw new Error('用法：agentia report <trace.jsonl>');
+        throw new Error(USAGE);
     }
     let raw;
     try {
@@ -66,7 +68,17 @@ export async function reportCommand(args) {
             (badLines > 0 ? `；另有 ${badLines} 行无法解析` : ''));
     }
     // 聚合口径与 inspector 面板 / 官网 playground 同源（构建期拷进来的 trace-view 产物）
-    const { summarizeTrace } = (await import(new URL('./inspector/summary.js', import.meta.url).href));
+    // 这份聚合实现由 packages/cli/scripts/copy-assets.mjs 在构建期从 trace-view 产物拷进来。
+    // 缺它只可能是「装坏了」或「直接跑未构建的源码」—— 原始 ERR_MODULE_NOT_FOUND 里全是
+    // dist 内部路径，用户读不出该做什么，故换成带补救动作的报错。
+    let summarizeTrace;
+    try {
+        ({ summarizeTrace } = (await import(new URL('./inspector/summary.js', import.meta.url).href)));
+    }
+    catch (e) {
+        throw new Error(`缺少 CLI 资源（inspector/summary.js）：${e.message}；` +
+            '请重装 @migor/cli 或重新构建（npm run build:cli）');
+    }
     const merged = new Map();
     let okRuns = 0;
     for (const t of traces) {

package/dist/templates.js

@@ -58,9 +58,11 @@ export function projectPackageJson(name) {
         type: 'module',
         scripts: {
             dev: 'tsx src/main.ts',
+            build: 'tsc -p tsconfig.json && node scripts/copy-assets.mjs',
+            start: 'node dist/main.js',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.5.0' },
+        dependencies: { '@migor/agentia': '^0.6.1' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',
@@ -76,6 +78,14 @@ export function projectTsconfig() {
             moduleResolution: 'NodeNext',
             lib: ['ES2022'],
             strict: true,
+            // 编译产物落 dist/（npm run build → npm start 跑 dist/main.js）；
+            // .md 文本资产由 scripts/copy-assets.mjs 跟随同相对路径拷过去
+            // （asset(import.meta.url, './x.md') 按**文件位置**解析，.md 必须跟着 .js 走）
+            rootDir: 'src',
+            outDir: 'dist',
+            // 框架零运行时依赖（不再有厂商 SDK 经传递链把 @types/node 带进编译程序），
+            // node 全局类型必须显式声明
+            types: ['node'],
             esModuleInterop: true,
             skipLibCheck: true,
         },
@@ -158,6 +168,13 @@ ANTHROPIC_API_KEY=sk-ant-...
 npm run dev -- "你的问题"
 \`\`\`
 
+## 构建与生产运行
+
+\`\`\`bash
+npm run build   # tsc → dist/ + .md 文本资产跟随拷贝（asset() 按文件位置解析，必须跟着 .js 走）
+npm start -- "你的问题"   # 跑编译产物 dist/main.js（部署/Docker 用这条）
+\`\`\`
+
 也可以用环境变量（适合 CI / 容器）——**真实环境变量优先，不会被 \`.env\` 覆盖**：
 
 \`\`\`bash
@@ -195,6 +212,36 @@ ANTHROPIC_API_KEY=
 # AGENTIA_MODEL=claude-opus-5
 `;
 }
+/** 脚手架的 scripts/copy-assets.mjs：把 src 下的 .md 文本资产拷进 dist/（同相对路径） */
+export function copyAssetsMjs() {
+    return `// 把能力文件夹里的 .md 文本资产拷进 dist/（与编译产物同相对路径）。
+// asset(import.meta.url, './x.md') 按**文件位置**解析，所以 .md 必须跟着 .js 走。
+import { cpSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const srcDir = join(here, '..', 'src');
+const outDir = join(here, '..', 'dist');
+
+function walk(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else if (e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+let n = 0;
+for (const f of walk(srcDir)) {
+  cpSync(f, join(outDir, f.slice(srcDir.length + 1)));
+  n++;
+}
+console.log(\`[copy-assets] \${n} 个 .md 资产 → dist/\`);
+`;
+}
 // ---------- g 命令能力模板 ----------
 export function toolIndexTs(name) {
     const cls = kebabToPascal(name);

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@migor/cli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {
     "agentia": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "repository": "retrychx/agentia",
   "homepage": "https://agentia-web.pages.dev",
@@ -33,7 +34,7 @@
     "prepublishOnly": "node ../../scripts/check-release.mjs && npm run build"
   },
   "devDependencies": {
-    "@types/node": "^22.0.2",
+    "@types/node": "^26.5.1",
     "typescript": "^7.0.2"
   }
 }