@house365/comate 0.1.0

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

@@ -0,0 +1,430 @@
+#!/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 (Comet duplicated it across 4 scripts).
+# - .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
+  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 table: key -> space-separated legal values ---
+declare -A ENUMS=(
+  [schema_version]="1"
+  [workflow]="full hotfix tweak"
+  [phase]="open design build verify archive"
+  [build_mode]="subagent-driven-development executing-plans direct"
+  [tdd_mode]="tdd direct"
+  [isolation]="branch worktree"
+  [verify_mode]="light full"
+  [verify_result]="pending pass fail"
+  [branch_status]="pending handled"
+  [direct_override]="true false"
+  [archived]="true false"
+  [source_kind]="conversation file"
+)
+
+# Keys whose values are free-form (paths, dates, commands, hashes, refs).
+# Listed so validate_change/validate can flag genuinely unknown keys.
+declare -A FREEFORM_KEYS=(
+  [design_doc]=1
+  [plan]=1
+  [verification_report]=1
+  [handoff_context]=1
+  [handoff_hash]=1
+  [impl_context]=1
+  [impl_hash]=1
+  [base_ref]=1
+  [base_branch]=1
+  [source_manifest]=1
+  [build_command]=1
+  [verify_command]=1
+  [created_at]=1
+  [verified_at]=1
+)
+
+# --- 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="${ENUMS[$key]:-}"
+  [ -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
+}
+
+# _yaml_read_all <file> <assoc-array-name> — load every known field into the
+# named associative array, defaulting missing fields to "null".
+_yaml_read_all() {
+  local file="$1" arrname="$2" k
+  for k in "${FIELD_ORDER[@]}"; do
+    local v
+    v=$(yaml_get "$file" "$k")
+    [ -z "$v" ] && v="null"
+    printf -v "${arrname}[$k]" '%s' "$v"
+  done
+}
+
+# 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 [ -z "${ENUMS[$key]:-}" ] && [ -z "${FREEFORM_KEYS[$key]:-}" ] && [ "$key" != "schema_version" ]; then
+    die "$COMATE_USAGE" "ERROR: unknown field '$key'"
+  fi
+  validate_enum "$key" "$value"
+
+  declare -A _cur
+  _yaml_read_all "$file" _cur
+  _cur[$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
+      printf '%s: %s\n' "$k" "${_cur[$k]:-null}"
+    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 <file> — sha256 hex of one file.
+hash_file() {
+  local file="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" | 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'; }