@rubytech/create-maxy-code 0.1.97 → 0.1.99

package/payload/platform/services/claude-session-manager/scripts/stash-cleanup.sh

@@ -0,0 +1,410 @@
+#!/usr/bin/env bash
+# Task 273 — one-time JSONL stash-composite cleanup.
+#
+# For each `<uuid>.<unix-ms>.jsonl` file under a CLAUDE_STATE_ROOT/projects
+# directory (top-level and archive/ subdir), pair it with the canonical
+# `<uuid>.jsonl`. Keep the larger of the two as the canonical; move the
+# smaller (with its sidecar) to QUARANTINE_ROOT, preserving the original
+# basename. If only the timestamped sibling exists (no canonical), promote
+# it to the canonical name. The quarantine path sits outside any directory
+# the fs-watcher scans, so quarantined files do not appear in the sidebar.
+#
+# Safety rails:
+#   1. Refuse to run if any PID file exists under CLAUDE_STATE_ROOT/sessions/.
+#      A live PTY holding one of the affected UUIDs is the failure mode this
+#      check guards against.
+#   2. Refuse to overwrite an existing quarantine target — if the same
+#      timestamped basename already sits in quarantine from a prior run,
+#      surface the conflict and skip rather than clobber.
+#   3. Sidecar `.meta.json` files follow the same disposition as their JSONL.
+#   4. A `.log` audit trail records every rename and quarantine move with
+#      from=, to=, bytes=, mtime=. The transcript is the operator's
+#      audit before approving permanent deletion in a follow-up task.
+#
+# Usage:
+#   stash-cleanup.sh <claude-state-root> [--dry-run]
+#     e.g. ~/.realagent-code/.claude
+#
+#   stash-cleanup.sh --self-test
+#     Seeds a temp dir with collision pairs, runs the cleanup against it,
+#     asserts post-conditions, and cleans up. Exits non-zero on failure.
+
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Task 273 JSONL stash-cleanup.
+
+Usage:
+  $0 <claude-state-root> [--dry-run]
+  $0 --self-test
+
+Arguments:
+  <claude-state-root>  e.g. ~/.realagent-code/.claude
+
+Flags:
+  --dry-run    Plan-only: log what would happen, change nothing on disk.
+  --self-test  Run the embedded smoke test; exits 0 on PASS.
+USAGE
+}
+
+log() { printf '[stash-cleanup] %s\n' "$*"; }
+err() { printf '[stash-cleanup] ERROR: %s\n' "$*" >&2; }
+
+# Returns 0 if the basename matches `<uuid>.<unix-ms>.jsonl`. UUID is
+# 36 chars including dashes; ms timestamp is exactly 13 digits.
+is_stash_composite_basename() {
+  local name="$1"
+  [[ "$name" =~ ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\.[0-9]{13}\.jsonl$ ]]
+}
+
+# Extract the canonical `<uuid>.jsonl` basename from a stash composite.
+canonical_basename_for() {
+  local stash="$1"
+  printf '%s.jsonl\n' "${stash:0:36}"
+}
+
+bytes_of() {
+  if [[ -f "$1" ]]; then
+    stat -f%z "$1" 2>/dev/null || stat -c%s "$1"
+  else
+    printf '0\n'
+  fi
+}
+
+mtime_of() {
+  if [[ -f "$1" ]]; then
+    stat -f%m "$1" 2>/dev/null || stat -c%Y "$1"
+  else
+    printf '0\n'
+  fi
+}
+
+# Move a JSONL file (and its sidecar if present) to quarantine, preserving
+# the original basename. Refuses to clobber.
+move_to_quarantine() {
+  local src="$1" qdir="$2" reason="$3"
+  local bn dst sidecar_src sidecar_dst
+  bn=$(basename "$src")
+  dst="$qdir/$bn"
+
+  if [[ -e "$dst" ]]; then
+    err "quarantine target already exists, skipping: $dst"
+    return 1
+  fi
+
+  local sz mt
+  sz=$(bytes_of "$src")
+  mt=$(mtime_of "$src")
+  if [[ "$DRY_RUN" == "yes" ]]; then
+    log "DRY quarantine reason=$reason from=$src to=$dst bytes=$sz mtime=$mt"
+  else
+    mkdir -p "$qdir"
+    mv "$src" "$dst"
+    log "quarantine reason=$reason from=$src to=$dst bytes=$sz mtime=$mt"
+  fi
+
+  # Sidecar follows: `<base>.meta.json` where <base> is the JSONL path minus
+  # the trailing `.jsonl`.
+  sidecar_src="${src%.jsonl}.meta.json"
+  sidecar_dst="${dst%.jsonl}.meta.json"
+  if [[ -f "$sidecar_src" ]]; then
+    if [[ -e "$sidecar_dst" ]]; then
+      err "sidecar quarantine target already exists, skipping: $sidecar_dst"
+      return 1
+    fi
+    local ssz smt
+    ssz=$(bytes_of "$sidecar_src")
+    smt=$(mtime_of "$sidecar_src")
+    if [[ "$DRY_RUN" == "yes" ]]; then
+      log "DRY quarantine-sidecar from=$sidecar_src to=$sidecar_dst bytes=$ssz mtime=$smt"
+    else
+      mv "$sidecar_src" "$sidecar_dst"
+      log "quarantine-sidecar from=$sidecar_src to=$sidecar_dst bytes=$ssz mtime=$smt"
+    fi
+  fi
+}
+
+# Promote `src` to `dst` by renaming. Sidecar follows.
+promote_in_place() {
+  local src="$1" dst="$2" reason="$3"
+  local sidecar_src sidecar_dst
+  local sz mt
+  sz=$(bytes_of "$src")
+  mt=$(mtime_of "$src")
+  if [[ "$DRY_RUN" == "yes" ]]; then
+    log "DRY promote reason=$reason from=$src to=$dst bytes=$sz mtime=$mt"
+  else
+    mv "$src" "$dst"
+    log "promote reason=$reason from=$src to=$dst bytes=$sz mtime=$mt"
+  fi
+
+  sidecar_src="${src%.jsonl}.meta.json"
+  sidecar_dst="${dst%.jsonl}.meta.json"
+  if [[ -f "$sidecar_src" ]]; then
+    local ssz smt
+    ssz=$(bytes_of "$sidecar_src")
+    smt=$(mtime_of "$sidecar_src")
+    if [[ "$DRY_RUN" == "yes" ]]; then
+      log "DRY promote-sidecar from=$sidecar_src to=$sidecar_dst bytes=$ssz mtime=$smt"
+    else
+      mv "$sidecar_src" "$sidecar_dst"
+      log "promote-sidecar from=$sidecar_src to=$sidecar_dst bytes=$ssz mtime=$smt"
+    fi
+  fi
+}
+
+# Process one directory (top-level or archive/). For each stash composite,
+# pair with canonical; resolve.
+process_dir() {
+  local dir="$1" qdir="$2"
+  [[ -d "$dir" ]] || { log "skip: $dir does not exist"; return 0; }
+
+  local handled=0
+  shopt -s nullglob
+  for path in "$dir"/*.jsonl; do
+    local bn
+    bn=$(basename "$path")
+    is_stash_composite_basename "$bn" || continue
+    handled=$((handled + 1))
+
+    local canonical_bn canonical_path
+    canonical_bn=$(canonical_basename_for "$bn")
+    canonical_path="$dir/$canonical_bn"
+
+    if [[ -f "$canonical_path" ]]; then
+      local stash_sz canonical_sz
+      stash_sz=$(bytes_of "$path")
+      canonical_sz=$(bytes_of "$canonical_path")
+      log "pair dir=$dir uuid=${bn:0:8} stash=$bn stash-bytes=$stash_sz canonical-bytes=$canonical_sz"
+
+      if (( stash_sz > canonical_sz )); then
+        # Stash wins. Quarantine canonical first (preserving its name),
+        # then promote stash to canonical.
+        local canonical_quarantine_name="$canonical_bn.canonical"
+        local canonical_qdst="$qdir/$canonical_quarantine_name"
+        if [[ -e "$canonical_qdst" ]]; then
+          err "canonical quarantine target exists, skipping pair: $canonical_qdst"
+          continue
+        fi
+        local csz cmt
+        csz=$(bytes_of "$canonical_path")
+        cmt=$(mtime_of "$canonical_path")
+        if [[ "$DRY_RUN" == "yes" ]]; then
+          log "DRY quarantine reason=smaller-canonical from=$canonical_path to=$canonical_qdst bytes=$csz mtime=$cmt"
+        else
+          mkdir -p "$qdir"
+          mv "$canonical_path" "$canonical_qdst"
+          log "quarantine reason=smaller-canonical from=$canonical_path to=$canonical_qdst bytes=$csz mtime=$cmt"
+        fi
+        # Canonical sidecar follows with the same suffix.
+        local csc_src="${canonical_path%.jsonl}.meta.json"
+        local csc_dst="${canonical_qdst%.jsonl}.meta.json"
+        if [[ -f "$csc_src" ]]; then
+          if [[ "$DRY_RUN" == "yes" ]]; then
+            log "DRY quarantine-sidecar from=$csc_src to=$csc_dst"
+          else
+            mv "$csc_src" "$csc_dst"
+            log "quarantine-sidecar from=$csc_src to=$csc_dst"
+          fi
+        fi
+        promote_in_place "$path" "$canonical_path" "stash-larger-than-canonical"
+      else
+        # Canonical wins (or equal). Quarantine stash with its original
+        # timestamped basename.
+        move_to_quarantine "$path" "$qdir" "smaller-stash" || true
+      fi
+    else
+      # No canonical on disk. Promote the stash to canonical.
+      log "lone-stash dir=$dir uuid=${bn:0:8} stash=$bn"
+      promote_in_place "$path" "$canonical_path" "no-canonical-present"
+    fi
+  done
+  shopt -u nullglob
+
+  log "summary dir=$dir composites-handled=$handled"
+}
+
+# Walks every project directory under <state-root>/projects/ and processes
+# top-level + archive/ for each.
+run_cleanup() {
+  local state_root="$1"
+  local projects_root="$state_root/projects"
+  local sessions_root="$state_root/sessions"
+  local quarantine_root="$state_root/quarantine"
+
+  [[ -d "$projects_root" ]] || { err "projects root not found: $projects_root"; return 2; }
+
+  # Pre-flight: no live PTY may be running. The sessions/ directory holds
+  # one PID file per live PTY (Task 199 contract); empty = no live PTYs.
+  if [[ -d "$sessions_root" ]]; then
+    shopt -s nullglob
+    local pids=("$sessions_root"/*.json)
+    shopt -u nullglob
+    if (( ${#pids[@]} > 0 )); then
+      err "live PTY detected — ${#pids[@]} PID file(s) under $sessions_root; refuse to touch on-disk state"
+      err "stop the affected sessions first, then retry"
+      return 3
+    fi
+  fi
+  log "pre-flight pid-files=0 sessions-root=$sessions_root"
+
+  shopt -s nullglob
+  local project_dirs=("$projects_root"/*/)
+  shopt -u nullglob
+  log "projects-found count=${#project_dirs[@]}"
+
+  for project_dir in "${project_dirs[@]}"; do
+    local slug
+    slug=$(basename "$project_dir")
+    local qdir="$quarantine_root/$slug"
+    log "project-begin slug=$slug"
+    process_dir "${project_dir%/}" "$qdir"
+    process_dir "${project_dir%/}/archive" "$qdir/archive"
+    log "project-end slug=$slug"
+  done
+
+  log "done state-root=$state_root quarantine-root=$quarantine_root dry-run=$DRY_RUN"
+}
+
+# ----- self-test --------------------------------------------------------
+
+self_test() {
+  local tmp
+  tmp=$(mktemp -d)
+  # Expand at trap-set time so the path survives function-local scope.
+  trap "rm -rf '$tmp'" EXIT
+
+  local state="$tmp/state"
+  mkdir -p "$state/projects/slug-A" "$state/projects/slug-A/archive" "$state/sessions"
+
+  # Pair 1: timestamped sibling is larger; should win.
+  local uuid1="4bfe4274-1111-4111-8111-111111111111"
+  local big="payload-big"
+  local small="x"
+  printf '%s' "$big" > "$state/projects/slug-A/${uuid1}.1779477697566.jsonl"
+  printf '%s' "$small" > "$state/projects/slug-A/${uuid1}.jsonl"
+
+  # Pair 2: canonical is larger; sibling loses.
+  local uuid2="9c26cc66-2222-4222-8222-222222222222"
+  printf '%s' "big-canonical" > "$state/projects/slug-A/${uuid2}.jsonl"
+  printf '%s' "tiny" > "$state/projects/slug-A/${uuid2}.1779477700000.jsonl"
+
+  # Pair 3 (archive): canonical wins (matches the be23f93a archive-pair shape).
+  local uuid3="654f5fe5-3333-4333-8333-333333333333"
+  printf '%s' "archived-big-history" > "$state/projects/slug-A/archive/${uuid3}.jsonl"
+  printf '%s' "tiny" > "$state/projects/slug-A/archive/${uuid3}.1779477705000.jsonl"
+
+  # Pair 4: lone stash, no canonical present.
+  local uuid4="abcdef01-4444-4444-8444-444444444444"
+  printf '%s' "lone-stash-content" > "$state/projects/slug-A/${uuid4}.1779477710000.jsonl"
+
+  # Sidecar on uuid1's stash (the winner) — should travel with the rename
+  # to canonical. Sidecar on uuid2's stash (the loser) — should follow to
+  # quarantine.
+  printf '{"meta":"win"}' > "$state/projects/slug-A/${uuid1}.1779477697566.meta.json"
+  printf '{"meta":"lose"}' > "$state/projects/slug-A/${uuid2}.1779477700000.meta.json"
+
+  DRY_RUN=no run_cleanup "$state" >/tmp/stash-cleanup-selftest.log 2>&1 \
+    || { cat /tmp/stash-cleanup-selftest.log; err "self-test: run_cleanup failed"; exit 1; }
+
+  local fail=0
+  local q="$state/quarantine/slug-A"
+  local qa="$state/quarantine/slug-A/archive"
+
+  # uuid1: canonical now holds "payload-big"; old canonical lives in
+  # quarantine with the `.canonical` suffix.
+  if [[ "$(cat "$state/projects/slug-A/${uuid1}.jsonl" 2>/dev/null)" != "$big" ]]; then
+    err "uuid1 canonical did not receive stash content"; fail=1
+  fi
+  if [[ -e "$state/projects/slug-A/${uuid1}.1779477697566.jsonl" ]]; then
+    err "uuid1 stash sibling still on disk after promotion"; fail=1
+  fi
+  if [[ "$(cat "$q/${uuid1}.jsonl.canonical" 2>/dev/null)" != "$small" ]]; then
+    err "uuid1 old canonical not in quarantine"; fail=1
+  fi
+  # Sidecar followed promotion.
+  if [[ "$(cat "$state/projects/slug-A/${uuid1}.meta.json" 2>/dev/null)" != '{"meta":"win"}' ]]; then
+    err "uuid1 sidecar did not follow promotion"; fail=1
+  fi
+
+  # uuid2: canonical untouched; stash sibling in quarantine.
+  if [[ "$(cat "$state/projects/slug-A/${uuid2}.jsonl" 2>/dev/null)" != "big-canonical" ]]; then
+    err "uuid2 canonical altered"; fail=1
+  fi
+  if [[ ! -f "$q/${uuid2}.1779477700000.jsonl" ]]; then
+    err "uuid2 stash sibling not quarantined"; fail=1
+  fi
+  if [[ "$(cat "$q/${uuid2}.1779477700000.meta.json" 2>/dev/null)" != '{"meta":"lose"}' ]]; then
+    err "uuid2 sidecar did not follow to quarantine"; fail=1
+  fi
+
+  # uuid3 (archive): canonical wins; stash sibling in archive-quarantine.
+  if [[ "$(cat "$state/projects/slug-A/archive/${uuid3}.jsonl" 2>/dev/null)" != "archived-big-history" ]]; then
+    err "uuid3 archive canonical altered"; fail=1
+  fi
+  if [[ ! -f "$qa/${uuid3}.1779477705000.jsonl" ]]; then
+    err "uuid3 archive stash sibling not quarantined under archive/"; fail=1
+  fi
+
+  # uuid4: lone stash promoted in place; no quarantine.
+  if [[ "$(cat "$state/projects/slug-A/${uuid4}.jsonl" 2>/dev/null)" != "lone-stash-content" ]]; then
+    err "uuid4 lone stash not promoted to canonical"; fail=1
+  fi
+  if [[ -e "$state/projects/slug-A/${uuid4}.1779477710000.jsonl" ]]; then
+    err "uuid4 stash file still on disk after promotion"; fail=1
+  fi
+
+  # No <uuid>.<unix-ms>.jsonl siblings remain in the projects scan scope.
+  local residual
+  residual=$(find "$state/projects" -type f -name '*.jsonl' \
+    | awk -F/ '{ print $NF }' \
+    | grep -cE '^[a-f0-9-]{36}\.[0-9]{13}\.jsonl$' || true)
+  if (( residual > 0 )); then
+    err "self-test: $residual timestamped siblings still present"; fail=1
+  fi
+
+  # Live-PTY guard: seed a PID file and confirm the script refuses.
+  printf '{"pid":1234}' > "$state/sessions/1234.json"
+  if DRY_RUN=no run_cleanup "$state" >>/tmp/stash-cleanup-selftest.log 2>&1; then
+    err "self-test: live-PTY guard did not refuse"; fail=1
+  fi
+  rm -f "$state/sessions/1234.json"
+
+  if (( fail > 0 )); then
+    cat /tmp/stash-cleanup-selftest.log
+    err "self-test: FAILED"
+    exit 1
+  fi
+
+  log "self-test: PASS"
+}
+
+# ----- entry point ------------------------------------------------------
+
+DRY_RUN=no
+case "${1:-}" in
+  -h|--help|"")
+    usage
+    exit 0
+    ;;
+  --self-test)
+    self_test
+    exit 0
+    ;;
+  *)
+    STATE_ROOT="${1:-}"
+    shift || true
+    while (( $# > 0 )); do
+      case "$1" in
+        --dry-run) DRY_RUN=yes ;;
+        *) err "unknown flag: $1"; usage; exit 2 ;;
+      esac
+      shift
+    done
+    [[ -n "$STATE_ROOT" ]] || { usage; exit 2; }
+    # Expand ~ since the caller may pass it.
+    STATE_ROOT="${STATE_ROOT/#\~/$HOME}"
+    run_cleanup "$STATE_ROOT" || exit $?
+    ;;
+esac

package/payload/premium-plugins/.claude-plugin/marketplace.json

@@ -4,6 +4,11 @@
     "name": "Rubytech LLC"
   },
   "plugins": [
+    {
+      "name": "founder-pack",
+      "source": "./founder-pack",
+      "version": "0.1.0"
+    },
     {
       "name": "teaching",
       "source": "./teaching",

package/payload/premium-plugins/founder-pack/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "founder-pack",
+  "description": "founder-pack plugin",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}