gstack/bin/gstack-learnings-log

#!/usr/bin/env bash
# gstack-learnings-log — append a learning to the project learnings file
# Usage: gstack-learnings-log --help
# Valid types: pattern, pitfall, preference, architecture, tool, operational, investigation
#
# Append-only storage. Duplicates (same key+type) are resolved at read time
# by gstack-learnings-search ("latest winner" per key+type).
# Heredoc delivery guard: bash 5.2+ pipes heredoc bodies <=64KiB, and on
# macOS a starved 512-byte pipe hangs bodies >=512B at startup. Compat level
# 50 restores the tempfile path (test/heredoc-pipe-deadlock.test.ts).
BASH_COMPAT=50
set -euo pipefail
GSTACK_BUN_CONFIG=/dev/null; case "${OSTYPE:-}" in msys*|cygwin*) if command -v cygpath >/dev/null 2>&1; then GSTACK_BUN_CONFIG=NUL; fi ;; esac

usage() {
  cat <<'EOF'
Usage: gstack-learnings-log '<json>'
       gstack-learnings-log --help

Appends one learning to this project's learnings.jsonl (append-only; the latest entry per key+type wins).
  {"skill":"<skill>","type":"<type>","key":"<kebab-key>","insight":"<one sentence>","confidence":<1-10>,
   "source":"<source>","files":["<path>"]}
  type     pattern pitfall preference architecture tool operational investigation
  key      letters, digits, - and _ only
  source   observed user-stated inferred cross-model (optional; user-stated marks it trusted)
  files    optional
Read learnings back with gstack-learnings-search.
EOF
}

case "${1:-}" in
  -h|--help) usage; exit 0 ;;
  "") usage >&2; exit 2 ;;
  -*) echo "gstack-learnings-log: unknown argument '$1'; pass one JSON object, or --help" >&2; exit 2 ;;
esac
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Windows git-bash (#1950): pwd yields a POSIX path (/c/Users/...), which Bun
# on Windows cannot resolve as an ES module specifier in the import below.
# cygpath -m converts to C:/Users/... which Bun accepts.
case "$(uname -s)" in
  MINGW*|MSYS*|CYGWIN*) command -v cygpath >/dev/null 2>&1 && SCRIPT_DIR="$(cygpath -m "$SCRIPT_DIR")" ;;
esac
eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
. "$(dirname "$0")/gstack-state-root.sh" 2>/dev/null || { echo "$0: cannot resolve the gstack state root: $(dirname "$0")/gstack-state-root.sh is missing. fix: reinstall with ./setup or /gstack-upgrade (docs/state-root.md)" >&2; exit 1; }
gstack_state_root_select
GSTACK_HOME="$_gstack_sr_root"
mkdir -p "$GSTACK_HOME/projects/$SLUG"

INPUT="$1"

# Validate and sanitize input. Errors surface (#1950): stderr is captured and
# printed on failure instead of swallowed — a silent exit 1 here cost Windows
# users every AI-logged learning.
TMPERR=$(mktemp "${TMPDIR:-/tmp}/gstack-learnings-log.XXXXXX") || { echo "gstack-learnings-log: could not create a temp file in ${TMPDIR:-/tmp}, so the learning was not recorded. Fix: point TMPDIR at a writable directory." >&2; exit 1; }
trap 'rm -f "$TMPERR"' EXIT
set +e
VALIDATED=$(printf '%s' "$INPUT" | GSTACK_LIB_DIR="$SCRIPT_DIR/../lib" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "
const { hasInjection } = await import(process.env.GSTACK_LIB_DIR + '/jsonl-store.ts');
const raw = await Bun.stdin.text();
let j;
try { j = JSON.parse(raw); } catch { process.stderr.write('gstack-learnings-log: invalid JSON, skipping\n'); process.exit(1); }

// Field validation: type must be from allowed list
const ALLOWED_TYPES = ['pattern', 'pitfall', 'preference', 'architecture', 'tool', 'operational', 'investigation'];
if (!j.type || !ALLOWED_TYPES.includes(j.type)) {
  process.stderr.write('gstack-learnings-log: invalid type \"' + (j.type || '') + '\", must be one of: ' + ALLOWED_TYPES.join(', ') + '\n');
  process.exit(1);
}

// Field validation: key must be alphanumeric, hyphens, underscores (no injection surface)
if (!j.key || !/^[a-zA-Z0-9_-]+$/.test(j.key)) {
  process.stderr.write('gstack-learnings-log: invalid key, must be alphanumeric with hyphens/underscores only\n');
  process.exit(1);
}

// Field validation: confidence must be 1-10
const conf = Number(j.confidence);
if (!Number.isInteger(conf) || conf < 1 || conf > 10) {
  process.stderr.write('gstack-learnings-log: confidence must be integer 1-10\n');
  process.exit(1);
}
j.confidence = conf;

// Field validation: source must be from allowed list
const ALLOWED_SOURCES = ['observed', 'user-stated', 'inferred', 'cross-model'];
if (j.source && !ALLOWED_SOURCES.includes(j.source)) {
  process.stderr.write('gstack-learnings-log: invalid source, must be one of: ' + ALLOWED_SOURCES.join(', ') + '\n');
  process.exit(1);
}

// Content sanitization: shared injection patterns (lib/jsonl-store.ts, D2A) —
// one audited list across learnings + decisions, no drift.
if (j.insight && hasInjection(j.insight)) {
  process.stderr.write('gstack-learnings-log: insight contains suspicious instruction-like content, rejected\n');
  process.exit(1);
}

// Inject timestamp if not present
if (!j.ts) j.ts = new Date().toISOString();

// Mark trust level based on source
// user-stated = user explicitly told the agent this. All others are AI-generated.
j.trusted = j.source === 'user-stated';

console.log(JSON.stringify(j));
" 2>"$TMPERR")
VALIDATE_RC=$?
set -e

if [ $VALIDATE_RC -ne 0 ] || [ -z "$VALIDATED" ]; then
  if [ -s "$TMPERR" ]; then
    cat "$TMPERR" >&2
  fi
  exit 1
fi

echo "$VALIDATED" >> "$GSTACK_HOME/projects/$SLUG/learnings.jsonl"

# gbrain-sync: enqueue for cross-machine sync (no-op if sync is off).
"$SCRIPT_DIR/gstack-brain-enqueue" "projects/$SLUG/learnings.jsonl" 2>/dev/null &