@procrastivity/clast 0.0.1

package/bin/clast

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# clast — main dispatcher.
+#
+# Parses global flags, sources libs, dispatches to a subcommand.
+# Subcommand files live in $CLAST_LIB/clast-subcommands/<name>.bash and
+# each defines a single function `clast_cmd_<name>`.
+set -euo pipefail
+
+CLAST_LIB="${CLAST_LIB:-$(dirname "$(realpath "$0")")/../lib/clast}"
+export CLAST_LIB
+
+# shellcheck source=lib/clast/clast-lib.bash
+source "$CLAST_LIB/clast-lib.bash"
+# shellcheck source=lib/clast/clast-decode-lib.bash
+source "$CLAST_LIB/clast-decode-lib.bash"
+# shellcheck source=lib/clast/clast-registry-lib.bash
+source "$CLAST_LIB/clast-registry-lib.bash"
+# shellcheck source=lib/clast/clast-manifest-lib.bash
+source "$CLAST_LIB/clast-manifest-lib.bash"
+
+# --- Global flag parsing -------------------------------------------------
+#
+# Walk argv before the subcommand name, peeling off any recognized global
+# flag and setting the corresponding env var. Stop at the first non-flag
+# arg (the subcommand) or at `--`. Remaining argv is passed to the
+# subcommand untouched.
+#
+# `--json` and `--journal-dir`/`--projects-dir` are forwarded to the lib
+# via env so subcommands can also accept them locally without re-parsing.
+
+declare -a _CLAST_REMAINING=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help|help)
+      clast_usage
+      exit 0
+      ;;
+    --version)
+      echo "clast $(clast_version)"
+      exit 0
+      ;;
+    --json)
+      export CLAST_JSON=1
+      shift
+      ;;
+    -v|--verbose)
+      export CLAST_VERBOSE=1
+      shift
+      ;;
+    -q|--quiet)
+      export CLAST_QUIET=1
+      shift
+      ;;
+    --journal-dir)
+      if [[ $# -lt 2 ]]; then
+        clast_log_error "--journal-dir requires a value"
+        exit 2
+      fi
+      export CLAST_JOURNAL_DIR="$2"
+      shift 2
+      ;;
+    --journal-dir=*)
+      export CLAST_JOURNAL_DIR="${1#*=}"
+      shift
+      ;;
+    --projects-dir)
+      if [[ $# -lt 2 ]]; then
+        clast_log_error "--projects-dir requires a value"
+        exit 2
+      fi
+      export CLAST_PROJECTS_DIR="$2"
+      shift 2
+      ;;
+    --projects-dir=*)
+      export CLAST_PROJECTS_DIR="${1#*=}"
+      shift
+      ;;
+    --)
+      shift
+      _CLAST_REMAINING+=("$@")
+      break
+      ;;
+    -*)
+      clast_log_error "unknown global flag: $1"
+      clast_usage >&2
+      exit 2
+      ;;
+    *)
+      # First non-flag arg is the subcommand; stop parsing.
+      _CLAST_REMAINING+=("$@")
+      break
+      ;;
+  esac
+done
+
+if [[ ${#_CLAST_REMAINING[@]} -eq 0 ]]; then
+  clast_usage
+  exit 0
+fi
+
+set -- "${_CLAST_REMAINING[@]}"
+
+cmd="$1"; shift
+
+# --- Subcommand dispatch -------------------------------------------------
+
+# Map of stubbed subcommands → step number that will implement them.
+# Future steps replace each stub with a real `source` + dispatch below.
+_clast_stub() {
+  local name="$1" step="$2"
+  clast_log_error "$name is not yet implemented (planned for step $step)"
+  exit 2
+}
+
+case "$cmd" in
+  whereami)
+    # shellcheck source=lib/clast/clast-subcommands/whereami.bash
+    source "$CLAST_LIB/clast-subcommands/whereami.bash"
+    clast_cmd_whereami "$@"
+    ;;
+  snapshot)
+    # shellcheck source=lib/clast/clast-subcommands/snapshot.bash
+    source "$CLAST_LIB/clast-subcommands/snapshot.bash"
+    clast_cmd_snapshot "$@"
+    ;;
+  projects)
+    # shellcheck source=lib/clast/clast-subcommands/projects.bash
+    source "$CLAST_LIB/clast-subcommands/projects.bash"
+    clast_cmd_projects "$@"
+    ;;
+  sessions)
+    # shellcheck source=lib/clast/clast-subcommands/sessions.bash
+    source "$CLAST_LIB/clast-subcommands/sessions.bash"
+    clast_cmd_sessions "$@"
+    ;;
+  show)
+    # shellcheck source=lib/clast/clast-subcommands/show.bash
+    source "$CLAST_LIB/clast-subcommands/show.bash"
+    clast_cmd_show "$@"
+    ;;
+  entries)
+    # shellcheck source=lib/clast/clast-subcommands/entries.bash
+    source "$CLAST_LIB/clast-subcommands/entries.bash"
+    clast_cmd_entries "$@"
+    ;;
+  breadcrumb)
+    # shellcheck source=lib/clast/clast-subcommands/breadcrumb.bash
+    source "$CLAST_LIB/clast-subcommands/breadcrumb.bash"
+    clast_cmd_breadcrumb "$@"
+    ;;
+  registry)
+    # shellcheck source=lib/clast/clast-subcommands/registry.bash
+    source "$CLAST_LIB/clast-subcommands/registry.bash"
+    clast_cmd_registry "$@"
+    ;;
+  stats)
+    # shellcheck source=lib/clast/clast-subcommands/stats.bash
+    source "$CLAST_LIB/clast-subcommands/stats.bash"
+    clast_cmd_stats "$@"
+    ;;
+  doctor)
+    # shellcheck source=lib/clast/clast-subcommands/doctor.bash
+    source "$CLAST_LIB/clast-subcommands/doctor.bash"
+    clast_cmd_doctor "$@"
+    ;;
+  *)
+    clast_log_error "unknown subcommand '$cmd'"
+    clast_usage >&2
+    exit 2
+    ;;
+esac

package/examples/config/config.toml.sample

@@ -0,0 +1,32 @@
+# examples/config/config.toml.sample
+#
+# NOTE: TOML config loading is planned for v1.x; v1.0 reads only
+# the equivalent environment variables. Set these in your shell
+# profile to get the same effect today.
+#
+# Uncommenting values in this file is a no-op in v1.0 because the
+# loader does not exist yet. Treat this file as documentation for
+# the planned config surface.
+#
+# ~/.config/clast/config.toml
+
+[paths]
+# Override where clast reads JSONL transcripts from.
+# Env equivalent: CLAST_PROJECTS_DIR
+# projects_dir = "/Users/you/.claude/projects"
+
+# Override where clast writes the journal.
+# Env equivalent: CLAST_JOURNAL_DIR
+# journal_dir = "/Users/you/.claude/journal"
+
+[time]
+# The "day" cutoff used by `clast stats`, `clast sessions`, and
+# the /day-wakeup window. Sessions started before this time on
+# date D count as belonging to date D-1.
+# Env equivalent: CLAST_DAY_CUTOFF
+# day_cutoff = "04:00"
+
+[logging]
+# Silence info logs (matches the global --quiet flag).
+# Env equivalent: CLAST_QUIET=1
+# quiet = false

package/examples/cron/clast-snapshot.service

@@ -0,0 +1,10 @@
+# clast hourly snapshot service.
+# Copy to ~/.config/systemd/user/clast-snapshot.service, edit ExecStart if needed,
+# then enable the timer with: systemctl --user enable --now clast-snapshot.timer
+
+[Unit]
+Description=Capture Claude Code transcripts with clast
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/clast snapshot

package/examples/cron/clast-snapshot.timer

@@ -0,0 +1,15 @@
+# clast hourly snapshot timer.
+# Copy to ~/.config/systemd/user/clast-snapshot.timer, then run:
+# systemctl --user enable --now clast-snapshot.timer
+
+[Unit]
+Description=Run clast snapshot hourly
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec=1h
+Persistent=true
+Unit=clast-snapshot.service
+
+[Install]
+WantedBy=timers.target

package/examples/cron/crontab.sample

@@ -0,0 +1,16 @@
+# clast cron sample for unattended transcript capture.
+# Install with: crontab -l | { cat; cat examples/cron/crontab.sample; } | crontab -
+# Edit the clast path if you installed somewhere other than /usr/local/bin.
+
+# Every hour at :05, capture any new transcripts.
+# Idempotent and silent on no-op, so safe to run frequently.
+5 * * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+
+# Alternative: every 15 minutes for active users moving between many sessions.
+# */15 * * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+
+# Alternative: once daily for hands-off archival.
+# 10 4 * * * /usr/local/bin/clast snapshot >/dev/null 2>&1
+
+# Alternative: no cron. Rely on the SessionStart hook installed with the plugin.
+# The hook covers most use cases already; cron is only useful when you want capture without ever opening Claude.

package/examples/workflows/morning-briefing.md

@@ -0,0 +1,137 @@
+# Morning Briefing Example
+
+This is a realistic walkthrough of one `/day-wakeup` run. Yesterday, `xesapps`
+finished a field-normalization fix, `notes` explored a journal template update,
+and `infra-tools` checked a flaky shell lint issue.
+
+```bash
+# User: /day-wakeup
+clast snapshot
+clast --json sessions --day yesterday
+```
+
+It filters to `curated: false`, groups by project, and shows:
+
+```text
+infra-tools  16:05  lint-shellcheck          17 messages
+notes        13:40  main                     31 messages
+xesapps      09:12  feature/field-normalize  58 messages
+```
+
+## Session 1: infra-tools
+
+The skill reads session details and breadcrumbs:
+
+```bash
+clast --json show 33333333-3333-4333-8333-333333333333 --full --turns 8
+clast breadcrumb --read --project infra-tools --day yesterday
+```
+
+It drafts a short entry:
+
+```markdown
+# Session: Shellcheck cleanup pass
+
+## Goal
+Understand why the lint job failed on the helper scripts.
+
+## Open threads
+- Decide whether to rewrite the helper or add a targeted shellcheck suppression.
+```
+
+AskUserQuestion presents `Accept`, `Accept + promote decision`, `Accept + promote
+common-issue`, `Accept + promote workflow`, `Edit`, `Skip`, and `Stop here`.
+
+The user chooses `Skip`. The skill writes nothing; the session remains
+uncurated and can be revisited in a later `/day-wakeup`.
+
+## Session 2: notes
+
+The skill reads the next transcript:
+
+```bash
+clast --json show 22222222-2222-4222-8222-222222222222 --full --turns 8
+clast breadcrumb --read --project notes --day yesterday
+```
+
+The user asks for a revision:
+
+```text
+User chooses: Edit
+Assistant asks: What should change?
+User: Make the title about the entry template, not the markdown cleanup.
+```
+
+The regenerated draft is accepted:
+
+```markdown
+# Session: Entry template cleanup
+## Goal
+Tighten the note-entry template before using it for project briefings.
+## What shipped
+- Drafted a shorter `## Open threads` section.
+- Removed duplicate wording from the template notes.
+```
+
+The skill writes through stdin:
+
+```bash
+clast entries write \
+  --session 22222222-2222-4222-8222-222222222222 \
+  --slug entry-template-cleanup \
+  --tags notes,template \
+  --title "Entry template cleanup" \
+  --body-stdin
+```
+
+## Session 3: xesapps
+
+The skill reads the session and breadcrumbs:
+
+```bash
+clast --json show 11111111-1111-4111-8111-111111111111 --full --turns 8
+clast breadcrumb --read --project xesapps --day yesterday
+```
+
+The user chooses `Accept + promote decision` for this draft:
+
+```markdown
+# Session: Field normalization fix
+## Goal
+Normalize field metadata before it reaches the consumer-field view.
+## What shipped
+- Added the canonical field-name path.
+- Merged the feature branch after the regression check passed.
+## Issues + fixes
+- **Issue:** The first pass changed display labels instead of canonical names.
+  **Fix:** Moved normalization earlier and kept display labels unchanged.
+```
+
+The skill asks for the promoted decision title and content. In v1.0, promoted
+items are folded into the entry body rather than written to separate decision,
+common-issue, or workflow files.
+
+```bash
+clast entries write \
+  --session 11111111-1111-4111-8111-111111111111 \
+  --slug field-normalization-fix \
+  --tags xesapps,fields,regression \
+  --title "Field normalization fix" \
+  --body-stdin
+```
+
+Final summary:
+
+```text
+Day wakeup complete.
+Curated: 2 sessions across 2 projects.
+Skipped: 1 session.
+Remaining uncurated: 1.
+Promoted: 1 decision (folded into the accepted entry for v1.0).
+Run `/wakeup <project>` to start working on a specific project today.
+```
+
+What this changes on disk:
+`entries/2026-05-31-1340-notes-entry-template-cleanup.md` and `entries/2026-05-31-0912-xesapps-field-normalization-fix.md` were written.
+`.manifest.jsonl` was already current from `clast snapshot`; curation does not append to it.
+The skipped `infra-tools` session stays uncurated and remains eligible for a later `/day-wakeup`.

package/hooks/hooks.json

@@ -0,0 +1,8 @@
+{
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "command": "${CLAUDE_PLUGIN_ROOT}/hooks/snapshot.sh"
+    }
+  ]
+}

package/hooks/snapshot.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# hooks/snapshot.sh
+#
+# Fired on Claude Code SessionStart. Backgrounds `clast snapshot` so it doesn't
+# block session start. Silent if clast isn't installed — the plugin can still
+# load cleanly even if the CLI isn't on PATH.
+#
+# Idempotent. Safe to run repeatedly. Best-effort: never propagates a non-zero
+# exit to Claude Code (a failed snapshot is not a session-start failure).
+# shellcheck shell=bash
+
+if command -v clast >/dev/null 2>&1; then
+  (clast snapshot >/dev/null 2>&1 &)
+fi
+exit 0

package/lib/clast/clast-decode-lib.bash

@@ -0,0 +1,184 @@
+# clast-decode-lib.bash — segment ↔ path encoder/decoder
+#
+# Claude Code stores transcripts under ~/.claude/projects/<segment>/, where
+# <segment> is the absolute project path with `/` replaced by `-`. The
+# encoding is lossy: a literal `-` in the source path becomes a `-` in the
+# segment, identical to a path separator. Decoding ambiguity is resolved
+# against the filesystem (and, for git repos, a `git rev-parse` probe).
+#
+# See docs/overview.md#glossary for the "segment" term and
+# docs/repo-bootstrap.md#libclastclast-decode-libbash for the algorithm.
+# shellcheck shell=bash
+
+if [[ -n "${_CLAST_DECODE_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_DECODE_LIB_SOURCED=1
+
+# clast_encode_path <absolute-path>
+#   "/home/beau/code/xesapps" -> "-home-beau-code-xesapps"
+#   "C:/Users/Beast/foo"      -> "C--Users-Beast-foo"
+clast_encode_path() {
+  local path="$1"
+  if [[ -z "$path" ]]; then
+    printf '\n'
+    return 0
+  fi
+  # Windows-style drive letter: "C:/..." -> "C-/..." (one dash for the colon),
+  # then the standard `/` -> `-` replacement turns the leading slash into a
+  # second dash, giving the canonical "C--..." form.
+  if [[ "$path" =~ ^([A-Za-z]):(/.*)$ ]]; then
+    path="${BASH_REMATCH[1]}-${BASH_REMATCH[2]}"
+  fi
+  printf '%s\n' "${path//\//-}"
+}
+
+# _clast_split_segment <segment>
+#   Strips a leading dash and (optionally) a Windows drive prefix. Sets
+#   globals _CLAST_PREFIX and _CLAST_REST for the caller. Returns 0 on
+#   success, 1 on empty input.
+#
+#   "-home-beau-foo"      -> prefix="/",    rest="home-beau-foo"
+#   "C--Users-Beast-foo"  -> prefix="C:/",  rest="Users-Beast-foo"
+#   "foo"                 -> prefix="/",    rest="foo"        (no leading dash)
+_clast_split_segment() {
+  local seg="$1"
+  if [[ -z "$seg" ]]; then
+    return 1
+  fi
+  if [[ "$seg" =~ ^([A-Za-z])--(.*)$ ]]; then
+    _CLAST_PREFIX="${BASH_REMATCH[1]}:/"
+    _CLAST_REST="${BASH_REMATCH[2]}"
+  elif [[ "$seg" == -* ]]; then
+    _CLAST_PREFIX="/"
+    _CLAST_REST="${seg#-}"
+  else
+    _CLAST_PREFIX="/"
+    _CLAST_REST="$seg"
+  fi
+  return 0
+}
+
+# clast_decode_candidates <segment>
+#   Print every possible decoding, one per line. No filesystem checks.
+#   Order is deterministic: separator-heavy decodings first (more `/`),
+#   matching the naive decode at the top of the list.
+clast_decode_candidates() {
+  local seg="$1"
+  if [[ -z "$seg" ]]; then
+    printf '\n'
+    return 0
+  fi
+  _clast_split_segment "$seg" || return 1
+  local prefix="$_CLAST_PREFIX" rest="$_CLAST_REST"
+
+  # Split rest on `-`. Each gap between tokens is either `/` (separator) or
+  # `-` (literal). Iterate bitmasks 0..(2^gaps - 1); bit set => literal dash.
+  local -a tokens=()
+  local IFS='-'
+  read -r -a tokens <<<"$rest"
+  unset IFS
+  local n=${#tokens[@]}
+  if (( n == 0 )); then
+    printf '%s\n' "$prefix"
+    return 0
+  fi
+  local gaps=$((n - 1))
+  local total=$((1 << gaps))
+  local mask i candidate
+  for (( mask = 0; mask < total; mask++ )); do
+    candidate="${tokens[0]}"
+    for (( i = 1; i < n; i++ )); do
+      if (( (mask >> (i - 1)) & 1 )); then
+        candidate+="-${tokens[i]}"
+      else
+        candidate+="/${tokens[i]}"
+      fi
+    done
+    printf '%s%s\n' "$prefix" "$candidate"
+  done
+}
+
+# _clast_naive_decode <segment>
+#   The "all dashes are separators" decoding — the first candidate.
+_clast_naive_decode() {
+  local seg="$1"
+  if [[ -z "$seg" ]]; then
+    printf '\n'
+    return 0
+  fi
+  _clast_split_segment "$seg" || return 1
+  local rest="${_CLAST_REST//-/\/}"
+  printf '%s%s\n' "$_CLAST_PREFIX" "$rest"
+}
+
+# clast_decode_segment <segment>
+#   Print the resolved absolute path. Exit 0 if confident, 1 if the answer
+#   is the naive decode but disk evidence is missing (caller may surface).
+clast_decode_segment() {
+  local seg="$1"
+  if [[ -z "$seg" ]]; then
+    printf '\n'
+    return 0
+  fi
+
+  local naive
+  naive="$(_clast_naive_decode "$seg")"
+
+  # 1. Naive decode resolves on disk → done.
+  if [[ -d "$naive" ]]; then
+    printf '%s\n' "$naive"
+    return 0
+  fi
+
+  # 2/3. Generate candidates, intersect with the filesystem.
+  local -a candidates=() existing=()
+  mapfile -t candidates < <(clast_decode_candidates "$seg")
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -d "$c" ]]; then
+      existing+=("$c")
+    fi
+  done
+
+  if (( ${#existing[@]} == 1 )); then
+    printf '%s\n' "${existing[0]}"
+    return 0
+  fi
+
+  if (( ${#existing[@]} > 1 )); then
+    # 3a. Consult sessions-index.json if present.
+    local idx projects_dir project_path
+    projects_dir="${CLAST_PROJECTS_DIR:-$HOME/.claude/projects}"
+    idx="$projects_dir/$seg/sessions-index.json"
+    if [[ -r "$idx" ]]; then
+      project_path="$(jq -r '.projectPath // empty' "$idx" 2>/dev/null || true)"
+      if [[ -n "$project_path" ]]; then
+        for c in "${existing[@]}"; do
+          if [[ "$c" == "$project_path" ]]; then
+            printf '%s\n' "$c"
+            return 0
+          fi
+        done
+      fi
+    fi
+    # 3b. git rev-parse probe.
+    local matches=()
+    for c in "${existing[@]}"; do
+      if git -C "$c" rev-parse --show-toplevel >/dev/null 2>&1; then
+        matches+=("$c")
+      fi
+    done
+    if (( ${#matches[@]} == 1 )); then
+      printf '%s\n' "${matches[0]}"
+      return 0
+    fi
+    # Still ambiguous — surface naive, caller decides.
+    printf '%s\n' "$naive"
+    return 1
+  fi
+
+  # 4. No candidate exists on disk.
+  printf '%s\n' "$naive"
+  return 1
+}