@procrastivity/clast 0.0.1

package/lib/clast/clast-lib.bash

@@ -0,0 +1,233 @@
+# clast-lib.bash — common helpers
+#
+# Sourced by the dispatcher and (transitively) by subcommands and tests.
+# Requires bash 4.4+, jq, and GNU coreutils `date` on PATH.
+# shellcheck shell=bash
+
+# Guard against double-sourcing.
+if [[ -n "${_CLAST_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_LIB_SOURCED=1
+
+# Hard dependency check: jq must be on PATH. Exit 3 (env problem) per
+# docs/overview.md#exit-codes if missing — no grep/sed fallback.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "clast: error: required dependency 'jq' not found on PATH" >&2
+  exit 3
+fi
+
+# --- Path helpers --------------------------------------------------------
+
+clast_journal_dir() {
+  printf '%s\n' "${CLAST_JOURNAL_DIR:-$HOME/.claude/journal}"
+}
+
+clast_projects_dir() {
+  printf '%s\n' "${CLAST_PROJECTS_DIR:-$HOME/.claude/projects}"
+}
+
+# --- Logging -------------------------------------------------------------
+
+# CLAST_QUIET=1 silences info logs. The global --quiet flag (step 03)
+# will set this before any subcommand runs.
+clast_log_info() {
+  if [[ -z "${CLAST_QUIET:-}" ]]; then
+    printf 'clast: info: %s\n' "$*" >&2
+  fi
+}
+
+clast_log_warn() {
+  printf 'clast: warn: %s\n' "$*" >&2
+}
+
+clast_log_error() {
+  printf 'clast: error: %s\n' "$*" >&2
+}
+
+# --- JSON ----------------------------------------------------------------
+
+# clast_json_get <jq-expression> <input>
+#   Thin wrapper around jq. <input> is a JSON string (not a file).
+#   Use process substitution for file input: clast_json_get '.x' "$(cat f.json)".
+clast_json_get() {
+  local expr="$1" input="$2"
+  jq -r "$expr" <<<"$input"
+}
+
+# --- Date math -----------------------------------------------------------
+#
+# Uses GNU `date -d` for relative-date math. The nix dev shell pulls in
+# coreutils, so this works on macOS too when invoked from inside the shell.
+# BSD `date` is NOT supported.
+
+# _clast_now_epoch — overridable hook so tests can inject a fixed "now".
+# Tests set CLAST_NOW_EPOCH=<seconds> to freeze time.
+_clast_now_epoch() {
+  if [[ -n "${CLAST_NOW_EPOCH:-}" ]]; then
+    printf '%s\n' "$CLAST_NOW_EPOCH"
+  else
+    date +%s
+  fi
+}
+
+# clast_today — local YYYY-MM-DD, adjusted by CLAST_DAY_CUTOFF (HH:MM, default 04:00).
+# A session starting before today's cutoff belongs to yesterday's bucket.
+clast_today() {
+  local cutoff="${CLAST_DAY_CUTOFF:-04:00}"
+  local cutoff_hours cutoff_mins cutoff_secs now adjusted
+  cutoff_hours="${cutoff%%:*}"
+  cutoff_mins="${cutoff##*:}"
+  # Strip leading zeros so bash arithmetic doesn't treat them as octal.
+  cutoff_hours=$((10#$cutoff_hours))
+  cutoff_mins=$((10#$cutoff_mins))
+  cutoff_secs=$((cutoff_hours * 3600 + cutoff_mins * 60))
+  now="$(_clast_now_epoch)"
+  adjusted=$((now - cutoff_secs))
+  date -d "@$adjusted" +%Y-%m-%d
+}
+
+# clast_parse_date <input> — print YYYY-MM-DD on stdout, exit non-zero on bad input.
+# Accepts:
+#   - ISO date: 2026-05-30
+#   - Keywords: today, yesterday, last-week
+#   - Offsets:  -1d, -3d, -1w, -2w (negative-only; future dates not supported)
+clast_parse_date() {
+  local input="$1"
+  if [[ -z "$input" ]]; then
+    clast_log_error "clast_parse_date: empty input"
+    return 2
+  fi
+
+  case "$input" in
+    today)
+      clast_today
+      return 0
+      ;;
+    yesterday)
+      _clast_offset_date 1 d
+      return 0
+      ;;
+    last-week)
+      _clast_offset_date 1 w
+      return 0
+      ;;
+    -[0-9]*d|-[0-9]*w)
+      local n unit
+      n="${input#-}"
+      unit="${n: -1}"
+      n="${n%?}"
+      if ! [[ "$n" =~ ^[0-9]+$ ]]; then
+        clast_log_error "clast_parse_date: invalid offset '$input'"
+        return 2
+      fi
+      _clast_offset_date "$n" "$unit"
+      return 0
+      ;;
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9])
+      # Validate by round-tripping through GNU date.
+      if ! date -d "$input" +%Y-%m-%d 2>/dev/null; then
+        clast_log_error "clast_parse_date: invalid ISO date '$input'"
+        return 2
+      fi
+      return 0
+      ;;
+    *)
+      clast_log_error "clast_parse_date: unrecognized '$input'"
+      return 2
+      ;;
+  esac
+}
+
+# _clast_offset_date <n> <d|w>  — print today's bucket minus N days/weeks.
+_clast_offset_date() {
+  local n="$1" unit="$2" days base
+  case "$unit" in
+    d) days="$n" ;;
+    w) days=$((n * 7)) ;;
+    *)
+      clast_log_error "_clast_offset_date: bad unit '$unit'"
+      return 2
+      ;;
+  esac
+  base="$(clast_today)"
+  date -d "$base -$days days" +%Y-%m-%d
+}
+
+# --- Atomic write --------------------------------------------------------
+
+# clast_atomic_write <path> <content>
+#   Writes <content> to <path>.tmp.$$ then renames over <path>.
+#   On any failure during the temp write, leaves the original untouched and
+#   removes the temp file.
+clast_atomic_write() {
+  local path="$1" content="$2" tmp
+  tmp="$path.tmp.$$"
+  if ! printf '%s' "$content" >"$tmp" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null || true
+    clast_log_error "clast_atomic_write: failed to write '$tmp'"
+    return 1
+  fi
+  if ! mv -f "$tmp" "$path" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null || true
+    clast_log_error "clast_atomic_write: failed to rename onto '$path'"
+    return 1
+  fi
+  return 0
+}
+
+# --- Version / usage -----------------------------------------------------
+
+_CLAST_VERSION_CACHE=""
+
+clast_version() {
+  if [[ -n "$_CLAST_VERSION_CACHE" ]]; then
+    printf '%s\n' "$_CLAST_VERSION_CACHE"
+    return 0
+  fi
+  local pkg pkg_root
+  pkg_root="${CLAST_LIB:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+  # CLAST_LIB points at lib/clast; the package.json sits two levels up.
+  if [[ -f "$pkg_root/package.json" ]]; then
+    pkg="$pkg_root/package.json"
+  elif [[ -f "$pkg_root/../../package.json" ]]; then
+    pkg="$pkg_root/../../package.json"
+  else
+    clast_log_error "clast_version: package.json not found"
+    return 1
+  fi
+  _CLAST_VERSION_CACHE="$(jq -r '.version' "$pkg")"
+  printf '%s\n' "$_CLAST_VERSION_CACHE"
+}
+
+# clast_usage — print top-level usage to stdout. The dispatcher redirects
+# to stderr for usage errors.
+clast_usage() {
+  cat <<'EOF'
+clast — Claude Code session journal
+
+Usage:
+  clast [GLOBAL FLAGS] <subcommand> [ARGS...]
+
+Subcommands:
+  whereami      Show current path, registry, and journal state
+  snapshot      Capture new transcripts into the journal
+  projects      List projects with activity in a window
+  sessions      List sessions in a window
+  show          Dump session metadata
+  entries       List or read curated journal entries
+  breadcrumb    Append a one-line in-flight hint
+  registry      Manage the project registry
+  stats         Token/duration/session-count stats
+  doctor        Sanity-check the journal
+
+Global flags:
+  -h, --help            Print this usage and exit
+      --version         Print version and exit
+      --json            Machine-readable JSON output
+  -v, --verbose         Extra diagnostic output to stderr
+  -q, --quiet           Suppress informational stdout output
+      --journal-dir P   Override ~/.claude/journal/ (env: CLAST_JOURNAL_DIR)
+      --projects-dir P  Override ~/.claude/projects/ (env: CLAST_PROJECTS_DIR)
+EOF
+}

package/lib/clast/clast-manifest-lib.bash

@@ -0,0 +1,232 @@
+# clast-manifest-lib.bash — manifest read/append/lookup/iterate/rebuild
+#
+# Sourced after clast-lib.bash. The manifest is an append-only JSONL log at
+# $(clast_journal_dir)/.manifest.jsonl, one line per capture event. Per
+# docs/cli-contract.md#manifest-line each line has seven required fields:
+# session_id, source, snapshot, captured_at, source_mtime, source_size,
+# day_bucket. Lookups use "most recent line wins" semantics.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+
+if [[ -n "${_CLAST_MANIFEST_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_MANIFEST_LIB_SOURCED=1
+
+# clast_manifest_path — single chokepoint so CLAST_JOURNAL_DIR override
+# (via clast_journal_dir) redirects every read/write in this file.
+clast_manifest_path() {
+  printf '%s\n' "$(clast_journal_dir)/.manifest.jsonl"
+}
+
+# _clast_manifest_now_iso — current UTC time, ISO 8601 with Z suffix.
+# Honors CLAST_NOW_EPOCH (test-only freeze hook from clast-lib.bash).
+_clast_manifest_now_iso() {
+  local epoch="${CLAST_NOW_EPOCH:-$(date +%s)}"
+  date -u -d "@$epoch" +%Y-%m-%dT%H:%M:%SZ
+}
+
+# clast_manifest_append <session-id> <source> <snapshot> <source-mtime> <source-size> <day-bucket>
+clast_manifest_append() {
+  if [[ $# -ne 6 ]]; then
+    clast_log_error "clast_manifest_append: expected 6 args, got $#"
+    return 2
+  fi
+  local session_id="$1" source="$2" snapshot="$3" source_mtime="$4" source_size="$5" day_bucket="$6"
+  local field
+  for field in session_id source snapshot source_mtime source_size day_bucket; do
+    if [[ -z "${!field}" ]]; then
+      clast_log_error "clast_manifest_append: empty field '$field'"
+      return 2
+    fi
+  done
+  if ! [[ "$source_size" =~ ^[0-9]+$ ]]; then
+    clast_log_error "clast_manifest_append: source_size must be a non-negative integer, got '$source_size'"
+    return 2
+  fi
+
+  local journal_dir
+  journal_dir="$(clast_journal_dir)"
+  if ! mkdir -p "$journal_dir"; then
+    clast_log_error "clast_manifest_append: failed to create '$journal_dir'"
+    return 1
+  fi
+
+  local captured_at line
+  captured_at="$(_clast_manifest_now_iso)"
+  line="$(jq -c -n \
+    --arg session_id "$session_id" \
+    --arg source "$source" \
+    --arg snapshot "$snapshot" \
+    --arg captured_at "$captured_at" \
+    --arg source_mtime "$source_mtime" \
+    --argjson source_size "$source_size" \
+    --arg day_bucket "$day_bucket" \
+    '{session_id: $session_id, source: $source, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: $source_size, day_bucket: $day_bucket}')" || {
+    clast_log_error "clast_manifest_append: jq failed to build manifest line"
+    return 1
+  }
+
+  # Append-only single-line write — crash-safe at line boundary per
+  # docs/overview.md#cross-machine-considerations. Do NOT use
+  # clast_atomic_write here: it rewrites the whole file and would clobber
+  # concurrent appends from another machine.
+  local manifest_path
+  manifest_path="$(clast_manifest_path)"
+  if ! printf '%s\n' "$line" >>"$manifest_path" 2>/dev/null; then
+    clast_log_error "clast_manifest_append: failed to append to '$manifest_path'"
+    return 1
+  fi
+}
+
+# clast_manifest_lookup <session-id>
+#   Print the most recent manifest line for <session-id>. Exit 1 if no
+#   match (including when the manifest file does not exist).
+clast_manifest_lookup() {
+  if [[ $# -ne 1 ]]; then
+    clast_log_error "clast_manifest_lookup: expected 1 arg, got $#"
+    return 2
+  fi
+  local sid="$1" path
+  path="$(clast_manifest_path)"
+  if [[ ! -f "$path" ]]; then
+    return 1
+  fi
+  # Manifest is append-only so file order is time order; tac to scan from
+  # newest backward, fromjson? skips garbage lines silently, head -n1 stops
+  # at the first match.
+  local line
+  line="$(tac "$path" | jq -cR --arg sid "$sid" 'fromjson? | select(.session_id == $sid)' | head -n1)"
+  if [[ -z "$line" ]]; then
+    return 1
+  fi
+  printf '%s\n' "$line"
+}
+
+# clast_manifest_has_capture <session-id> <source-mtime>
+#   Exit 0 if a manifest line exists for this (session_id, source_mtime)
+#   pair; exit 1 otherwise. Fast-path predicate for `clast snapshot`.
+clast_manifest_has_capture() {
+  if [[ $# -ne 2 ]]; then
+    clast_log_error "clast_manifest_has_capture: expected 2 args, got $#"
+    return 2
+  fi
+  local sid="$1" mtime="$2" path
+  path="$(clast_manifest_path)"
+  if [[ ! -f "$path" ]]; then
+    return 1
+  fi
+  local match
+  match="$(jq -cR --arg sid "$sid" --arg mtime "$mtime" \
+    'fromjson? | select(.session_id == $sid and .source_mtime == $mtime)' \
+    "$path" | head -n1)"
+  if [[ -z "$match" ]]; then
+    return 1
+  fi
+  return 0
+}
+
+# clast_manifest_iterate <jq-filter-body>
+#   Stream every manifest line whose parsed object matches the supplied
+#   select() body (e.g. '.day_bucket == "2026-05-30"'). Malformed lines
+#   are silently skipped via fromjson?. Missing manifest = no output, 0.
+clast_manifest_iterate() {
+  if [[ $# -ne 1 ]]; then
+    clast_log_error "clast_manifest_iterate: expected 1 arg, got $#"
+    return 2
+  fi
+  local filter="$1" path
+  path="$(clast_manifest_path)"
+  if [[ ! -f "$path" ]]; then
+    return 0
+  fi
+  jq -cR 'fromjson? | select('"$filter"')' "$path"
+}
+
+# clast_manifest_rebuild_from_disk
+#   Walk $(clast_journal_dir)/transcripts/<day>/<segment>/<uuid>.jsonl and
+#   write a best-effort manifest atomically. For doctor --fix (step 10).
+#   source / source_size are unrecoverable from the snapshot alone, so
+#   they're emitted as null / 0 — round-trips through lookup, schema
+#   validators can still flag the lossy lines.
+clast_manifest_rebuild_from_disk() {
+  local journal_dir manifest_path transcripts_root tmp_file
+  journal_dir="$(clast_journal_dir)"
+  manifest_path="$(clast_manifest_path)"
+  transcripts_root="$journal_dir/transcripts"
+
+  if ! mkdir -p "$journal_dir"; then
+    clast_log_error "clast_manifest_rebuild_from_disk: failed to create '$journal_dir'"
+    return 1
+  fi
+
+  tmp_file="$(mktemp "$journal_dir/.manifest.jsonl.rebuild.XXXXXX")" || {
+    clast_log_error "clast_manifest_rebuild_from_disk: mktemp failed"
+    return 1
+  }
+
+  local count=0
+  if [[ -d "$transcripts_root" ]]; then
+    local snapshot day session_id mtime_epoch mtime_iso line
+    # source / source_size are unrecoverable: the snapshot file's size is
+    # the captured copy's size, not the original source's size at capture
+    # time, and the source path is not encoded in the snapshot itself.
+    while IFS= read -r snapshot; do
+      [[ -z "$snapshot" ]] && continue
+      session_id="$(basename "$snapshot" .jsonl)"
+      day="$(basename "$(dirname "$(dirname "$snapshot")")")"
+      if ! mtime_epoch="$(stat -c %Y "$snapshot" 2>/dev/null || stat -f %m "$snapshot" 2>/dev/null)" || [[ -z "$mtime_epoch" ]]; then
+        clast_log_error "clast_manifest_rebuild_from_disk: stat failed for '$snapshot'"
+        rm -f "$tmp_file"
+        return 1
+      fi
+      if ! mtime_iso="$(date -u -d "@$mtime_epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)" || [[ -z "$mtime_iso" ]]; then
+        clast_log_error "clast_manifest_rebuild_from_disk: date conversion failed for '$snapshot' (epoch '$mtime_epoch')"
+        rm -f "$tmp_file"
+        return 1
+      fi
+      line="$(jq -c -n \
+        --arg session_id "$session_id" \
+        --arg snapshot "${snapshot#"$journal_dir/"}" \
+        --arg captured_at "$mtime_iso" \
+        --arg source_mtime "$mtime_iso" \
+        --arg day_bucket "$day" \
+        '{session_id: $session_id, source: null, snapshot: $snapshot, captured_at: $captured_at, source_mtime: $source_mtime, source_size: 0, day_bucket: $day_bucket}')" || {
+        clast_log_error "clast_manifest_rebuild_from_disk: jq failed for '$snapshot'"
+        rm -f "$tmp_file"
+        return 1
+      }
+      if ! printf '%s\n' "$line" >>"$tmp_file" 2>/dev/null; then
+        clast_log_error "clast_manifest_rebuild_from_disk: failed to write to '$tmp_file'"
+        rm -f "$tmp_file"
+        return 1
+      fi
+      count=$((count + 1))
+    done < <(find "$transcripts_root" -mindepth 3 -maxdepth 3 -type f -name '*.jsonl' | sort)
+
+    # Sort the temp file by captured_at ascending. The find|sort above sorts
+    # by path; re-sort by captured_at to honor the documented invariant.
+    if (( count > 0 )); then
+      local sorted
+      sorted="$(jq -sc 'sort_by(.captured_at) | .[]' "$tmp_file")" || {
+        clast_log_error "clast_manifest_rebuild_from_disk: failed to sort rebuilt manifest"
+        rm -f "$tmp_file"
+        return 1
+      }
+      if ! printf '%s\n' "$sorted" >"$tmp_file" 2>/dev/null; then
+        clast_log_error "clast_manifest_rebuild_from_disk: failed to write sorted manifest to '$tmp_file'"
+        rm -f "$tmp_file"
+        return 1
+      fi
+    fi
+  fi
+
+  if ! mv -f "$tmp_file" "$manifest_path"; then
+    clast_log_error "clast_manifest_rebuild_from_disk: failed to rename onto '$manifest_path'"
+    rm -f "$tmp_file"
+    return 1
+  fi
+
+  clast_log_info "manifest rebuilt: $count line(s)"
+  return 0
+}