jsharness 1.1.0 → 1.3.0

package/lib/index.mjs

@@ -8,9 +8,20 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
+import https from 'https';
+import zlib from 'zlib';
+import { execSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+// ============================================================
+// 远端源配置（GitHub 仓库 + npm registry）
+// ============================================================
+
+const HARNESS_GITHUB_REPO = 'jieaiag/harness-engineering'; // TODO: 替换为实际仓库
+const HARNESS_NPM_PACKAGE = 'jsharness';
+const HARNESS_BRANCH = 'main';
+
 // ============================================================
 // 支持的 AI 工具清单
 // ============================================================
@@ -497,6 +508,223 @@ function extractBody(markdown) {
 // 扫描 Harness 源文件
 // ============================================================
 
+/**
+ * 获取 .harness/ 模板源目录
+ *
+ * 三级回退策略：
+ *   1. 本包自带（import.meta.url 定位）— npx 缓存正常时最快
+ *   2. npx 缓存解压目录 — 某些 npx 版本 .harness/ 未包含时
+ *   3. 从 npm registry 下载 tgz 并解压到临时目录 — 纯净环境兜底
+ *
+ * 类似 OpenSpec/SpecKit 的初始化方式：不依赖项目本地 node_modules，
+ * 而是从远端（npm registry）直接拉取模板文件写入目标项目。
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<string|null>} .harness/ 目录的绝对路径，全部失败返回 null
+ */
+async function getHarnessSourceDir(options = {}) {
+  const { verbose = false } = options;
+
+  // ── 策略 1: 本包自带 .harness/（基于 import.meta.url）──
+  const libDir = path.dirname(fileURLToPath(import.meta.url));
+  const bundledDir = path.join(libDir, '..', '.harness');
+  if (fs.existsSync(bundledDir) && fs.existsSync(path.join(bundledDir, 'rules'))) {
+    if (verbose) console.log(`   📂 源=本包自带: ${bundledDir}`);
+    return bundledDir;
+  }
+
+  // ── 策略 2: npx 缓存中查找 jsharness 包 ──
+  try {
+    const npxCacheDir = findNpxCacheDir();
+    if (npxCacheDir) {
+      if (verbose) console.log(`   📂 源=npx缓存: ${npxCacheDir}`);
+      return npxCacheDir;
+    }
+  } catch { /* ignore */ }
+
+  // ── 策略 3: 从 npm registry 下载 jsharness tgz 并解压 ──
+  console.log('   ⬇️  本地未找到 .harness/ 模板，从 npm 远端拉取...');
+  const remoteDir = await downloadAndExtractFromNpm(options);
+  if (remoteDir) {
+    if (verbose) console.log(`   📂 源=npm远端: ${remoteDir}`);
+    return remoteDir;
+  }
+
+  return null;
+}
+
+/**
+ * 在 npx 缓存目录中搜索包含 .harness/ 的 jsharness 包
+ */
+function findNpxCacheDir() {
+  const candidates = [];
+
+  // npm 缓存根目录
+  try {
+    const npmCacheRoot = execSync('npm config get cache', { encoding: 'utf-8' }).trim();
+    candidates.push(path.join(npmCacheRoot, '_npx'));
+  } catch { /* ignore */ }
+
+  // 常见 npx 缓存路径
+  const homeDir = process.env.HOME || process.env.USERPROFILE || process.env.HOMEPATH || '';
+  if (homeDir) {
+    candidates.push(
+      path.join(homeDir, 'AppData', 'Local', 'npm-cache', '_npx'),  // Windows
+      path.join(homeDir, '.npm', '_npx'),                            // Linux/macOS
+    );
+  }
+
+  for (const cacheRoot of candidates) {
+    if (!fs.existsSync(cacheRoot)) continue;
+
+    // 递归搜索含 .harness/ 的 jsharness 包目录
+    const found = searchHarnessInDir(cacheRoot, 3);
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/**
+ * 在指定目录下递归搜索包含 .harness/rules/ 的目录
+ */
+function searchHarnessInDir(dir, maxDepth) {
+  if (maxDepth <= 0) return null;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const fullPath = path.join(dir, entry.name);
+
+      // 检查是否包含 .harness/rules/
+      const harnessDir = path.join(fullPath, '.harness');
+      if (fs.existsSync(path.join(harnessDir, 'rules'))) {
+        return harnessDir;
+      }
+
+      // 继续向下搜索
+      const found = searchHarnessInDir(fullPath, maxDepth - 1);
+      if (found) return found;
+    }
+  } catch { /* ignore permission errors */ }
+  return null;
+}
+
+/**
+ * 从 npm registry 下载 jsharness 包并解压 .harness/ 到临时目录
+ */
+async function downloadAndExtractFromNpm(options = {}) {
+  const { verbose = false } = options;
+
+  try {
+    // 1. 获取包的 tgz URL
+    const packUrl = await getNpmPackageTarballUrl();
+    if (!packUrl) return null;
+
+    // 2. 下载 tgz 到临时目录
+    const tmpDir = path.join(process.env.TEMP || process.env.TMP || '/tmp', `jsharness-${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    const tgzPath = path.join(tmpDir, 'jsharness.tgz');
+
+    if (verbose) console.log(`   📦 下载: ${packUrl}`);
+    await downloadFile(packUrl, tgzPath);
+
+    // 3. 解压（优先 tar 命令，回退到 Node.js 流式解压）
+    const extractDir = path.join(tmpDir, 'extracted');
+    fs.mkdirSync(extractDir, { recursive: true });
+
+    try {
+      execSync(`tar -xzf "${tgzPath}" -C "${extractDir}"`, { stdio: verbose ? 'inherit' : 'pipe' });
+    } catch {
+      // tar 命令失败（某些 Windows 环境），使用 Node.js 解压
+      if (verbose) console.log('   📦 tar 命令失败，使用 Node.js 解压...');
+      await extractTgzWithNode(tgzPath, extractDir);
+    }
+
+    // 解压后目录结构: package/.harness/ 或 .harness/
+    const harnessDir = path.join(extractDir, 'package', '.harness');
+    if (fs.existsSync(harnessDir)) return harnessDir;
+
+    const altDir = path.join(extractDir, '.harness');
+    if (fs.existsSync(altDir)) return altDir;
+
+    // 深度搜索
+    return searchHarnessInDir(extractDir, 2);
+  } catch (err) {
+    if (verbose) console.log(`   ⚠️  npm 远端下载失败: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * 使用 Node.js 内置模块解压 .tgz 文件
+ * .tgz = gzip(tar)，使用 zlib + tar 命令组合
+ */
+async function extractTgzWithNode(tgzPath, destDir) {
+  // Windows 10+ 和 Linux/macOS 都自带 tar 命令
+  // 但 Windows 的 tar.exe 路径可能不同
+  const tarCommands = [
+    `tar -xzf "${tgzPath}" -C "${destDir}"`,
+    `cmd /c "tar -xzf \\"${tgzPath}\\" -C \\"${destDir}\\""`,
+  ];
+
+  for (const cmd of tarCommands) {
+    try {
+      execSync(cmd, { stdio: 'pipe' });
+      return; // 成功
+    } catch { /* 尝试下一种 */ }
+  }
+
+  throw new Error('所有 tar 命令均失败，请确认系统安装了 tar');
+}
+
+/**
+ * 获取 jsharness 包在 npm registry 上的 tarball URL
+ */
+async function getNpmPackageTarballUrl() {
+  const url = `https://registry.npmjs.org/${HARNESS_NPM_PACKAGE}/latest`;
+  const data = await httpGetJSON(url);
+  return data?.dist?.tarball || null;
+}
+
+/**
+ * HTTP GET 返回 JSON
+ */
+function httpGetJSON(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { timeout: 10000 }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return httpGetJSON(res.headers.location).then(resolve, reject);
+      }
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(body)); } catch { reject(new Error('Invalid JSON')); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * 下载文件到本地路径
+ */
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath);
+    https.get(url, { timeout: 30000 }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadFile(res.headers.location, destPath).then(resolve, reject);
+      }
+      res.pipe(file);
+      file.on('finish', () => { file.close(resolve); });
+    }).on('error', (err) => {
+      fs.unlinkSync(destPath);
+      reject(err);
+    });
+  });
+}
+
 export function scanHarnessRules(harnessDir, stackFilter) {
   const rulesDir = path.join(harnessDir, 'rules');
   const results = [];
@@ -512,7 +740,6 @@ export function scanHarnessRules(harnessDir, stackFilter) {
       if (stackFilter && stackFilter !== 'all') {
         const lowerRel = relPath.toLowerCase();
         if (stackFilter === 'vue3' && !lowerRel.includes('vue') && !lowerRel.includes('frontend') && !lowerRel.includes('global')) {
-          // 对于 vue3 过滤，保留 global 和 frontend/vue 相关
           if (!lowerRel.includes('global') && !lowerRel.includes('frontend') && !lowerRel.includes('web')) {
             continue;
           }
@@ -709,20 +936,18 @@ export async function runInit(projectDir, options = {}) {
   console.log('\n🔧 Harness Engineering 初始化');
   console.log(`   目标目录: ${projectDir}\n`);
 
-  // 1. 确定 Harness 源路径
-  const harnessDir = findHarnessSource(projectDir);
+  // 1. 多源获取 .harness/ 模板（本包自带 → npx缓存 → npm远端）
+  const harnessDir = await getHarnessSourceDir({ verbose });
   if (!harnessDir) {
-    console.error('❌ 未找到 .harness/ 目录。');
-    console.error('');
-    console.error('   请先安装 jsharness：');
-    console.error('     npm i -D jsharness');
+    console.error('❌ 无法获取 .harness/ 模板。');
     console.error('');
-    console.error('   然后重新运行：');
-    console.error('     npx jsharness init --verbose');
+    console.error('   已尝试：');
+    console.error('     1. 本包自带的 .harness/ 目录');
+    console.error('     2. npx 缓存目录');
+    console.error('     3. npm registry 远端下载');
     console.error('');
-    const nmPath = path.join(projectDir, 'node_modules', 'jsharness', '.harness');
-    console.error(`   [DEBUG] 项目目录: ${projectDir}`);
-    console.error(`   [DEBUG] node_modules/jsharness/.harness 存在: ${fs.existsSync(nmPath) ? '是' : '否'}`);
+    console.error('   请检查网络连接，或手动安装后重试：');
+    console.error('     npm install -g jsharness && jsharness init');
     process.exit(1);
   }
   if (verbose) console.log(`   📂 Harness 源: ${harnessDir}`);
@@ -1086,54 +1311,4 @@ export function archiveOpenSpecChange(projectDir, changeName) {
   console.log(`\n✅ 变更 "${changeName}" 已归档到 openspec/changes/archive/${path.basename(archiveDir)}/\n`);
 }
 
-// ============================================================
-// 内部：查找 Harness 源
-// ============================================================
-
-function findHarnessSource(projectDir) {
-  // 1. 项目自身的 .harness/
-  const localHarness = path.join(projectDir, '.harness');
-  if (fs.existsSync(localHarness)) return localHarness;
 
-  // 2. 通过 node_modules 查找（npm i -D jsharness 后）
-  const nmCandidates = [
-    path.join(projectDir, 'node_modules', 'jsharness', '.harness'),
-    path.join(projectDir, 'node_modules', '.pnpm', 'jsharness*', 'node_modules', 'jsharness', '.harness'),
-  ];
-  for (const c of nmCandidates) {
-    try {
-      const expanded = (c.includes('*') ? fs.readdirSync(path.dirname(c))
-        .filter(d => d.startsWith('jsharness')).map(d => path.join(path.dirname(c), d, 'node_modules', 'jsharness', '.harness')) : [c])
-        .flat();
-      for (const p of expanded) {
-        if (fs.existsSync(p)) return p;
-      }
-    } catch { /* skip */ }
-  }
-
-  // 3. 通过 require.resolve 定位 npm 包根
-  try {
-    const _require = createRequire(import.meta.url);
-    const pkgPath = _require.resolve('jsharness/package.json');
-    const packageHarness = path.join(path.dirname(pkgPath), '.harness');
-    if (fs.existsSync(packageHarness)) return packageHarness;
-  } catch {
-    // require 解析失败，继续尝试其他方式
-  }
-
-  // 4. __dirname 相对路径（本地开发模式）
-  const devHarness = path.join(__dirname, '..', '..', '.harness');
-  if (fs.existsSync(devHarness)) return devHarness;
-
-  // 5. 最后尝试：沿 __dirname 向上搜索 .harness
-  let current = __dirname;
-  for (let i = 0; i < 5; i++) {
-    const candidate = path.join(current, '.harness');
-    if (fs.existsSync(candidate) && current !== projectDir) return candidate;
-    const parent = path.dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-
-  return null;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsharness",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Harness Engineering - AI 编程行为工程化管控系统。将 rules/skills/gate/agents 一键注入到 CodeBuddy、Cursor、Copilot 等 AI 工具中。",
   "main": "lib/index.mjs",
   "bin": {