@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate/scripts/comate-lib.sh

@@ -1,559 +0,0 @@
-#!/bin/bash
-# comate-lib.sh — shared library for comate (sourced, never executed directly)
-#
-# Single source of truth for: YAML flat read/write, field-order template + enums,
-# hashing, logging, exit-code contract. Other scripts `source` this file.
-#
-# - all YAML logic lives here
-# - .comate.yaml is a declared flat `key: value` subset; validate_flat_yaml enforces it.
-# - yaml_set does full-rewrite + atomic mv + write-back verification.
-# - stable exit codes — 0 OK | 1 BLOCK | 2 USAGE | 3 ENV | 4 CORRUPT.
-#
-# This file MUST NOT set `set -e` / `set -u`: it is sourced into hosts that
-# manage their own shell options.
-
-# --- Exit-code contract ---
-readonly COMATE_OK=0
-readonly COMATE_BLOCK=1
-readonly COMATE_USAGE=2
-readonly COMATE_ENV=3
-readonly COMATE_CORRUPT=4
-
-# --- Color logging on stderr ---
-_comate_color() {
-  # $1 = ansi code, $2 = message
-  if [ -t 2 ]; then
-    printf '\033[%sm%s\033[0m\n' "$1" "$2" >&2
-  else
-    printf '%s\n' "$2" >&2
-  fi
-}
-log_pass() { _comate_color "32" "$1"; }
-log_fail() { _comate_color "31" "$1"; }
-log_warn() { _comate_color "33" "$1"; }
-log_info() { _comate_color "36" "$1"; }
-
-# die <code> <msg> — print red error to stderr and exit with the given code.
-die() {
-  local code="$1"
-  shift
-  _comate_color "31" "$*"
-  exit "$code"
-}
-
-# --- Canonical field order ---
-# Every yaml_set rewrites the whole file in this order, so diffs stay stable
-# and duplicate keys are impossible.
-# Three-place sync rule: a new field must be added here, in ENUMS (if enum),
-# and in the bats yaml fixtures.
-FIELD_ORDER=(
-  schema_version
-  workflow
-  phase
-  phase_step
-  phase_step_data
-  build_mode
-  tdd_mode
-  isolation
-  verify_mode
-  verify_result
-  design_doc
-  plan
-  verification_report
-  branch_status
-  handoff_context
-  handoff_hash
-  impl_context
-  impl_hash
-  direct_override
-  base_ref
-  base_branch
-  source_kind
-  source_manifest
-  build_command
-  verify_command
-  created_at
-  verified_at
-  archived
-)
-
-# Current schema version written by `state init`.
-readonly COMATE_SCHEMA_VERSION=1
-
-# --- Enum tables ---
-# Keep these as case-based lookups instead of associative arrays. macOS ships
-# Bash 3.2, which has normal arrays but not `declare -A`.
-enum_keys() {
-  printf '%s\n' \
-    schema_version workflow phase build_mode tdd_mode isolation verify_mode \
-    verify_result branch_status direct_override archived source_kind
-}
-
-enum_values() {
-  case "$1" in
-    schema_version)  printf '%s\n' '1' ;;
-    workflow)        printf '%s\n' 'full fix' ;;
-    phase)           printf '%s\n' 'open design build verify archive' ;;
-    build_mode)      printf '%s\n' 'subagent-driven-development executing-plans direct' ;;
-    tdd_mode)        printf '%s\n' 'tdd direct' ;;
-    isolation)       printf '%s\n' 'branch worktree' ;;
-    verify_mode)     printf '%s\n' 'light full' ;;
-    verify_result)   printf '%s\n' 'pending pass fail' ;;
-    branch_status)   printf '%s\n' 'pending handled discarded' ;;
-    direct_override) printf '%s\n' 'true false' ;;
-    archived)        printf '%s\n' 'true false' ;;
-    source_kind)     printf '%s\n' 'conversation file' ;;
-    *) return 1 ;;
-  esac
-}
-
-# Keys whose values are free-form (paths, dates, commands, hashes, refs).
-# Listed as a case lookup so unknown fields can still be rejected on Bash 3.2.
-is_freeform_key() {
-  case "$1" in
-    design_doc|plan|verification_report|handoff_context|handoff_hash|\
-    impl_context|impl_hash|base_ref|base_branch|source_manifest|\
-    build_command|verify_command|created_at|verified_at|phase_step|phase_step_data)
-      return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-# --- Path location ---
-
-# comate_change_dir <name> — echo the change directory, preferring the active
-# location but falling back to archive/ if that is where it lives.
-comate_change_dir() {
-  local name="$1"
-  if [ -d "openspec/changes/$name" ]; then
-    echo "openspec/changes/$name"
-  elif [ -d "openspec/changes/archive/$name" ]; then
-    echo "openspec/changes/archive/$name"
-  else
-    echo "openspec/changes/$name"
-  fi
-}
-
-# comate_yaml_for <name> — echo path to that change's .comate.yaml.
-comate_yaml_for() {
-  echo "$(comate_change_dir "$1")/.comate.yaml"
-}
-
-# --- Input validation ---
-
-# validate_change_name <name> — only [A-Za-z0-9_-]; reject empty and `..`.
-validate_change_name() {
-  local name="$1"
-  if [ -z "$name" ]; then
-    die "$COMATE_USAGE" "ERROR: change name cannot be empty"
-  fi
-  if [[ "$name" == *..* ]]; then
-    die "$COMATE_USAGE" "ERROR: change name cannot contain '..' (path traversal not allowed): '$name'"
-  fi
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    die "$COMATE_USAGE" "ERROR: invalid change name '$name' (allowed: a-z A-Z 0-9 - _)"
-  fi
-}
-
-# validate_enum <key> <value> — die if value not legal for an enum key.
-# Free-form keys and unlisted keys pass through. null/empty always allowed.
-validate_enum() {
-  local key="$1" value="$2"
-  local legal
-  legal=$(enum_values "$key" 2>/dev/null) || legal=""
-  [ -z "$legal" ] && return 0
-  [ -z "$value" ] && return 0
-  [ "$value" = "null" ] && return 0
-  local v
-  for v in $legal; do
-    [ "$value" = "$v" ] && return 0
-  done
-  die "$COMATE_USAGE" "ERROR: invalid value '$value' for '$key' (expected: $legal)"
-}
-
-# --- YAML read (single implementation) ---
-
-# _strip_inline_comment — drop a ` #...` comment that is not inside quotes.
-_strip_inline_comment() {
-  printf '%s\n' "$1" | awk -v squote="'" '
-    {
-      out = ""; quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) { quote = c }
-          else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out); print out; next
-          }
-        } else if (c == quote) { quote = "" }
-        out = out c
-      }
-      print out
-    }'
-}
-
-# _strip_wrapping_quotes — remove a single pair of wrapping quotes.
-_strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
-    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
-    *)     printf '%s\n' "$value" ;;
-  esac
-}
-
-# yaml_get <file> <key> — echo the value (comment/quote-stripped), empty if absent.
-yaml_get() {
-  local file="$1" key="$2"
-  [ -f "$file" ] || return 0
-  local value
-  value=$(grep "^${key}:" "$file" 2>/dev/null | head -1 | sed "s/^${key}:[[:space:]]*//" || true)
-  value=$(_strip_inline_comment "$value")
-  _strip_wrapping_quotes "$value"
-}
-
-# yaml_keys <file> — list all top-level keys, one per line.
-yaml_keys() {
-  local file="$1"
-  [ -f "$file" ] || return 0
-  grep -E '^[A-Za-z0-9_-]+:' "$file" 2>/dev/null | sed 's/:.*//' || true
-}
-
-# validate_flat_yaml <file> — enforce that .comate.yaml is the
-# declared subset: top-level `key: value` scalars plus `#` comments only.
-# Reject indented lines, list items, block/flow collections. die(CORRUPT) on violation.
-validate_flat_yaml() {
-  local file="$1"
-  [ -f "$file" ] || die "$COMATE_CORRUPT" "ERROR: state file not found: $file"
-  local lineno=0 line
-  while IFS= read -r line || [ -n "$line" ]; do
-    lineno=$((lineno + 1))
-    # Allow blank lines and full-line comments.
-    case "$line" in
-      "" ) continue ;;
-    esac
-    if [[ "$line" =~ ^[[:space:]]*# ]]; then
-      continue
-    fi
-    # Reject leading whitespace (nesting / continuation / list under a key).
-    if [[ "$line" =~ ^[[:space:]]+ ]]; then
-      die "$COMATE_CORRUPT" "ERROR: $file:$lineno indented line not allowed (flat key:value only): $line"
-    fi
-    # Reject top-level list items.
-    if [[ "$line" =~ ^- ]]; then
-      die "$COMATE_CORRUPT" "ERROR: $file:$lineno list item not allowed (flat key:value only): $line"
-    fi
-    # Require a `key: value` shape.
-    if [[ ! "$line" =~ ^[A-Za-z0-9_-]+: ]]; then
-      die "$COMATE_CORRUPT" "ERROR: $file:$lineno not a 'key: value' line: $line"
-    fi
-    # Reject values that open a block scalar (| or >).
-    local val
-    val=$(printf '%s\n' "$line" | sed 's/^[A-Za-z0-9_-]*:[[:space:]]*//')
-    val=$(_strip_inline_comment "$val")
-    case "$val" in
-      "|"|">"|"|-"|">-"|"|+"|">+")
-        die "$COMATE_CORRUPT" "ERROR: $file:$lineno block scalar not allowed (flat key:value only): $line" ;;
-    esac
-  done < "$file"
-  return 0
-}
-
-# --- YAML write (full rewrite + atomic mv + write-back check) ---
-
-# yaml_set <file> <key> <value> — validate enum, read whole file, set key in
-# memory, rewrite every field in FIELD_ORDER to a temp file, atomically mv into
-# place, then read back and confirm the value matches.
-yaml_set() {
-  local file="$1" key="$2" value="$3"
-  [ -f "$file" ] || die "$COMATE_CORRUPT" "ERROR: state file not found: $file"
-
-  # Reject keys we do not know about (prevents silent typo fields).
-  if ! enum_values "$key" >/dev/null 2>&1 && ! is_freeform_key "$key" && [ "$key" != "schema_version" ]; then
-    die "$COMATE_USAGE" "ERROR: unknown field '$key'"
-  fi
-  validate_enum "$key" "$value"
-
-  local tmp
-  tmp=$(mktemp "${TMPDIR:-/tmp}/comate.XXXXXX") || die "$COMATE_ENV" "ERROR: mktemp failed"
-  {
-    printf '# comate state — flat key:value only, no nesting\n'
-    local k
-    for k in "${FIELD_ORDER[@]}"; do
-      local current
-      if [ "$k" = "$key" ]; then
-        current="$value"
-      else
-        current=$(yaml_get "$file" "$k")
-      fi
-      [ -z "$current" ] && current="null"
-      printf '%s: %s\n' "$k" "$current"
-    done
-  } > "$tmp"
-
-  mv "$tmp" "$file" || { rm -f "$tmp"; die "$COMATE_ENV" "ERROR: failed to replace $file"; }
-
-  # Write-back verification.
-  local readback
-  readback=$(yaml_get "$file" "$key")
-  if [ "$readback" != "$value" ]; then
-    die "$COMATE_CORRUPT" "ERROR: write-back mismatch for '$key': wrote '$value', read '$readback'"
-  fi
-}
-
-# --- Hashing (cross-platform) ---
-
-# _hash_stream — sha256 of stdin, hex only.
-_hash_stream() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 | awk '{print $1}'
-  else
-    die "$COMATE_ENV" "ERROR: sha256sum or shasum is required"
-  fi
-}
-
-# _hash_file_stream <file> - emit canonical content for hashing.
-# Text files are normalized to LF so a checkout/tool that temporarily writes
-# CRLF cannot create a false provenance or impl_hash drift. Binary files stay
-# byte-for-byte unchanged.
-_hash_file_stream() {
-  local file="$1"
-  if [ ! -s "$file" ] || LC_ALL=C grep -Iq . "$file" 2>/dev/null; then
-    sed 's/\r$//' "$file"
-  else
-    cat "$file"
-  fi
-}
-
-# hash_file <file> - sha256 hex of one file (LF-canonical for text).
-hash_file() {
-  local file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    _hash_file_stream "$file" | sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    _hash_file_stream "$file" | shasum -a 256 | awk '{print $1}'
-  else
-    die "$COMATE_ENV" "ERROR: sha256sum or shasum is required"
-  fi
-}
-
-# hash_files_manifest <file...> — for each existing file emit `path:`/`sha256:`
-# lines, then hash the whole manifest. Order-stable, missing files skipped.
-hash_files_manifest() {
-  local f
-  for f in "$@"; do
-    if [ -f "$f" ]; then
-      printf 'path:%s\n' "$f"
-      printf 'sha256:%s\n' "$(hash_file "$f")"
-    fi
-  done | _hash_stream
-}
-
-# file_nonempty <path>
-file_nonempty() { [ -f "$1" ] && [ -s "$1" ]; }
-
-# --- Source tracking (knowledge-base provenance) ---
-
-# comate_kb_root — repo-relative root under which source files may be tracked.
-comate_kb_root() { echo "docs/knowledge-base"; }
-
-# _abs_path <path> — absolute, symlink-resolved path; empty + non-zero if it
-# cannot be resolved. realpath/readlink -f preferred; dir-level fallback otherwise.
-_abs_path() {
-  local p="$1"
-  if command -v realpath >/dev/null 2>&1; then
-    realpath "$p" 2>/dev/null
-  elif command -v readlink >/dev/null 2>&1 && readlink -f "$p" >/dev/null 2>&1; then
-    readlink -f "$p" 2>/dev/null
-  else
-    local dir base
-    dir=$(dirname "$p"); base=$(basename "$p")
-    ( cd "$dir" 2>/dev/null && printf '%s/%s\n' "$(pwd -P)" "$base" )
-  fi
-}
-
-# validate_kb_path <path> — echo the repo-relative path if it resolves to an
-# existing file under the knowledge-base root, else echo nothing and return 1.
-# Rejects '..' traversal, absolute/repo-external paths, and symlink escapes.
-validate_kb_path() {
-  local raw="$1" root_abs target_abs cwd
-  [ -n "$raw" ] || return 1
-  case "$raw" in *..*) return 1 ;; esac
-  [ -f "$raw" ] || return 1
-  root_abs=$(_abs_path "$(comate_kb_root)") || return 1
-  [ -n "$root_abs" ] || return 1
-  target_abs=$(_abs_path "$raw") || return 1
-  [ -n "$target_abs" ] || return 1
-  case "$target_abs" in
-    "$root_abs"/*) ;;
-    *) return 1 ;;
-  esac
-  cwd=$(_abs_path .) || return 1
-  printf '%s\n' "${target_abs#"$cwd"/}"
-}
-
-# sources_manifest_for <name> — echo path to a change's source manifest.
-sources_manifest_for() {
-  echo "$(comate_change_dir "$1")/.comate/sources.manifest"
-}
-
-# sources_manifest_paths <manifest> — list recorded `path:` values, one per line.
-sources_manifest_paths() {
-  local m="$1"
-  [ -f "$m" ] || return 0
-  grep '^path:' "$m" 2>/dev/null | sed 's/^path://' || true
-}
-
-# sources_drift <manifest> — recompute sha256 for each recorded path and compare
-# against the manifest. Echo human-readable detail; return COMATE_OK if all
-# match, COMATE_BLOCK on drift/missing file, COMATE_CORRUPT on malformed entries.
-sources_drift() {
-  local m="$1" path="" recorded="" rc=0 line actual
-  [ -f "$m" ] || { echo "manifest not found: $m"; return "$COMATE_CORRUPT"; }
-  while IFS= read -r line || [ -n "$line" ]; do
-    case "$line" in
-      path:*)   path="${line#path:}" ;;
-      sha256:*)
-        recorded="${line#sha256:}"
-        if [ -z "$path" ]; then echo "manifest corrupt: sha256 with no preceding path"; return "$COMATE_CORRUPT"; fi
-        if [ ! -f "$path" ]; then
-          echo "source file missing: $path"; rc=1
-        else
-          actual=$(hash_file "$path")
-          if [ "$actual" != "$recorded" ]; then
-            echo "source drifted: $path"
-            echo "  recorded: $recorded"
-            echo "  actual:   $actual"
-            rc=1
-          fi
-        fi
-        ;;
-      ---|"") path=""; recorded="" ;;
-    esac
-  done < "$m"
-  [ "$rc" -eq 0 ] && return "$COMATE_OK"
-  return "$COMATE_BLOCK"
-}
-
-# json_escape <string> — escape backslash and double-quote for JSON values.
-json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
-
-# --- PRD gate (phase 0: quality gate + split) ---
-#
-# gate.yaml lives NEXT TO the PRD (<prd>.gate.yaml), not under openspec/changes,
-# so it has its own flat schema kept separate from the change .comate.yaml
-# FIELD_ORDER (mixing them would pollute every change state file with gate keys).
-# It is the machine truth for "may a change be spawned from this PRD"; the
-# markdown review report is the human-readable derivative.
-
-readonly GATE_SCHEMA_VERSION=1
-
-# Canonical field order for gate.yaml (same full-rewrite discipline as yaml_set).
-GATE_FIELD_ORDER=(
-  schema_version
-  prd_path
-  prd_hash
-  gate_status
-  score
-  blocking_open
-  review_report
-  spawned_changes
-  changes_map
-  gated_at
-  created_at
-)
-
-# gate_status is the only enum. `stale` is computed (hash mismatch) but also
-# storable so a detected-stale gate persists across runs.
-gate_enum_values() {
-  case "$1" in
-    schema_version) printf '%s\n' '1' ;;
-    gate_status)    printf '%s\n' 'reviewing blocked passed passed-with-tbd stale' ;;
-    *) return 1 ;;
-  esac
-}
-
-# gate_stem_for <prd> — derive the short stem used to name a PRD's gate.yaml
-# and review report. A conforming PRD file is `PRD-<NNN>-<title>.md`, whose
-# gate/report drop the title and key off `PRD-<NNN>` (so one dir with
-# PRD-001/PRD-002 gets PRD-001.gate.yaml / PRD-002.gate.yaml). Non-conforming
-# names (no PRD-NNN prefix) fall back to the full basename so callers still get
-# a stable, collision-free stem instead of an error.
-gate_stem_for() {
-  local base stem
-  base=$(basename "$1")
-  base="${base%.markdown}"
-  base="${base%.md}"
-  # Avoid a capture group in `[[ =~ ]]`: the old parser in macOS Bash 3.2
-  # treats an unquoted `(` as syntax before the conditional can run.
-  stem=$(printf '%s\n' "$base" | sed -n 's/^\([Pp][Rr][Dd]-[0-9][0-9]*\).*/\1/p')
-  if [ -n "$stem" ]; then
-    echo "$stem"
-  else
-    echo "$base"
-  fi
-}
-
-# gate_path_for <prd> — echo the gate.yaml path adjacent to the PRD.
-# Named `<stem>.gate.yaml` where stem is PRD-<NNN> (see gate_stem_for).
-gate_path_for() {
-  local prd="$1" dir stem
-  dir=$(dirname "$prd")
-  stem=$(gate_stem_for "$prd")
-  echo "${dir}/${stem}.gate.yaml"
-}
-
-# gate_report_for <prd> — echo the review report path (PRD same dir).
-# Named `<stem>-REVIEW.md` where stem is PRD-<NNN> (see gate_stem_for).
-gate_report_for() {
-  local prd="$1" dir stem
-  dir=$(dirname "$prd")
-  stem=$(gate_stem_for "$prd")
-  echo "${dir}/${stem}-REVIEW.md"
-}
-
-# gate_yaml_set <file> <key> <value> — gate-file analogue of yaml_set: validate
-# enum, read the whole file, set one key, rewrite every GATE_FIELD_ORDER field,
-# atomic mv, write-back verify.
-gate_yaml_set() {
-  local file="$1" key="$2" value="$3"
-  [ -f "$file" ] || die "$COMATE_CORRUPT" "ERROR: gate file not found: $file"
-
-  local known=0 k
-  for k in "${GATE_FIELD_ORDER[@]}"; do
-    [ "$k" = "$key" ] && { known=1; break; }
-  done
-  [ "$known" -eq 1 ] || die "$COMATE_USAGE" "ERROR: unknown gate field '$key'"
-
-  local legal
-  legal=$(gate_enum_values "$key" 2>/dev/null) || legal=""
-  if [ -n "$legal" ] && [ -n "$value" ] && [ "$value" != "null" ]; then
-    local ok=0 v
-    for v in $legal; do [ "$value" = "$v" ] && { ok=1; break; }; done
-    [ "$ok" -eq 1 ] || die "$COMATE_USAGE" "ERROR: invalid value '$value' for '$key' (expected: $legal)"
-  fi
-
-  local tmp
-  tmp=$(mktemp "${TMPDIR:-/tmp}/comate-gate.XXXXXX") || die "$COMATE_ENV" "ERROR: mktemp failed"
-  {
-    printf '# comate PRD gate — flat key:value only, no nesting\n'
-    for k in "${GATE_FIELD_ORDER[@]}"; do
-      local current
-      if [ "$k" = "$key" ]; then
-        current="$value"
-      else
-        current=$(yaml_get "$file" "$k")
-      fi
-      [ -z "$current" ] && current="null"
-      printf '%s: %s\n' "$k" "$current"
-    done
-  } > "$tmp"
-  mv "$tmp" "$file" || { rm -f "$tmp"; die "$COMATE_ENV" "ERROR: failed to replace $file"; }
-
-  local readback; readback=$(yaml_get "$file" "$key")
-  if [ "$readback" != "$value" ]; then
-    die "$COMATE_CORRUPT" "ERROR: gate write-back mismatch for '$key': wrote '$value', read '$readback'"
-  fi
-}