devflow-kit 3.0.1 → 3.2.0

package/src/assets/scripts/hooks/ensure-root-gitignore

@@ -26,7 +26,7 @@
 #   - session-start-context (always-on, memory-independent — covers memory-off
 #     projects that still use learning/knowledge)
 # Both reach this one writer so the rule is applied identically everywhere; this
-# decouples git-tracking of .devflow/ from any single feature toggle (avoids PF-014).
+# decouples git-tracking of .devflow/ from any single feature toggle.
 #
 # Idempotent and O(1) after the first run via the .root-gitignore-configured-v6
 # marker under .devflow/ (project-local). The marker is a claim, not proof, so the
@@ -58,6 +58,22 @@
 # `!.claudeignore` entry means "the user owns that line" — emit the block without it.
 # All matching is whole-line and whitespace-tolerant; never substring.
 #
+# D-GITIGNORE-LINK-INSIDE: a root .gitignore that is a symbolic link is written only
+# when the file it resolves to lies inside the project root and outside any .git
+# folder in the project, the project's own or a nested repository's: no part of its
+# path below the root may be named .git, in any letter case, as git itself refuses
+# such a path. Then that file is read and written directly, never through the link.
+# Otherwise nothing is read or written anywhere, no marker is stamped, the skip is
+# logged once and the caller goes on. Reason: a repository can commit .gitignore as a
+# link to any file on the machine, and the carve-out would be appended to it; a file
+# in a .git is no file of the repository's either, but git's own hooks and config,
+# and a line appended to a hook runs as a command the next time git runs it. The case
+# matters because a case-insensitive file system (macOS) opens .git for .GIT. The TS
+# twin, ensureDevflowGitignore in src/targets/claude-code/post-install.ts, applies the
+# same rule the same way: the link is followed one hop at a time, at most 40 hops, and
+# only its last folder is resolved physically, so a missing file inside the project
+# is created there as before.
+#
 # Usage: source ensure-root-gitignore "$PROJECT_ROOT"
 # Sourced helper: uses `return` (never exit), _ERG_-prefixed locals (never clobbers
 # caller vars).
@@ -68,6 +84,76 @@ _ERG_DEVFLOW_DIR="$1/.devflow"
 _ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v6"
 _ERG_GITIGNORE="$1/.gitignore"
 
+# _erg_resolve_inside <root> <link> — follow the symbolic link <link> one hop at a
+# time, at most 40, and set _ERG_RESOLVED to the file it leads to, its folder
+# resolved physically. Returns 0 when that file lies inside <root> and no part of its
+# path below <root> is named .git in any letter case (D-GITIGNORE-LINK-INSIDE);
+# returns 1, with _ERG_RESOLVED empty, when it does not and when the link cannot be
+# followed: a read that fails, an empty or folder-like target, a chain longer than
+# 40, a folder that does not resolve. A predicate: call it in an `if`, never as a
+# plain statement under `set -e`. Relative targets are joined to the folder the link
+# sits in as spelled, never normalised, so `..` is resolved by the file system as the
+# write itself would resolve it. Each hop forks one readlink; `cd -P` and $PWD are
+# builtins, and the caller's folder is restored before returning.
+_erg_resolve_inside() {
+  local _root="$1" _cur="$2" _target="" _dir="" _base="" _root_real="" _hops=0 _back="$PWD"
+  _ERG_RESOLVED=''
+  # Absolute from the start, so no path is read as an option, searched for along
+  # CDPATH, or taken relative to a folder this function moved into.
+  case "$_root" in /*) ;; *) _root="$_back/$_root" ;; esac
+  case "$_cur" in /*) ;; *) _cur="$_back/$_cur" ;; esac
+  while [ -L "$_cur" ]; do
+    [ "$_hops" -lt 40 ] || return 1
+    # The `x` keeps a target's own trailing newlines from command substitution; the
+    # one newline readlink adds is then removed.
+    _target="$(readlink "$_cur" 2>/dev/null && printf x)"
+    case "$_target" in *x) _target="${_target%x}" ;; *) return 1 ;; esac
+    _target="${_target%$'\n'}"
+    case "$_target" in
+      '') return 1 ;;
+      /*) _cur="$_target" ;;
+      *) _cur="${_cur%/*}/$_target" ;;
+    esac
+    _hops=$((_hops + 1))
+  done
+  _base="${_cur##*/}"
+  _dir="${_cur%/*}"
+  case "$_base" in ''|.|..) return 1 ;; esac
+  [ -n "$_dir" ] || _dir=/
+  if cd -P "$_root" 2>/dev/null; then
+    _root_real="${PWD%/}"
+    if cd -P "$_dir" 2>/dev/null; then _ERG_RESOLVED="${PWD%/}/$_base"; fi
+  fi
+  cd "$_back" 2>/dev/null || true
+  case "$_ERG_RESOLVED" in
+    '') ;;
+    "$_root_real"/?*)
+      # Each part below the root is tested whole, in any letter case: `cd -P` keeps
+      # the spelling the link gave, and a case-insensitive file system opens `.git`
+      # for `.GIT`.
+      case "/${_ERG_RESOLVED#"$_root_real"/}/" in
+        */.[Gg][Ii][Tt]/*) ;;
+        *) return 0 ;;
+      esac
+      ;;
+  esac
+  _ERG_RESOLVED=''
+  return 1
+}
+
+# D-GITIGNORE-LINK-INSIDE (above): checked before the fast path, so a link that leads
+# elsewhere is neither read nor written. A regular .gitignore costs one builtin test.
+if [ -L "$_ERG_GITIGNORE" ]; then
+  if _erg_resolve_inside "$1" "$_ERG_GITIGNORE"; then
+    _ERG_GITIGNORE="$_ERG_RESOLVED"
+  else
+    if declare -F log >/dev/null 2>&1; then
+      log "Skipped: $_ERG_GITIGNORE is a symbolic link that leads outside the project, into a .git, or nowhere; nothing was written through it"
+    fi
+    return 0
+  fi
+fi
+
 # Whole-line, whitespace-tolerant matchers. `*` and `.` are escaped so the ERE
 # matches the literal gitignore patterns.
 _ERG_RE_OPTOUT='^[[:space:]]*/\.devflow/[[:space:]]*$'
@@ -208,18 +294,30 @@ else
     # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
     # comment first, then fall through to the shared append below. Portable (grep
     # filter + mv; no sed -i, which differs on BSD/GNU).
-    # The pipeline's own status is deliberately ignored: grep -v exits 1 when it
+    # The filter's own status is deliberately ignored: grep -v exits 1 when it
     # emits no lines, which is the correct outcome for a .gitignore whose only
-    # content was the legacy entry. The redirect creates _ERG_TMP either way.
+    # content was the legacy entry, so `true` ends the group and the subshell fails
+    # only when the copy cannot be created. The copy is created only where nothing
+    # stands at its name: builtin tests come first, so an entry already there, a
+    # link to a FIFO or a device included, is never opened (noclobber alone would
+    # open one, as no regular file stands there), and noclobber then makes the
+    # create itself exclusive (D-HOOKS-NO-SYMLINK, git-marker). Such an entry is
+    # removed instead; the upgrade then waits for a later run, and the skip is
+    # logged once.
     _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
-    grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null \
-      | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
-      > "$_ERG_TMP" 2>/dev/null
-    if [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
+    if [ ! -e "$_ERG_TMP" ] && [ ! -L "$_ERG_TMP" ] && (set -o noclobber; {
+          grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" \
+            | grep -vF '# Devflow runtime data (local by default; remove to share via git)'
+          true
+        } > "$_ERG_TMP") 2>/dev/null \
+      && [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
       :
     else
-      rm -f "$_ERG_TMP" 2>/dev/null
+      rm -f "$_ERG_TMP" 2>/dev/null || true
       _ERG_MODE=fail
+      if declare -F log >/dev/null 2>&1; then
+        log "Legacy .devflow/ entry not upgraded: its copy could not be written ($_ERG_TMP); a later run retries"
+      fi
     fi
   fi
 fi
@@ -231,7 +329,8 @@ fi
 # unchanged, and when the run ends on a last line with no newline, one is added
 # before <text>. Each read ends in a trailing `x`, so command substitution cannot
 # strip the file's own trailing newlines. The file is rewritten in place with one
-# `>`, as the TS twin's writeFile does, so a symlinked .gitignore keeps its link.
+# `>`, as the TS twin's writeFile does; a .gitignore linked to a file inside the
+# project is rewritten at that file, so the link stays (D-GITIGNORE-LINK-INSIDE).
 # Returns non-zero, having written nothing, when the anchor line cannot be found.
 _erg_insert_in_block() {
   local _anchor="$1" _run="$2" _text="$3" _hit="" _n="" _next="" _line="" _i=0 _head="" _tail=""
@@ -284,9 +383,22 @@ case "$_ERG_MODE" in
     ;;
 esac
 
-# On success, stamp the current-format v6 marker and drop legacy markers.
+# On success, stamp the current-format v6 marker and drop legacy markers. The marker
+# is created only where nothing stands, never `touch`ed: `touch` follows a symbolic
+# link committed at its path (D-HOOKS-NO-SYMLINK, git-marker), and so does
+# noclobber's create when the link leads to a FIFO, where it would wait at every
+# session start and prompt, or to a device. So builtin tests come first: a link
+# there is left as it was and the skip logged once, a marker already there is all
+# the fast path needs, and noclobber makes the create itself exclusive. A `.devflow`
+# that is itself a link is refused by both callers before they reach this file.
 [ "$_ERG_OK" = 1 ] && {
-  touch "$_ERG_MARKER"
+  if [ -L "$_ERG_MARKER" ]; then
+    if declare -F log >/dev/null 2>&1; then
+      log "Marker not stamped: $_ERG_MARKER is a symbolic link"
+    fi
+  elif [ ! -e "$_ERG_MARKER" ]; then
+    (set -o noclobber; : > "$_ERG_MARKER") 2>/dev/null || true
+  fi
   _erg_drop_legacy_markers
 }
 return 0

package/src/assets/scripts/hooks/git-marker

@@ -62,3 +62,74 @@ df_is_project_root() {
   [ -n "$_root_real" ] || return 1
   [ "$_root_real" != "$_home_real" ]
 }
+
+# df_no_symlink_below <root> <path>... — returns 0 when no <path>, and no folder
+# between <root> and it, is a symbolic link. Returns 1 when one is, and for any
+# call it cannot vouch for: no <path>, an empty <root>, a <path> not below <root>,
+# or a <path> with an empty, `.` or `..` part or more than 64 parts below <root>.
+# A predicate: call it in an `if` or an `||` list, never as a plain statement
+# under `set -e`.
+#
+# D-HOOKS-NO-SYMLINK: a hook writes under a project's `.devflow/`, and reads a file
+# there into the session context, a backup, a prompt or an agent directive, only
+# where nothing on the way down from the root is a symbolic link. A repository can
+# commit a link anywhere in its own `.devflow/`, and the hooks' shell commands follow
+# one. `>>` and `touch` write through a linked file and `mkdir -p` creates folders
+# inside a linked folder, so a linked queue or folder would put captured
+# conversation text into whatever file the link names. `head`, `sed`, `read` and
+# `jq` read through one, so a linked working memory, backup or decisions file would
+# put whatever file the link names into the session, the memory refresh's prompt or
+# the backup the next session restores, with no one choosing to read it. Each hook
+# checks every path this rule covers: a refused write is skipped and a refused
+# read is treated as an absent file (df_file_below below), each logged once. A
+# rename's target is one of those paths: `mv` moves a file into the folder a link
+# at its target names, so a link there, to anything, refuses the rename.
+#
+# Only the part of each path below <root> is checked, never the root or a folder
+# above it: the root is where the session runs or where git keeps the ledger,
+# chosen by the user and not by what the repository holds, and a folder above it
+# may legitimately be a link (on macOS /tmp and /var lead into /private). The check
+# runs just before the write or the read, so a process that swaps a link in between
+# is not stopped; such a process already runs as the user.
+#
+# Zero forks: builtin `[ -L ]` tests and parameter expansion only.
+df_no_symlink_below() {
+  local _root="$1" _path="" _rest="" _seg="" _at="" _n=0
+  [ -n "$_root" ] || return 1
+  shift
+  [ "$#" -gt 0 ] || return 1
+  for _path in "$@"; do
+    case "$_path" in
+      "$_root"/?*) _rest="${_path#"$_root"/}" ;;
+      *) return 1 ;;
+    esac
+    _at="$_root"
+    _n=0
+    while [ -n "$_rest" ]; do
+      [ "$_n" -lt 64 ] || return 1
+      _seg="${_rest%%/*}"
+      if [ "$_seg" = "$_rest" ]; then _rest=""; else _rest="${_rest#*/}"; fi
+      case "$_seg" in ''|.|..) return 1 ;; esac
+      _at="$_at/$_seg"
+      if [ -L "$_at" ]; then return 1; fi
+      _n=$((_n + 1))
+    done
+  done
+  return 0
+}
+
+# df_file_below <root> <path> — returns 0 when <path> is a regular file that
+# df_no_symlink_below admits, so a hook may read it. Returns 1 when no regular file
+# stands there, and when a symbolic link sits on its path: the file is then treated
+# as absent (D-HOOKS-NO-SYMLINK, above), and that refusal is logged once through the
+# caller's log(), where it defines one. `[ -f ]` follows a link, so a dangling link
+# or a link to a folder reads as absent with nothing logged: nothing would be read
+# through it. A predicate, like df_no_symlink_below; it forks nothing unless it logs.
+df_file_below() {
+  [ -f "$2" ] || return 1
+  if df_no_symlink_below "$1" "$2"; then return 0; fi
+  if declare -F log >/dev/null 2>&1; then
+    log "Skipped: a symbolic link sits on the path to $2; treated as absent"
+  fi
+  return 1
+}

package/src/assets/scripts/hooks/is-hex-sha

@@ -3,7 +3,7 @@
 # Usage: source "$SCRIPT_DIR/is-hex-sha"  then  is_hex_sha <value> [min_len] [max_len]
 # Returns 0 (true) if value consists entirely of lowercase hex chars and has
 # length within [min_len, max_len].  Defaults: min_len=7, max_len=40.
-# Pure shell — no forks (PF-008-safe).
+# Pure shell — no forks.
 
 is_hex_sha() {
   local _v="$1" _min="${2:-7}" _max="${3:-40}" _len