@procrastivity/clast 0.0.3 → 0.0.5

package/lib/clast/clast-porcelain-subcommands/brief.bash

@@ -0,0 +1,236 @@
+# clast brief — LLM-powered project briefing.
+#
+# Replicates the /brief plugin skill using an OpenAI-compatible chat
+# completions endpoint. Reads curated entries, breadcrumbs, and today's
+# sessions for a project (via clast-plumbing), then synthesizes a briefing.
+#
+# Usage: clast brief [<project-slug>]
+#   If no slug is given, resolves from the current working directory.
+# shellcheck shell=bash
+
+# --- Resolve project ---------------------------------------------------------
+
+_clast_brief_resolve_project() {
+  local slug="${1:-}"
+
+  if [[ -n "$slug" ]]; then
+    printf '%s' "$slug"
+    return
+  fi
+
+  local resolved
+  resolved="$(clast-plumbing registry resolve "$(pwd)" 2>/dev/null)" || true
+  if [[ -n "$resolved" ]]; then
+    printf '%s' "$resolved"
+    return
+  fi
+
+  clast_porcelain_die "Not in a registered project. Run \`clast-plumbing registry add .\` first, or invoke as \`clast brief <slug>\`."
+}
+
+# --- Gather data -------------------------------------------------------------
+
+# Group key for an entry: per-directory label, else branch, else "default".
+# A slug may span several directories; grouping keeps their work distinct
+# instead of letting the single newest entry stand in for the whole project.
+_clast_brief_gather_entries() {
+  local project="$1" current_label="${2:-}"
+
+  # Pull the full entries list (no global cap). A global `--limit` here would
+  # let one busy clone with N newer entries push the current clone out of the
+  # window entirely before we ever see it — even though the per-group/total
+  # caps below already keep the prompt within the brief's token budget.
+  local entries_json
+  entries_json="$(clast-plumbing --json entries --project "$project" 2>/dev/null)" || true
+
+  if [[ -z "$entries_json" ]] || [[ "$(jq 'length' <<<"$entries_json" 2>/dev/null)" == "0" ]]; then
+    return
+  fi
+
+  # Ordered, de-duplicated group keys in newest-first order of first
+  # appearance (entries list is already sorted newest-first). If a
+  # current_label was provided AND it appears in the entries, hoist it to
+  # the front so the active thread gets its share before total_cap is hit.
+  local -a groups=()
+  mapfile -t groups < <(jq -r --arg cur "$current_label" '
+    [ .[] | (.label // .branch // "default") ] as $keys
+    | (reduce $keys[] as $k ([]; if index($k) then . else . + [$k] end)) as $uniq
+    | (if $cur != "" and ($uniq | index($cur)) != null
+         then [$cur] + ($uniq - [$cur])
+         else $uniq end)
+    | .[]
+  ' <<<"$entries_json")
+
+  # A single-workspace project renders exactly as before (no group headers),
+  # so this change is a strict superset for the common case.
+  local single_group=0
+  (( ${#groups[@]} <= 1 )) && single_group=1
+
+  # Per-group and total caps keep the prompt within the brief's token budget.
+  local per_group=3 total_cap=8 emitted=0
+  local result="" g
+
+  for g in "${groups[@]}"; do
+    (( emitted >= total_cap )) && break
+
+    local -a paths=()
+    mapfile -t paths < <(jq -r --arg g "$g" --argjson per "$per_group" '
+      [ .[] | select((.label // .branch // "default") == $g) ][0:$per] | .[].path
+    ' <<<"$entries_json")
+    (( ${#paths[@]} == 0 )) && continue
+
+    # Build this group's body first, so we can skip the header if nothing reads.
+    local group_block="" p entry_body
+    for p in "${paths[@]}"; do
+      (( emitted >= total_cap )) && break
+      entry_body="$(clast-plumbing entries read "$p" 2>/dev/null)" || true
+      if [[ -z "$entry_body" ]]; then continue; fi
+      if [[ -n "$group_block" ]]; then
+        group_block="${group_block}
+
+---
+
+"
+      fi
+      group_block="${group_block}${entry_body}"
+      emitted=$(( emitted + 1 ))
+    done
+    [[ -z "$group_block" ]] && continue
+
+    local block="$group_block"
+    if (( single_group == 0 )); then
+      local branch_disp
+      branch_disp="$(jq -r --arg g "$g" '
+        [ .[] | select((.label // .branch // "default") == $g) ][0].branch // ""
+      ' <<<"$entries_json")"
+      local header="## Workspace: $g"
+      if [[ -n "$branch_disp" && "$branch_disp" != "null" ]]; then
+        header="$header (branch: $branch_disp)"
+      fi
+      block="${header}
+
+${group_block}"
+    fi
+
+    if [[ -n "$result" ]]; then
+      result="${result}
+
+"
+    fi
+    result="${result}${block}"
+  done
+
+  printf '%s' "$result"
+}
+
+_clast_brief_gather_breadcrumbs() {
+  local project="$1"
+  clast-plumbing breadcrumb --read --project "$project" --day today 2>/dev/null || true
+}
+
+_clast_brief_gather_sessions() {
+  # NOTE: today's sessions come from the manifest, not curated entries, so
+  # they are not (yet) grouped by workspace label the way entries are. Per-
+  # directory session grouping is a possible follow-up.
+  local project="$1"
+  local sessions_json
+  sessions_json="$(clast-plumbing --json sessions --day today --project "$project" 2>/dev/null)" || true
+
+  if [[ -z "$sessions_json" ]] || [[ "$(jq 'length' <<<"$sessions_json" 2>/dev/null)" == "0" ]]; then
+    return
+  fi
+
+  local n
+  n="$(jq 'length' <<<"$sessions_json")"
+
+  if (( n > 5 )); then
+    local latest_start
+    latest_start="$(jq -r 'sort_by(.start) | last | .start // ""' <<<"$sessions_json")"
+    printf 'Worked %d sessions today, most recent at %s.' "$n" "${latest_start:11:5}"
+    return
+  fi
+
+  jq -r '
+    sort_by(.start) | .[] |
+    "\(.start[11:16]) start: \(if .branch and .branch != "null" then .branch else "no branch" end), \(.msg_count_approx) messages"
+  ' <<<"$sessions_json" 2>/dev/null || true
+}
+
+# --- User prompt -------------------------------------------------------------
+
+_clast_brief_build_user_prompt() {
+  local project="$1" entries="$2" breadcrumbs="$3" sessions="$4" current_label="$5"
+
+  local template_file template
+  template_file="$(clast_porcelain_user_prompt_file brief-user)"
+
+  if [[ -n "$template_file" ]]; then
+    template="$(cat "$template_file")"
+    template="${template//\{\{project\}\}/${project}}"
+    template="${template//\{\{current_label\}\}/${current_label:-unknown}}"
+    template="${template//\{\{entries\}\}/${entries:-None.}}"
+    template="${template//\{\{breadcrumbs\}\}/${breadcrumbs:-None.}}"
+    template="${template//\{\{sessions\}\}/${sessions:-None.}}"
+    printf '%s' "$template"
+  else
+    clast_porcelain_warn "user prompt template not found: brief-user.md — using inline fallback"
+    cat <<EOF
+Project: ${project}
+Current workspace (the directory you are in now): ${current_label:-unknown}
+
+Recent curated entries, grouped by workspace (newest first):
+${entries:-None.}
+
+Today's breadcrumbs for this project:
+${breadcrumbs:-None.}
+
+Today's session activity for this project:
+${sessions:-None.}
+EOF
+  fi
+}
+
+# --- Main --------------------------------------------------------------------
+
+clast_cmd_brief() {
+  clast_porcelain_preflight_llm
+
+  local project
+  project="$(_clast_brief_resolve_project "${1:-}")"
+  clast_porcelain_info "Briefing for project: $project"
+
+  # When the project was resolved from the current directory (no positional
+  # slug), find that directory's workspace label so the briefing can prefer
+  # the active thread for the clone the user is actually in.
+  local current_label=""
+  if [[ -z "${1:-}" ]]; then
+    current_label="$(clast-plumbing registry resolve "$(pwd)" --json 2>/dev/null | jq -r '.label // empty' 2>/dev/null)" || true
+  fi
+
+  clast_porcelain_info "Gathering context..."
+
+  local entries breadcrumbs sessions
+  entries="$(_clast_brief_gather_entries "$project" "$current_label")"
+  breadcrumbs="$(_clast_brief_gather_breadcrumbs "$project")"
+  sessions="$(_clast_brief_gather_sessions "$project")"
+
+  if [[ -z "$entries" && -z "$breadcrumbs" && -z "$sessions" ]]; then
+    clast_porcelain_info "No curated entries, breadcrumbs, or sessions for \`$project\`."
+    clast_porcelain_info "Run \`clast wake\` to curate recent sessions first, or run \`clast-plumbing sessions --project $project\` to see what's available."
+    return 0
+  fi
+
+  local system_prompt user_prompt
+  system_prompt="$(clast_porcelain_load_system_prompt brief-system)"
+  user_prompt="$(_clast_brief_build_user_prompt "$project" "$entries" "$breadcrumbs" "$sessions" "$current_label")"
+
+  clast_porcelain_info "Synthesizing briefing..."
+  printf '\n'
+
+  local briefing
+  if ! briefing="$(clast_porcelain_llm_chat "$system_prompt" "$user_prompt")"; then
+    clast_porcelain_die "LLM call failed"
+  fi
+
+  printf '%s\n' "$briefing"
+}

package/lib/clast/clast-porcelain-subcommands/retro.bash

@@ -0,0 +1,236 @@
+# clast retro — LLM-condensed work retrospective grouped by work day → project.
+#
+# Round 2 of the retro feature. Structure comes from the deterministic core
+# (`clast-plumbing retro --json --bodies`); the model only condenses each
+# session's body into a few retro bullets. Summaries are cached per session_id
+# (content-fingerprinted) under the journal dir, so re-runs are free unless a
+# session changed or --refresh is passed. See .wip/initiatives/clast-retro/.
+# shellcheck shell=bash
+
+_clast_retrosum_usage() {
+  cat <<'EOF'
+Usage: clast retro [--from DATE] [--to DATE] [--window work-days|file-dates]
+                   [--refresh] [--json]
+
+Condense the work retrospective (grouped by actual work day → project) into
+model-written bullets per session. Structure is deterministic; only the prose
+condensation calls the LLM. Summaries are cached per session under
+<journal>/.retro-summaries/ and reused until the session content changes.
+
+Flags:
+  --from DATE     Start of the window (inclusive). Default: corpus start.
+  --to DATE       End of the window (inclusive). Default: corpus end.
+  --window WHICH  work-days (default) | file-dates. See `clast-plumbing retro`.
+  --refresh       Ignore cached summaries and re-summarize (rewrites the cache).
+  --json          Emit the manifest with a `summary` per session (no render).
+  -h, --help      Print this usage and exit.
+
+Requires the CLAST_LLM_* env vars (see `clast --help`).
+EOF
+}
+
+# _clast_retrosum_fingerprint  (stdin → short hex/cksum on stdout)
+#   Content fingerprint of a session body; changes invalidate the cache.
+_clast_retrosum_fingerprint() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -c1-16
+  else
+    cksum | awk '{print $1}'
+  fi
+}
+
+# _clast_retrosum_build_user <project> <work_day> <session_id> <body>
+_clast_retrosum_build_user() {
+  local project="$1" work_day="$2" sid="$3" body="$4"
+  local tf tpl
+  tf="$(clast_porcelain_user_prompt_file retro-summary-user)"
+  if [[ -n "$tf" ]]; then
+    tpl="$(cat "$tf")"
+    tpl="${tpl//\{\{project\}\}/$project}"
+    tpl="${tpl//\{\{work_day\}\}/$work_day}"
+    tpl="${tpl//\{\{session_id\}\}/$sid}"
+    tpl="${tpl//\{\{body\}\}/$body}"
+    printf '%s' "$tpl"
+  else
+    printf 'Project: %s\nWork day: %s\nSession id: %s\n\nEntry body:\n%s\n' \
+      "$project" "$work_day" "$sid" "$body"
+  fi
+}
+
+# _clast_retrosum_summary <project> <work_day> <session_id> <body> <cache_dir> <refresh>
+#   Echo the condensed summary. Cache hit (matching fingerprint) reuses; miss
+#   calls the LLM and writes the cache. Returns nonzero on LLM failure.
+_clast_retrosum_summary() {
+  local project="$1" work_day="$2" sid="$3" body="$4" cache_dir="$5" refresh="$6"
+  local fp cache_file cached_fp
+  fp="$(printf '%s' "$body" | _clast_retrosum_fingerprint)"
+  cache_file="$cache_dir/$sid.json"
+
+  if (( ! refresh )) && [[ -r "$cache_file" ]]; then
+    cached_fp="$(jq -r '.fingerprint // empty' "$cache_file" 2>/dev/null)"
+    if [[ -n "$cached_fp" && "$cached_fp" == "$fp" ]]; then
+      jq -r '.summary // empty' "$cache_file"
+      return 0
+    fi
+  fi
+
+  local system user summary
+  system="$(clast_porcelain_load_system_prompt retro-summary-system)"
+  user="$(_clast_retrosum_build_user "$project" "$work_day" "$sid" "$body")"
+  if ! summary="$(clast_porcelain_llm_chat "$system" "$user")"; then
+    return 1
+  fi
+
+  if mkdir -p "$cache_dir" 2>/dev/null; then
+    jq -n --arg fp "$fp" --arg s "$summary" '{fingerprint:$fp, summary:$s}' \
+      >"$cache_file" 2>/dev/null || clast_porcelain_warn "failed to cache summary for $sid"
+  fi
+  printf '%s' "$summary"
+}
+
+# _clast_retrosum_journal_dir — resolve the journal dir (for the cache).
+_clast_retrosum_journal_dir() {
+  if [[ -n "${CLAST_JOURNAL_DIR:-}" ]]; then
+    printf '%s' "$CLAST_JOURNAL_DIR"
+    return
+  fi
+  local jd
+  jd="$(clast-plumbing whereami 2>/dev/null | awk '/^journal_dir:/{print $2}')" || true
+  printf '%s' "${jd:-$HOME/.claude/journal}"
+}
+
+clast_cmd_retro() {
+  local from="" to="" window="work-days" refresh=0 as_json=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --from)     [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --from requires a value"; return 2; }; from="$2"; shift 2 ;;
+      --from=*)   from="${1#*=}"; shift ;;
+      --to)       [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --to requires a value"; return 2; }; to="$2"; shift 2 ;;
+      --to=*)     to="${1#*=}"; shift ;;
+      --window)   [[ $# -lt 2 ]] && { clast_porcelain_log_error "retro: --window requires a value"; return 2; }; window="$2"; shift 2 ;;
+      --window=*) window="${1#*=}"; shift ;;
+      --refresh)  refresh=1; shift ;;
+      --json)     as_json=1; shift ;;
+      -h|--help)  _clast_retrosum_usage; return 0 ;;
+      --) shift; break ;;
+      *) clast_porcelain_log_error "retro: unknown argument '$1'"; return 2 ;;
+    esac
+  done
+
+  clast_porcelain_preflight_llm
+
+  # Structure + per-session bodies from the deterministic core.
+  local -a pl=(--json retro --bodies --window "$window")
+  [[ -n "$from" ]] && pl+=(--from "$from")
+  [[ -n "$to" ]] && pl+=(--to "$to")
+  local manifest
+  if ! manifest="$(clast-plumbing "${pl[@]}" 2>/dev/null)"; then
+    local msg
+    msg="$(jq -r '.error // empty' <<<"$manifest" 2>/dev/null || true)"
+    clast_porcelain_die "retro: ${msg:-failed to build manifest}" 2
+  fi
+
+  local cache_dir
+  cache_dir="$(_clast_retrosum_journal_dir)/.retro-summaries"
+
+  # Summarize each session; collect key → summary.
+  local -a summary_pairs=()
+  local sess sid key cache_id project work_day body title summary
+  while IFS= read -r sess; do
+    [[ -z "$sess" ]] && continue
+    sid="$(jq -r '.session_id // ""' <<<"$sess")"
+    # Fold key: session_id, or the unique first entry path for id-less sessions
+    # (must match the plumbing manifest's key so summaries fold back correctly
+    # and two id-less sessions don't collide on a shared "null" key).
+    key="$(jq -r '.session_id // .entries[0]' <<<"$sess")"
+    # Cache filename must be unique and filesystem-safe even without an id.
+    if [[ -n "$sid" ]]; then
+      cache_id="$sid"
+    else
+      cache_id="noid-$(printf '%s' "$key" | _clast_retrosum_fingerprint)"
+    fi
+    work_day="$(jq -r '.work_day' <<<"$sess")"
+    body="$(jq -r '.body // ""' <<<"$sess")"
+    project="$(jq -r '.project_path // "(no project)"' <<<"$sess")"
+    if [[ -z "$body" ]]; then
+      summary="(no body to summarize)"
+    elif ! summary="$(_clast_retrosum_summary "$project" "$work_day" "$cache_id" "$body" "$cache_dir" "$refresh")"; then
+      clast_porcelain_warn "summary failed for session ${sid:-<no id>} — leaving it unsummarized"
+      summary="(summary unavailable)"
+    fi
+    summary_pairs+=("$(jq -cn --arg k "$key" --arg v "$summary" '{key:$k, summary:$v}')")
+  done < <(jq -c '.days[].projects[].sessions[]' <<<"$manifest")
+
+  # Fold summaries back into the manifest and drop the raw bodies. The manifest
+  # carries --bodies only as summarizer input; neither the JSON nor the render
+  # path consumes .body, so strip it here to keep --json condensed and
+  # consistent with the plumbing's lean-by-default output (raw bodies remain
+  # available via `clast-plumbing --json retro --bodies`). The manifest can
+  # exceed MAX_ARG_STRLEN — feed it via stdin and the summary pairs via
+  # --slurpfile, never argv.
+  local enriched="$manifest"
+  if (( ${#summary_pairs[@]} > 0 )); then
+    # Key by `session_id // .entries[0]` (always a non-null string), matching
+    # the pairs above: this can't abort jq on a null id and keeps two id-less
+    # sessions distinct instead of collapsing them onto a shared key.
+    enriched="$(printf '%s' "$manifest" | jq -c --slurpfile pairs <(printf '%s\n' "${summary_pairs[@]}") '
+      (reduce $pairs[] as $p ({}; .[$p.key] = $p.summary)) as $sum
+      | .days |= map(.projects |= map(.sessions |= map(
+          del(.body) + {summary: ($sum[(.session_id // .entries[0])] // null)})))
+    ')"
+  fi
+
+  if (( as_json )); then
+    printf '%s\n' "$enriched"
+    return 0
+  fi
+
+  _clast_retrosum_render "$enriched"
+}
+
+# _clast_retrosum_render <manifest-with-summaries>
+_clast_retrosum_render() {
+  local manifest="$1"
+  local from to window
+  from="$(jq -r '.from // "(start)"' <<<"$manifest")"
+  to="$(jq -r '.to // "(end)"' <<<"$manifest")"
+  window="$(jq -r '.window' <<<"$manifest")"
+  printf 'Retro: %s -> %s (%s)\n' "$from" "$to" "$window"
+
+  local nd
+  nd="$(jq '.days | length' <<<"$manifest")"
+  if (( nd == 0 )); then
+    printf '\n(no sessions in range)\n'
+    return 0
+  fi
+
+  local di pj si day np project ns sess sid shortsid title summary note flag
+  for (( di = 0; di < nd; di++ )); do
+    day="$(jq -r ".days[$di].day" <<<"$manifest")"
+    printf '\n== %s ==\n' "$day"
+    note="$(jq -r --arg d "$day" '.days['"$di"'].curation_dates // [] |
+      if . == [] or . == [$d] then empty
+      else "  (filed " + (join(", ")) + "; work day reconstructed from session snapshots)"
+      end' <<<"$manifest")"
+    [[ -n "$note" ]] && printf '%s\n' "$note"
+    np="$(jq ".days[$di].projects | length" <<<"$manifest")"
+    for (( pj = 0; pj < np; pj++ )); do
+      project="$(jq -r ".days[$di].projects[$pj].project_name // .days[$di].projects[$pj].project_path // \"(no project)\"" <<<"$manifest")"
+      printf '\n[%s]\n' "$project"
+      ns="$(jq ".days[$di].projects[$pj].sessions | length" <<<"$manifest")"
+      for (( si = 0; si < ns; si++ )); do
+        sess="$(jq -c ".days[$di].projects[$pj].sessions[$si]" <<<"$manifest")"
+        sid="$(jq -r '.session_id' <<<"$sess")"
+        shortsid="${sid:0:8}"
+        title="$(jq -r '.title // "(untitled)"' <<<"$sess")"
+        [[ -z "$title" || "$title" == "null" ]] && title="(untitled)"
+        summary="$(jq -r '.summary // "(no summary)"' <<<"$sess")"
+        flag=""
+        [[ "$(jq -r '.interrupted // false' <<<"$sess")" == "true" ]] && flag="  [interrupted]"
+        printf '\n  * %s  (%s)%s\n' "$title" "$shortsid" "$flag"
+        printf '%s\n' "$summary"
+      done
+    done
+  done
+}

package/lib/clast/clast-porcelain-subcommands/undismiss.bash

@@ -0,0 +1,27 @@
+# clast undismiss — restore session(s) dismissed during `clast wake`.
+#
+# A convenience verb over `clast-plumbing sessions undismiss`: `clast wake`
+# now prints each session's id, so recovering an accidental [d] is a direct
+# `clast undismiss <id>` without dropping down to the plumbing surface.
+# shellcheck shell=bash
+
+clast_cmd_undismiss() {
+  case "${1:-}" in
+    -h|--help)
+      cat <<'EOF'
+Usage: clast undismiss <session-id> [<session-id>...]
+
+Restore session(s) previously dismissed (e.g. an accidental [d] in
+`clast wake`). Session ids are shown in the `clast wake` review header.
+EOF
+      return 0
+      ;;
+  esac
+
+  if ! command -v clast-plumbing >/dev/null 2>&1; then
+    clast_porcelain_die "required tool not found: clast-plumbing"
+  fi
+
+  # Thin passthrough: plumbing owns UUID validation and JSON/human output.
+  clast-plumbing sessions undismiss "$@"
+}