orient-entrypoints

#!/bin/bash
# Detects project entrypoint systems (Makefile etc.) and surfaces their
# targets so an agent can act without an exploratory roundtrip.
#
# Usage: orient-entrypoints [PATH]
#   PATH defaults to the git toplevel of cwd, or cwd itself if not in a repo.
#
# Silent (no output, exit 0) when no entrypoint system is detected.
# Each detected system emits an h4 heading named after the command an agent
# would use to interact further (e.g. `make`); intended to sit under an h3.
#
# Hard rule: parse only, never invoke.
# Repos can be untrusted content (e.g. freshly cloned from elsewhere);
# the existence of files in the repo must not translate into code execution.
# Any future addition here must follow the same rule.
#
# This script focuses on detection.  Per-system parsing lives in sibling
# scripts (e.g. `skim-makefile`) so they can be used independently.

set -euo pipefail

HERE=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")

# Resolve the project root via the single source of truth.
# `find-project-root` is strict (git toplevel or exit 1); we add a cwd
# fallback here since this script still wants to detect entrypoints in
# unmanaged directories.
if [ $# -ge 1 ]; then
	root=$(cd "$1" && pwd)
elif root=$("$HERE/find-project-root" 2>/dev/null); then
	:
else
	root="$PWD"
fi

# --- Makefile -------------------------------------------------------------
#
# Search order matches GNU make's own (GNUmakefile, makefile, Makefile).
# Only the first hit matters: that's the one make itself would use.
makefile=""
for candidate in GNUmakefile makefile Makefile; do
	if [ -f "$root/$candidate" ]; then
		makefile="$root/$candidate"
		break
	fi
done

if [ -n "$makefile" ]; then
	rel="${makefile#$root/}"
	echo "#### \`make\`"
	echo
	echo "From \`${rel}\`:"
	echo
	"$HERE/skim-makefile" "$makefile"
fi

# --- Future entrypoint systems --------------------------------------------
#
# Add detection blocks here for justfile, Taskfile.yml, scripts/, etc.
# Same rules apply: parse only, never invoke.  Each block stays silent if
# its system isn't present, and emits an h4 heading named after the command
# an agent would use (`just`, `task`, ...) when it is.  Per-system parsing
# should live in its own `skim-*` sibling script.