coding-agent-harness 1.0.8 → 1.1.0

package/dist/lib/check-task-contracts.mjs

@@ -1,11 +1,11 @@
-// @ts-nocheck
 // Task contract checks depend on dynamic task scan metadata until checker domain types are modeled.
 import fs from "node:fs";
 import path from "node:path";
 import { lessonCandidatesFile, readFileSafe, toPosix, visualMapFile, } from "./core-shared.mjs";
-import { listTaskPlanPaths, parseTaskBudget, parseTaskContractInfo, } from "./task-scanner.mjs";
+import { parseTaskBudget, parseTaskContractInfo } from "./task-metadata.mjs";
+import { createScannerTaskRepository, taskPlanPathFromRecord } from "./task-repository.mjs";
 import { parseTaskAuditMetadata } from "./task-audit-metadata.mjs";
-export function validatePlanContracts(target, { strict = true, taskPlanPaths } = {}) {
+export function validatePlanContracts(target, { strict = true, tasks } = {}) {
     const failures = [];
     const warnings = [];
     const report = (message) => {
@@ -14,7 +14,9 @@ export function validatePlanContracts(target, { strict = true, taskPlanPaths } =
         else
             warnings.push(`adoption-needed: ${message}`);
     };
-    for (const taskPlanPath of taskPlanPaths || listTaskPlanPaths(target)) {
+    const taskRecords = tasks || createScannerTaskRepository(target).list();
+    for (const task of taskRecords) {
+        const taskPlanPath = taskPlanPathFromRecord(target, task);
         const taskDir = path.dirname(taskPlanPath);
         const relativeDir = toPosix(path.relative(target.projectRoot, taskDir));
         const taskPlanContent = readFileSafe(taskPlanPath);

package/dist/lib/command-registry.mjs

@@ -0,0 +1,248 @@
+const HELP_NOTES = `If init runs in an interactive terminal and --locale is omitted, it asks for a
+language. Non-interactive init defaults to en-US.
+
+Human review confirmation is available only through local Dashboard workbench.
+
+Preset discovery:
+  Project presets live in <target>/.coding-agent-harness/presets/<preset-id>/.
+  User presets live in ~/.coding-agent-harness/presets/<preset-id>/.
+  Harness discovers project presets first when a target is supplied, then user
+  presets, then bundled package presets under presets/<preset-id>/.
+  "harness init" seeds bundled presets into the target project. "harness
+  install-user" and npm postinstall seed bundled presets into the user root.
+  Use "harness preset seed" to repair or re-run preset seeding.
+  Use "harness preset install" with a local preset folder, .zip archive, or
+  bundled preset id. Preset archives must contain preset.yaml at the archive
+  root or inside one top-level folder.
+  Use "harness preset list --json" to see available presets, their source,
+  purpose, compatible budgets, and manifest path. Use "harness preset inspect
+  <id> --json" for the full preset manifest summary.
+
+Module workflow:
+  Registered modules are stored in the root harness.yaml under modules.items.
+  "harness module register" writes YAML, creates module brief.md/module_plan.md,
+  and regenerates planning/modules/Module-Registry.md as a read-only view.
+  "harness module scaffold" repairs only module-owned root docs; task execution
+  files stay under planning/modules/<key>/tasks/<task-id>/.
+  "harness new-task --module <key>" creates a module task and applies the module
+  task preset by default. Unknown modules must be registered first, or use
+  --register-module with --module-title/--module-prefix/--module-scope.`;
+export function dispatchCommand(registry, argv) {
+    if (isTopLevelHelpRequest(argv)) {
+        console.log(generateCommandHelp(registry));
+        return;
+    }
+    const resolved = resolveCommand(registry, argv);
+    if (!resolved) {
+        console.log(generateCommandHelp(registry));
+        if (isUnresolvedCommandHelpRequest(argv))
+            return;
+        process.exit(2);
+    }
+    if (isCommandHelpRequest(resolved.raw)) {
+        console.log(generateCommandHelp(registry));
+        return;
+    }
+    return resolved.definition.handler(createCommandContext(resolved.definition, resolved.raw));
+}
+export function resolveCommand(registry, argv) {
+    const sorted = [...registry].sort((left, right) => commandWordCount(right.name) - commandWordCount(left.name));
+    for (const definition of sorted) {
+        const words = definition.name.split(" ");
+        if (words.every((word, index) => argv[index] === word)) {
+            return { definition, raw: [...argv.slice(words.length)] };
+        }
+    }
+    return null;
+}
+export function createCommandContext(definition, raw) {
+    const mutableArgs = [...raw];
+    const readers = createArgReaders(mutableArgs);
+    const parsed = parseCommandArgs(definition.flags || [], raw);
+    return {
+        definition,
+        args: parsed,
+        raw: [...raw],
+        target: definition.hasTarget === false ? "." : targetFromArgsAfterKnownFlags(definition.flags || [], raw),
+        ...readers,
+    };
+}
+export function createArgReaders(args) {
+    return {
+        takeFlag(name, fallback = false) {
+            const index = args.indexOf(name);
+            if (index < 0)
+                return fallback;
+            args.splice(index, 1);
+            return true;
+        },
+        takeOption(name, fallback = "") {
+            return takeOptionFromArgs(args, name, fallback);
+        },
+        targetArg() {
+            return trailingTargetArg(args);
+        },
+    };
+}
+export function parseCommandArgs(flags, argv) {
+    const result = { flags: {}, options: {}, repeated: {}, positionals: [] };
+    for (const flag of flags) {
+        const key = flagKey(flag.name);
+        if (flag.default === undefined)
+            continue;
+        if (flag.type === "boolean")
+            result.flags[key] = Boolean(flag.default);
+        else if (flag.type === "string[]")
+            result.repeated[key] = Array.isArray(flag.default) ? flag.default.map(String) : [];
+        else
+            result.options[key] = String(flag.default);
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const definition = flags.find((flag) => flag.name === arg || flag.alias === arg);
+        if (!definition) {
+            if (!arg.startsWith("-"))
+                result.positionals.push(arg);
+            continue;
+        }
+        const key = flagKey(definition.name);
+        if (definition.type === "boolean") {
+            result.flags[key] = true;
+            continue;
+        }
+        const fallback = definition.default === undefined || Array.isArray(definition.default) ? "" : String(definition.default);
+        const value = argv[index + 1] || fallback;
+        if (definition.type === "string[]") {
+            result.repeated[key] = result.repeated[key] || [];
+            result.repeated[key].push(value);
+        }
+        else {
+            result.options[key] = value;
+        }
+        index += 1;
+    }
+    return result;
+}
+export 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;
+}
+export function takeRepeatedOptionsFromArgs(args, flag) {
+    const values = [];
+    for (let index = 0; index < args.length;) {
+        if (args[index] !== flag) {
+            index += 1;
+            continue;
+        }
+        const value = args[index + 1] || "";
+        args.splice(index, 2);
+        if (!value)
+            throw new Error(`${flag} requires a value`);
+        values.push(value);
+    }
+    return values;
+}
+export function generateCommandHelp(registry) {
+    const usageLines = [];
+    const seenUsages = new Set();
+    for (const command of registry) {
+        const usage = command.usage || buildUsage(command);
+        if (seenUsages.has(usage))
+            continue;
+        seenUsages.add(usage);
+        usageLines.push(`  ${usage}`);
+    }
+    const lines = [
+        "Coding Agent Harness",
+        "",
+        "Usage:",
+        ...usageLines,
+        "",
+        HELP_NOTES,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function validateCommandRegistry(registry) {
+    const issues = [];
+    const seenCommands = new Set();
+    for (const command of registry) {
+        if (!command.name.trim())
+            issues.push("command has empty name");
+        if (seenCommands.has(command.name))
+            issues.push(`duplicate command name: ${command.name}`);
+        seenCommands.add(command.name);
+        if (!command.description.trim())
+            issues.push(`${command.name}: missing description`);
+        if (typeof command.handler !== "function")
+            issues.push(`${command.name}: missing handler`);
+        const seenFlags = new Set();
+        for (const flag of command.flags || []) {
+            if (!flag.name.startsWith("--"))
+                issues.push(`${command.name}: flag must use -- prefix: ${flag.name}`);
+            if (seenFlags.has(flag.name))
+                issues.push(`${command.name}: duplicate flag ${flag.name}`);
+            seenFlags.add(flag.name);
+            if (flag.alias) {
+                if (seenFlags.has(flag.alias))
+                    issues.push(`${command.name}: duplicate flag alias ${flag.alias}`);
+                seenFlags.add(flag.alias);
+            }
+            if (!flag.description.trim())
+                issues.push(`${command.name}: ${flag.name} missing description`);
+        }
+    }
+    return issues;
+}
+function isTopLevelHelpRequest(argv) {
+    return argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h";
+}
+function isCommandHelpRequest(raw) {
+    return raw[0] === "help" || raw.includes("--help") || raw.includes("-h");
+}
+function isUnresolvedCommandHelpRequest(argv) {
+    return argv[1] === "help" || argv.includes("--help") || argv.includes("-h");
+}
+function buildUsage(command) {
+    const positionals = (command.positionals || []).map((positional) => `<${positional}>`);
+    const flags = (command.flags || []).map((flag) => `[${flag.name}${flag.type === "boolean" ? "" : " value"}]`);
+    const target = command.hasTarget === false ? [] : ["[target]"];
+    return ["harness", command.name, ...positionals, ...flags, ...target].join(" ");
+}
+function targetFromArgsAfterKnownFlags(flags, argv) {
+    const args = [...argv];
+    for (const flag of flags) {
+        if (flag.type === "boolean") {
+            removeBooleanFlag(args, flag.name);
+            if (flag.alias)
+                removeBooleanFlag(args, flag.alias);
+        }
+        else {
+            removeOption(args, flag.name);
+            if (flag.alias)
+                removeOption(args, flag.alias);
+        }
+    }
+    return trailingTargetArg(args);
+}
+function removeBooleanFlag(args, name) {
+    for (let index = args.indexOf(name); index >= 0; index = args.indexOf(name))
+        args.splice(index, 1);
+}
+function removeOption(args, name) {
+    for (let index = args.indexOf(name); index >= 0; index = args.indexOf(name))
+        args.splice(index, 2);
+}
+function trailingTargetArg(args) {
+    const candidate = args[args.length - 1] || "";
+    return candidate && !candidate.startsWith("-") ? candidate : ".";
+}
+function flagKey(name) {
+    return name.replace(/^-+/, "");
+}
+function commandWordCount(name) {
+    return name.split(" ").length;
+}

package/dist/lib/core-shared.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -18,6 +17,18 @@ export function userPresetRootForHome(home = "") {
     return path.join(path.resolve(home || os.homedir()), ".coding-agent-harness/presets");
 }
 export const userPresetRoot = userPresetRootForHome();
+export const harnessPathTemplateFields = [
+    "harnessRoot",
+    "planningRoot",
+    "tasksRoot",
+    "modulesRoot",
+    "externalRoot",
+    "governanceRoot",
+    "generatedRoot",
+    "regressionRoot",
+    "ledgerPath",
+    "closeoutIndexPath",
+];
 export const supportedLocales = new Set(["zh-CN", "en-US"]);
 export const allowedReviewDispositions = new Set([
     "open",
@@ -95,6 +106,70 @@ export function readBundledTemplate(source) {
         throw new Error(`Bundled template is empty: ${source}`);
     return content;
 }
+export function harnessPathContext(targetOrPaths) {
+    const paths = (targetOrPaths?.harness || targetOrPaths || {});
+    const projectRoot = String(paths.projectRoot || targetOrPaths?.projectRoot || "");
+    const result = {};
+    for (const field of harnessPathTemplateFields) {
+        const value = String(paths[field] || "");
+        if (!value)
+            continue;
+        result[field] = projectRoot && path.isAbsolute(value)
+            ? toPosix(path.relative(projectRoot, value))
+            : toPosix(value);
+    }
+    return result;
+}
+export function absoluteHarnessPathContext(targetOrPaths) {
+    const paths = (targetOrPaths?.harness || targetOrPaths || {});
+    const projectRoot = String(paths.projectRoot || targetOrPaths?.projectRoot || "");
+    const result = {};
+    for (const field of harnessPathTemplateFields) {
+        const value = String(paths[field] || "");
+        if (!value)
+            continue;
+        result[field] = path.isAbsolute(value) ? value : path.join(projectRoot, value);
+    }
+    return result;
+}
+export function renderHarnessTemplate(content, context = {}, { strict = false, missing = "preserve" } = {}) {
+    return String(content).replace(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (match, key) => {
+        const value = getTemplateValue(context, key);
+        if (value == null) {
+            if (strict)
+                throw new Error(`Unknown template token: ${key}`);
+            return missing === "empty" ? "" : match;
+        }
+        return String(value);
+    });
+}
+export function validateHarnessPathTemplateTokens(content, label = "template") {
+    const failures = [];
+    for (const match of String(content || "").matchAll(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g)) {
+        const key = match[1];
+        if (!key.startsWith("paths."))
+            continue;
+        const field = key.slice("paths.".length);
+        if (!harnessPathTemplateFields.includes(field))
+            failures.push(`${label} uses unknown path token: ${key}`);
+    }
+    return failures;
+}
+export function resolveHarnessPathTemplate(value, target, label = "path") {
+    const rendered = renderHarnessTemplate(String(value || ""), { paths: harnessPathContext(target) }, { strict: true });
+    const normalized = toPosix(path.normalize(rendered));
+    if (!rendered.trim())
+        throw new Error(`${label} resolved to an empty path`);
+    if (path.isAbsolute(rendered) || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+        throw new Error(`${label} escapes target root: ${value}`);
+    }
+    return normalized;
+}
+function getTemplateValue(context, key) {
+    return String(key).split(".").reduce((cursor, part) => (cursor && typeof cursor === "object" && Object.prototype.hasOwnProperty.call(cursor, part)
+        ? cursor[part]
+        : undefined), context);
+}
 export function walkFiles(root, options = {}) {
     const results = [];
     if (!fs.existsSync(root))
@@ -196,7 +271,7 @@ export function nowTimestamp() {
 export function normalizeTaskId(value) {
     return slug(value || "task");
 }
-export function renderTaskTemplate(content, { taskId, title, locale, budget = "standard", moduleKey = "", preset = "none", presetVersion = "", evidenceBundle = "", longRunning = false, scaffoldProvenance = {}, taskAudit = {} }) {
+export function renderTaskTemplate(content, { taskId, title, locale, budget = "standard", moduleKey = "", preset = "none", presetVersion = "", evidenceBundle = "", longRunning = false, scaffoldProvenance = {}, taskAudit = {}, target, paths = target ? harnessPathContext(target) : {}, }) {
     const date = todayDate();
     const provenance = {
         createdBy: scaffoldProvenance.createdBy || "harness new-task",
@@ -206,7 +281,7 @@ export function renderTaskTemplate(content, { taskId, title, locale, budget = "s
         templateSource: scaffoldProvenance.templateSource || "templates/planning/brief.md",
         exceptionReason: scaffoldProvenance.exceptionReason || "n/a",
     };
-    return String(content)
+    return renderHarnessTemplate(String(content), { paths })
         .replaceAll("{{TASK_ID}}", taskId)
         .replaceAll("{{TASK_TITLE}}", title)
         .replaceAll("{{DATE}}", date)