Skip to content

PAIR-code/deliberate-lab / .agents/skills/workspace-overview

workspace-overview

Verified

Inspect the local Deliberate Lab workspace environment, Node.js version, bare repository worktrees, remotes, git status, and toolchain readiness.

FileKindSize
SKILL.mdskill md3.9 KB
scripts/workspace-overview.shexecutablescript12.4 KB

scripts/workspace-overview.sh

View on GitHub
#!/usr/bin/env bash
#
# workspace-overview.sh β€” Deliberate Lab Workspace & Environment Diagnostic
#
# Inspects:
# 1. Node.js version against .nvmrc with automated discovery & PATH remediation
# 2. Git bare repository topology, active worktree, and sibling worktrees
# 3. Toolchain status (remotes, gh CLI auth)
# 4. Monorepo dependencies and build artifacts (utils/dist, functions/lib)
#

set -uo pipefail

if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
  echo "Usage: $(basename "$0")"
  echo "Inspects Deliberate Lab workspace environment, Node runtime, git topology, toolchain, and build artifacts."
  exit 0
fi

generate_overview() {
  echo "======================================================"
  echo "         Deliberate Lab β€” Workspace Overview         "
  echo "======================================================"
  echo ""

# -----------------------------------------------------------------------------
# Helper: Run command with bounded timeout (ADR 0003 Standard 6)
# -----------------------------------------------------------------------------
run_with_timeout() {
  local duration="$1"
  shift
  if command -v timeout >/dev/null 2>&1; then
    timeout "$duration" "$@"
  else
    "$@"
  fi
}

# -----------------------------------------------------------------------------
# 1. Locate .nvmrc and Determine Target Node Version
# -----------------------------------------------------------------------------
find_nvmrc() {
  local dir="${1:-$PWD}"
  while [ "$dir" != "/" ]; do
    if [ -f "$dir/.nvmrc" ]; then
      echo "$dir/.nvmrc"
      return 0
    fi
    dir="$(dirname "$dir")"
  done
  # Also check sibling directories if in bare container
  for sibling in "$PWD"/*/.nvmrc; do
    if [ -f "$sibling" ]; then
      echo "$sibling"
      return 0
    fi
  done
  return 1
}

NVMRC_FILE="$(find_nvmrc || true)"
REQUIRED_NODE="22"
if [ -n "$NVMRC_FILE" ] && [ -f "$NVMRC_FILE" ]; then
  REQUIRED_NODE="$(tr -d '[:space:]v' < "$NVMRC_FILE")"
fi
REQUIRED_MAJOR="$(echo "$REQUIRED_NODE" | cut -d. -f1)"

echo "[1/4] Node.js & Runtime Environment"
echo "      Source of truth (.nvmrc): Node v${REQUIRED_MAJOR}"

# Check active node in $PATH
echo "      $ command -v node"
ACTIVE_NODE_PATH="$(command -v node 2>/dev/null || true)"
ACTIVE_NODE_VERSION=""
ACTIVE_NODE_MAJOR=""
NODE_MATCHED=false

if [ -n "$ACTIVE_NODE_PATH" ]; then
  ACTIVE_NODE_VERSION="$(node -v 2>/dev/null | tr -d 'v' || true)"
  ACTIVE_NODE_MAJOR="$(echo "$ACTIVE_NODE_VERSION" | cut -d. -f1)"
  if [ "$ACTIVE_NODE_MAJOR" = "$REQUIRED_MAJOR" ]; then
    NODE_MATCHED=true
    echo "      [OK] Active Node: v${ACTIVE_NODE_VERSION} ($ACTIVE_NODE_PATH)"
  else
    echo "      [WARN] Active Node is v${ACTIVE_NODE_VERSION} ($ACTIVE_NODE_PATH), but v${REQUIRED_MAJOR} is required."
  fi
else
  echo "      [WARN] Node.js is not found in the current \$PATH."
fi

# Tiered Discovery & Remediation if not matched
if [ "$NODE_MATCHED" = false ]; then
  CANDIDATE_NODE=""

  # Search NVM directories
  NVM_PATHS=(
    "${NVM_DIR:-$HOME/.nvm}/versions/node"
    "$HOME/.nvm/versions/node"
  )
  for nvm_dir in "${NVM_PATHS[@]}"; do
    if [ -d "$nvm_dir" ]; then
      # Find all matching v<REQUIRED_MAJOR>.* directories and pick highest version
      latest_match="$(find "$nvm_dir" -maxdepth 1 -type d -name "v${REQUIRED_MAJOR}.*" 2>/dev/null | sort -V | tail -n1)"
      if [ -n "$latest_match" ] && [ -x "$latest_match/bin/node" ]; then
        CANDIDATE_NODE="$latest_match/bin/node"
        break
      fi
    fi
  done

  # Search FNM / ASDF / Volta if NVM didn't yield a match
  if [ -z "$CANDIDATE_NODE" ]; then
    for fnm_dir in "$HOME/.local/share/fnm/current/bin" "$HOME/.fnm/current/bin"; do
      if [ -x "$fnm_dir/node" ]; then
        ver="$("$fnm_dir/node" -v 2>/dev/null | tr -d 'v')"
        if [ "$(echo "$ver" | cut -d. -f1)" = "$REQUIRED_MAJOR" ]; then
          CANDIDATE_NODE="$fnm_dir/node"
          break
        fi
      fi
    done
  fi

  if [ -n "$CANDIDATE_NODE" ]; then
    CANDIDATE_DIR="$(dirname "$CANDIDATE_NODE")"
    CANDIDATE_VER="$("$CANDIDATE_NODE" -v 2>/dev/null || echo "v${REQUIRED_MAJOR}")"
    echo "      [FOUND] Compatible binary discovered: $CANDIDATE_VER ($CANDIDATE_NODE)"
    echo ""
    echo "      πŸ‘‰ Action Required for Agent / Shell:"
    echo "         To use Node ${REQUIRED_MAJOR} in this session (and persistent terminal sessions), run:"
    echo "         export PATH=\"${CANDIDATE_DIR}:\$PATH\""
    echo ""
  else
    # Check if NVM is installed
    if [ -f "${NVM_DIR:-$HOME/.nvm}/nvm.sh" ]; then
      echo "      [ERROR] Node v${REQUIRED_MAJOR} is not installed in NVM."
      echo "      πŸ‘‰ Run: nvm install ${REQUIRED_MAJOR} && nvm use ${REQUIRED_MAJOR}"
    else
      echo "      [ERROR] Node.js v${REQUIRED_MAJOR} is not installed on this system."
      echo "      πŸ‘‰ Please install Node.js v${REQUIRED_MAJOR} directly or via NVM (https://github.com/nvm-sh/nvm)."
    fi
  fi
fi
echo ""

# -----------------------------------------------------------------------------
# 2. Git & Worktree Topology
# -----------------------------------------------------------------------------
echo "[2/4] Git & Worktree Topology"

if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "      [ERROR] Not inside a git repository."
else
  # Check if in a bare container or a worktree checkout
  IS_INSIDE_WORK_TREE="$(git rev-parse --is-inside-work-tree 2>/dev/null || echo "false")"
  IS_BARE_ROOT=false
  if [ "$IS_INSIDE_WORK_TREE" != "true" ] && ([ -d ".bare" ] || [ -f ".git" ]); then
    IS_BARE_ROOT=true
  fi

  CURRENT_DIR="$(basename "$PWD")"
  echo "      Current directory: $CURRENT_DIR"

  if [ "$IS_BARE_ROOT" = true ]; then
    echo "      Current context:   Bare repository parent container (holding .bare/ and sibling worktrees)"
    echo "      Working tree:      (n/a - switch to a sibling worktree directory to edit code)"
  else
    echo "      $ git branch --show-current && git rev-parse --short HEAD"
    CURRENT_BRANCH="$(git branch --show-current 2>/dev/null || true)"
    [ -z "$CURRENT_BRANCH" ] && CURRENT_BRANCH="(detached HEAD)"
    CURRENT_COMMIT="$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")"
    echo "      Current branch:    $CURRENT_BRANCH ($CURRENT_COMMIT)"

    # Uncommitted changes
    echo "      $ git status --porcelain"
    DIRTY_COUNT="$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
    if [ "$DIRTY_COUNT" -eq 0 ]; then
      echo "      Working tree:      clean"
    else
      echo "      Working tree:      $DIRTY_COUNT uncommitted file(s)"
    fi

    # Upstream tracking
    echo "      $ git rev-parse --abbrev-ref @{u}"
    TRACKING_REF="$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || true)"
    if [ -n "$TRACKING_REF" ]; then
      COUNTS="$(git rev-list --left-right --count "HEAD...$TRACKING_REF" 2>/dev/null || echo "0 0")"
      AHEAD="$(echo "$COUNTS" | awk '{print $1}')"
      BEHIND="$(echo "$COUNTS" | awk '{print $2}')"
      echo "      Tracking ref:      $TRACKING_REF (ahead: $AHEAD, behind: $BEHIND)"
    else
      echo "      Tracking ref:      (none configured)"
    fi
  fi

  echo ""
  echo "      $ git worktree list"
  echo "      Worktrees:"
  git worktree list 2>/dev/null | while read -r line; do
    wt_path="$(echo "$line" | awk '{print $1}')"
    wt_commit="$(echo "$line" | awk '{print $2}')"
    wt_branch="$(echo "$line" | awk '{$1=""; $2=""; print $0}' | sed 's/^[ \t]*//')"

    rel_path="$(realpath --relative-to="$PWD" "$wt_path" 2>/dev/null || echo "$wt_path")"
    [[ "$rel_path" != /* && "$rel_path" != .* ]] && rel_path="./$rel_path"

    if [[ "$wt_branch" == *"(bare)"* ]] || [ "$wt_commit" = "(bare)" ]; then
      echo "          ${rel_path} (bare)"
    else
      dirty_count="$(git -C "$wt_path" status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
      status_str="[clean]"
      if [ -n "$dirty_count" ] && [ "$dirty_count" -gt 0 ]; then
        status_str="[dirty: ${dirty_count} file(s)]"
      fi

      if [ "$wt_path" = "$PWD" ]; then
        echo "       ==> ${rel_path} ($wt_commit) ${wt_branch} ${status_str} [current]"
      else
        echo "          ${rel_path} ($wt_commit) ${wt_branch} ${status_str}"
      fi
    fi
  done

  echo ""
  echo "      $ git branch -vv"
  git branch -vv 2>/dev/null | sed 's/^/          /'
fi
echo ""

# -----------------------------------------------------------------------------
# 3. Toolchain & Remotes
# -----------------------------------------------------------------------------
echo "[3/4] Toolchain & Remotes"

# Remotes check
if git rev-parse --git-dir >/dev/null 2>&1; then
  echo "      $ git remote -v"
  git remote -v 2>/dev/null | sed 's/^/      /'
fi

# GitHub CLI check (bounded by timeout per ADR 0003 Standard 6)
echo "      $ gh api user -q .login"
if command -v gh >/dev/null 2>&1; then
  GH_TIMEOUT="${GH_TIMEOUT:-5s}"
  GH_USER=""
  GH_EXIT_CODE=0
  GH_USER="$(run_with_timeout "$GH_TIMEOUT" gh api user -q .login 2>/dev/null)" || GH_EXIT_CODE=$?

  if [ "$GH_EXIT_CODE" -eq 0 ] && [ -n "$GH_USER" ]; then
    echo "      [OK] GitHub CLI (gh): Authenticated as @${GH_USER}"
    echo "      $ gh repo set-default --view"
    GH_DEF_REPO="$(run_with_timeout "$GH_TIMEOUT" gh repo set-default --view 2>/dev/null || true)"
    if [ -n "$GH_DEF_REPO" ]; then
      echo "      [OK] GitHub CLI (gh): Default repo is $GH_DEF_REPO"
    else
      echo "      [WARN] GitHub CLI (gh): Default repo not set across remotes"
      echo "      πŸ‘‰ Run: gh repo set-default PAIR-code/deliberate-lab"
    fi
  elif [ "$GH_EXIT_CODE" -eq 124 ]; then
    echo "      [WARN] GitHub CLI (gh): Timed out after ${GH_TIMEOUT} attempting to verify authentication."
    echo "             The system credential store (e.g. GNOME Keyring) may be locked or awaiting an interactive desktop prompt."
    echo "             πŸ‘‰ Action Required:"
    echo "                - Unlock your desktop session or check for an active keyring prompt."
    echo "                - Once unlocked, re-run $(basename "$0") to confirm authentication."
  else
    echo "      [WARN] GitHub CLI (gh): Installed but not authenticated (run 'gh auth login')"
  fi
else
  echo "      [WARN] GitHub CLI (gh): Not installed in \$PATH"
fi
echo ""

# -----------------------------------------------------------------------------
# 4. Monorepo Build Artifacts & Dependencies
# -----------------------------------------------------------------------------
echo "[4/4] Monorepo Artifacts & Dependencies"

# Find the worktree root containing package.json
WORKTREE_ROOT="$PWD"
if [ ! -f "$WORKTREE_ROOT/package.json" ]; then
  # If at bare root, check main or first worktree
  for cand in "$PWD"/main "$PWD"/*; do
    if [ -f "$cand/package.json" ]; then
      WORKTREE_ROOT="$cand"
      break
    fi
  done
fi

if [ -f "$WORKTREE_ROOT/package.json" ]; then
  # Check root node_modules
  if [ -d "$WORKTREE_ROOT/node_modules" ]; then
    echo "      [OK] node_modules: Installed in $(basename "$WORKTREE_ROOT")"
  else
    echo "      [WARN] node_modules: Missing in $(basename "$WORKTREE_ROOT"). Run: npm ci"
  fi

  # Check utils/dist (critical shared library)
  if [ -d "$WORKTREE_ROOT/utils/dist" ] && [ -n "$(ls -A "$WORKTREE_ROOT/utils/dist" 2>/dev/null)" ]; then
    echo "      [OK] utils/dist: Built (shared types & utilities available)"
  else
    echo "      [WARN] utils/dist: Missing or empty. Downstream packages (functions, frontend) will fail."
    echo "             πŸ‘‰ Run: npm run build -w utils"
  fi

  # Check functions/lib
  if [ -d "$WORKTREE_ROOT/functions/lib" ] && [ -n "$(ls -A "$WORKTREE_ROOT/functions/lib" 2>/dev/null)" ]; then
    echo "      [OK] functions/lib: Built"
  else
    echo "      [INFO] functions/lib: Not built (needed if running/testing Cloud Functions; run: npm run build -w functions)"
  fi
else
  echo "      [INFO] Bare repository root container. Switch to a worktree directory to inspect node_modules and build artifacts."
fi

  echo ""
  echo "======================================================"
  echo "Overview complete. Follow any [WARN] or [ERROR] instructions above."
  echo "======================================================"
}

OVERVIEW_OUTPUT="$(generate_overview)"
TOTAL_BYTES="${#OVERVIEW_OUTPUT}"
LIMIT="${OVERVIEW_BUFFER_LIMIT:-7000}" # Safe ceiling comfortably below 8,192 byte terminal buffer (ADR 0003 Standard 5)

if [ "$TOTAL_BYTES" -gt "$LIMIT" ]; then
  OUT_FILE="$(mktemp "${TMPDIR:-/tmp}/workspace-overview-XXXXXX.txt")"
  printf "%s\n" "$OVERVIEW_OUTPUT" > "$OUT_FILE"
  echo "Workspace overview (${TOTAL_BYTES} bytes) exceeds 8KB terminal limit; saved to: ${OUT_FILE} (view with view_file)"
else
  printf "%s\n" "$OVERVIEW_OUTPUT"
fi
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall