coding-agent-harness 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.0.8
+
+- Preserve the executable bit for the packaged `dist/harness.mjs` npm bin
+  entry during dist builds and prepack.
+- Extend release observation checks to fail if the packed or installed
+  `harness` bin is not executable.
+- Add `migrate-structure --plan` to the dist and installed-package command
+  smoke matrix.
+
+## 1.0.7
+
+- Generate `harness init --add-npm-scripts` commands with
+  `npx --yes coding-agent-harness ...` so target projects can run Harness
+  scripts without adding a project dependency or relying on a global install.
+- Isolate the dist observation command matrix from local ignored docs by using
+  the minimal target-project fixture for target-facing commands.
+- Preserve the executable bit on the committed `dist/harness.mjs` CLI entry.
+
+## 1.0.6
+
+- Bump the npm package version after the 1.0.5 publication so the TypeScript
+  runtime-source migration can be published again.
+
 ## 1.0.5
 
 - Relicense the public package from MIT to AGPL-3.0-or-later.

package/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for helping improve Coding Agent Harness. This repository contains the pu
 
 ## Before You Start
 
-- Use Node.js 18 or newer. CI currently runs on Node.js 20.
+- Use Node.js 24 or newer. CI should run on the minimum supported line.
 - Install root dependencies with `npm install` from the repository root.
 - If you change `harness-gui`, also run `npm ci` inside `harness-gui/`.
 - Keep pull requests focused. Separate documentation, CLI/runtime, template, preset, and GUI work when the changes are independent.

package/dist/build-dist.mjs

@@ -43,6 +43,10 @@ export function buildRuntimeDist({ projectRoot = repoRoot, configPath = path.joi
         syncDirectory(buildOutDir, absoluteOutDir);
         fs.rmSync(buildOutDir, { recursive: true, force: true });
     }
+    restoreExecutableEntrypoints({
+        outDir: absoluteOutDir,
+        binRelativePaths: ["harness.mjs"],
+    });
     const files = collectFiles(absoluteOutDir).filter((file) => file.endsWith(".mjs")).sort();
     const relativeFiles = files.map((file) => toPosix(path.relative(absoluteOutDir, file)));
     const requiredFiles = [
@@ -126,6 +130,15 @@ function syncDirectory(sourceDir, targetDir) {
         fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
     }
 }
+function restoreExecutableEntrypoints({ outDir, binRelativePaths }) {
+    for (const relativePath of binRelativePaths) {
+        const file = path.join(outDir, relativePath);
+        if (!fs.existsSync(file))
+            continue;
+        const stat = fs.statSync(file);
+        fs.chmodSync(file, stat.mode | 0o755);
+    }
+}
 function toPosix(value) {
     return value.split(path.sep).join("/");
 }

package/dist/check-dist-observation.mjs

@@ -48,7 +48,10 @@ export function checkDistObservation({ projectRoot = defaultProjectRoot, runPack
             failures.push({ code: "pack-dry-run-failed", message: `npm pack dry-run failed\nSTDOUT:\n${pack.stdout}\nSTDERR:\n${pack.stderr}` });
         }
         else {
-            const packed = JSON.parse(pack.stdout)[0].files.map((file) => file.path).sort();
+            const packedEntries = JSON.parse(pack.stdout)[0].files;
+            const packed = packedEntries.map((file) => file.path).sort();
+            const packedModeByPath = new Map(packedEntries.map((file) => [file.path, file.mode]));
+            const distHarnessMode = packedModeByPath.get("dist/harness.mjs");
             observations.package = {
                 entryCount: packed.length,
                 hasDistHarness: packed.includes("dist/harness.mjs"),
@@ -57,11 +60,16 @@ export function checkDistObservation({ projectRoot = defaultProjectRoot, runPack
                 hasScriptsHarness: packed.includes("scripts/harness.mjs"),
                 hasScripts: packed.some((file) => file.startsWith("scripts/")),
                 hasTests: packed.some((file) => file.startsWith("tests/")),
+                distHarnessMode,
+                distHarnessExecutable: typeof distHarnessMode === "number" && Boolean(distHarnessMode & 0o111),
             };
             for (const required of ["dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
                 if (!packed.includes(required))
                     failures.push({ code: "packed-file-missing", file: required, message: `package missing ${required}` });
             }
+            if (!observations.package.distHarnessExecutable) {
+                failures.push({ code: "packed-bin-not-executable", file: "dist/harness.mjs", mode: distHarnessMode, message: "package bin dist/harness.mjs must be executable" });
+            }
             if (observations.package.hasScripts)
                 failures.push({ code: "package-includes-scripts", message: "package must not include scripts/** after historical shim deletion" });
             if (observations.package.hasTests)
@@ -127,12 +135,13 @@ function runMatrix(root, failures, commandMatrix) {
     const distHarness = path.join(root, "dist/harness.mjs");
     const matrix = [
         { id: "help", args: ["--help"] },
-        { id: "status", args: ["status", "--json", "."] },
-        { id: "task-list", args: ["task-list", "--json", "."] },
-        { id: "preset-list", args: ["preset", "list", "--json", "."] },
+        { id: "status", args: ["status", "--json", "examples/minimal-project"] },
+        { id: "task-list", args: ["task-list", "--json", "examples/minimal-project"] },
+        { id: "preset-list", args: ["preset", "list", "--json", "examples/minimal-project"] },
         { id: "source-check", args: ["check", "--profile", "source-package", "."] },
         { id: "target-check", args: ["check", "--profile", "target-project", "examples/minimal-project"] },
         { id: "migrate-plan", args: ["migrate-plan", "--json", "--limit", "20", "examples/minimal-project"] },
+        { id: "migrate-structure-plan", args: ["migrate-structure", "--plan", "--json", "examples/minimal-project"] },
         { id: "dashboard", args: ["dashboard", "--out-dir", path.join("tmp", `pr-27-observation-dashboard-${process.pid}`), "examples/minimal-project"] },
     ];
     for (const entry of matrix) {
@@ -211,11 +220,15 @@ function runInstalledPackageSmoke(root, failures, observations) {
     if (!pkg)
         return;
     const binTarget = fs.existsSync(bin) ? fs.readlinkSync(bin) : "";
+    const installedBinFile = path.join(packageRoot, "dist/harness.mjs");
+    const installedBinMode = fs.existsSync(installedBinFile) ? fs.statSync(installedBinFile).mode : undefined;
     observations.installSmoke = {
         nodeVersion,
         tempRoot,
         binTarget,
         bin: pkg.bin?.harness,
+        binMode: installedBinMode,
+        binExecutable: typeof installedBinMode === "number" && Boolean(installedBinMode & 0o111),
         postinstall: pkg.scripts?.postinstall,
         observeDist: pkg.scripts?.["observe:dist"],
         hasTests: fs.existsSync(path.join(packageRoot, "tests")),
@@ -229,6 +242,9 @@ function runInstalledPackageSmoke(root, failures, observations) {
     if (!binTarget.includes("dist/harness.mjs")) {
         failures.push({ code: "installed-bin-link-not-dist", message: `installed bin link does not target dist/harness.mjs: ${binTarget}` });
     }
+    if (!observations.installSmoke.binExecutable) {
+        failures.push({ code: "installed-bin-not-executable", file: "dist/harness.mjs", mode: installedBinMode, message: "installed package bin dist/harness.mjs must be executable" });
+    }
     for (const relative of ["dist/harness.mjs", "dist/postinstall.mjs", "dist/check-dist-observation.mjs"]) {
         if (!fs.existsSync(path.join(packageRoot, relative)))
             failures.push({ code: "installed-file-missing", file: relative, message: `installed package missing ${relative}` });
@@ -272,12 +288,13 @@ function runInstalledPackageSmoke(root, failures, observations) {
 function runInstalledMatrix(root, runtimeEnv, failures, steps) {
     const matrix = [
         { id: "installed-help", cwd: root, args: ["--help"] },
-        { id: "installed-status", cwd: root, args: ["status", "--json", "."] },
-        { id: "installed-task-list", cwd: root, args: ["task-list", "--json", "."] },
-        { id: "installed-preset-list", cwd: root, args: ["preset", "list", "--json", "."] },
+        { id: "installed-status", cwd: root, args: ["status", "--json", "examples/minimal-project"] },
+        { id: "installed-task-list", cwd: root, args: ["task-list", "--json", "examples/minimal-project"] },
+        { id: "installed-preset-list", cwd: root, args: ["preset", "list", "--json", "examples/minimal-project"] },
         { id: "installed-source-check", cwd: root, args: ["check", "--profile", "source-package", "."] },
         { id: "installed-target-check", cwd: root, args: ["check", "--profile", "target-project", "examples/minimal-project"] },
         { id: "installed-migrate-plan", cwd: root, args: ["migrate-plan", "--json", "--limit", "20", "examples/minimal-project"] },
+        { id: "installed-migrate-structure-plan", cwd: root, args: ["migrate-structure", "--plan", "--json", "examples/minimal-project"] },
         { id: "installed-dashboard", cwd: root, args: ["dashboard", "--out-dir", path.join("tmp", `pr-27-installed-observation-dashboard-${process.pid}`), "examples/minimal-project"] },
     ];
     for (const entry of matrix) {

package/dist/check-no-ts-nocheck.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceRoots = ["scripts", "tests"];
+const tsNocheckPattern = /^\s*\/\/\s*@ts-nocheck\b/;
+export function checkNoTsNocheck({ repoRoot = defaultRepoRoot, allowlistPath = path.join(repoRoot, "scripts/ts-nocheck-allowlist.json"), } = {}) {
+    const files = collectMtsFiles(repoRoot);
+    const allowlist = readAllowlist(allowlistPath);
+    const violations = [];
+    const observed = new Set();
+    for (const file of files) {
+        const absolutePath = path.join(repoRoot, file);
+        const lines = fs.readFileSync(absolutePath, "utf8").split(/\r?\n/);
+        const lineIndex = lines.findIndex((line) => tsNocheckPattern.test(line));
+        if (lineIndex === -1)
+            continue;
+        observed.add(file);
+        if (!allowlist.has(file)) {
+            violations.push({
+                code: "unlisted-ts-nocheck",
+                file,
+                line: lineIndex + 1,
+                message: `${file}:${lineIndex + 1} has @ts-nocheck but is not in scripts/ts-nocheck-allowlist.json`,
+            });
+        }
+    }
+    for (const file of allowlist) {
+        if (!observed.has(file)) {
+            violations.push({
+                code: "stale-ts-nocheck-allowlist",
+                file,
+                message: `${file} is listed in scripts/ts-nocheck-allowlist.json but no longer has @ts-nocheck`,
+            });
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+function collectMtsFiles(repoRoot) {
+    const files = [];
+    for (const root of sourceRoots) {
+        const absoluteRoot = path.join(repoRoot, root);
+        if (!fs.existsSync(absoluteRoot))
+            continue;
+        walk(absoluteRoot, files, repoRoot);
+    }
+    return files.sort();
+}
+function walk(current, files, repoRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        const name = path.basename(current);
+        if (name === "node_modules" || name === ".worktrees" || name === "tmp")
+            return;
+        for (const entry of fs.readdirSync(current))
+            walk(path.join(current, entry), files, repoRoot);
+        return;
+    }
+    if (stat.isFile() && current.endsWith(".mts")) {
+        files.push(path.relative(repoRoot, current).split(path.sep).join("/"));
+    }
+}
+function readAllowlist(allowlistPath) {
+    if (!allowlistPath || !fs.existsSync(allowlistPath))
+        return new Set();
+    const parsed = JSON.parse(fs.readFileSync(allowlistPath, "utf8"));
+    const files = normalizeAllowlistFiles(parsed);
+    return new Set(files);
+}
+function normalizeAllowlistFiles(parsed) {
+    if (Array.isArray(parsed))
+        return parsed.filter((value) => typeof value === "string");
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const files = parsed.files;
+    return Array.isArray(files) ? files.filter((value) => typeof value === "string") : [];
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const result = checkNoTsNocheck();
+    if (!result.ok) {
+        console.error(result.violations.map((violation) => violation.message).join("\n"));
+        process.exit(1);
+    }
+    console.log("No @ts-nocheck gate passed");
+}

package/dist/check-type-boundaries.mjs

@@ -6,24 +6,27 @@ import { fileURLToPath } from "node:url";
 const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourceRoots = ["scripts", "tests"];
 const importPattern = /\b(import|export)\s+(type\s+)?(?:[^'"]*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
-const tsEscapePattern = /@(ts-ignore|ts-expect-error)\b|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
-export function checkTypeBoundaries({ repoRoot = defaultRepoRoot } = {}) {
+const tsEscapePattern = /@(ts-ignore|ts-expect-error)\b|\bas\s+unknown\s+as\b|\bRecord\s*<\s*string\s*,\s*any\s*>|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
+export function checkTypeBoundaries({ repoRoot = defaultRepoRoot, escapeAllowlistPath = path.join(repoRoot, "scripts/type-escape-allowlist.json"), } = {}) {
     const files = collectSourceFiles(repoRoot);
     const violations = [];
+    const escapeAllowlist = readEscapeAllowlist(escapeAllowlistPath);
     for (const file of files) {
         const absolutePath = path.join(repoRoot, file);
         const content = fs.readFileSync(absolutePath, "utf8");
         const imports = parseImports(content);
-        if (file.endsWith(".ts")) {
+        if (file.endsWith(".ts") || file.endsWith(".mts")) {
             const lines = content.split(/\r?\n/);
             for (const [index, line] of lines.entries()) {
                 if (tsEscapePattern.test(line)) {
-                    violations.push({
+                    const violation = {
                         code: "ts-escape-hatch",
                         file,
                         line: index + 1,
                         message: `${file}:${index + 1} uses a TypeScript escape hatch that requires review`,
-                    });
+                    };
+                    if (!isEscapeAllowed(escapeAllowlist, violation))
+                        violations.push(violation);
                 }
             }
         }
@@ -127,7 +130,21 @@ function hasTypeScriptSourceExtension(filePath) {
     return typeof filePath === "string" && /\.(mts|ts)$/.test(filePath);
 }
 function isTypeOnlyTypeScriptImport(file, imported) {
-    return file.endsWith(".ts") && imported.kind === "import" && imported.typeOnly;
+    return (file.endsWith(".ts") || file.endsWith(".mts")) && imported.kind === "import" && imported.typeOnly;
+}
+function readEscapeAllowlist(allowlistPath) {
+    if (!allowlistPath || !fs.existsSync(allowlistPath))
+        return new Set();
+    const parsed = JSON.parse(fs.readFileSync(allowlistPath, "utf8"));
+    const entries = Array.isArray(parsed) ? parsed : parsed.escapes || [];
+    return new Set(entries.map((entry) => {
+        if (typeof entry === "string")
+            return entry;
+        return `${entry.file}:${entry.line}:${entry.code || "ts-escape-hatch"}`;
+    }));
+}
+function isEscapeAllowed(allowlist, violation) {
+    return allowlist.has(`${violation.file}:${violation.line}:${violation.code}`) || allowlist.has(`${violation.file}:${violation.line}`);
 }
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
     const result = checkTypeBoundaries();

package/dist/commands/preset-command.mjs

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import { checkPresetPackage, inspectPresetPackage, installPresetPackage, listPresetPackages, seedBundledPresets, uninstallPresetPackage, } from "../lib/harness-core.mjs";
+import { checkPresetPackage, inspectPresetPackage, installPresetPackage, listPresetPackages, seedBundledPresets, runPresetEntrypoint, uninstallPresetPackage, } from "../lib/harness-core.mjs";
 export function runPresetCommand({ args, takeFlag, targetArg }) {
     const subcommand = args.shift() || "list";
     const json = takeFlag("--json");
@@ -80,6 +80,20 @@ export function runPresetCommand({ args, takeFlag, targetArg }) {
             else
                 console.log(`${result.removed ? "Removed" : "Preset not installed"}: ${result.id}`);
         }
+        else if (subcommand === "run") {
+            const taskRef = takeOptionFromArgs(args, "--task", "");
+            const id = args.shift();
+            const entrypoint = args.shift();
+            if (!id)
+                throw new Error("Missing preset id");
+            if (!entrypoint)
+                throw new Error("Missing preset entrypoint");
+            const result = runPresetEntrypoint(id, entrypoint, { taskRef, targetInput: targetArg(), json });
+            if (json)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                console.log(`Preset run ${result.status}: ${result.preset}.${result.entrypoint} (${result.materialized.length} writes)`);
+        }
         else {
             throw new Error(`Unknown preset subcommand: ${subcommand}`);
         }
@@ -89,3 +103,11 @@ export function runPresetCommand({ args, takeFlag, targetArg }) {
         process.exit(1);
     }
 }
+function takeOptionFromArgs(args, name, fallback = "") {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return fallback;
+    const value = args[index + 1] || fallback;
+    args.splice(index, 2);
+    return value;
+}

package/dist/commands/task-command.mjs

@@ -128,7 +128,8 @@ export function runTaskCommand(command, { args, takeFlag, takeOption, targetArg
         const lesson = takeOption("--lesson", "");
         const search = takeOption("--search", "");
         const missingMaterials = takeFlag("--missing-materials");
-        const result = listLifecycleTasks(targetArg(), { state, moduleKey, queue, preset, review, lesson, search, missingMaterials });
+        const includeArchived = takeFlag("--include-archived");
+        const result = listLifecycleTasks(targetArg(), { state, moduleKey, queue, preset, review, lesson, search, missingMaterials, includeArchived });
         if (json) {
             console.log(JSON.stringify(result, null, 2));
         }

package/dist/harness.mjs

@@ -90,6 +90,7 @@ Usage:
   harness preset install <folder|zip|builtin-id> [--project] [--force] [--json] [target]
   harness preset seed [--project] [--force] [--dry-run] [--json] [target]
   harness preset uninstall <id> [--project] [--json] [target]
+  harness preset run <id> <plan|scaffold|check> --task <task-id> [--json] [target]
   harness new-task [task-id] [--module key] [--budget simple|standard|complex] [--preset id] [--from-session session.json] [--long-running] [--title title] [--locale zh-CN|en-US] [--dry-run] [target]
   harness task-start <task-id> [--message text] [target]
   harness task-phase <task-id> <phase-id> [--state done] [--completion 100] [--evidence present] [target]
@@ -100,7 +101,7 @@ Usage:
   harness lesson-promote <task-id> <candidate-id> [--dry-run|--apply] [target]
   harness lesson-sediment <task-id> <candidate-id> [--dry-run] [--title title] [target]
   harness task-complete <task-id> [--message text] [target]
-  harness task-list [--json] [--state state] [--module key] [--queue queue] [--preset id] [--review status] [--lesson status] [--missing-materials] [--search text] [target]
+  harness task-list [--json] [--state state] [--module key] [--queue queue] [--preset id] [--review status] [--lesson status] [--missing-materials] [--include-archived] [--search text] [target]
   harness task-index [--json] [target]
   harness task-supersede <old-task-id> --by <new-task-id> [--reason text] [target]
   harness task-delete <task-id> --soft [--reason text] [target]

package/dist/lib/capability-registry.mjs

@@ -571,8 +571,8 @@ function writeNpmScripts(target, { dryRun = true } = {}) {
     const pkg = readJsonSafe(packagePath, {});
     const scripts = { ...(pkg.scripts || {}) };
     const additions = {
-        "harness:dev": "coding-agent-harness dev .",
-        "harness:dashboard": "coding-agent-harness dashboard --out-dir tmp/harness-dashboard .",
+        "harness:dev": "npx --yes coding-agent-harness dev .",
+        "harness:dashboard": "npx --yes coding-agent-harness dashboard --out-dir tmp/harness-dashboard .",
     };
     let changed = false;
     const scriptChanges = [];

package/dist/lib/harness-core.mjs

@@ -10,6 +10,7 @@ export * from "./dashboard-workbench.mjs";
 export * from "./migration-planner.mjs";
 export * from "./structure-migration.mjs";
 export * from "./preset-registry.mjs";
+export * from "./preset-runner.mjs";
 export * from "./governance-index-generator.mjs";
 export * from "./task-lifecycle.mjs";
 export * from "./task-lesson-sedimentation.mjs";

package/dist/lib/preset-engine.mjs

@@ -94,6 +94,7 @@ export function buildPresetContext(preset, { target, taskDir, taskId, taskTitle,
         taskId,
         targetRoot: target.projectRoot,
         entrypoint: "newTask",
+        resolvedInputs,
     });
     const context = {
         kind: evaluatedValues.kind || preset.task?.kind || "general",

package/dist/lib/preset-registry.mjs

@@ -258,6 +258,9 @@ export function validatePresetPackage(preset) {
             if (!preset.writeScopes.some((scope) => scope.path === writeScope)) {
                 failures.push(`${name} writes undeclared scope: ${writeScope}`);
             }
+            if (name === "newTask" && !newTaskWriteScopeAllowed(writeScope)) {
+                failures.push("newTask entrypoint writes must stay under coding-agent-harness/planning/**");
+            }
         }
         if (["script", "check"].includes(entrypoint.type)) {
             const entryPath = path.join(preset.directory, entrypoint.command || "");
@@ -282,7 +285,7 @@ export function validatePresetPackage(preset) {
     }
     return { failures, warnings };
 }
-export function buildPresetAudit(preset, { taskId = "", targetRoot = "", entrypoint = "newTask", writeScopes = [] } = {}) {
+export function buildPresetAudit(preset, { taskId = "", targetRoot = "", entrypoint = "newTask", writeScopes = [], resolvedInputs = {} } = {}) {
     const entrypoints = {
         [entrypoint]: preset.entrypoints[entrypoint],
     };
@@ -294,6 +297,7 @@ export function buildPresetAudit(preset, { taskId = "", targetRoot = "", entrypo
         manifestSha256: preset.manifestSha256,
         entrypoints,
         writeScopes: scopes,
+        resolvedInputs,
         taskId,
         targetRoot,
         generatedAt: new Date().toISOString(),
@@ -526,6 +530,14 @@ function validateAuditEvidenceFiles(preset, failures) {
         }
     }
 }
+function newTaskWriteScopeAllowed(writeScope) {
+    const normalized = toPosix(path.normalize(String(writeScope || "")));
+    const legacyPlanningScope = ["docs", "09-PLANNING"].join("/");
+    return (normalized === "coding-agent-harness/planning/**" ||
+        normalized.startsWith("coding-agent-harness/planning/") ||
+        normalized === `${legacyPlanningScope}/**` ||
+        normalized.startsWith(`${legacyPlanningScope}/`));
+}
 function validatePresetPackageFile(preset, relativePath, label, failures) {
     const filePath = path.join(preset.directory, relativePath || "");
     if (!isInside(preset.directory, filePath)) {