@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/chunk-ICPZNX6O.js

@@ -0,0 +1,199 @@
+import {
+  logger
+} from "./chunk-EBJQ6N4M.js";
+import {
+  ALLOWED_COGNITIVE_MODES
+} from "./chunk-BKHS7RPB.js";
+import {
+  CLIError,
+  ExitCode
+} from "./chunk-3WGJMBKH.js";
+
+// src/commands/create-skill.ts
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs";
+import YAML from "yaml";
+var KEBAB_CASE_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function buildSkillYaml(opts) {
+  const doc = {
+    name: opts.name,
+    version: "0.1.0",
+    description: opts.description,
+    cognitive_mode: opts.cognitiveMode ?? "constructive-architect",
+    triggers: ["manual"],
+    platforms: ["claude-code", "gemini-cli"],
+    tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+    type: "flexible",
+    state: {
+      persistent: false,
+      files: []
+    },
+    depends_on: []
+  };
+  return doc;
+}
+function toListSection(items, fallback) {
+  return items && items.length > 0 ? items.map((i) => `- \`${i}\``).join("\n") : fallback;
+}
+function buildSkillMdSections(opts) {
+  return {
+    mode: opts.cognitiveMode ?? "constructive-architect",
+    reads: toListSection(opts.reads, "- _No read patterns specified_"),
+    produces: opts.produces ? `- \`${opts.produces}\`` : "- _No output specified_",
+    preChecks: toListSection(opts.preChecks, "- _None_"),
+    postChecks: toListSection(opts.postChecks, "- _None_")
+  };
+}
+function buildSkillMdBody(name, description, mode, reads, produces, preChecks, postChecks, run) {
+  return `# ${name}
+
+> Cognitive Mode: ${mode}
+
+${description}
+
+## When to Use
+
+- [Describe when this skill should be invoked]
+- [Describe the trigger conditions]
+
+## Context Assembly
+
+### Reads
+${reads}
+
+### Produces
+${produces}
+
+## Deterministic Checks
+
+### Pre-checks
+${preChecks}
+
+### Post-checks
+${postChecks}
+
+## Process
+
+1. [Describe the step-by-step process]
+2. [Add additional steps as needed]
+
+## Harness Integration
+
+This skill integrates with the harness engineering workflow. It can be invoked via:
+
+\`\`\`bash
+${run}
+\`\`\`
+
+## Success Criteria
+
+- [Define what a successful execution looks like]
+- [Add measurable criteria]
+
+## Examples
+
+\`\`\`bash
+${run}
+\`\`\`
+
+## Rationalizations to Reject
+
+<!-- TODO: Add 3-8 domain-specific rationalizations. Do not repeat universal rationalizations (defined in harness-skill-authoring). -->
+
+| Rationalization | Reality |
+| --- | --- |
+| "[Domain-specific excuse]" | [Why this is wrong and what to do instead] |
+`;
+}
+function buildSkillMd(opts) {
+  const { mode, reads, produces, preChecks, postChecks } = buildSkillMdSections(opts);
+  const run = `harness skill run ${opts.name}`;
+  return buildSkillMdBody(
+    opts.name,
+    opts.description,
+    mode,
+    reads,
+    produces,
+    preChecks,
+    postChecks,
+    run
+  );
+}
+function generateSkillFiles(opts) {
+  if (!KEBAB_CASE_RE.test(opts.name)) {
+    throw new CLIError(
+      `Invalid skill name "${opts.name}". Must be kebab-case (e.g., my-skill).`,
+      ExitCode.VALIDATION_FAILED
+    );
+  }
+  if (opts.cognitiveMode && !ALLOWED_COGNITIVE_MODES.includes(opts.cognitiveMode)) {
+    throw new CLIError(
+      `Invalid cognitive mode "${opts.cognitiveMode}". Allowed: ${ALLOWED_COGNITIVE_MODES.join(", ")}`,
+      ExitCode.VALIDATION_FAILED
+    );
+  }
+  const baseDir = opts.outputDir ?? path.join(process.cwd(), "agents", "skills", "claude-code");
+  const skillDir = path.join(baseDir, opts.name);
+  if (fs.existsSync(skillDir)) {
+    throw new CLIError(`Skill directory already exists: ${skillDir}`, ExitCode.VALIDATION_FAILED);
+  }
+  fs.mkdirSync(skillDir, { recursive: true });
+  const skillYaml = buildSkillYaml(opts);
+  const skillYamlPath = path.join(skillDir, "skill.yaml");
+  fs.writeFileSync(skillYamlPath, YAML.stringify(skillYaml));
+  const skillMd = buildSkillMd(opts);
+  const skillMdPath = path.join(skillDir, "SKILL.md");
+  fs.writeFileSync(skillMdPath, skillMd);
+  return { skillYamlPath, skillMdPath };
+}
+function handleSkillError(error, json) {
+  if (!(error instanceof CLIError)) throw error;
+  if (json) {
+    console.log(JSON.stringify({ error: error.message }));
+  } else {
+    logger.error(error.message);
+  }
+  process.exit(error.exitCode);
+}
+async function runCreateSkillAction(opts) {
+  try {
+    const result = generateSkillFiles(opts);
+    if (!opts.quiet) {
+      logger.success(`Created skill "${opts.name}"`);
+      logger.info(`  ${result.skillYamlPath}`);
+      logger.info(`  ${result.skillMdPath}`);
+    }
+    if (opts.json) {
+      logger.raw({ name: opts.name, files: [result.skillYamlPath, result.skillMdPath] });
+    }
+  } catch (error) {
+    handleSkillError(error, opts.json ?? false);
+  }
+}
+function createCreateSkillCommand() {
+  const command = new Command("create-skill").description("Scaffold a new skill with skill.yaml and SKILL.md").requiredOption("--name <name>", "Skill name (kebab-case)").requiredOption("--description <desc>", "Skill description").option(
+    "--cognitive-mode <mode>",
+    `Cognitive mode (${ALLOWED_COGNITIVE_MODES.join(", ")})`,
+    "constructive-architect"
+  ).option("--reads <patterns...>", "File patterns the skill reads").option("--produces <output>", "What the skill produces").option("--pre-checks <commands...>", "Pre-check commands").option("--post-checks <commands...>", "Post-check commands").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    await runCreateSkillAction({
+      name: opts.name,
+      description: opts.description,
+      cognitiveMode: opts.cognitiveMode,
+      reads: opts.reads,
+      produces: opts.produces,
+      preChecks: opts.preChecks,
+      postChecks: opts.postChecks,
+      quiet: globalOpts.quiet,
+      json: globalOpts.json
+    });
+  });
+  return command;
+}
+
+export {
+  generateSkillFiles,
+  createCreateSkillCommand
+};

package/dist/chunk-LASBAGC6.js

@@ -0,0 +1,125 @@
+import {
+  resolveSkillsDir
+} from "./chunk-6B6UN6SG.js";
+import {
+  SkillMetadataSchema
+} from "./chunk-BKHS7RPB.js";
+
+// src/persona/skill-executor.ts
+import * as fs from "fs";
+import * as path from "path";
+import { parse } from "yaml";
+function resolveOutputMode(mode, trigger) {
+  if (mode !== "auto") return mode;
+  return trigger === "manual" ? "inline" : "artifact";
+}
+function buildArtifactPath(projectPath, headSha) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const sha = headSha?.slice(0, 7) ?? "unknown";
+  return path.join(projectPath, ".harness", "reviews", `${date}-${sha}.md`);
+}
+function buildArtifactContent(skillName, trigger, headSha) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  return [
+    "---",
+    `skill: ${skillName}`,
+    `trigger: ${trigger}`,
+    `sha: ${headSha?.slice(0, 7) ?? "unknown"}`,
+    `date: ${date}`,
+    `assessment: pending`,
+    "---",
+    "",
+    `# Review by ${skillName}`,
+    "",
+    "## Strengths",
+    "",
+    "- (review pending)",
+    "",
+    "## Issues",
+    "",
+    "### Critical",
+    "",
+    "- None identified",
+    "",
+    "### Important",
+    "",
+    "- None identified",
+    "",
+    "### Suggestions",
+    "",
+    "- None identified",
+    "",
+    "## Assessment",
+    "",
+    "Pending \u2014 skill execution scaffolded.",
+    "",
+    "## Harness Checks",
+    "",
+    "- (run harness validate, check-deps, check-docs to populate)",
+    ""
+  ].join("\n");
+}
+async function executeSkill(skillName, context) {
+  const startTime = Date.now();
+  const skillsDir = resolveSkillsDir();
+  const skillDir = path.join(skillsDir, skillName);
+  if (!fs.existsSync(skillDir)) {
+    return {
+      status: "fail",
+      output: `Skill not found: ${skillName}`,
+      durationMs: Date.now() - startTime
+    };
+  }
+  const yamlPath = path.join(skillDir, "skill.yaml");
+  if (!fs.existsSync(yamlPath)) {
+    return {
+      status: "fail",
+      output: `skill.yaml not found for ${skillName}`,
+      durationMs: Date.now() - startTime
+    };
+  }
+  const raw = fs.readFileSync(yamlPath, "utf-8");
+  const parsed = parse(raw);
+  const metadataResult = SkillMetadataSchema.safeParse(parsed);
+  if (!metadataResult.success) {
+    return {
+      status: "fail",
+      output: `Invalid skill metadata: ${metadataResult.error.message}`,
+      durationMs: Date.now() - startTime
+    };
+  }
+  const skillMdPath = path.join(skillDir, "SKILL.md");
+  if (!fs.existsSync(skillMdPath)) {
+    return {
+      status: "fail",
+      output: `SKILL.md not found for ${skillName}`,
+      durationMs: Date.now() - startTime
+    };
+  }
+  const skillContent = fs.readFileSync(skillMdPath, "utf-8");
+  const metadata = metadataResult.data;
+  const resolvedMode = resolveOutputMode(context.outputMode, context.trigger);
+  const output = `Skill ${metadata.name} (${metadata.type}) loaded.
+Cognitive mode: ${metadata.cognitive_mode ?? "default"}
+Content length: ${skillContent.length} chars
+Trigger: ${context.trigger}
+`;
+  let artifactPath;
+  if (resolvedMode === "artifact") {
+    artifactPath = buildArtifactPath(context.projectPath, context.headSha);
+    const artifactContent = buildArtifactContent(skillName, context.trigger, context.headSha);
+    const dir = path.dirname(artifactPath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(artifactPath, artifactContent, "utf-8");
+  }
+  return {
+    status: "pass",
+    output,
+    ...artifactPath ? { artifactPath } : {},
+    durationMs: Date.now() - startTime
+  };
+}
+
+export {
+  executeSkill
+};

package/dist/chunk-LM5Z2WCA.js

@@ -0,0 +1,31 @@
+import {
+  toKebabCase
+} from "./chunk-KET4QQZB.js";
+import {
+  Err,
+  Ok
+} from "./chunk-5LMZA5LZ.js";
+
+// src/persona/generators/runtime.ts
+function generateRuntime(persona) {
+  try {
+    const config = {
+      name: toKebabCase(persona.name),
+      skills: persona.skills,
+      steps: persona.steps,
+      timeout: persona.config.timeout,
+      severity: persona.config.severity
+    };
+    return Ok(JSON.stringify(config, null, 2));
+  } catch (error) {
+    return Err(
+      new Error(
+        `Failed to generate runtime config: ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+  }
+}
+
+export {
+  generateRuntime
+};

package/dist/chunk-LOUH2LIC.js

@@ -0,0 +1,67 @@
+import {
+  Err,
+  Ok
+} from "./chunk-5LMZA5LZ.js";
+
+// src/persona/generators/ci-workflow.ts
+import YAML from "yaml";
+function buildGitHubTriggers(triggers) {
+  const on = {};
+  for (const trigger of triggers) {
+    switch (trigger.event) {
+      case "on_pr": {
+        const prConfig = {};
+        if (trigger.conditions?.paths) prConfig.paths = trigger.conditions.paths;
+        on.pull_request = prConfig;
+        break;
+      }
+      case "on_commit": {
+        const pushConfig = {};
+        if (trigger.conditions?.branches) pushConfig.branches = trigger.conditions.branches;
+        on.push = pushConfig;
+        break;
+      }
+      case "scheduled":
+        on.schedule = [{ cron: trigger.cron }];
+        break;
+    }
+  }
+  return on;
+}
+function generateCIWorkflow(persona, platform) {
+  try {
+    if (platform === "gitlab") return Err(new Error("GitLab CI generation is not yet supported"));
+    const severity = persona.config.severity;
+    const steps = [
+      { uses: "actions/checkout@v4" },
+      { uses: "actions/setup-node@v4", with: { "node-version": "20" } },
+      { uses: "pnpm/action-setup@v4", with: { run_install: "frozen" } }
+    ];
+    const commandSteps = persona.steps.filter((s) => "command" in s);
+    for (const step of commandSteps) {
+      const severityFlag = severity ? ` --severity ${severity}` : "";
+      steps.push({ run: `npx harness ${step.command}${severityFlag}` });
+    }
+    const workflow = {
+      name: persona.name,
+      on: buildGitHubTriggers(persona.triggers),
+      jobs: {
+        enforce: {
+          "runs-on": "ubuntu-latest",
+          steps
+        }
+      }
+    };
+    return Ok(YAML.stringify(workflow, { lineWidth: 0 }));
+  } catch (error) {
+    return Err(
+      new Error(
+        `Failed to generate CI workflow: ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+  }
+}
+
+export {
+  generateCIWorkflow
+};

package/dist/chunk-LRX6J7IA.js

@@ -0,0 +1,250 @@
+import {
+  resolveConfig
+} from "./chunk-ZOIGL5PP.js";
+import {
+  Ok
+} from "./chunk-5LMZA5LZ.js";
+import {
+  logger
+} from "./chunk-EBJQ6N4M.js";
+import {
+  ExitCode
+} from "./chunk-3WGJMBKH.js";
+
+// src/commands/check-phase-gate.ts
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs";
+
+// src/utils/files.ts
+import { glob } from "glob";
+async function findFiles(pattern, cwd = process.cwd()) {
+  return glob(pattern, { cwd, absolute: true });
+}
+
+// src/output/formatter.ts
+import chalk from "chalk";
+var OutputMode = {
+  /** Output as formatted JSON */
+  JSON: "json",
+  /** Output as human-readable text */
+  TEXT: "text",
+  /** Minimal output, only errors and successes */
+  QUIET: "quiet",
+  /** Full output with detailed context and suggestions */
+  VERBOSE: "verbose"
+};
+function appendIssueLines(lines, issue, mode) {
+  const location = issue.file ? issue.line ? `${issue.file}:${issue.line}` : issue.file : "unknown";
+  lines.push(`  ${chalk.yellow("*")} ${chalk.dim(location)}`);
+  lines.push(`    ${issue.message}`);
+  if (issue.suggestion && mode === OutputMode.VERBOSE) {
+    lines.push(`    ${chalk.dim("->")} ${issue.suggestion}`);
+  }
+}
+var OutputFormatter = class {
+  /**
+   * Creates a new OutputFormatter.
+   *
+   * @param mode - The output mode to use. Defaults to TEXT.
+   */
+  constructor(mode = OutputMode.TEXT) {
+    this.mode = mode;
+  }
+  mode;
+  /**
+   * Formats raw data for output.
+   *
+   * @param data - The data to format.
+   * @returns A string representation of the data based on the current mode.
+   */
+  format(data) {
+    if (this.mode === OutputMode.JSON) {
+      return JSON.stringify(data, null, 2);
+    }
+    return String(data);
+  }
+  /**
+   * Formats a validation result into a user-friendly string.
+   *
+   * @param result - The validation result to format.
+   * @returns A formatted string containing the validation status and any issues.
+   */
+  formatValidation(result) {
+    if (this.mode === OutputMode.JSON) {
+      return JSON.stringify(result, null, 2);
+    }
+    if (this.mode === OutputMode.QUIET) {
+      if (result.valid) return "";
+      return result.issues.map((i) => `${i.file ?? ""}: ${i.message}`).join("\n");
+    }
+    const lines = [];
+    if (result.valid) {
+      lines.push(chalk.green("v validation passed"));
+    } else {
+      lines.push(chalk.red(`x Validation failed (${result.issues.length} issues)`));
+      lines.push("");
+      for (const issue of result.issues) {
+        appendIssueLines(lines, issue, this.mode);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+   * Formats a summary line with a success/failure icon and label.
+   *
+   * @param label - The name of the field to summarize.
+   * @param value - The value to display.
+   * @param success - Whether the summary represents a success or failure state.
+   * @returns A formatted summary string, or an empty string in JSON or QUIET modes.
+   */
+  formatSummary(label, value, success) {
+    if (this.mode === OutputMode.JSON || this.mode === OutputMode.QUIET) {
+      return "";
+    }
+    const icon = success ? chalk.green("v") : chalk.red("x");
+    return `${icon} ${label}: ${value}`;
+  }
+};
+
+// src/commands/check-phase-gate.ts
+function resolveSpecPath(implFile, implPattern, specPattern, cwd) {
+  const relImpl = path.relative(cwd, implFile).replace(/\\/g, "/");
+  const implBase = (implPattern.split("*")[0] ?? "").replace(/\/+$/, "");
+  const afterBase = relImpl.startsWith(implBase + "/") ? relImpl.slice(implBase.length + 1) : relImpl;
+  const segments = afterBase.split("/");
+  const firstSegment = segments[0] ?? "";
+  const feature = segments.length > 1 ? firstSegment : path.basename(firstSegment, path.extname(firstSegment));
+  const specRelative = specPattern.replace("{feature}", feature);
+  return path.resolve(cwd, specRelative);
+}
+function checkSpecContent(specPath, relImpl, relSpec, missingSpecs) {
+  const content = fs.readFileSync(specPath, "utf-8");
+  const sectionPattern = /^#+\s*(Observable Truths|Success Criteria|Acceptance Criteria)/im;
+  const sectionMatch = sectionPattern.exec(content);
+  if (!sectionMatch) {
+    missingSpecs.push({
+      implFile: relImpl,
+      expectedSpec: `${relSpec} (missing requirements section: expected Observable Truths, Success Criteria, or Acceptance Criteria heading)`
+    });
+    return;
+  }
+  const sectionStart = sectionMatch.index + sectionMatch[0].length;
+  const nextHeadingMatch = /^#+\s/m.exec(content.slice(sectionStart));
+  const sectionContent = nextHeadingMatch ? content.slice(sectionStart, sectionStart + nextHeadingMatch.index) : content.slice(sectionStart);
+  if (!/^\s*\d+\.\s+/m.test(sectionContent)) {
+    missingSpecs.push({
+      implFile: relImpl,
+      expectedSpec: `${relSpec} (requirements section "${sectionMatch[1]}" has no numbered items)`
+    });
+  }
+}
+async function runCheckPhaseGate(options) {
+  const configResult = resolveConfig(options.configPath);
+  if (!configResult.ok) {
+    return configResult;
+  }
+  const config = configResult.value;
+  const cwd = options.cwd ?? (options.configPath ? path.dirname(path.resolve(options.configPath)) : process.cwd());
+  if (!config.phaseGates?.enabled) {
+    return Ok({
+      pass: true,
+      skipped: true,
+      missingSpecs: [],
+      checkedFiles: 0
+    });
+  }
+  const phaseGates = config.phaseGates;
+  const missingSpecs = [];
+  let checkedFiles = 0;
+  for (const mapping of phaseGates.mappings) {
+    const implFiles = await findFiles(mapping.implPattern, cwd);
+    for (const implFile of implFiles) {
+      checkedFiles++;
+      const expectedSpec = resolveSpecPath(implFile, mapping.implPattern, mapping.specPattern, cwd);
+      const relImpl = path.relative(cwd, implFile).replace(/\\/g, "/");
+      const relSpec = path.relative(cwd, expectedSpec).replace(/\\/g, "/");
+      if (!fs.existsSync(expectedSpec)) {
+        missingSpecs.push({ implFile: relImpl, expectedSpec: relSpec });
+      } else if (mapping.contentValidation) {
+        checkSpecContent(expectedSpec, relImpl, relSpec, missingSpecs);
+      }
+    }
+  }
+  const pass = missingSpecs.length === 0;
+  return Ok({
+    pass,
+    skipped: false,
+    severity: phaseGates.severity,
+    missingSpecs,
+    checkedFiles
+  });
+}
+function resolvePhaseGateOutputMode(globalOpts) {
+  if (globalOpts.json) return OutputMode.JSON;
+  if (globalOpts.quiet) return OutputMode.QUIET;
+  if (globalOpts.verbose) return OutputMode.VERBOSE;
+  return OutputMode.TEXT;
+}
+function handlePhaseGateError(error, mode) {
+  if (mode === OutputMode.JSON) {
+    console.log(JSON.stringify({ error: error.message }));
+  } else {
+    logger.error(error.message);
+  }
+  process.exit(error.exitCode);
+}
+function handlePhaseGateSkipped(value, mode, formatter) {
+  if (mode === OutputMode.JSON) {
+    console.log(formatter.format(value));
+  } else if (mode !== OutputMode.QUIET) {
+    logger.dim("Phase gates not enabled, skipping.");
+  }
+  process.exit(ExitCode.SUCCESS);
+}
+function printPhaseGateResult(value, formatter) {
+  const output = formatter.formatValidation({
+    valid: value.pass,
+    issues: value.missingSpecs.map((m) => ({
+      file: m.implFile,
+      message: `Missing spec: ${m.expectedSpec}`
+    }))
+  });
+  if (output) console.log(output);
+  const summary = formatter.formatSummary(
+    "Phase gate check",
+    `${value.checkedFiles} files checked, ${value.missingSpecs.length} missing specs`,
+    value.pass
+  );
+  if (summary) console.log(summary);
+}
+function createCheckPhaseGateCommand() {
+  const command = new Command("check-phase-gate").description("Verify that implementation files have matching spec documents").action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = resolvePhaseGateOutputMode(globalOpts);
+    const formatter = new OutputFormatter(mode);
+    const result = await runCheckPhaseGate({
+      configPath: globalOpts.config,
+      json: globalOpts.json,
+      verbose: globalOpts.verbose,
+      quiet: globalOpts.quiet
+    });
+    if (!result.ok) handlePhaseGateError(result.error, mode);
+    const value = result.value;
+    if (value.skipped) handlePhaseGateSkipped(value, mode, formatter);
+    printPhaseGateResult(value, formatter);
+    if (!value.pass && value.severity === "error") {
+      process.exit(ExitCode.VALIDATION_FAILED);
+    }
+    process.exit(ExitCode.SUCCESS);
+  });
+  return command;
+}
+
+export {
+  OutputMode,
+  OutputFormatter,
+  findFiles,
+  runCheckPhaseGate,
+  createCheckPhaseGateCommand
+};