@kaiohenricunha/harness 0.2.0

package/plugins/harness/src/lib/argv.mjs

@@ -0,0 +1,108 @@
+/**
+ * Tiny argv parser built on Node's `util.parseArgs` (available since Node 18,
+ * engines.node `>=20`).
+ *
+ * Recognizes the harness-wide flag set:
+ *   --help / -h       bool
+ *   --version / -V    bool
+ *   --json            bool
+ *   --verbose / -v    bool
+ *   --no-color        bool
+ *
+ * Callers add their own flags via the `spec` parameter; the harness-wide set
+ * is merged in automatically.
+ *
+ * @typedef {object} FlagSpec
+ * @property {'boolean'|'string'} type
+ * @property {string} [short]       single-letter alias
+ * @property {string|boolean} [default]
+ * @property {boolean} [multiple]   allow repetition (array of values)
+ *
+ * @typedef {{ [name: string]: FlagSpec }} FlagsSpec
+ *
+ * @typedef {object} ParsedArgs
+ * @property {{ [name: string]: boolean|string|string[]|undefined }} flags
+ * @property {string[]} positional
+ * @property {boolean} help
+ * @property {boolean} version
+ * @property {boolean} json
+ * @property {boolean} verbose
+ * @property {boolean} noColor
+ */
+
+import { parseArgs } from 'node:util';
+
+/** Harness-wide flag set auto-included in every `parse()` call. */
+export const HARNESS_FLAGS = Object.freeze({
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'V' },
+  json: { type: 'boolean' },
+  verbose: { type: 'boolean', short: 'v' },
+  'no-color': { type: 'boolean' },
+});
+
+/**
+ * Parse `argv` (typically `process.argv.slice(2)`) against `spec`.
+ * Throws `Error` with a `.code = 'USAGE_UNKNOWN_FLAG'` property on unknown
+ * flags so callers can map to `EXIT_CODES.USAGE` without string matching.
+ *
+ * @param {string[]} argv
+ * @param {FlagsSpec} [spec]
+ * @returns {ParsedArgs}
+ */
+export function parse(argv, spec = {}) {
+  const merged = { ...HARNESS_FLAGS, ...spec };
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: /** @type {any} */ (merged),
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (err) {
+    const wrapped = new Error(err instanceof Error ? err.message : String(err));
+    /** @type {any} */ (wrapped).code = 'USAGE_UNKNOWN_FLAG';
+    throw wrapped;
+  }
+  const values = /** @type {Record<string, any>} */ (parsed.values);
+  return {
+    flags: values,
+    positional: parsed.positionals,
+    help: Boolean(values.help),
+    version: Boolean(values.version),
+    json: Boolean(values.json),
+    verbose: Boolean(values.verbose),
+    noColor: Boolean(values['no-color']),
+  };
+}
+
+/**
+ * Render a conventional `--help` message.
+ *
+ * @param {object} meta
+ * @param {string} meta.name         e.g. "harness-validate-specs"
+ * @param {string} meta.synopsis     e.g. "harness-validate-specs [OPTIONS]"
+ * @param {string} meta.description  1-2 sentence summary.
+ * @param {FlagsSpec} [meta.flags]   Bin-specific flags to document (harness-wide flags are always appended).
+ * @returns {string}
+ */
+export function helpText(meta) {
+  const lines = [
+    meta.synopsis,
+    '',
+    meta.description,
+    '',
+    'Options:',
+  ];
+  const all = { ...(meta.flags ?? {}), ...HARNESS_FLAGS };
+  const longest = Math.max(...Object.keys(all).map((k) => k.length + 2));
+  for (const [name, def] of Object.entries(all)) {
+    const long = `--${name}`;
+    const short = /** @type {any} */ (def).short ? `, -${/** @type {any} */ (def).short}` : '';
+    lines.push(`  ${long}${short}`.padEnd(longest + 6) + (def.type === 'string' ? '<value>' : ''));
+  }
+  lines.push('');
+  lines.push('Exit codes: 0 ok, 1 validation failure, 2 env error, 64 usage error.');
+  return lines.join('\n');
+}

package/plugins/harness/src/lib/debug.mjs

@@ -0,0 +1,37 @@
+/**
+ * Debug logger gated on `HARNESS_DEBUG=1`.
+ *
+ * Replaces silent `catch` blocks in `spec-harness-lib.mjs:28-29` and `:184-186`
+ * (legacy behavior) with opt-in diagnostic output. When the env flag is unset,
+ * `debug()` is a no-op — zero runtime cost in normal operation.
+ *
+ * Usage:
+ *   } catch (err) {
+ *     debug('git:rev-parse', err.message);
+ *     return null;
+ *   }
+ *
+ * @param {string} tag
+ * @param {...unknown} args
+ * @returns {void}
+ */
+export function debug(tag, ...args) {
+  if (process.env.HARNESS_DEBUG !== '1') return;
+  process.stderr.write(`[harness:${tag}] ${args.map(stringify).join(' ')}\n`);
+}
+
+/** @returns {boolean} */
+export function isDebug() {
+  return process.env.HARNESS_DEBUG === '1';
+}
+
+/** @param {unknown} v */
+function stringify(v) {
+  if (v instanceof Error) return v.stack ?? v.message;
+  if (typeof v === 'string') return v;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

package/plugins/harness/src/lib/errors.mjs

@@ -0,0 +1,147 @@
+/**
+ * Structured error taxonomy for every harness validator.
+ *
+ * Every validator emits instances of `ValidationError` rather than raw strings.
+ * This gives consumers a machine-parseable `.code`, `.file`, and `.pointer`
+ * while keeping `.toString()` readable for human-first CLI output.
+ *
+ * @typedef {object} StructuredError
+ * @property {string} code      Stable enum value (see `ERROR_CODES`). Never rename.
+ * @property {string} message   Human-readable one-liner. May contain identifier names.
+ * @property {string} [file]    Repo-relative path where the error was detected.
+ * @property {string} [pointer] JSON Pointer or dotted key when the error is inside a structured file.
+ * @property {number} [line]    1-indexed line number when available.
+ * @property {string} [expected] Text describing what the validator expected.
+ * @property {string} [got]      Text describing what was observed.
+ * @property {string} [hint]     Actionable remediation suggestion.
+ * @property {'spec'|'skill'|'manifest'|'coverage'|'drift'|'scaffold'|'settings'|'env'|'usage'} [category]
+ */
+
+/**
+ * Stable error codes. Consumers may match on these; renames are breaking changes.
+ */
+export const ERROR_CODES = Object.freeze({
+  // spec
+  SPEC_JSON_INVALID: 'SPEC_JSON_INVALID',
+  SPEC_STATUS_INVALID: 'SPEC_STATUS_INVALID',
+  SPEC_MISSING_REQUIRED_FIELD: 'SPEC_MISSING_REQUIRED_FIELD',
+  SPEC_ID_MISMATCH: 'SPEC_ID_MISMATCH',
+  SPEC_LINKED_PATH_MISSING: 'SPEC_LINKED_PATH_MISSING',
+  SPEC_ACCEPTANCE_EMPTY: 'SPEC_ACCEPTANCE_EMPTY',
+  SPEC_DEPENDENCY_UNKNOWN: 'SPEC_DEPENDENCY_UNKNOWN',
+  // skill
+  SKILL_FRONTMATTER_MISSING: 'SKILL_FRONTMATTER_MISSING',
+  SKILL_NAME_MISMATCH: 'SKILL_NAME_MISMATCH',
+  // manifest
+  MANIFEST_CHECKSUM_MISMATCH: 'MANIFEST_CHECKSUM_MISMATCH',
+  MANIFEST_ENTRY_MISSING: 'MANIFEST_ENTRY_MISSING',
+  MANIFEST_ORPHAN_FILE: 'MANIFEST_ORPHAN_FILE',
+  MANIFEST_DEPENDENCY_CYCLE: 'MANIFEST_DEPENDENCY_CYCLE',
+  // coverage
+  COVERAGE_UNCOVERED: 'COVERAGE_UNCOVERED',
+  COVERAGE_NO_SPEC_RATIONALE: 'COVERAGE_NO_SPEC_RATIONALE',
+  COVERAGE_UNKNOWN_SPEC_ID: 'COVERAGE_UNKNOWN_SPEC_ID',
+  // drift
+  DRIFT_TEAM_COUNT: 'DRIFT_TEAM_COUNT',
+  DRIFT_PROTECTED_PATH: 'DRIFT_PROTECTED_PATH',
+  DRIFT_INSTRUCTION_FILES: 'DRIFT_INSTRUCTION_FILES',
+  DRIFT_INSTRUCTION_FILE_MISSING: 'DRIFT_INSTRUCTION_FILE_MISSING',
+  // scaffold
+  SCAFFOLD_CONFLICT: 'SCAFFOLD_CONFLICT',
+  SCAFFOLD_USAGE: 'SCAFFOLD_USAGE',
+  // settings / hooks (sh validator parity)
+  SETTINGS_SEC_1: 'SETTINGS_SEC_1',
+  SETTINGS_SEC_2: 'SETTINGS_SEC_2',
+  SETTINGS_SEC_3: 'SETTINGS_SEC_3',
+  SETTINGS_SEC_4: 'SETTINGS_SEC_4',
+  SETTINGS_OPS_1: 'SETTINGS_OPS_1',
+  SETTINGS_OPS_2: 'SETTINGS_OPS_2',
+  // env / usage
+  ENV_REPO_ROOT_UNKNOWN: 'ENV_REPO_ROOT_UNKNOWN',
+  ENV_FACTS_MISSING: 'ENV_FACTS_MISSING',
+  USAGE_UNKNOWN_FLAG: 'USAGE_UNKNOWN_FLAG',
+  USAGE_MISSING_POSITIONAL: 'USAGE_MISSING_POSITIONAL',
+});
+
+/**
+ * Structured validator error. Extends `Error` so existing `throw`/`catch`
+ * paths continue to work; extra properties give consumers a machine-parseable
+ * view.
+ */
+export class ValidationError extends Error {
+  /**
+   * @param {StructuredError} details
+   */
+  constructor(details) {
+    if (!details || typeof details !== 'object') {
+      throw new TypeError('ValidationError requires a StructuredError details object');
+    }
+    if (!details.code || typeof details.code !== 'string') {
+      throw new TypeError('ValidationError requires a non-empty `code`');
+    }
+    if (!details.message || typeof details.message !== 'string') {
+      throw new TypeError('ValidationError requires a non-empty `message`');
+    }
+    super(details.message);
+    this.name = 'ValidationError';
+    this.code = details.code;
+    if (details.file !== undefined) this.file = details.file;
+    if (details.pointer !== undefined) this.pointer = details.pointer;
+    if (details.line !== undefined) this.line = details.line;
+    if (details.expected !== undefined) this.expected = details.expected;
+    if (details.got !== undefined) this.got = details.got;
+    if (details.hint !== undefined) this.hint = details.hint;
+    if (details.category !== undefined) this.category = details.category;
+  }
+
+  /**
+   * Legacy string format: `"<file>: <message>"` so existing tests and CI
+   * pipelines that regex on stderr continue to work unchanged.
+   * @returns {string}
+   */
+  toString() {
+    return this.file ? `${this.file}: ${this.message}` : this.message;
+  }
+
+  /**
+   * JSON-safe representation for `--json` output.
+   * @returns {StructuredError}
+   */
+  toJSON() {
+    /** @type {StructuredError} */
+    const out = { code: this.code, message: this.message };
+    if (this.file !== undefined) out.file = this.file;
+    if (this.pointer !== undefined) out.pointer = this.pointer;
+    if (this.line !== undefined) out.line = this.line;
+    if (this.expected !== undefined) out.expected = this.expected;
+    if (this.got !== undefined) out.got = this.got;
+    if (this.hint !== undefined) out.hint = this.hint;
+    if (this.category !== undefined) out.category = this.category;
+    return out;
+  }
+}
+
+/**
+ * Render a single error for human-readable CLI output. Mirrors the
+ * `✗ <message>` prefix style used by `plugins/harness/scripts/validate-settings.sh:43-45`.
+ *
+ * @param {ValidationError | StructuredError | Error} err
+ * @param {{ verbose?: boolean }} [opts]
+ * @returns {string}
+ */
+export function formatError(err, opts = {}) {
+  const verbose = Boolean(opts.verbose);
+  const prefix = err.file ? `${err.file}: ` : '';
+  const head = `${prefix}${err.message ?? String(err)}`;
+  if (!verbose) return head;
+
+  const tail = [];
+  if (err.code) tail.push(`  code:     ${err.code}`);
+  if (err.pointer !== undefined) tail.push(`  pointer:  ${err.pointer}`);
+  if (err.line !== undefined) tail.push(`  line:     ${err.line}`);
+  if (err.expected !== undefined) tail.push(`  expected: ${err.expected}`);
+  if (err.got !== undefined) tail.push(`  got:      ${err.got}`);
+  if (err.hint !== undefined) tail.push(`  hint:     ${err.hint}`);
+  if (err.category !== undefined) tail.push(`  category: ${err.category}`);
+  return tail.length > 0 ? `${head}\n${tail.join('\n')}` : head;
+}

package/plugins/harness/src/lib/exit-codes.mjs

@@ -0,0 +1,18 @@
+/**
+ * Named exit code enum for every harness bin.
+ *
+ * Convention:
+ * - 0 OK           — success
+ * - 1 VALIDATION   — one or more validation rules failed (the expected failure mode)
+ * - 2 ENV          — misconfigured environment (missing file, bad git repo, unreadable facts)
+ * - 64 USAGE       — bad CLI invocation (unknown flag, missing required positional)
+ *
+ * 64 mirrors BSD sysexits.h EX_USAGE so operators can distinguish user error
+ * from a real validation failure in CI pipelines.
+ */
+export const EXIT_CODES = Object.freeze({
+  OK: 0,
+  VALIDATION: 1,
+  ENV: 2,
+  USAGE: 64,
+});

package/plugins/harness/src/lib/output.mjs

@@ -0,0 +1,90 @@
+/**
+ * Shared CLI output primitives — the JS parity of
+ * `plugins/harness/scripts/validate-settings.sh:43-45`.
+ *
+ * Provides the same ✓/✗/⚠ format with ANSI coloring when the stream is a TTY,
+ * plus a `--json` buffer-and-flush mode so CI pipelines can consume a single
+ * JSON array of events instead of regexing stderr.
+ *
+ * @typedef {'pass'|'fail'|'warn'|'info'} OutputKind
+ *
+ * @typedef {object} OutputEvent
+ * @property {OutputKind} kind
+ * @property {string} message
+ * @property {object} [details]  Optional structured payload (e.g. `ValidationError.toJSON()`).
+ *
+ * @typedef {object} Output
+ * @property {(msg: string) => void} pass
+ * @property {(msg: string, details?: object) => void} fail
+ * @property {(msg: string, details?: object) => void} warn
+ * @property {(msg: string) => void} info
+ * @property {() => void} flush          Emit buffered JSON when in json mode. No-op otherwise.
+ * @property {() => { fail: number, warn: number, pass: number }} counts
+ *
+ * @typedef {object} OutputOptions
+ * @property {boolean} [json]     When true, buffer events and emit a JSON array on flush().
+ * @property {boolean} [noColor]  When true, suppress ANSI escapes regardless of TTY.
+ * @property {NodeJS.WritableStream} [stream]  Defaults to process.stdout.
+ * @property {NodeJS.ProcessEnv} [env]         Defaults to process.env.
+ */
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+/**
+ * Construct an `Output` with the given behavior flags.
+ *
+ * @param {OutputOptions} [opts]
+ * @returns {Output}
+ */
+export function createOutput(opts = {}) {
+  const env = opts.env ?? process.env;
+  const stream = opts.stream ?? process.stdout;
+  const json = Boolean(opts.json);
+  const noColor = Boolean(opts.noColor) || 'NO_COLOR' in env;
+  const useAnsi = !json && !noColor && Boolean(stream.isTTY);
+
+  const counts = { pass: 0, fail: 0, warn: 0 };
+  /** @type {OutputEvent[]} */
+  const buffer = [];
+
+  const color = (code, text) => (useAnsi ? `${code}${text}${RESET}` : text);
+
+  /**
+   * @param {OutputKind} kind
+   * @param {string} message
+   * @param {object} [details]
+   */
+  const emit = (kind, message, details) => {
+    if (kind === 'pass') counts.pass++;
+    else if (kind === 'fail') counts.fail++;
+    else if (kind === 'warn') counts.warn++;
+    if (json) {
+      /** @type {OutputEvent} */
+      const event = { kind, message };
+      if (details !== undefined) event.details = details;
+      buffer.push(event);
+      return;
+    }
+    let glyph;
+    if (kind === 'pass') glyph = color(GREEN, '✓');
+    else if (kind === 'fail') glyph = color(RED, '✗');
+    else if (kind === 'warn') glyph = color(YELLOW, '⚠');
+    else glyph = ' ';
+    stream.write(`  ${glyph} ${message}\n`);
+  };
+
+  return {
+    pass: (msg) => emit('pass', msg),
+    fail: (msg, details) => emit('fail', msg, details),
+    warn: (msg, details) => emit('warn', msg, details),
+    info: (msg) => emit('info', msg),
+    flush: () => {
+      if (!json) return;
+      stream.write(JSON.stringify({ events: buffer, counts }, null, 2) + '\n');
+    },
+    counts: () => ({ ...counts }),
+  };
+}