spexcode 0.2.0 → 0.2.2

package/spec-cli/src/tree.ts

@@ -0,0 +1,118 @@
+// @@@ spex tree - the CLI's human-readable graph view: the same assembled board the dashboard's
+// tidy-tree renders, as an indented terminal tree. Pure presentation over buildBoard()'s nodes —
+// no read path of its own; status colours and badge semantics mirror the dashboard (drift /
+// stale-yatsu / open-issues counts). Governed by the spex-tree spec node.
+
+// the subset of a board node this view consumes (buildBoard attaches more; we read only these).
+export type TreeNode = {
+  id: string
+  parent: string | null
+  title: string
+  status: string
+  version?: number
+  drift?: number
+  ghost?: boolean
+  openIssues?: unknown[]
+  scenarios?: { name: string }[]
+  evals?: { scenario: string; fresh?: boolean }[]
+}
+
+export type TreeOpts = { node?: string; depth?: number; color?: boolean }
+
+// dashboard status palette mapped onto ANSI: merged=green, active=cyan (live/in-flight, distinct
+// from the warning yellow), drift=yellow (the dashboard's warning colour), pending=muted grey.
+const STATUS_ANSI: Record<string, string> = { merged: '32', active: '36', drift: '33', pending: '90' }
+
+// stale-yatsu count: declared scenarios whose LATEST reading exists but is no longer fresh.
+// board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
+// axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
+function staleYatsu(n: TreeNode): number {
+  if (!n.scenarios?.length || !n.evals?.length) return 0
+  const latest = new Map(n.evals.map((r) => [r.scenario, r]))
+  return n.scenarios.filter((s) => { const r = latest.get(s.name); return r && r.fresh === false }).length
+}
+
+function childrenIndex(nodes: TreeNode[]): Map<string | null, TreeNode[]> {
+  const byParent = new Map<string | null, TreeNode[]>()
+  for (const n of nodes) {
+    const list = byParent.get(n.parent) ?? []
+    list.push(n)
+    byParent.set(n.parent, list)
+  }
+  return byParent
+}
+
+// resolve the display roots: --node picks one subtree; default is the forest of parentless nodes
+// (a node whose parent id isn't on the board — a ghost mid-add, say — surfaces as a root rather
+// than vanishing). Unknown --node throws (fail loud, caller prints + exits 2), never an empty tree.
+function roots(nodes: TreeNode[], nodeId?: string): TreeNode[] {
+  if (nodeId) {
+    const hit = nodes.find((n) => n.id === nodeId)
+    if (!hit) throw new Error(`no spec node "${nodeId}" — spex tree lists every id; spex search <topic> finds one by intent`)
+    return [hit]
+  }
+  const ids = new Set(nodes.map((n) => n.id))
+  return nodes.filter((n) => n.parent === null || !ids.has(n.parent))
+}
+
+export function renderTree(nodes: TreeNode[], opts: TreeOpts = {}): string {
+  const color = opts.color ?? false
+  const c = (code: string, t: string) => (color ? `\x1b[${code}m${t}\x1b[0m` : t)
+  const byParent = childrenIndex(nodes)
+  const lines: string[] = []
+
+  const badges = (n: TreeNode): string => {
+    const parts: string[] = []
+    if (n.ghost) parts.push(c('90', 'ghost'))
+    if (n.drift) parts.push(c('33', `drift:${n.drift}`))
+    const stale = staleYatsu(n)
+    if (stale) parts.push(c('90', `stale:${stale}`))
+    if (n.openIssues?.length) parts.push(c('31', `issues:${n.openIssues.length}`))
+    return parts.length ? '  ' + parts.join(' ') : ''
+  }
+
+  const line = (n: TreeNode, prefix: string, branch: string) => {
+    const code = STATUS_ANSI[n.status] ?? '0'
+    // base state is invisible: merged (~80% of nodes) is the healthy ground state, already carried by
+    // the dot's colour — only deviations get a text label. Without colour the word IS the signal, so
+    // every status (merged included) prints in plain-text mode.
+    const label = color && n.status === 'merged' ? '' : ' ' + c(code, `[${n.status}]`)
+    const title = n.title && n.title !== n.id ? ' ' + c('90', '· ' + n.title) : ''
+    lines.push(`${prefix}${branch}${c(code, '●')} ${n.id}${label}${title}${badges(n)}`)
+  }
+
+  const walk = (n: TreeNode, prefix: string, branch: string, childPrefix: string, depth: number) => {
+    line(n, prefix, branch)
+    const kids = byParent.get(n.id) ?? []
+    if (!kids.length) return
+    if (opts.depth !== undefined && depth >= opts.depth) {
+      lines.push(`${childPrefix}${c('90', `└─ … ${kids.length} more (raise --depth)`)}`)
+      return
+    }
+    kids.forEach((k, i) => {
+      const last = i === kids.length - 1
+      walk(k, childPrefix, last ? '└─ ' : '├─ ', childPrefix + (last ? '   ' : '│  '), depth + 1)
+    })
+  }
+
+  for (const r of roots(nodes, opts.node)) walk(r, '', '', '', 0)
+  return lines.join('\n')
+}
+
+// the machine exit: the same filtered subtree as NESTED objects, badge counts precomputed — a
+// shaped view, not a replacement for `spex board` (which stays the full flat payload). Pruned
+// children degrade to their ids, so --depth still tells the machine what exists below the cut.
+export function treeJson(nodes: TreeNode[], opts: TreeOpts = {}): object[] {
+  const byParent = childrenIndex(nodes)
+  const shape = (n: TreeNode, depth: number): object => {
+    const kids = byParent.get(n.id) ?? []
+    const pruned = opts.depth !== undefined && depth >= opts.depth
+    return {
+      id: n.id, title: n.title, status: n.status, version: n.version ?? 0,
+      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.openIssues?.length ?? 0,
+      ...(n.ghost ? { ghost: true } : {}),
+      children: pruned ? kids.map((k) => k.id) : kids.map((k) => shape(k, depth + 1)),
+    }
+  }
+  return roots(nodes, opts.node).map((r) => shape(r, 0))
+}

package/spec-cli/templates/hooks/post-merge

@@ -21,7 +21,7 @@ if command -v spex >/dev/null 2>&1; then
   spex issues nudge "$node"
 elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
   "$repo_root/node_modules/.bin/spex" issues nudge "$node"
-elif [ -x "$main_root/spec-cli/node_modules/.bin/tsx" ] && [ -f "$main_root/spec-cli/src/cli.ts" ]; then
-  "$main_root/spec-cli/node_modules/.bin/tsx" "$main_root/spec-cli/src/cli.ts" issues nudge "$node"
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  "$main_root/spec-cli/bin/spex.mjs" issues nudge "$node"
 fi
 exit 0

package/spec-cli/templates/hooks/pre-commit

@@ -7,7 +7,7 @@
 # no node_modules of its own, so the dogfood tsx path reaches the main checkout's. First that exists wins:
 #   1. `spex` on PATH                  - installed globally / on the shell PATH.
 #   2. <repo>/node_modules/.bin/spex   - a project that did `npm i @spexcode/spec-cli` (the dep's bin).
-#   3. monorepo tsx + cli.ts by path   - dogfood: run the CLI from source.
+#   3. monorepo launcher by path       - dogfood: bin/spex.mjs (owns tsx resolution + the mid-merge guard).
 main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
 repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
 spex_kind=
@@ -15,21 +15,33 @@ if command -v spex >/dev/null 2>&1; then
   spex_kind=path
 elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
   spex_kind=local
-elif [ -x "$main_root/spec-cli/node_modules/.bin/tsx" ] && [ -f "$main_root/spec-cli/src/cli.ts" ]; then
-  spex_kind=tsx
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  spex_kind=pkg
 fi
 spex_cli() {
   case "$spex_kind" in
     path)  spex "$@" ;;
     local) "$repo_root/node_modules/.bin/spex" "$@" ;;
-    tsx)   "$main_root/spec-cli/node_modules/.bin/tsx" "$main_root/spec-cli/src/cli.ts" "$@" ;;
+    pkg)   "$main_root/spec-cli/bin/spex.mjs" "$@" ;;
     *)     return 127 ;;
   esac
 }
 
+# @@@ tree-unchanged stamp - a commit whose tree EQUALS HEAD's tree (`git write-tree` over the commit's own
+# index — the hook's GIT_INDEX_FILE, a temp HEAD-tree index for `commit --only --allow-empty`) adds NO
+# content: it cannot smuggle code past the main-guard below and cannot introduce spec↔code drift, so the
+# whole hook passes it. This is `spex ack`'s empty Spec-OK stamp — the reason ack works on a trunk merge
+# commit (amending it would re-author the merge after MERGE_HEAD is gone and read as direct authoring) and
+# with a DIRTY real index (the lint shim below reads the real index via git.ts's env-strip, which would
+# otherwise block the stamp on the very drift it acknowledges). Deliberately a one-line tree compare, not an
+# "is this an amend?" heuristic (undecidable at pre-commit time).
+if [ "$(git write-tree 2>/dev/null)" = "$(git rev-parse 'HEAD^{tree}' 2>/dev/null || echo none)" ]; then
+  exit 0
+fi
+
 # @@@ main-guard - the worktree model: never author directly on the trunk; the trunk only RECEIVES merges.
-# Reject a direct commit while HEAD is the trunk. Merges pass (MERGE_HEAD present).
-# Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
+# Reject a direct commit while HEAD is the trunk. Merges pass (MERGE_HEAD present), and a tree-unchanged
+# stamp already passed above. Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
 #
 # The trunk is resolved the SAME way the rest of SpexCode resolves it — `spex internal trunk` = layout.ts
 # mainBranch() (config override → the main checkout's current branch → 'main') — so the guard protects
@@ -48,7 +60,7 @@ trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
 if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
   echo "✗ SpexCode: direct commits on $trunk (the trunk) are blocked." >&2
   echo "  Work in a worktree (.worktrees/<node>, branch node/<id>) and merge back." >&2
-  echo "  Merges pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
+  echo "  Merges and tree-unchanged stamps (spex ack) pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
   exit 1
 fi
 
@@ -58,16 +70,23 @@ fi
 # hook's GIT_DIR, so lint validates THIS worktree's `.spec`).
 if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
   if [ -n "$spex_kind" ]; then
-    if ! spex_cli lint >&2; then
+    spex_cli lint >&2
+    lint_rc=$?
+    # exit 75 = the launcher's mid-merge guard (spex's own source holds conflict markers — transient).
+    # Degrade to advisory rather than walling every commit behind a merge someone else is resolving.
+    if [ "$lint_rc" -eq 75 ]; then
+      echo "• SpexCode: spec-lint skipped — spex is paused mid-merge (exit 75); CI still enforces." >&2
+    elif [ "$lint_rc" -ne 0 ]; then
       echo "✗ SpexCode: spec-lint failed — fix the spec↔code links or bypass with SPEXCODE_SKIP_LINT=1." >&2
       exit 1
-    fi
-    # @@@ yatsu backstop - reject a staged yatsu offender: a stray pixel blob copied into the tree (blobs
-    # belong in the shared git common dir, never committed) OR a malformed yatsu.md (a scenario schema
-    # violation). Logic lives in spec-yatsu; this is the lint-shim's twin. (this node's contract)
-    if ! spex_cli yatsu check-staged >&2; then
-      echo "✗ SpexCode: yatsu check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
-      exit 1
+    else
+      # @@@ yatsu backstop - reject a staged yatsu offender: a stray pixel blob copied into the tree (blobs
+      # belong in the shared git common dir, never committed) OR a malformed yatsu.md (a scenario schema
+      # violation). Logic lives in spec-yatsu; this is the lint-shim's twin. (this node's contract)
+      if ! spex_cli yatsu check-staged >&2; then
+        echo "✗ SpexCode: yatsu check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
+        exit 1
+      fi
     fi
   else
     # Advisory hook: no CLI found (project hasn't installed @spexcode/spec-cli; monorepo not `npm install`ed).

package/spec-cli/templates/hooks/prepare-commit-msg

@@ -33,5 +33,12 @@ if [ -z "$sid" ] && [ -n "${CODEX_THREAD_ID:-}" ]; then # codex: alias the threa
 fi
 
 [ -z "$sid" ] && exit 0
-printf '\nSession: %s\n' "$sid" >> "$msg_file"
+# Stamp via interpret-trailers (git's own sample-hook mechanism), NOT a raw printf append: appending after a
+# message that already carries a trailer block (e.g. `spex ack`'s Spec-OK) opens a new paragraph, and git then
+# parses ONLY the last paragraph as trailers — the earlier trailers silently become body prose. interpret-trailers
+# appends into the existing block, keeping ONE parseable block. It needs the file newline-terminated first:
+# on an unterminated message (git merge -m writes MERGE_MSG without one) it folds the trailer into the subject
+# paragraph, where git's trailer parser never looks — the reason merge commits' Session: never parsed.
+[ -n "$(tail -c1 "$msg_file")" ] && echo >> "$msg_file"
+git interpret-trailers --in-place --trailer "Session: $sid" "$msg_file"
 exit 0