1#!/bin/sh
2# planning-with-files: resolve active plan directory.
3#
4# Resolution order:
5#   1. $PLAN_ID env var → ./.planning/$PLAN_ID/ if exists
6#   2. ./.planning/.active_plan content → matching dir if exists
7#   3. Newest ./.planning/<dir>/ by mtime
8#   4. Otherwise empty stdout (caller falls back to legacy ./task_plan.md)
9#
10# Always exits 0. Never errors out the agent loop.
11#
12# Usage:
13#   PLAN_DIR="$(sh scripts/resolve-plan-dir.sh)"
14#   PLAN_FILE="${PLAN_DIR:+$PLAN_DIR/}task_plan.md"
15 
16set -u
17 
18PLAN_ROOT="${1:-${PWD}/.planning}"
19ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
20 
21# Plan-id safe-identifier check. Rejects whitespace, path separators, leading
22# dots, and empty strings; accepts the YYYY-MM-DD-<slug> shape from
23# init-session.sh as well as legacy hand-created names like "alpha" or
24# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
25# .active_plan file containing only whitespace or random text) without
26# enforcing a date prefix that would break backward compatibility.
27SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'
28 
29slug_is_valid() {
30    case "$1" in
31        '') return 1 ;;
32    esac
33    printf "%s" "$1" | grep -Eq "${SLUG_RE}"
34}
35 
36# Portable path canonicalizer. realpath first (Linux, modern coreutils),
37# then readlink -f (older GNU), then python3/python os.path.realpath. Prints
38# the canonical absolute path on success; prints nothing and returns 1 on a
39# full miss so the caller can decide what to do. No python spawn on the happy
40# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
41canonicalize() {
42    target="$1"
43    if command -v realpath >/dev/null 2>&1; then
44        out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
45            printf "%s\n" "${out}"; return 0; }
46    fi
47    if command -v readlink >/dev/null 2>&1; then
48        out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
49            printf "%s\n" "${out}"; return 0; }
50    fi
51    if command -v python3 >/dev/null 2>&1; then
52        out="$(python3 -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
53            && [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
54    fi
55    if command -v python >/dev/null 2>&1; then
56        out="$(python -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
57            && [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
58    fi
59    return 1
60}
61 
62# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
63# path under the project root (the CWD the script runs from). A symlink inside
64# a valid slug dir pointing at /etc or outside the workspace would otherwise let
65# the hooks hash and inject an arbitrary file. On any violation we return 1 so
66# the caller treats the candidate as unresolved and falls back safely. If
67# canonicalization is unavailable for BOTH paths we fail open (return 0) to keep
68# legacy behavior byte-equivalent on minimal shells that lack realpath/readlink
69# and python; the SLUG_RE check already blocks traversal in the slug name.
70is_within_root() {
71    candidate="$1"
72    root_real="$(canonicalize "${PWD}")" || root_real=""
73    cand_real="$(canonicalize "${candidate}")" || cand_real=""
74    if [ -z "${root_real}" ] || [ -z "${cand_real}" ]; then
75        return 0
76    fi
77    case "${cand_real}" in
78        "${root_real}"|"${root_real}"/*) return 0 ;;
79        *) return 1 ;;
80    esac
81}
82 
83# Portable mtime resolver. Tries GNU stat, BSD stat, BSD/macOS date -r,
84# python3, then perl. Returns "0" on full miss so callers can sort.
85mtime_of() {
86    target="$1"
87    out="$(stat -c '%Y' "${target}" 2>/dev/null)"
88    if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
89    out="$(stat -f '%m' "${target}" 2>/dev/null)"
90    if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
91    out="$(date -r "${target}" +%s 2>/dev/null)"
92    if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
93    if command -v python3 >/dev/null 2>&1; then
94        out="$(python3 -c "import os,sys;print(int(os.stat(sys.argv[1]).st_mtime))" "${target}" 2>/dev/null)"
95        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
96    fi
97    if command -v python >/dev/null 2>&1; then
98        out="$(python -c "import os,sys;print(int(os.stat(sys.argv[1]).st_mtime))" "${target}" 2>/dev/null)"
99        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
100    fi
101    if command -v perl >/dev/null 2>&1; then
102        out="$(perl -e 'print((stat shift)[9])' "${target}" 2>/dev/null)"
103        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
104    fi
105    printf "0\n"
106}
107 
108resolve_from_env() {
109    plan_id="${PLAN_ID:-}"
110    slug_is_valid "${plan_id}" || return 1
111    candidate="${PLAN_ROOT}/${plan_id}"
112    if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
113        printf "%s\n" "${candidate}"
114        return 0
115    fi
116    return 1
117}
118 
119resolve_from_active_file() {
120    [ -f "${ACTIVE_FILE}" ] || return 1
121    plan_id="$(tr -d '\r\n[:space:]' < "${ACTIVE_FILE}")"
122    slug_is_valid "${plan_id}" || return 1
123    candidate="${PLAN_ROOT}/${plan_id}"
124    if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
125        printf "%s\n" "${candidate}"
126        return 0
127    fi
128    return 1
129}
130 
131resolve_latest_dir() {
132    [ -d "${PLAN_ROOT}" ] || return 1
133    # Portable newest-mtime selector. Skips hidden dirs, slug-invalid names,
134    # and dirs without task_plan.md (e.g. sessions/).
135    latest=""
136    latest_mtime=0
137    for entry in "${PLAN_ROOT}"/*/; do
138        [ -d "${entry}" ] || continue
139        clean="${entry%/}"
140        name="$(basename "${clean}")"
141        case "${name}" in
142            .*) continue ;;
143        esac
144        slug_is_valid "${name}" || continue
145        [ -f "${clean}/task_plan.md" ] || continue
146        is_within_root "${clean}" || continue
147        mtime="$(mtime_of "${clean}")"
148        if [ "${mtime}" -gt "${latest_mtime}" ] 2>/dev/null; then
149            latest_mtime="${mtime}"
150            latest="${clean}"
151        fi
152    done
153    if [ -n "${latest}" ]; then
154        printf "%s\n" "${latest}"
155        return 0
156    fi
157    return 1
158}
159 
160if resolve_from_env; then exit 0; fi
161if resolve_from_active_file; then exit 0; fi
162if resolve_latest_dir; then exit 0; fi
163exit 0
164