@pzy560117/codex-harness 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# Codex Harness CLI
+
+Thin CLI for downloading a Codex Harness package source and invoking the PowerShell runtime/install scripts.
+
+## Commands
+
+```powershell
+harness init
+harness doctor
+harness verify
+harness run
+```
+
+## 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

@@ -0,0 +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);
+});

package/lib/commands/doctor.js

@@ -0,0 +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 });
+}

package/lib/commands/init.js

@@ -0,0 +1,99 @@
+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, "..", "..", "..");
+}
+
+export async function initCommand(options) {
+  const localPackageRoot = getLocalPackageRoot();
+  const projectRoot = detectProjectRoot(options.projectRoot);
+  const userProfile = process.env.USERPROFILE;
+  if (!userProfile) {
+    throw new Error("USERPROFILE is not set.");
+  }
+
+  const packageRoot = resolvePackageSourceRoot({
+    packageRoot: localPackageRoot,
+    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) {
+    args.push("-InitGitIfNeeded");
+  }
+
+  if (options.plan) {
+    args.push("-Plan");
+  }
+
+  await invokePowerShellScript(scriptPath, args, { cwd: effectivePackageRoot });
+}

package/lib/commands/run.js

@@ -0,0 +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 });
+}

package/lib/commands/verify.js

@@ -0,0 +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 });
+}

package/lib/main.js

@@ -0,0 +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]
+`);
+}

package/lib/powershell/find-powershell.js

@@ -0,0 +1,3 @@
+export function findPowerShell() {
+  return "powershell";
+}

package/lib/powershell/invoke-script.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+import { findPowerShell } from "./find-powershell.js";
+
+export function invokePowerShellScript(scriptPath, args = [], options = {}) {
+  const powershell = findPowerShell();
+  const commandArgs = [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-File",
+    scriptPath,
+    ...args
+  ];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(powershell, commandArgs, {
+      cwd: options.cwd,
+      stdio: "inherit"
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      const error = new Error(`PowerShell script failed with exit code ${code}: ${scriptPath}`);
+      error.exitCode = code || 1;
+      reject(error);
+    });
+  });
+}

package/lib/project/assert-initialized.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function assertInitialized(projectRoot) {
+  const requiredPaths = [
+    "tools/harness/doctor.ps1",
+    "tools/harness/verify.ps1",
+    "tools/harness/codex-loop.ps1",
+    "task.json"
+  ];
+
+  for (const relativePath of requiredPaths) {
+    const fullPath = path.join(projectRoot, relativePath);
+    if (!fs.existsSync(fullPath)) {
+      const error = new Error(`Project is not initialized. Missing: ${relativePath}. Run 'harness init'.`);
+      error.exitCode = 2;
+      throw error;
+    }
+  }
+}

package/lib/project/detect-project-root.js

@@ -0,0 +1,5 @@
+import process from "node:process";
+
+export function detectProjectRoot(projectRoot) {
+  return projectRoot || process.cwd();
+}

package/lib/release/cache-layout.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { RELEASE_MANIFEST_FILE } from "./release-manifest.js";
+
+export function getPackageCacheRoot(userProfile) {
+  return path.win32.join(userProfile, ".codex", "packages", "codex-harness");
+}
+
+export function getPackageInstallRoot(userProfile, version) {
+  return path.win32.join(getPackageCacheRoot(userProfile), version);
+}
+
+export function getUserPackageLockPath(userProfile) {
+  return path.win32.join(getPackageCacheRoot(userProfile), "package.lock.json");
+}
+
+export function getReleaseAssetNames(version) {
+  return {
+    zip: `codex-harness-${version}-win.zip`,
+    sha256: `codex-harness-${version}-win.sha256`,
+    manifest: RELEASE_MANIFEST_FILE
+  };
+}
+
+export function getDownloadedZipPath(userProfile, version) {
+  return path.win32.join(getPackageCacheRoot(userProfile), getReleaseAssetNames(version).zip);
+}
+
+export function getDownloadedShaPath(userProfile, version) {
+  return path.win32.join(getPackageCacheRoot(userProfile), getReleaseAssetNames(version).sha256);
+}
+
+export function getDownloadedManifestPath(userProfile, version) {
+  return path.win32.join(getPackageCacheRoot(userProfile), `release-manifest-${version}.json`);
+}

package/lib/release/download-release.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+
+export async function downloadToFile(url, destinationPath) {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "codex-harness-cli"
+    },
+    redirect: "follow"
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+
+  await mkdir(path.dirname(destinationPath), { recursive: true });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(destinationPath, buffer);
+  return destinationPath;
+}
+
+export function fileExists(pathLike) {
+  return fs.existsSync(pathLike);
+}

package/lib/release/package-source-layout.js

@@ -0,0 +1,13 @@
+export const RELEASE_SOURCE_ENTRIES = [
+  "AGENTS.md",
+  "README.md",
+  "PACKAGE.md",
+  "install-manifest.json",
+  "install-manifest.schema.json",
+  "tools/install",
+  "docs/codex-harness-engineering/templates"
+];
+
+export function shouldIncludeReleaseSource(relativePath) {
+  return RELEASE_SOURCE_ENTRIES.includes(relativePath);
+}

package/lib/release/release-config.js

@@ -0,0 +1,6 @@
+export const DEFAULT_RELEASE_OWNER = "pzy560117";
+export const DEFAULT_RELEASE_REPO = "codex-herness-agent";
+
+export function buildReleaseAssetUrl({ owner = DEFAULT_RELEASE_OWNER, repo = DEFAULT_RELEASE_REPO, version, assetName }) {
+  return `https://github.com/${owner}/${repo}/releases/download/v${version}/${assetName}`;
+}

package/lib/release/release-manifest.js

@@ -0,0 +1,76 @@
+export const RELEASE_MANIFEST_FILE = "release-manifest.json";
+export const DEFAULT_RELEASE_PLATFORM = "win32-x64";
+
+export function createReleaseManifest({
+  packageName = "codex-harness",
+  version,
+  zipFile,
+  sha256File,
+  sha256,
+  size,
+  releaseTag = `v${version}`,
+  generatedAt,
+  owner = "",
+  repo = "",
+  sourceCommit = ""
+}) {
+  if (!version) {
+    throw new Error("release manifest version is required.");
+  }
+
+  if (!zipFile || !sha256File || !sha256) {
+    throw new Error("release manifest assets are incomplete.");
+  }
+
+  return {
+    package: packageName,
+    version,
+    releaseTag,
+    generatedAt: generatedAt ?? new Date().toISOString(),
+    source: {
+      owner,
+      repo,
+      commit: sourceCommit
+    },
+    platforms: {
+      [DEFAULT_RELEASE_PLATFORM]: {
+        zip: zipFile,
+        sha256File,
+        sha256,
+        size
+      }
+    }
+  };
+}
+
+export function getReleasePlatformEntry(manifest, platform = DEFAULT_RELEASE_PLATFORM) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error("release manifest is missing.");
+  }
+
+  if (String(manifest.package || "").trim() !== "codex-harness") {
+    throw new Error("release manifest package must be codex-harness.");
+  }
+
+  const version = String(manifest.version || "").trim();
+  if (!version) {
+    throw new Error("release manifest version is missing.");
+  }
+
+  const entry = manifest.platforms?.[platform];
+  if (!entry) {
+    throw new Error(`release manifest does not include platform ${platform}.`);
+  }
+
+  if (!entry.zip || !entry.sha256File || !entry.sha256) {
+    throw new Error(`release manifest platform ${platform} is incomplete.`);
+  }
+
+  return {
+    version,
+    zip: entry.zip,
+    sha256File: entry.sha256File,
+    sha256: entry.sha256,
+    size: entry.size ?? null
+  };
+}

package/lib/release/resolve-package-source.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+
+export function resolvePackageSourceRoot({ packageRoot, cachedRoot, fsLike }) {
+  const existsSync = fsLike?.existsSync ?? (() => false);
+  const localScript = path.win32.join(packageRoot, "tools", "install", "install-agent.ps1");
+  if (existsSync(localScript)) {
+    return packageRoot;
+  }
+
+  const cachedScript = path.win32.join(cachedRoot, "tools", "install", "install-agent.ps1");
+  if (existsSync(cachedScript)) {
+    return cachedRoot;
+  }
+
+  return "";
+}

package/lib/release/resolve-version.js

@@ -0,0 +1,26 @@
+import { DEFAULT_RELEASE_OWNER, DEFAULT_RELEASE_REPO } from "./release-config.js";
+
+export async function resolveVersion(requestedVersion) {
+  if (requestedVersion && requestedVersion !== "latest") {
+    return requestedVersion;
+  }
+
+  const apiUrl = `https://api.github.com/repos/${DEFAULT_RELEASE_OWNER}/${DEFAULT_RELEASE_REPO}/releases/latest`;
+  const response = await fetch(apiUrl, {
+    headers: {
+      "User-Agent": "codex-harness-cli"
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to resolve latest release version: ${response.status} ${response.statusText}`);
+  }
+
+  const json = await response.json();
+  const tag = String(json.tag_name || "").trim();
+  if (!tag) {
+    throw new Error("Latest release did not include tag_name.");
+  }
+
+  return tag.startsWith("v") ? tag.slice(1) : tag;
+}

package/lib/release/unpack-zip.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { invokePowerShellScript } from "../powershell/invoke-script.js";
+
+export async function unpackZip(zipPath, destinationRoot) {
+  if (!fs.existsSync(destinationRoot)) {
+    fs.mkdirSync(destinationRoot, { recursive: true });
+  }
+
+  const scriptPath = path.join(destinationRoot, "__expand-archive.ps1");
+  fs.writeFileSync(
+    scriptPath,
+    `Expand-Archive -LiteralPath '${zipPath.replace(/'/g, "''")}' -DestinationPath '${destinationRoot.replace(/'/g, "''")}' -Force`,
+    "utf8"
+  );
+
+  try {
+    await invokePowerShellScript(scriptPath, [], { cwd: destinationRoot });
+  } finally {
+    if (fs.existsSync(scriptPath)) {
+      fs.unlinkSync(scriptPath);
+    }
+  }
+}

package/lib/release/verify-sha256.js

@@ -0,0 +1,16 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+
+export async function verifyFileSha256(filePath, shaFilePath, expectedSha256 = "") {
+  const fileBuffer = await fs.readFile(filePath);
+  const expected = (await fs.readFile(shaFilePath, "utf8")).trim().split(/\s+/)[0];
+  const actual = crypto.createHash("sha256").update(fileBuffer).digest("hex");
+
+  if (expected.toLowerCase() !== actual.toLowerCase()) {
+    throw new Error(`SHA256 mismatch for ${filePath}`);
+  }
+
+  if (expectedSha256 && expectedSha256.toLowerCase() !== actual.toLowerCase()) {
+    throw new Error(`Release manifest SHA256 mismatch for ${filePath}`);
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pzy560117/codex-harness",
+  "version": "0.1.0",
+  "description": "Codex Harness installer and project runtime CLI",
+  "type": "module",
+  "bin": {
+    "harness": "./bin/harness.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  }
+}