@pzy560117/codex-harness 0.1.3 → 0.1.4

package/README.md

@@ -1,27 +1,164 @@
-# Codex Harness CLI
-
-Thin CLI for invoking the PowerShell runtime/install scripts. Published npm packages embed the package source directly and only fall back to GitHub Release downloads when the embedded package source is unavailable.
-
-## Commands
-
-```powershell
-harness init
-harness doctor
-harness verify
-harness run
-```
-
-如果目标项目准备在 Codex app 中使用 `/goal` 长时间推进，安装完成后优先阅读：
-
-- `docs/codex-harness-engineering/goal-harness-integration-guide.md`
-- `docs/codex-harness-engineering/examples/goal-templates.md`
-
-`/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook` 主链。
-
-## Release Assets
-
-GitHub Release assets are built from the repository package source with:
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
-```
+# Codex Harness CLI
+
+Thin CLI for initializing and driving a Codex Harness project from npm. The published package embeds its own `package-source/` and only falls back to GitHub Release assets when the embedded package source is unavailable.
+
+## Install
+
+### Use with `npx`
+
+适合一次性初始化或临时验证：
+
+```powershell
+npx @pzy560117/codex-harness init
+```
+
+### Global install
+
+适合长期在本机重复使用：
+
+```powershell
+npm install -g @pzy560117/codex-harness
+```
+
+安装后命令名是：
+
+```powershell
+harness
+```
+
+## Quick Start
+
+### 1. 初始化当前项目
+
+在目标项目根目录执行：
+
+```powershell
+harness init
+```
+
+如果当前目录还不是 Git 仓库，CLI 会调用安装器并按默认策略初始化项目所需的 Harness runtime。
+
+### 2. 运行 doctor
+
+```powershell
+harness doctor
+```
+
+这会检查：
+
+- runtime 文件是否齐备
+- `task.json` 是否可读
+- install manifest / lock / config 是否一致
+- PowerShell / prompts / rules / trace schema 是否健康
+
+### 3. 运行 verify
+
+```powershell
+harness verify
+```
+
+这是包级 sanity check，至少会做 `git diff --check`，并校验 hooks、PowerShell 语法和 package freshness。
+
+### 4. 跑 driver
+
+```powershell
+harness run --run-until-done
+```
+
+这会转调项目里的：
+
+- `tools/harness/codex-loop.ps1`
+
+主执行链仍然是：
+
+```text
+task.json
+  -> codex-loop.ps1
+  -> review / test / trace / commit
+```
+
+## Commands
+
+```powershell
+harness init [--version <version>] [--project-root <path>] [--vendor] [--force] [--init-git] [--plan]
+harness doctor [--project-root <path>]
+harness verify [--project-root <path>]
+harness run [--project-root <path>] [--task-file <path>] [--run-until-done]
+```
+
+## Common Usage
+
+### 初始化到指定目录
+
+```powershell
+harness init --project-root E:\repo\my-project
+```
+
+### 只看安装计划，不改文件
+
+```powershell
+harness init --plan
+```
+
+### 钉住远程版本初始化
+
+```powershell
+npx @pzy560117/codex-harness init --version 0.1.4
+```
+
+适合 release smoke 或回滚到某个已发布版本。
+
+### 对已初始化项目跑检查
+
+```powershell
+harness doctor --project-root E:\repo\my-project
+harness verify --project-root E:\repo\my-project
+```
+
+### 指定任务文件运行
+
+```powershell
+harness run --task-file custom-task.json --run-until-done
+```
+
+## What `init` installs
+
+默认 `init` 会安装 project scope 的运行面，包括：
+
+- `AGENTS.md`
+- `.codex/`
+- `tools/harness/`
+- `docs/ai/`
+- `docs/spec/`
+- `.agents/skills`
+- `.agents/workflows`
+- `.codex-harness/state|locks|manifests`
+
+安装完成后，建议优先做三件事：
+
+1. 裁剪 `docs/ai/repo-map.md`
+2. 裁剪 `docs/ai/architecture-brief.md`
+3. 运行 `harness doctor` 和 `harness verify`
+
+## `/goal` usage
+
+如果目标项目准备在 Codex app 中使用 `/goal` 长时间推进，安装完成后优先阅读：
+
+- `docs/codex-harness-engineering/goal-harness-integration-guide.md`
+- `docs/codex-harness-engineering/examples/goal-templates.md`
+
+`/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook` 主链。
+
+## Windows notes
+
+- CLI 会优先尝试 `pwsh`，回退到 `powershell`。
+- 所有真正的安装/验证/运行动作最后都回到 PowerShell 脚本。
+- 如果企业环境限制脚本执行，请优先检查 PowerShell Execution Policy 和企业代理。
+
+## Release Assets
+
+GitHub Release assets are built from the repository package source with:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
+```

package/bin/harness.js

@@ -1,7 +1,7 @@
-#!/usr/bin/env node
-import { runCli } from "../lib/main.js";
-
-runCli(process.argv).catch((error) => {
-  console.error(error?.message || String(error));
-  process.exit(error?.exitCode || 1);
-});
+#!/usr/bin/env node
+import { runCli } from "../lib/main.js";
+
+runCli(process.argv).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exit(error?.exitCode || 1);
+});

package/lib/commands/doctor.js

@@ -1,12 +1,12 @@
-import path from "node:path";
-
-import { detectProjectRoot } from "../project/detect-project-root.js";
-import { assertInitialized } from "../project/assert-initialized.js";
-import { invokePowerShellScript } from "../powershell/invoke-script.js";
-
-export async function doctorCommand(options) {
-  const projectRoot = detectProjectRoot(options.projectRoot);
-  assertInitialized(projectRoot);
-  const scriptPath = path.join(projectRoot, "tools", "harness", "doctor.ps1");
-  await invokePowerShellScript(scriptPath, ["-ProjectRoot", projectRoot], { cwd: projectRoot });
-}
+import path from "node:path";
+
+import { detectProjectRoot } from "../project/detect-project-root.js";
+import { assertInitialized } from "../project/assert-initialized.js";
+import { invokePowerShellScript } from "../powershell/invoke-script.js";
+
+export async function doctorCommand(options) {
+  const projectRoot = detectProjectRoot(options.projectRoot);
+  assertInitialized(projectRoot);
+  const scriptPath = path.join(projectRoot, "tools", "harness", "doctor.ps1");
+  await invokePowerShellScript(scriptPath, ["-ProjectRoot", projectRoot], { cwd: projectRoot });
+}

package/lib/commands/init.js

@@ -1,105 +1,105 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-
-import { detectProjectRoot } from "../project/detect-project-root.js";
-import { invokePowerShellScript } from "../powershell/invoke-script.js";
-import {
-  getDownloadedManifestPath,
-  getDownloadedShaPath,
-  getDownloadedZipPath,
-  getPackageInstallRoot,
-  getReleaseAssetNames
-} from "../release/cache-layout.js";
-import { downloadToFile, fileExists } from "../release/download-release.js";
-import { buildReleaseAssetUrl } from "../release/release-config.js";
-import { getReleasePlatformEntry } from "../release/release-manifest.js";
-import { resolvePackageSourceRoot } from "../release/resolve-package-source.js";
-import { resolveVersion } from "../release/resolve-version.js";
-import { unpackZip } from "../release/unpack-zip.js";
-import { verifyFileSha256 } from "../release/verify-sha256.js";
-
-function getLocalPackageRoot() {
-  return path.resolve(import.meta.dirname, "..", "..", "..");
-}
-
-function getCliPackageRoot() {
-  return path.resolve(import.meta.dirname, "..", "..");
-}
-
-export async function initCommand(options) {
-  const localPackageRoot = getLocalPackageRoot();
-  const embeddedPackageRoot = path.join(getCliPackageRoot(), "package-source");
-  const projectRoot = detectProjectRoot(options.projectRoot);
-  const userProfile = process.env.USERPROFILE;
-  if (!userProfile) {
-    throw new Error("USERPROFILE is not set.");
-  }
-
-  const packageRoot = resolvePackageSourceRoot({
-    packageRoot: localPackageRoot,
-    embeddedRoot: embeddedPackageRoot,
-    cachedRoot: "",
-    fsLike: { existsSync: fileExists }
-  });
-
-  let effectivePackageRoot = packageRoot;
-  if (effectivePackageRoot === "") {
-    const version = await resolveVersion(options.version);
-    const manifestPath = getDownloadedManifestPath(userProfile, version);
-    const fallbackAssets = getReleaseAssetNames(version);
-
-    if (!fileExists(manifestPath)) {
-      await downloadToFile(buildReleaseAssetUrl({ version, assetName: fallbackAssets.manifest }), manifestPath);
-    }
-
-    const releaseManifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-    const releaseAssets = getReleasePlatformEntry(releaseManifest);
-    if (releaseAssets.version !== version) {
-      throw new Error(`Release manifest version mismatch: expected ${version}, got ${releaseAssets.version}`);
-    }
-
-    const packageInstallRoot = getPackageInstallRoot(userProfile, releaseAssets.version);
-    const zipPath = getDownloadedZipPath(userProfile, releaseAssets.version);
-    const shaPath = getDownloadedShaPath(userProfile, releaseAssets.version);
-
-    if (!fileExists(zipPath)) {
-      await downloadToFile(buildReleaseAssetUrl({ version, assetName: releaseAssets.zip }), zipPath);
-    }
-
-    if (!fileExists(shaPath)) {
-      await downloadToFile(buildReleaseAssetUrl({ version, assetName: releaseAssets.sha256File }), shaPath);
-    }
-
-    await verifyFileSha256(zipPath, shaPath, releaseAssets.sha256);
-
-    if (!fileExists(path.join(packageInstallRoot, "tools", "install", "install-agent.ps1"))) {
-      await unpackZip(zipPath, packageInstallRoot);
-    }
-
-    effectivePackageRoot = packageInstallRoot;
-  }
-
-  const scriptPath = path.join(effectivePackageRoot, "tools", "install", "install-agent.ps1");
-  const args = ["-ProjectRoot", projectRoot];
-
-  if (options.vendor) {
-    args.push("-Scope", "vendor");
-  } else {
-    args.push("-Scope", "project");
-  }
-
-  if (options.force) {
-    args.push("-Force");
-  }
-
-  if (options.initGit !== false) {
-    args.push("-InitGitIfNeeded");
-  }
-
-  if (options.plan) {
-    args.push("-Plan");
-  }
-
-  await invokePowerShellScript(scriptPath, args, { cwd: effectivePackageRoot });
-}
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { detectProjectRoot } from "../project/detect-project-root.js";
+import { invokePowerShellScript } from "../powershell/invoke-script.js";
+import {
+  getDownloadedManifestPath,
+  getDownloadedShaPath,
+  getDownloadedZipPath,
+  getPackageInstallRoot,
+  getReleaseAssetNames
+} from "../release/cache-layout.js";
+import { downloadToFile, fileExists } from "../release/download-release.js";
+import { buildReleaseAssetUrl } from "../release/release-config.js";
+import { getReleasePlatformEntry } from "../release/release-manifest.js";
+import { resolvePackageSourceRoot } from "../release/resolve-package-source.js";
+import { resolveVersion } from "../release/resolve-version.js";
+import { unpackZip } from "../release/unpack-zip.js";
+import { verifyFileSha256 } from "../release/verify-sha256.js";
+
+function getLocalPackageRoot() {
+  return path.resolve(import.meta.dirname, "..", "..", "..");
+}
+
+function getCliPackageRoot() {
+  return path.resolve(import.meta.dirname, "..", "..");
+}
+
+export async function initCommand(options) {
+  const localPackageRoot = getLocalPackageRoot();
+  const embeddedPackageRoot = path.join(getCliPackageRoot(), "package-source");
+  const projectRoot = detectProjectRoot(options.projectRoot);
+  const userProfile = process.env.USERPROFILE;
+  if (!userProfile) {
+    throw new Error("USERPROFILE is not set.");
+  }
+
+  const packageRoot = resolvePackageSourceRoot({
+    packageRoot: localPackageRoot,
+    embeddedRoot: embeddedPackageRoot,
+    cachedRoot: "",
+    fsLike: { existsSync: fileExists }
+  });
+
+  let effectivePackageRoot = packageRoot;
+  if (effectivePackageRoot === "") {
+    const version = await resolveVersion(options.version);
+    const manifestPath = getDownloadedManifestPath(userProfile, version);
+    const fallbackAssets = getReleaseAssetNames(version);
+
+    if (!fileExists(manifestPath)) {
+      await downloadToFile(buildReleaseAssetUrl({ version, assetName: fallbackAssets.manifest }), manifestPath);
+    }
+
+    const releaseManifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    const releaseAssets = getReleasePlatformEntry(releaseManifest);
+    if (releaseAssets.version !== version) {
+      throw new Error(`Release manifest version mismatch: expected ${version}, got ${releaseAssets.version}`);
+    }
+
+    const packageInstallRoot = getPackageInstallRoot(userProfile, releaseAssets.version);
+    const zipPath = getDownloadedZipPath(userProfile, releaseAssets.version);
+    const shaPath = getDownloadedShaPath(userProfile, releaseAssets.version);
+
+    if (!fileExists(zipPath)) {
+      await downloadToFile(buildReleaseAssetUrl({ version, assetName: releaseAssets.zip }), zipPath);
+    }
+
+    if (!fileExists(shaPath)) {
+      await downloadToFile(buildReleaseAssetUrl({ version, assetName: releaseAssets.sha256File }), shaPath);
+    }
+
+    await verifyFileSha256(zipPath, shaPath, releaseAssets.sha256);
+
+    if (!fileExists(path.join(packageInstallRoot, "tools", "install", "install-agent.ps1"))) {
+      await unpackZip(zipPath, packageInstallRoot);
+    }
+
+    effectivePackageRoot = packageInstallRoot;
+  }
+
+  const scriptPath = path.join(effectivePackageRoot, "tools", "install", "install-agent.ps1");
+  const args = ["-ProjectRoot", projectRoot];
+
+  if (options.vendor) {
+    args.push("-Scope", "vendor");
+  } else {
+    args.push("-Scope", "project");
+  }
+
+  if (options.force) {
+    args.push("-Force");
+  }
+
+  if (options.initGit !== false) {
+    args.push("-InitGitIfNeeded");
+  }
+
+  if (options.plan) {
+    args.push("-Plan");
+  }
+
+  await invokePowerShellScript(scriptPath, args, { cwd: effectivePackageRoot });
+}

package/lib/commands/run.js

@@ -1,22 +1,22 @@
-import path from "node:path";
-
-import { detectProjectRoot } from "../project/detect-project-root.js";
-import { assertInitialized } from "../project/assert-initialized.js";
-import { invokePowerShellScript } from "../powershell/invoke-script.js";
-
-export async function runCommand(options) {
-  const projectRoot = detectProjectRoot(options.projectRoot);
-  assertInitialized(projectRoot);
-  const scriptPath = path.join(projectRoot, "tools", "harness", "codex-loop.ps1");
-  const args = ["-ProjectRoot", projectRoot];
-
-  if (options.taskFile) {
-    args.push("-TaskFile", options.taskFile);
-  }
-
-  if (options.runUntilDone) {
-    args.push("-RunUntilDone");
-  }
-
-  await invokePowerShellScript(scriptPath, args, { cwd: projectRoot });
-}
+import path from "node:path";
+
+import { detectProjectRoot } from "../project/detect-project-root.js";
+import { assertInitialized } from "../project/assert-initialized.js";
+import { invokePowerShellScript } from "../powershell/invoke-script.js";
+
+export async function runCommand(options) {
+  const projectRoot = detectProjectRoot(options.projectRoot);
+  assertInitialized(projectRoot);
+  const scriptPath = path.join(projectRoot, "tools", "harness", "codex-loop.ps1");
+  const args = ["-ProjectRoot", projectRoot];
+
+  if (options.taskFile) {
+    args.push("-TaskFile", options.taskFile);
+  }
+
+  if (options.runUntilDone) {
+    args.push("-RunUntilDone");
+  }
+
+  await invokePowerShellScript(scriptPath, args, { cwd: projectRoot });
+}

package/lib/commands/verify.js

@@ -1,12 +1,12 @@
-import path from "node:path";
-
-import { detectProjectRoot } from "../project/detect-project-root.js";
-import { assertInitialized } from "../project/assert-initialized.js";
-import { invokePowerShellScript } from "../powershell/invoke-script.js";
-
-export async function verifyCommand(options) {
-  const projectRoot = detectProjectRoot(options.projectRoot);
-  assertInitialized(projectRoot);
-  const scriptPath = path.join(projectRoot, "tools", "harness", "verify.ps1");
-  await invokePowerShellScript(scriptPath, ["-ProjectRoot", projectRoot], { cwd: projectRoot });
-}
+import path from "node:path";
+
+import { detectProjectRoot } from "../project/detect-project-root.js";
+import { assertInitialized } from "../project/assert-initialized.js";
+import { invokePowerShellScript } from "../powershell/invoke-script.js";
+
+export async function verifyCommand(options) {
+  const projectRoot = detectProjectRoot(options.projectRoot);
+  assertInitialized(projectRoot);
+  const scriptPath = path.join(projectRoot, "tools", "harness", "verify.ps1");
+  await invokePowerShellScript(scriptPath, ["-ProjectRoot", projectRoot], { cwd: projectRoot });
+}

package/lib/main.js

@@ -1,62 +1,62 @@
-import { initCommand } from "./commands/init.js";
-import { doctorCommand } from "./commands/doctor.js";
-import { verifyCommand } from "./commands/verify.js";
-import { runCommand } from "./commands/run.js";
-
-function normalizeOptionName(name) {
-  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-
-export function parseCliArgs(argv) {
-  const args = [...argv].slice(2);
-  const command = args.shift() || "help";
-  const options = {};
-
-  while (args.length > 0) {
-    const token = args.shift();
-    if (!token.startsWith("--")) {
-      continue;
-    }
-
-    const rawName = token.slice(2);
-    const optionName = normalizeOptionName(rawName);
-    if (args.length === 0 || args[0].startsWith("--")) {
-      options[optionName] = true;
-      continue;
-    }
-
-    options[optionName] = args.shift();
-  }
-
-  return { command, options };
-}
-
-export async function runCli(argv) {
-  const { command, options } = parseCliArgs(argv);
-
-  switch (command) {
-    case "init":
-      return initCommand(options);
-    case "doctor":
-      return doctorCommand(options);
-    case "verify":
-      return verifyCommand(options);
-    case "run":
-      return runCommand(options);
-    case "help":
-    default:
-      printHelp();
-      return;
-  }
-}
-
-function printHelp() {
-  console.log(`Codex Harness CLI
-
-Usage:
-  harness init [--version <version>] [--project-root <path>] [--vendor] [--force] [--init-git] [--plan]
-  harness doctor [--project-root <path>]
-  harness verify [--project-root <path>]
-  harness run [--project-root <path>] [--task-file <path>] [--run-until-done]
-`);
-}
+import { initCommand } from "./commands/init.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { verifyCommand } from "./commands/verify.js";
+import { runCommand } from "./commands/run.js";
+
+function normalizeOptionName(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+export function parseCliArgs(argv) {
+  const args = [...argv].slice(2);
+  const command = args.shift() || "help";
+  const options = {};
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (!token.startsWith("--")) {
+      continue;
+    }
+
+    const rawName = token.slice(2);
+    const optionName = normalizeOptionName(rawName);
+    if (args.length === 0 || args[0].startsWith("--")) {
+      options[optionName] = true;
+      continue;
+    }
+
+    options[optionName] = args.shift();
+  }
+
+  return { command, options };
+}
+
+export async function runCli(argv) {
+  const { command, options } = parseCliArgs(argv);
+
+  switch (command) {
+    case "init":
+      return initCommand(options);
+    case "doctor":
+      return doctorCommand(options);
+    case "verify":
+      return verifyCommand(options);
+    case "run":
+      return runCommand(options);
+    case "help":
+    default:
+      printHelp();
+      return;
+  }
+}
+
+function printHelp() {
+  console.log(`Codex Harness CLI
+
+Usage:
+  harness init [--version <version>] [--project-root <path>] [--vendor] [--force] [--init-git] [--plan]
+  harness doctor [--project-root <path>]
+  harness verify [--project-root <path>]
+  harness run [--project-root <path>] [--task-file <path>] [--run-until-done]
+`);
+}