@procrastivity/clast 0.0.1

package/lib/clast/clast-registry-lib.bash

@@ -0,0 +1,252 @@
+# clast-registry-lib.bash — projects.json read/write/resolve
+#
+# Sourced after clast-lib.bash and clast-decode-lib.bash. The registry is
+# an append-only JSONL log at $(clast_journal_dir)/projects.json (the
+# ".json" name is historical — semantically it is JSONL). See
+# docs/cli-contract.md#registry-line-in-projectsjson for the on-disk
+# schema and docs/cli-contract.md#clast-registry for the resolution rules.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+# shellcheck source=lib/clast/clast-decode-lib.bash
+
+if [[ -n "${_CLAST_REGISTRY_LIB_SOURCED:-}" ]]; then
+  return 0
+fi
+_CLAST_REGISTRY_LIB_SOURCED=1
+
+# clast_registry_path — single chokepoint so CLAST_JOURNAL_DIR override
+# redirects every read/write.
+clast_registry_path() {
+  printf '%s\n' "$(clast_journal_dir)/projects.json"
+}
+
+# clast_registry_list_json — print the registry as a compact JSON array.
+# Missing file → []. Malformed lines are silently dropped (fromjson?).
+clast_registry_list_json() {
+  local path
+  path="$(clast_registry_path)"
+  if [[ ! -f "$path" ]]; then
+    printf '[]\n'
+    return 0
+  fi
+  jq -cR 'fromjson?' "$path" \
+    | jq -cs 'map(select(type == "object" and .path != null))'
+}
+
+# clast_registry_match_remote <remote>
+#   Print slug of first line whose .remote == <remote>; return 1 if none.
+#   Empty <remote> → return 1 (does not match unset remotes).
+clast_registry_match_remote() {
+  local remote="${1:-}"
+  if [[ -z "$remote" ]]; then
+    return 1
+  fi
+  local arr slug
+  arr="$(clast_registry_list_json)"
+  slug="$(jq -r --arg r "$remote" 'map(select(.remote == $r)) | .[0].slug // empty' <<<"$arr")"
+  if [[ -z "$slug" ]]; then
+    return 1
+  fi
+  printf '%s\n' "$slug"
+}
+
+# clast_registry_resolve <path-or-segment>
+#   Print slug on hit, return 1 silently on miss.
+clast_registry_resolve() {
+  local input="${1:-}"
+  if [[ -z "$input" ]]; then
+    return 1
+  fi
+
+  local arr
+  arr="$(clast_registry_list_json)"
+
+  # Segment input: starts with `-`. Decode (possibly ambiguous) then
+  # resolve as a path.
+  if [[ "$input" == -* ]]; then
+    local -a candidates=()
+    mapfile -t candidates < <(clast_decode_candidates "$input")
+    local c slug
+    # Prefer registry-matching candidate over filesystem-resolving one.
+    for c in "${candidates[@]}"; do
+      slug="$(_clast_registry_lookup_path "$c" "$arr")" || continue
+      if [[ -n "$slug" ]]; then
+        printf '%s\n' "$slug"
+        return 0
+      fi
+    done
+    return 1
+  fi
+
+  # Path input: canonicalize. `realpath -m` resolves non-existent paths
+  # (whereami inside a non-git tmpdir). BSD realpath lacks -m; the nix
+  # dev shell pulls in GNU coreutils.
+  local canon
+  canon="$(realpath -m "$input" 2>/dev/null || printf '%s' "$input")"
+  local slug
+  slug="$(_clast_registry_lookup_path "$canon" "$arr")" || return 1
+  if [[ -z "$slug" ]]; then
+    return 1
+  fi
+  printf '%s\n' "$slug"
+}
+
+# _clast_registry_lookup_path <path> <registry-json-array>
+#   First match wins: scan .path, then .aliases[]. Print slug or empty.
+_clast_registry_lookup_path() {
+  local p="$1" arr="$2"
+  jq -r --arg p "$p" '
+    (map(select(.path == $p)) | .[0].slug)
+    // (map(select(.aliases? // [] | index($p) != null)) | .[0].slug)
+    // empty
+  ' <<<"$arr"
+}
+
+# clast_registry_add <path> [--slug NAME] [--remote URL]
+#   Append a single JSONL line. Default slug = basename(path). Default
+#   remote = `git -C <path> remote get-url origin` (or absent). If the
+#   resolved remote matches an existing entry's remote, append a new line
+#   carrying that entry's slug and rolling its known paths into aliases.
+#   Print the appended JSON on stdout. Exit 2 on bad args, 1 on write fail.
+clast_registry_add() {
+  local path="" slug="" remote="" remote_explicit=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --slug)
+        if [[ $# -lt 2 ]]; then
+          clast_log_error "clast_registry_add: --slug requires a value"
+          return 2
+        fi
+        slug="$2"; shift 2 ;;
+      --slug=*)  slug="${1#*=}"; shift ;;
+      --remote)
+        if [[ $# -lt 2 ]]; then
+          clast_log_error "clast_registry_add: --remote requires a value"
+          return 2
+        fi
+        remote="$2"; remote_explicit=1; shift 2 ;;
+      --remote=*) remote="${1#*=}"; remote_explicit=1; shift ;;
+      -*)
+        clast_log_error "clast_registry_add: unknown flag '$1'"
+        return 2
+        ;;
+      *)
+        if [[ -n "$path" ]]; then
+          clast_log_error "clast_registry_add: unexpected positional '$1'"
+          return 2
+        fi
+        path="$1"; shift
+        ;;
+    esac
+  done
+
+  # Reject empty / whitespace-only paths.
+  local trimmed="${path//[[:space:]]/}"
+  if [[ -z "$trimmed" ]]; then
+    clast_log_error "clast_registry_add: <path> is required"
+    return 2
+  fi
+
+  # Canonicalize. -m tolerates non-existent paths.
+  local canon
+  canon="$(realpath -m "$path" 2>/dev/null || printf '%s' "$path")"
+
+  # Resolve default remote if not given. Tolerate missing git / non-repo.
+  if [[ $remote_explicit -eq 0 ]]; then
+    if command -v git >/dev/null 2>&1 && [[ -d "$canon" ]]; then
+      remote="$(git -C "$canon" remote get-url origin 2>/dev/null || true)"
+    fi
+  fi
+
+  # Default slug from basename.
+  if [[ -z "$slug" ]]; then
+    slug="$(basename "$canon")"
+  fi
+
+  # Aliases roll-up only when remote matched an existing entry.
+  local arr matched_slug
+  arr="$(clast_registry_list_json)"
+  local aliases_json='[]'
+  if [[ -n "$remote" ]]; then
+    matched_slug="$(jq -r --arg r "$remote" 'map(select(.remote == $r)) | .[0].slug // empty' <<<"$arr")"
+    if [[ -n "$matched_slug" ]]; then
+      slug="$matched_slug"
+      # Collect every known path for this slug (excluding the new one),
+      # plus their existing aliases.
+      aliases_json="$(jq -c --arg s "$slug" --arg p "$canon" '
+        [ .[] | select(.slug == $s) | [.path] + (.aliases // []) ]
+        | add // []
+        | map(select(. != $p))
+        | unique
+      ' <<<"$arr")"
+    fi
+  fi
+
+  local journal_dir
+  journal_dir="$(clast_journal_dir)"
+  if ! mkdir -p "$journal_dir"; then
+    clast_log_error "clast_registry_add: failed to create '$journal_dir'"
+    return 1
+  fi
+
+  local first_seen
+  first_seen="$(clast_today)"
+
+  local line
+  line="$(jq -c -n \
+    --arg path "$canon" \
+    --arg slug "$slug" \
+    --arg remote "$remote" \
+    --arg first_seen "$first_seen" \
+    --argjson aliases "$aliases_json" \
+    '{path: $path, slug: $slug, remote: $remote, first_seen: $first_seen}
+     | with_entries(select(.value != null and .value != ""))
+     | . + {aliases: $aliases}')" || {
+    clast_log_error "clast_registry_add: jq failed to build registry line"
+    return 1
+  }
+
+  local registry_path
+  registry_path="$(clast_registry_path)"
+  if ! printf '%s\n' "$line" >>"$registry_path" 2>/dev/null; then
+    clast_log_error "clast_registry_add: failed to append to '$registry_path'"
+    return 1
+  fi
+
+  printf '%s\n' "$line"
+}
+
+# clast_registry_remove <slug>
+#   Whole-file rewrite via clast_atomic_write. Return 0 only when ≥ 1
+#   line was removed; 1 otherwise. Never touches files other than
+#   projects.json.
+clast_registry_remove() {
+  local slug="${1:-}"
+  if [[ -z "$slug" ]]; then
+    clast_log_error "clast_registry_remove: <slug> is required"
+    return 2
+  fi
+  local registry_path
+  registry_path="$(clast_registry_path)"
+  if [[ ! -f "$registry_path" ]]; then
+    return 1
+  fi
+
+  local before after kept
+  before="$(jq -cR 'fromjson? | select(.path != null)' "$registry_path" | grep -c . || true)"
+  kept="$(jq -cR --arg s "$slug" 'fromjson? | select(.path != null and .slug != $s)' "$registry_path")"
+  after="$(printf '%s\n' "$kept" | grep -c . || true)"
+  if (( before == after )); then
+    return 1
+  fi
+
+  # Trailing newline only when content is non-empty.
+  local content=""
+  if [[ -n "$kept" ]]; then
+    content="$kept"$'\n'
+  fi
+  if ! clast_atomic_write "$registry_path" "$content"; then
+    return 1
+  fi
+  return 0
+}

package/lib/clast/clast-subcommands/breadcrumb.bash

@@ -0,0 +1,454 @@
+# clast-subcommands/breadcrumb.bash — `clast breadcrumb` write/read/list.
+#
+# Breadcrumbs are one-line in-flight hints stored under
+#   $(clast_journal_dir)/breadcrumbs/YYYY-MM-DD-<project>.md
+# with tiny YAML frontmatter and append-only Markdown body lines.
+# shellcheck shell=bash
+# shellcheck source=lib/clast/clast-lib.bash
+# shellcheck source=lib/clast/clast-registry-lib.bash
+# shellcheck source=lib/clast/clast-decode-lib.bash
+
+clast_cmd_breadcrumb() {
+  local arg saw_read=0 saw_list=0 before_double_dash=1
+
+  _clast_breadcrumb_strip_json "$@"
+  set -- "${_CLAST_BREADCRUMB_JSON_STRIPPED[@]}"
+
+  for arg in "$@"; do
+    case "$arg" in
+      -h|--help)
+        _clast_breadcrumb_usage
+        return 0
+        ;;
+    esac
+  done
+
+  for arg in "$@"; do
+    if (( before_double_dash )) && [[ "$arg" == "--" ]]; then
+      before_double_dash=0
+      continue
+    fi
+    if (( ! before_double_dash )); then
+      continue
+    fi
+    case "$arg" in
+      --read) saw_read=1 ;;
+      --list) saw_list=1 ;;
+    esac
+  done
+
+  if (( saw_read && saw_list )); then
+    _clast_breadcrumb_err "--read and --list are mutually exclusive" 2
+    return 2
+  fi
+
+  if (( saw_list )); then
+    _clast_breadcrumb_strip_mode --list "$@"
+    _clast_breadcrumb_list "${_CLAST_BREADCRUMB_STRIPPED[@]}"
+  elif (( saw_read )); then
+    _clast_breadcrumb_strip_mode --read "$@"
+    _clast_breadcrumb_read "${_CLAST_BREADCRUMB_STRIPPED[@]}"
+  else
+    _clast_breadcrumb_write "$@"
+  fi
+}
+
+_clast_breadcrumb_strip_json() {
+  local arg before_double_dash=1
+  _CLAST_BREADCRUMB_JSON_STRIPPED=()
+  for arg in "$@"; do
+    if (( before_double_dash )) && [[ "$arg" == "--" ]]; then
+      before_double_dash=0
+      _CLAST_BREADCRUMB_JSON_STRIPPED+=("$arg")
+      continue
+    fi
+    if (( before_double_dash )) && [[ "$arg" == "--json" ]]; then
+      export CLAST_JSON=1
+      continue
+    fi
+    _CLAST_BREADCRUMB_JSON_STRIPPED+=("$arg")
+  done
+}
+
+_clast_breadcrumb_usage() {
+  cat <<'EOF'
+Usage:
+  clast breadcrumb [--project SLUG | --global] [--date DATE] <TEXT>
+  clast breadcrumb --read [--project SLUG | --global] [--day DATE]
+  clast breadcrumb --list [--day DATE]
+
+DATE accepts ISO, today, yesterday, last-week, -Nd, -Nw.
+EOF
+}
+
+_clast_breadcrumb_err() {
+  local msg="$1" code="${2:-2}"
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -cn --arg m "$msg" --argjson c "$code" '{error:$m, code:$c}'
+  else
+    printf 'clast: breadcrumb: %s\n' "$msg" >&2
+  fi
+}
+
+_clast_breadcrumb_strip_mode() {
+  local strip="$1" arg stripped=0 before_double_dash=1
+  shift
+  _CLAST_BREADCRUMB_STRIPPED=()
+  for arg in "$@"; do
+    if (( before_double_dash )) && [[ "$arg" == "--" ]]; then
+      before_double_dash=0
+      _CLAST_BREADCRUMB_STRIPPED+=("$arg")
+      continue
+    fi
+    if (( before_double_dash )) && (( ! stripped )) && [[ "$arg" == "$strip" ]]; then
+      stripped=1
+      continue
+    fi
+    _CLAST_BREADCRUMB_STRIPPED+=("$arg")
+  done
+}
+
+_clast_breadcrumb_resolve_date() {
+  local flag="$1" input="$2" resolved
+  if ! resolved="$(clast_parse_date "$input" 2>/dev/null)"; then
+    return 2
+  fi
+  if ! [[ "$resolved" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+    return 2
+  fi
+  printf '%s\n' "$resolved"
+}
+
+_clast_breadcrumb_resolve_scope() {
+  local project_filter="$1" scope_global="$2" out_name="$3" resolved_slug reg_json
+  if [[ -n "$project_filter" ]]; then
+    resolved_slug="$project_filter"
+    reg_json="$(clast_registry_list_json)"
+    if ! jq -e --arg s "$resolved_slug" 'any(.slug == $s)' <<<"$reg_json" >/dev/null; then
+      clast_log_warn "slug '$resolved_slug' not in registry"
+    fi
+    printf -v "$out_name" '%s' "$resolved_slug"
+    return 0
+  fi
+  if [[ "$scope_global" == "1" ]]; then
+    printf -v "$out_name" '%s' "_global"
+    return 0
+  fi
+  if resolved_slug="$(clast_registry_resolve "$PWD" 2>/dev/null)" && [[ -n "$resolved_slug" ]]; then
+    printf -v "$out_name" '%s' "$resolved_slug"
+    return 0
+  fi
+
+  return 1
+}
+
+_clast_breadcrumb_path() {
+  local day="$1" slug="$2" journal_dir
+  journal_dir="$(realpath -m "$(clast_journal_dir)")"
+  printf '%s\n' "$journal_dir/breadcrumbs/$day-$slug.md"
+}
+
+_clast_breadcrumb_validate_slug() {
+  local slug="$1"
+  if [[ -z "$slug" || "$slug" == "." || "$slug" == ".." || "$slug" == *"/"* || "$slug" == *$'\n'* || "$slug" == *$'\r'* ]]; then
+    _clast_breadcrumb_err "invalid project slug '$slug'" 2
+    return 2
+  fi
+}
+
+_clast_breadcrumb_line_count() {
+  local path="$1" count
+  count="$(grep -c '^- ' "$path" 2>/dev/null || true)"
+  printf '%s\n' "${count:-0}"
+}
+
+_clast_breadcrumb_parse_scope_flag() {
+  local flag="$1" project_filter_name="$2" scope_global_name="$3"
+  local -n project_filter_ref="$project_filter_name"
+  local -n scope_global_ref="$scope_global_name"
+  case "$flag" in
+    project)
+      if [[ "$scope_global_ref" == "1" ]]; then
+        _clast_breadcrumb_err "--project and --global are mutually exclusive" 2
+        return 2
+      fi
+      ;;
+    global)
+      if [[ -n "$project_filter_ref" ]]; then
+        _clast_breadcrumb_err "--project and --global are mutually exclusive" 2
+        return 2
+      fi
+      scope_global_ref=1
+      ;;
+  esac
+}
+
+_clast_breadcrumb_write() {
+  local project_filter="" scope_global=0 date_input="" resolved_date="" slug="" text="" path line epoch hhmm content line_count rel
+  local -a words=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h|--help)
+        _clast_breadcrumb_usage
+        return 0
+        ;;
+      --project)
+        if [[ $# -lt 2 ]]; then _clast_breadcrumb_err "--project requires a value" 2; return 2; fi
+        _clast_breadcrumb_parse_scope_flag project project_filter scope_global || return $?
+        project_filter="$2"
+        shift 2
+        ;;
+      --project=*)
+        _clast_breadcrumb_parse_scope_flag project project_filter scope_global || return $?
+        project_filter="${1#*=}"
+        shift
+        ;;
+      --global)
+        _clast_breadcrumb_parse_scope_flag global project_filter scope_global || return $?
+        shift
+        ;;
+      --date)
+        if [[ $# -lt 2 ]]; then _clast_breadcrumb_err "--date requires a value" 2; return 2; fi
+        date_input="$2"
+        shift 2
+        ;;
+      --date=*)
+        date_input="${1#*=}"
+        shift
+        ;;
+      --)
+        shift
+        while [[ $# -gt 0 ]]; do words+=("$1"); shift; done
+        ;;
+      -*)
+        _clast_breadcrumb_err "unknown flag '$1'" 2
+        return 2
+        ;;
+      *)
+        words+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local word
+  for word in "${words[@]}"; do
+    if [[ "$word" == *$'\n'* || "$word" == *$'\r'* ]]; then
+      _clast_breadcrumb_err "text must be a single line" 2
+      return 2
+    fi
+  done
+  text="${words[*]}"
+  if ! [[ "$text" =~ [^[:space:]] ]]; then
+    _clast_breadcrumb_err "missing required argument <TEXT>" 2
+    return 2
+  fi
+
+  if [[ -n "$date_input" ]]; then
+    if ! resolved_date="$(_clast_breadcrumb_resolve_date --date "$date_input")"; then
+      _clast_breadcrumb_err "invalid --date '$date_input'" 2
+      return 2
+    fi
+  else
+    resolved_date="$(clast_today)"
+  fi
+
+  if ! _clast_breadcrumb_resolve_scope "$project_filter" "$scope_global" slug; then
+    _clast_breadcrumb_err "pwd does not resolve to a registered project (pass --project SLUG or --global)" 1
+    return 1
+  fi
+  _clast_breadcrumb_validate_slug "$slug" || return $?
+  path="$(_clast_breadcrumb_path "$resolved_date" "$slug")"
+  mkdir -p "$(dirname "$path")" || { _clast_breadcrumb_err "failed to create breadcrumbs directory" 1; return 1; }
+
+  epoch="${CLAST_NOW_EPOCH:-$(date +%s)}"
+  if ! hhmm="$(date -d "@$epoch" +%H:%M 2>/dev/null)"; then
+    _clast_breadcrumb_err "failed to format timestamp" 1
+    return 1
+  fi
+  line="- $hhmm — $text"
+
+  if [[ ! -e "$path" ]]; then
+    content=$'---\n'
+    content+="date: $resolved_date"$'\n'
+    content+="project: $slug"$'\n'
+    content+=$'---\n\n'
+    content+="$line"$'\n'
+    if ! clast_atomic_write "$path" "$content"; then
+      _clast_breadcrumb_err "failed to write '$path'" 1
+      return 1
+    fi
+  else
+    if [[ -s "$path" ]] && [[ "$(tail -c 1 "$path" | wc -l | tr -d ' ')" == "0" ]]; then
+      printf '\n%s\n' "$line" >>"$path" || { _clast_breadcrumb_err "failed to append '$path'" 1; return 1; }
+    else
+      printf '%s\n' "$line" >>"$path" || { _clast_breadcrumb_err "failed to append '$path'" 1; return 1; }
+    fi
+  fi
+
+  line_count="$(_clast_breadcrumb_line_count "$path")"
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -cn --arg path "$path" --arg slug "$slug" --arg date "$resolved_date" --argjson n "$line_count" \
+      '{path:$path, slug:$slug, date:$date, line_count:$n}'
+  elif [[ -n "${CLAST_VERBOSE:-}" ]]; then
+    rel="breadcrumbs/$resolved_date-$slug.md"
+    printf 'clast: breadcrumb: wrote %s (%s lines)\n' "$rel" "$line_count" >&2
+  fi
+}
+
+_clast_breadcrumb_read() {
+  local project_filter="" scope_global=0 day_input="" resolved_day="" slug="" path
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h|--help)
+        _clast_breadcrumb_usage
+        return 0
+        ;;
+      --project)
+        if [[ $# -lt 2 ]]; then _clast_breadcrumb_err "--project requires a value" 2; return 2; fi
+        _clast_breadcrumb_parse_scope_flag project project_filter scope_global || return $?
+        project_filter="$2"
+        shift 2
+        ;;
+      --project=*)
+        _clast_breadcrumb_parse_scope_flag project project_filter scope_global || return $?
+        project_filter="${1#*=}"
+        shift
+        ;;
+      --global)
+        _clast_breadcrumb_parse_scope_flag global project_filter scope_global || return $?
+        shift
+        ;;
+      --day)
+        if [[ $# -lt 2 ]]; then _clast_breadcrumb_err "--day requires a value" 2; return 2; fi
+        day_input="$2"
+        shift 2
+        ;;
+      --day=*)
+        day_input="${1#*=}"
+        shift
+        ;;
+      --)
+        shift
+        if [[ $# -gt 0 ]]; then _clast_breadcrumb_err "unexpected arg '$1'" 2; return 2; fi
+        ;;
+      -*)
+        _clast_breadcrumb_err "unknown flag '$1'" 2
+        return 2
+        ;;
+      *)
+        _clast_breadcrumb_err "unexpected arg '$1'" 2
+        return 2
+        ;;
+    esac
+  done
+
+  if [[ -n "$day_input" ]]; then
+    if ! resolved_day="$(_clast_breadcrumb_resolve_date --day "$day_input")"; then
+      _clast_breadcrumb_err "invalid --day '$day_input'" 2
+      return 2
+    fi
+  else
+    resolved_day="$(clast_today)"
+  fi
+  if ! _clast_breadcrumb_resolve_scope "$project_filter" "$scope_global" slug; then
+    _clast_breadcrumb_err "pwd does not resolve to a registered project (pass --project SLUG or --global)" 1
+    return 1
+  fi
+  _clast_breadcrumb_validate_slug "$slug" || return $?
+  path="$(_clast_breadcrumb_path "$resolved_day" "$slug")"
+
+  if [[ -f "$path" ]]; then
+    if [[ -n "${CLAST_JSON:-}" ]]; then
+      jq -n --arg path "$path" --rawfile content "$path" '{path:$path, exists:true, content:$content}'
+    elif [[ -z "${CLAST_QUIET:-}" ]]; then
+      cat -- "$path"
+    fi
+  else
+    if [[ -n "${CLAST_JSON:-}" ]]; then
+      jq -cn --arg path "$path" '{path:$path, exists:false, content:""}'
+    fi
+  fi
+}
+
+_clast_breadcrumb_list() {
+  local day_input="" resolved_day="" dir rows_json
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h|--help)
+        _clast_breadcrumb_usage
+        return 0
+        ;;
+      --day)
+        if [[ $# -lt 2 ]]; then _clast_breadcrumb_err "--day requires a value" 2; return 2; fi
+        day_input="$2"
+        shift 2
+        ;;
+      --day=*)
+        day_input="${1#*=}"
+        shift
+        ;;
+      --)
+        shift
+        if [[ $# -gt 0 ]]; then _clast_breadcrumb_err "unexpected arg '$1'" 2; return 2; fi
+        ;;
+      -*)
+        _clast_breadcrumb_err "unknown flag '$1'" 2
+        return 2
+        ;;
+      *)
+        _clast_breadcrumb_err "unexpected arg '$1'" 2
+        return 2
+        ;;
+    esac
+  done
+
+  if [[ -n "$day_input" ]]; then
+    if ! resolved_day="$(_clast_breadcrumb_resolve_date --day "$day_input")"; then
+      _clast_breadcrumb_err "invalid --day '$day_input'" 2
+      return 2
+    fi
+  else
+    resolved_day="$(clast_today)"
+  fi
+
+  dir="$(realpath -m "$(clast_journal_dir)")/breadcrumbs"
+  rows_json="$(_clast_breadcrumb_list_rows "$dir" "$resolved_day")"
+  if [[ -n "${CLAST_JSON:-}" ]]; then
+    jq -n --argjson rows "$rows_json" '$rows'
+    return 0
+  fi
+  if [[ -n "${CLAST_QUIET:-}" ]]; then
+    return 0
+  fi
+
+  printf '%-17s %-50s %11s\n' "project" "path" "breadcrumbs"
+  jq -r '.[] | [.project, .path, (.line_count|tostring)] | @tsv' <<<"$rows_json" \
+    | while IFS=$'\t' read -r project path count; do
+        if [[ "$project" == "_global" ]]; then
+          project="(global)"
+        fi
+        printf '%-17s %-50s %11s\n' "$project" "$path" "$count"
+      done
+}
+
+_clast_breadcrumb_list_rows() {
+  local dir="$1" day="$2" file base project count abs
+  if [[ ! -d "$dir" ]]; then
+    printf '[]\n'
+    return 0
+  fi
+
+  find "$dir" -maxdepth 1 -type f -name "$day-*.md" -print0 \
+    | while IFS= read -r -d '' file; do
+        base="$(basename "$file")"
+        project="${base#"$day-"}"
+        project="${project%.md}"
+        abs="$(realpath -m "$file")"
+        count="$(_clast_breadcrumb_line_count "$file")"
+        jq -cn --arg project "$project" --arg path "$abs" --argjson line_count "$count" \
+          '{project:$project, path:$path, line_count:$line_count}'
+      done \
+    | jq -cs 'sort_by(.project)'
+}