easy-coding-harness 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -6,11 +6,19 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
-## 0.5.1
+## 0.5.3
 
-- 修复 Claude Code hook 命令使用相对路径导致在子目录 cwd 下找不到 `.claude/hooks/*.py` 的问题；Claude、Codex、Qoder 的 hook 配置现在安装时渲染为带引号的绝对脚本路径。
-- `easy-coding upgrade` 可直接刷新存量 0.5.0 项目的 hook 配置并解决该问题；升级后 `ec-init` 合规扫描会校验 hook 配置是否已使用当前版本要求的绝对路径。
-- `easy-coding clear` 和 `install-manifest.json` 兼容新绝对 hook 命令，清理时仍按项目相对 hook 路径识别托管注册项。
+- 根治 `task.json` 绝对路径泄漏：`.easy-coding/tasks/project-init/task.json` 不再写入本机仓库绝对路径。该 `project_path` 字段无任何消费方，直接移除，可提交产物彻底去本地化。
+- `easy-coding upgrade` 会自动剥离存量项目中遗留的 `project_path` 字段，让老项目也随升级变干净。
+- 根治 hook 编译产物：hook launcher 设置 `sys.dont_write_bytecode=True`，运行时不再在 `.claude/hooks/`、`.codex/hooks/`、`.qoder/hooks/` 旁生成 `__pycache__/*.pyc`；同时 `init` / `add-agent` / `upgrade` 会向项目 `.gitignore` 追加 `__pycache__/` 作为兜底防御。launcher 内容变化会触发 `upgrade` 刷新存量 hook 注册。
+- 版本自 `0.5.2-beta.0` 升级为 `0.5.3`，合并 beta.0 的全部 portable hook 修复。跳过 `0.5.2` 正式版：升级检测的 `compareVersions` 会截断预发布后缀，若发 `0.5.2` 会把已安装 `0.5.2-beta.0` 的项目误判为已最新而不提示本次迁移；递增到 `0.5.3` 可让 beta 用户正确检测到升级。
+
+## 0.5.2-beta.0
+
+- 修复 Claude Code hook 命令使用直接相对路径导致在子目录 cwd 下找不到 `.claude/hooks/*.py` 的问题；Claude、Codex、Qoder 的 hook 配置现在使用可共享的 portable relative launcher，并绑定 `.easy-coding/config.yaml` 的 `project.id`，避免把本机仓库绝对路径写入可提交配置，同时防止 supermodule 父仓 hook 被子仓 cwd 错路由。
+- `easy-coding upgrade` 可直接刷新存量 0.5.0 项目和已安装 0.5.1 beta 绝对路径配置；同版本也会修复缺失、重复、事件错位或 stale 的托管 hook 注册。
+- `easy-coding clear` 和 `install-manifest.json` 兼容 portable launcher、旧直接相对命令和旧绝对 hook 命令，清理时仍按项目相对 hook 路径识别托管注册项。
+- npm `0.5.1` 已发布不可覆盖，本版本作为 beta 修复包发布，用于替代原 `0.5.1` beta。
 
 ## 0.5.0
 

package/dist/cli.js

@@ -61,6 +61,7 @@ function colorizeBanner(art) {
 }
 
 // src/utils/config-yaml.ts
+import { randomUUID } from "crypto";
 import { readFile as readFile2 } from "fs/promises";
 import YAML, { isScalar, isSeq, parseDocument } from "yaml";
 
@@ -108,6 +109,7 @@ function createDefaultConfig(params) {
     harness_version: params.harnessVersion,
     agents: params.agents,
     project: {
+      id: params.projectId ?? createProjectId(),
       name: params.projectName
     },
     memory: {
@@ -138,6 +140,14 @@ async function readConfigYaml(filePath) {
   const content = await readFile2(filePath, "utf8");
   return YAML.parse(content);
 }
+async function readProjectIdIfExists(filePath) {
+  try {
+    const config = await readConfigYaml(filePath);
+    return typeof config.project?.id === "string" && config.project.id.trim() ? config.project.id : null;
+  } catch {
+    return null;
+  }
+}
 async function updateConfigYaml(filePath, updater) {
   const content = await readFile2(filePath, "utf8");
   const document = parseDocument(content);
@@ -160,11 +170,27 @@ async function updateHarnessVersion(filePath, version) {
     config.harness_version = version;
   });
 }
+async function ensureProjectId(filePath) {
+  let projectId = "";
+  await updateConfigYaml(filePath, (config) => {
+    if (!config.project || typeof config.project !== "object") {
+      config.project = { id: createProjectId(), name: "" };
+    }
+    if (typeof config.project.id !== "string" || !config.project.id.trim()) {
+      config.project.id = createProjectId();
+    }
+    projectId = config.project.id;
+  });
+  return projectId;
+}
 async function updateSupermoduleConfig(filePath, supermodule) {
   return updateConfigYaml(filePath, (config) => {
     config.supermodule = supermodule;
   });
 }
+function createProjectId() {
+  return `ec-${randomUUID()}`;
+}
 
 // src/utils/gitignore.ts
 import path3 from "path";
@@ -182,6 +208,7 @@ var MAIN_SPEC_DIR = "main";
 var DEV_SPEC_DIR = "dev";
 var TEMPLATES_DIR = "templates";
 var SESSIONS_GITIGNORE_ENTRY = ".easy-coding/sessions/";
+var HOOK_BYTECODE_GITIGNORE_ENTRY = "__pycache__/";
 var GENERATED_REGION_START = "<!-- \u2550\u2550\u2550 easy-coding-harness generated (DO NOT EDIT BETWEEN MARKERS) \u2550\u2550\u2550 -->";
 var GENERATED_REGION_END = "<!-- \u2550\u2550\u2550 end easy-coding-harness generated \u2550\u2550\u2550 -->";
 
@@ -201,6 +228,13 @@ async function ensureGitignoreEntry(cwd, entry, heading = "# \u2550\u2550\u2550
 async function ensureEasyCodingSessionsIgnored(cwd) {
   return ensureGitignoreEntry(cwd, SESSIONS_GITIGNORE_ENTRY);
 }
+async function ensureHookBytecodeIgnored(cwd) {
+  return ensureGitignoreEntry(
+    cwd,
+    HOOK_BYTECODE_GITIGNORE_ENTRY,
+    "# \u2550\u2550\u2550 easy-coding-harness (auto-generated) \u2550\u2550\u2550\n# Python bytecode from hook scripts; do not commit"
+  );
+}
 
 // src/utils/install-manifest.ts
 import { createHash } from "crypto";
@@ -568,17 +602,21 @@ async function writeRuntimeScaffold(cwd, agents, opts = {}) {
   const easyCodingDir = path6.join(cwd, EASY_CODING_DIR);
   await ensureDir(easyCodingDir);
   const configPath2 = path6.join(easyCodingDir, CONFIG_FILE);
+  let projectId = opts.projectId ?? createProjectId();
   if (!await pathExists(configPath2)) {
     const projectName = path6.basename(cwd);
     await writeConfigYaml(
       configPath2,
       createDefaultConfig({
         projectName,
+        projectId,
         harnessVersion: VERSION,
         agents,
         supermodule: opts.supermodule
       })
     );
+  } else {
+    projectId = await ensureProjectId(configPath2);
   }
   await ensureDir(path6.join(easyCodingDir, "tasks"));
   await ensureDir(path6.join(easyCodingDir, SESSIONS_DIR));
@@ -586,6 +624,7 @@ async function writeRuntimeScaffold(cwd, agents, opts = {}) {
   await ensureDir(path6.join(easyCodingDir, SPEC_DIR, DEV_SPEC_DIR));
   await writeMemoryScaffold(easyCodingDir);
   await writeTemplatesScaffold(easyCodingDir);
+  return projectId;
 }
 async function writeTemplatesScaffold(easyCodingDir) {
   const templatesDir = path6.join(easyCodingDir, TEMPLATES_DIR);
@@ -627,7 +666,6 @@ function createProjectInitTask(params) {
     context: {
       agents_installed: params.agents,
       cli_version: VERSION,
-      project_path: params.cwd,
       init_source: params.initSource ?? "fresh",
       ...params.legacyAssets ? { legacy_assets: params.legacyAssets } : {},
       ...params.legacyMissingHarnessFiles ? { legacy_missing_harness_files: params.legacyMissingHarnessFiles } : {}
@@ -648,7 +686,6 @@ async function writeProjectInitTask(cwd, agents, options = {}) {
   await writeTaskJson(
     getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID),
     createProjectInitTask({
-      cwd,
       agents,
       initSource: options.initSource,
       legacyAssets: options.legacyAssets,
@@ -656,6 +693,15 @@ async function writeProjectInitTask(cwd, agents, options = {}) {
     })
   );
 }
+async function stripInitTaskProjectPath(cwd) {
+  const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
+  if (!await pathExists(filePath)) return false;
+  const task = await readTaskJson(filePath);
+  if (!task.context || !("project_path" in task.context)) return false;
+  task.context.project_path = void 0;
+  await writeTaskJson(filePath, task);
+  return true;
+}
 async function setPendingInitSince(cwd, version) {
   const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
   if (!await pathExists(filePath)) return;
@@ -762,17 +808,28 @@ function resolvePlaceholders(content, ctx, contentName = "template") {
   }
   return resolved;
 }
-function withInstallPaths(cwd, ctx) {
-  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
+async function withProjectInstallPaths(cwd, ctx, projectId) {
+  const resolvedProjectId = projectId ?? await readProjectIdIfExists(path8.join(cwd, EASY_CODING_DIR, CONFIG_FILE));
+  return withInstallPaths(cwd, ctx, resolvedProjectId ?? void 0);
+}
+function withInstallPaths(cwd, ctx, projectId) {
   return {
     ...ctx,
-    platform_hooks_dir_abs: hooksDir,
-    platform_hooks_dir_shell: jsonStringContent(shellDoubleQuoteArg(hooksDir))
+    platform_hook_session_start_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "session-start.py", process.platform, projectId)
+    ),
+    platform_hook_inject_workflow_state_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "inject-workflow-state.py", process.platform, projectId)
+    ),
+    platform_hook_inject_subagent_context_command: jsonStringContent(
+      renderHookCommand(cwd, ctx, "inject-subagent-context.py", process.platform, projectId)
+    )
   };
 }
-function renderHookCommand(cwd, ctx, scriptName, platform = process.platform) {
-  const hooksDir = toPosixPath(path8.resolve(cwd, ctx.platform_config_dir, "hooks"));
-  return `${ctx.python_cmd} ${shellDoubleQuoteArg(hooksDir, platform)}/${scriptName}`;
+function renderHookCommand(_cwd, ctx, scriptName, platform = process.platform, projectId) {
+  const launcher = `import base64;exec(base64.b64decode('${Buffer.from(HOOK_LAUNCHER_PYTHON).toString("base64")}').decode())`;
+  const rootIdArg = projectId ? ` ${shellDoubleQuoteArg(projectId, platform)}` : "";
+  return `${ctx.python_cmd} -c ${shellDoubleQuoteArg(launcher, platform)}${rootIdArg} ${ctx.platform_config_dir}/hooks/${scriptName}`;
 }
 function shellDoubleQuoteArg(value, platform = process.platform) {
   if (platform === "win32") {
@@ -783,12 +840,58 @@ function shellDoubleQuoteArg(value, platform = process.platform) {
   }
   return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
 }
-function toPosixPath(filePath) {
-  return filePath.split(path8.sep).join("/");
-}
 function jsonStringContent(value) {
   return JSON.stringify(value).slice(1, -1);
 }
+var HOOK_LAUNCHER_PYTHON = [
+  "import io,json,os,re,runpy,sys",
+  "sys.dont_write_bytecode=True",
+  "from pathlib import Path",
+  "payload=sys.stdin.read()",
+  "try:",
+  "    data=json.loads(payload or '{}')",
+  "except Exception:",
+  "    data={}",
+  "expected_id=sys.argv[1] if len(sys.argv) > 2 else None",
+  "script_arg=sys.argv[2] if len(sys.argv) > 2 else (sys.argv[1] if len(sys.argv) > 1 else None)",
+  "def project_id(root):",
+  "    try:",
+  "        lines=(root / '.easy-coding' / 'config.yaml').read_text(encoding='utf-8').splitlines()",
+  "    except Exception:",
+  "        return None",
+  "    in_project=False",
+  "    for line in lines:",
+  "        if not in_project:",
+  "            if re.match(r'^project\\s*:\\s*(?:#.*)?$', line):",
+  "                in_project=True",
+  "            continue",
+  "        if not line.strip() or line.lstrip().startswith('#'):",
+  "            continue",
+  "        if not line.startswith((' ', '\\t')):",
+  "            return None",
+  `        match=re.match(r"\\s+id\\s*:\\s*['\\"]?([^'\\"#\\s]+)", line)`,
+  "        if match:",
+  "            return match.group(1)",
+  "    return None",
+  "def roots_from(raw):",
+  "    if not raw:",
+  "        return []",
+  "    start=Path(raw).resolve()",
+  "    return [candidate for candidate in (start, *start.parents) if (candidate / '.easy-coding').is_dir()]",
+  "sources=[os.environ.get('CLAUDE_PROJECT_DIR'), os.environ.get('QODER_PROJECT_DIR'), data.get('cwd'), os.getcwd()]",
+  "root=None",
+  "if expected_id:",
+  "    root=next((candidate for raw in sources for candidate in roots_from(raw) if project_id(candidate) == expected_id), None)",
+  "else:",
+  "    root=next((candidate for raw in sources for candidate in roots_from(raw)), None)",
+  "target=(root / script_arg) if root and script_arg else None",
+  "if target and target.is_file():",
+  "    os.chdir(root)",
+  "    data['cwd']=str(root)",
+  "    sys.stdin=io.StringIO(json.dumps(data))",
+  "    sys.path.insert(0, str(target.parent))",
+  "    runpy.run_path(str(target), run_name='__main__')"
+].join("\n");
 async function resolveSkills(ctx) {
   const skillsRoot = getTemplatePath("common", "skills");
   const entries = await readdir2(skillsRoot);
@@ -944,7 +1047,7 @@ function stripTemplateExtension(fileName) {
 async function configureClaude(cwd, opts = {}) {
   const platform = "claude-code";
   const meta = PLATFORM_META[platform];
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const dest = path9.join(cwd, ".claude");
   const hookConfigPath = path9.join(cwd, meta.hookConfigFile);
   const artifacts = [];
@@ -982,7 +1085,7 @@ import path10 from "path";
 async function configureCodex(cwd, opts = {}) {
   const platform = "codex";
   const meta = PLATFORM_META[platform];
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const hookConfigPath = path10.join(cwd, meta.hookConfigFile);
   const artifacts = [];
   artifacts.push(
@@ -1098,7 +1201,7 @@ async function existingManagedSkillArtifacts(skillsDir, skillNames, platform) {
 async function configureQoder(cwd, opts = {}) {
   const platform = "qoder";
   const meta = resolvePlatformMeta(cwd, platform);
-  const ctx = withInstallPaths(cwd, meta.templateContext);
+  const ctx = await withProjectInstallPaths(cwd, meta.templateContext, opts.projectId);
   const dest = path12.join(cwd, ctx.platform_config_dir);
   const hookConfigPath = path12.join(cwd, meta.hookConfigFile);
   const artifacts = [];
@@ -1149,17 +1252,22 @@ var CONFIGURATORS = {
 };
 
 // src/commands/install-harness.ts
-async function configurePlatformsForDir(targetDir, platforms, boundary) {
+async function configurePlatformsForDir(targetDir, platforms, opts = {}) {
   const artifacts = [];
   for (const platform of platforms) {
-    artifacts.push(...await CONFIGURATORS[platform](targetDir, { supermodule: boundary }));
+    artifacts.push(...await CONFIGURATORS[platform](targetDir, opts));
   }
   return artifacts;
 }
 async function installHarnessToDir(targetDir, platforms, ctx) {
-  const artifacts = await configurePlatformsForDir(targetDir, platforms, boundaryFromContext(ctx));
+  const projectId = createProjectId();
+  const artifacts = await configurePlatformsForDir(targetDir, platforms, {
+    supermodule: boundaryFromContext(ctx),
+    projectId
+  });
   await writeRuntimeScaffold(targetDir, platforms, {
-    supermodule: supermoduleConfigFromContext(ctx)
+    supermodule: supermoduleConfigFromContext(ctx),
+    projectId
   });
   await writeInstallManifest(targetDir, {
     harnessVersion: VERSION,
@@ -1172,6 +1280,7 @@ async function installHarnessToDir(targetDir, platforms, ctx) {
     legacyMissingHarnessFiles: ctx.legacyMissingHarnessFiles
   });
   await ensureEasyCodingSessionsIgnored(targetDir);
+  await ensureHookBytecodeIgnored(targetDir);
   return artifacts;
 }
 function supermoduleConfigFromContext(ctx) {
@@ -1653,14 +1762,13 @@ async function addAgent(opts) {
     const toInstall = platforms.filter((platform) => !config.agents.includes(platform));
     const agents = [...config.agents, ...toInstall];
     if (toInstall.length > 0) {
-      const artifacts = await configurePlatformsForDir(
-        target.dir,
-        toInstall,
-        target.boundary
-      );
-      await writeRuntimeScaffold(target.dir, agents, {
+      const projectId = await writeRuntimeScaffold(target.dir, agents, {
         supermodule: target.supermodule
       });
+      const artifacts = await configurePlatformsForDir(target.dir, toInstall, {
+        supermodule: target.boundary,
+        projectId
+      });
       await writeInstallManifest(target.dir, {
         harnessVersion: VERSION,
         agents: toInstall,
@@ -1668,6 +1776,7 @@ async function addAgent(opts) {
         mode: "merge"
       });
       await ensureEasyCodingSessionsIgnored(target.dir);
+      await ensureHookBytecodeIgnored(target.dir);
       await addAgentsToConfig(target.configPath, toInstall);
       await setPendingInitSince(target.dir, VERSION);
       installedLabels.push(`${target.label}: ${toInstall.join(", ")}`);
@@ -2757,23 +2866,24 @@ async function upgrade(opts) {
     }
   }
   for (const { target, config } of pending) {
-    const artifacts = await configurePlatformsForDir(
-      target.dir,
-      config.agents,
-      target.boundary
-    );
-    await writeRuntimeScaffold(target.dir, config.agents, {
+    const projectId = await writeRuntimeScaffold(target.dir, config.agents, {
       supermodule: target.supermodule
     });
+    const artifacts = await configurePlatformsForDir(target.dir, config.agents, {
+      supermodule: target.boundary,
+      projectId
+    });
     await writeInstallManifest(target.dir, {
       harnessVersion: VERSION,
       agents: config.agents,
       artifacts
     });
     await ensureEasyCodingSessionsIgnored(target.dir);
+    await ensureHookBytecodeIgnored(target.dir);
     await updateHarnessVersion(target.configPath, VERSION);
     await updateSupermoduleConfig(target.configPath, target.supermodule);
     await setPendingInitSince(target.dir, VERSION);
+    await stripInitTaskProjectPath(target.dir);
   }
   if (parentTopologyRefresh) {
     await refreshSupermoduleParent(
@@ -2811,15 +2921,19 @@ async function resolvePendingUpgradeTargets(targets) {
         `${target.label} harness version ${installedVersion} is newer than CLI ${VERSION}. Update the CLI first.`
       );
     }
-    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config.agents)) {
+    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config)) {
       pending.push({ target, config });
     }
   }
   return pending;
 }
-async function needsHookConfigRefresh(target, agents) {
+async function needsHookConfigRefresh(target, config) {
+  const projectId = typeof config.project?.id === "string" ? config.project.id.trim() : "";
+  if (!projectId) {
+    return true;
+  }
   const manifest = await readInstallManifest(target.dir);
-  for (const agent of agents) {
+  for (const agent of config.agents) {
     const meta = resolvePlatformMeta(target.dir, agent);
     const configPath2 = path22.join(target.dir, meta.hookConfigFile);
     const content = await readTextIfExists(configPath2);
@@ -2834,7 +2948,7 @@ async function needsHookConfigRefresh(target, agents) {
     }
     const commandsByEvent = collectHookCommandsByEvent(parsed.hooks);
     const commands = [...commandsByEvent.values()].flat();
-    const expectedRegistrations = expectedHookRegistrations(target.dir, meta, agent);
+    const expectedRegistrations = expectedHookRegistrations(target.dir, meta, agent, projectId);
     const expectedCommandSet = new Set(
       expectedRegistrations.map((registration) => registration.command)
     );
@@ -2859,10 +2973,10 @@ async function needsHookConfigRefresh(target, agents) {
   }
   return false;
 }
-function expectedHookRegistrations(cwd, meta, platform) {
+function expectedHookRegistrations(cwd, meta, platform, projectId) {
   return EXPECTED_HOOK_REGISTRATION_SCRIPTS[platform].map(({ event, scriptName }) => ({
     event,
-    command: renderHookCommand(cwd, meta.templateContext, scriptName)
+    command: renderHookCommand(cwd, meta.templateContext, scriptName, process.platform, projectId)
   }));
 }
 function hasExpectedHookRegistrations(commandsByEvent, expectedRegistrations) {