compass

compass: scaffold; add cwd-orient and git-orient

commit 2f34e088638948686c5f6e9e6f6471b7198e7ca6 · browse this tree
Ximianth, 2026-06-24 12:52:42 UTC

Two leaf scripts following the conventions outlined in the README:
- bash, markdown output scoped to h3-or-smaller context,
- silent when inapplicable (git-orient exits 0 with no output
  when cwd is not inside a git work tree),
- one concern per script.

git-orient reports root, branch, last commit, and a dirty/untracked
split derived from `git status --porcelain=v1`.

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e5a758
--- /dev/null
+++ b/README.md
@@ -0,0 +1,22 @@
+compass
+=======
+
+Small scripts for rapidly orienting in a project area.
+
+Each script is standalone:
+run individually for debugging,
+or compose into larger summaries (e.g. an agent's system prompt).
+
+## Conventions
+
+- One concern per script.
+- Output is markdown, scoped so the top-level output fits under an `h3` or smaller.
+  Composers wrap in larger sections as needed.
+- If a script has nothing applicable to say, it stays silent (exits 0 with no output).
+  Errors are different: surface those.
+- Bash for now.  Nushell on the table once we want to pass structured data between scripts.
+
+## Scripts
+
+- `cwd-orient`     -- describes the current working directory.
+- `git-orient`     -- describes the surrounding git repo, if any.
diff --git a/cwd-orient b/cwd-orient
new file mode 100755
index 0000000..5430d73
--- /dev/null
+++ b/cwd-orient
@@ -0,0 +1,18 @@
+#!/bin/bash
+# Briefly describes the current working directory.
+#
+# Emits a short markdown fragment intended to sit under an h3 or smaller.
+# Always has something to say (cwd always exists), so it never goes silent.
+
+set -euo pipefail
+
+cwd="${PWD}"
+
+# Count entries (depth 1), separating dirs and files, ignoring dotfiles.
+# We use `find` rather than globbing to avoid surprises with empty dirs.
+n_dirs=$(find "$cwd" -mindepth 1 -maxdepth 1 -type d -not -name '.*' | wc -l)
+n_files=$(find "$cwd" -mindepth 1 -maxdepth 1 -type f -not -name '.*' | wc -l)
+n_hidden=$(find "$cwd" -mindepth 1 -maxdepth 1 -name '.*' | wc -l)
+
+echo "- path: \`${cwd}\`"
+echo "- contents: ${n_dirs} dirs, ${n_files} files, ${n_hidden} hidden entries (depth 1)."
diff --git a/git-orient b/git-orient
new file mode 100755
index 0000000..0f046db
--- /dev/null
+++ b/git-orient
@@ -0,0 +1,42 @@
+#!/bin/bash
+# Briefly describes the git repo surrounding the current working directory.
+#
+# Silent (no output, exit 0) when cwd is not inside a git repo.
+# Emits a markdown fragment intended to sit under an h3 or smaller.
+#
+# Reports: repo root, current branch, last commit (short), and worktree dirtiness.
+
+set -euo pipefail
+
+# Bail silently if not inside a repo.
+# `rev-parse --is-inside-work-tree` prints to stderr on miss; squelch it.
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+	exit 0
+fi
+
+root=$(git rev-parse --show-toplevel)
+
+# Branch: prefer symbolic name; fall back to short sha on detached HEAD.
+branch=$(git symbolic-ref --quiet --short HEAD || git rev-parse --short HEAD)
+
+# Last commit: short sha, relative date, subject.
+# `--no-show-signature` keeps output stable across gpg config.
+last_commit=$(git log -1 --no-show-signature --format='%h %cr -- %s' 2>/dev/null || echo '(no commits yet)')
+
+# Worktree status: counts of tracked-modified vs untracked entries.
+# `--porcelain=v1` is stable; untracked lines start with `??`,
+# anything else with content is a tracked change.
+# `grep -c` exits 1 on no match, which would trip `set -e`; `|| true` neutralizes that.
+status=$(git status --porcelain=v1 2>/dev/null || true)
+if [ -z "$status" ]; then
+	n_dirty=0
+	n_untracked=0
+else
+	n_untracked=$(printf '%s\n' "$status" | grep -c '^??' || true)
+	n_dirty=$(printf '%s\n' "$status" | grep -cv '^??' || true)
+fi
+
+echo "- repo root: \`${root}\`"
+echo "- branch: \`${branch}\`"
+echo "- last commit: ${last_commit}"
+echo "- worktree: ${n_dirty} modified tracked, ${n_untracked} untracked."