@svayam-opensource/prj 0.5.1

package/scripts/install-deps.sh

@@ -0,0 +1,292 @@
+#!/usr/bin/env bash
+# install-deps.sh
+# Hard-gate tool check for the Agentic Development Framework.
+#
+# Verifies the local toolchain is ready:
+#   Required: git, gh (authenticated), python3, pyyaml
+#   Optional: yq  (python3+pyyaml covers all functionality)
+#
+# Auto-installs missing required tools (or hard-stops in --check mode).
+#
+# GitHub identity & access verification (which org / which user) lives
+# in setup.sh, where the configured github_org is known. Run setup.sh
+# next to configure your org; it will verify access against the values
+# you provide.
+#
+# Supported platforms:
+#   - macOS       (via Homebrew)
+#   - Ubuntu/Debian Linux  (via apt)
+#   - RHEL/Fedora/CentOS   (via dnf/yum)
+#   - Arch Linux   (via pacman)
+#   - Alpine Linux (via apk)
+#   - Windows/WSL  (treated as the underlying Linux distro)
+#   - Git Bash/Cygwin on Windows (limited — WSL strongly recommended)
+#
+# Usage:
+#   bash scripts/install-deps.sh           # install missing required deps, then verify
+#   bash scripts/install-deps.sh --check   # check only, do not install
+
+set -euo pipefail
+
+CHECK_ONLY=false
+[[ "${1:-}" == "--check" ]] && CHECK_ONLY=true
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONFIG="$REPO_ROOT/org-config.yaml"
+
+# ── Output helpers ────────────────────────────────────────────────────────────
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; DIM='\033[2m'; NC='\033[0m'
+ok()        { echo -e "${GREEN}  ✓${NC} $*"; }
+fail()      { echo -e "${RED}  ✗${NC} $*"; }
+warn()      { echo -e "${YELLOW}  !${NC} $*"; }
+info()      { echo -e "${CYAN}  →${NC} $*"; }
+note()      { echo -e "${DIM}    $*${NC}"; }
+hard_stop() { echo ""; echo -e "${RED}HARD STOP:${NC} $*" >&2; echo ""; exit 1; }
+
+# ── OS / distro detection ─────────────────────────────────────────────────────
+
+detect_os() {
+  OS=""
+  PKG_MGR=""
+  case "$(uname -s)" in
+    Darwin) OS="macos" ;;
+    Linux)
+      OS="linux"
+      if grep -qi microsoft /proc/version 2>/dev/null; then
+        warn "Running inside WSL — treating as Linux."
+      fi
+      if   command -v apt-get &>/dev/null; then PKG_MGR="apt"
+      elif command -v dnf     &>/dev/null; then PKG_MGR="dnf"
+      elif command -v yum     &>/dev/null; then PKG_MGR="yum"
+      elif command -v pacman  &>/dev/null; then PKG_MGR="pacman"
+      elif command -v apk     &>/dev/null; then PKG_MGR="apk"
+      else PKG_MGR="unknown"
+      fi
+      ;;
+    MINGW*|CYGWIN*|MSYS*)
+      OS="windows-bash"
+      warn "Git Bash / Cygwin detected — WSL is strongly recommended."
+      PKG_MGR="winget"
+      ;;
+    *) OS="unknown" ;;
+  esac
+}
+
+# ── Installers ────────────────────────────────────────────────────────────────
+
+install_brew() {
+  if ! command -v brew &>/dev/null; then
+    info "Installing Homebrew..."
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  fi
+}
+
+install_git() {
+  case "$OS-$PKG_MGR" in
+    macos-*)        install_brew; brew install git ;;
+    linux-apt)      sudo apt-get install -y git ;;
+    linux-dnf)      sudo dnf install -y git ;;
+    linux-yum)      sudo yum install -y git ;;
+    linux-pacman)   sudo pacman -S --noconfirm git ;;
+    linux-apk)      sudo apk add --no-cache git ;;
+    windows-bash-*) warn "Install Git for Windows from https://git-scm.com/download/win" ;;
+    *)              warn "Could not auto-install git — install manually." ;;
+  esac
+}
+
+install_gh_binary() {
+  info "Downloading gh binary from GitHub releases..."
+  local GH_VERSION="2.49.2"
+  local ARCH=$(uname -m)
+  local ARCH_TAG
+  case "$ARCH" in
+    x86_64)        ARCH_TAG="amd64" ;;
+    aarch64|arm64) ARCH_TAG="arm64" ;;
+    *)             ARCH_TAG="amd64" ;;
+  esac
+  local BINARY_URL="https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_${ARCH_TAG}.tar.gz"
+  local INSTALL_DIR="${HOME}/.local/bin"
+  mkdir -p "$INSTALL_DIR"
+  local TMP=$(mktemp -d)
+  curl -fsSL "$BINARY_URL" | tar -xz -C "$TMP"
+  cp "$TMP/gh_${GH_VERSION}_linux_${ARCH_TAG}/bin/gh" "$INSTALL_DIR/gh"
+  chmod +x "$INSTALL_DIR/gh"
+  rm -rf "$TMP"
+  if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
+    warn "Add $INSTALL_DIR to your PATH:"
+    warn "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc  # or ~/.zshrc"
+    export PATH="$INSTALL_DIR:$PATH"
+  fi
+}
+
+install_gh() {
+  case "$OS-$PKG_MGR" in
+    macos-*)
+      install_brew; brew install gh
+      ;;
+    linux-apt)
+      curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+      echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+      sudo apt-get update -q
+      sudo apt-get install -y gh
+      ;;
+    linux-dnf)
+      sudo dnf install -y 'dnf-command(config-manager)'
+      sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
+      sudo dnf install -y gh
+      ;;
+    linux-yum)
+      sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
+      sudo yum install -y gh
+      ;;
+    linux-pacman)   sudo pacman -S --noconfirm github-cli ;;
+    linux-apk)      install_gh_binary ;;
+    linux-unknown)  install_gh_binary ;;
+    windows-bash-*) warn "Install GitHub CLI from https://cli.github.com or: winget install GitHub.cli" ;;
+    *)              warn "Could not auto-install gh — see https://cli.github.com" ;;
+  esac
+}
+
+install_python3() {
+  case "$OS-$PKG_MGR" in
+    macos-*)      install_brew; brew install python3 ;;
+    linux-apt)    sudo apt-get install -y python3 python3-pip ;;
+    linux-dnf)    sudo dnf install -y python3 python3-pip ;;
+    linux-yum)    sudo yum install -y python3 python3-pip ;;
+    linux-pacman) sudo pacman -S --noconfirm python python-pip ;;
+    linux-apk)    sudo apk add --no-cache python3 py3-pip ;;
+    *)            warn "Install python3 manually from https://python.org" ;;
+  esac
+}
+
+install_pyyaml() {
+  if python3 -c "import yaml" &>/dev/null; then
+    return 0
+  fi
+  info "Installing PyYAML..."
+  case "$OS-$PKG_MGR" in
+    macos-*)
+      pip3 install --break-system-packages pyyaml \
+        || { warn "pip3 failed — trying brew pyyaml..."; brew install pyyaml 2>/dev/null || true; }
+      ;;
+    linux-apt)
+      sudo apt-get install -y python3-yaml 2>/dev/null \
+        || pip3 install --user pyyaml
+      ;;
+    linux-dnf)
+      sudo dnf install -y python3-pyyaml 2>/dev/null \
+        || pip3 install --user pyyaml
+      ;;
+    linux-yum)
+      sudo yum install -y python3-pyyaml 2>/dev/null \
+        || pip3 install --user pyyaml
+      ;;
+    linux-pacman) sudo pacman -S --noconfirm python-yaml ;;
+    linux-apk)    sudo apk add --no-cache py3-yaml ;;
+    *)
+      pip3 install --user pyyaml \
+        || warn "Could not install PyYAML — install manually: pip3 install --user pyyaml"
+      ;;
+  esac
+}
+
+# ── Phase 1: Required + optional tool checks ─────────────────────────────────
+
+echo ""
+echo "Agentic Development Framework — Environment Check"
+echo "=================================================="
+detect_os
+echo "  OS:          $OS"
+echo "  Pkg manager: ${PKG_MGR:-n/a}"
+echo ""
+echo "Tools:"
+
+REQUIRED=(git gh python3)
+MISSING_REQUIRED=()
+
+for dep in "${REQUIRED[@]}"; do
+  if command -v "$dep" &>/dev/null; then
+    ok "$dep  ($(command -v "$dep"))"
+  else
+    fail "$dep  — required, not found"
+    MISSING_REQUIRED+=("$dep")
+  fi
+done
+
+# pyyaml as a python3 module
+if command -v python3 &>/dev/null && python3 -c "import yaml" &>/dev/null; then
+  ok "pyyaml  (python3 module)"
+elif command -v python3 &>/dev/null; then
+  fail "pyyaml  — required python3 module, not found"
+  MISSING_REQUIRED+=("pyyaml")
+fi
+
+# yq is optional — python3 + pyyaml covers all functionality
+if command -v yq &>/dev/null; then
+  ok "yq      ($(command -v yq))  ${DIM}[optional]${NC}"
+else
+  info "yq      not installed  ${DIM}[optional — python3 + pyyaml covers all functionality]${NC}"
+fi
+
+echo ""
+
+# Auto-install required if not in --check mode
+if [[ ${#MISSING_REQUIRED[@]} -gt 0 ]]; then
+  if $CHECK_ONLY; then
+    hard_stop "Missing required: ${MISSING_REQUIRED[*]}. Run without --check to attempt auto-install."
+  fi
+  echo "Installing missing required tools: ${MISSING_REQUIRED[*]}"
+  echo ""
+  for dep in "${MISSING_REQUIRED[@]}"; do
+    info "Installing $dep..."
+    case "$dep" in
+      git)     install_git ;;
+      gh)      install_gh ;;
+      python3) install_python3 ;;
+      pyyaml)  install_pyyaml ;;
+    esac
+  done
+
+  # Re-verify
+  echo ""
+  echo "Re-verifying..."
+  ALL_OK=true
+  for dep in "${MISSING_REQUIRED[@]}"; do
+    if [[ "$dep" == "pyyaml" ]]; then
+      if python3 -c "import yaml" &>/dev/null; then
+        ok "pyyaml  (python3 module)"
+      else
+        fail "pyyaml  — still not installed"
+        ALL_OK=false
+      fi
+    else
+      if command -v "$dep" &>/dev/null; then
+        ok "$dep  ($(command -v "$dep"))"
+      else
+        fail "$dep  — still not installed"
+        ALL_OK=false
+      fi
+    fi
+  done
+  $ALL_OK || hard_stop "Required tools could not be installed. See warnings above; install manually then re-run."
+  echo ""
+fi
+
+# ── gh authentication ─────────────────────────────────────────────────────────
+
+echo "GitHub CLI auth:"
+if ! gh auth status &>/dev/null; then
+  fail "gh CLI is not authenticated"
+  hard_stop "Run: gh auth login"
+fi
+ok "gh authenticated"
+
+echo ""
+ok "All required tools installed and gh authenticated."
+echo ""
+echo "Next: bash setup.sh   (configure for your org and verify GitHub access)"
+echo ""

package/scripts/join.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Script: join
+# Purpose: Set up an authorized member's OWN per-project workspace on an existing
+#          active/paused project. No new NNN, no change to assigned_to or
+#          seeded_by — this is how a teammate gets a local working copy under
+#          the per-task / team-ownership model (POL-047).
+# Usage:   bash join.sh <project_id>
+# Compliance: authorization via is_authorized (assigned_to individual or team).
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+PROJECT_ID="${1:-}"
+[[ -n "$PROJECT_ID" ]] || hard_stop "Usage: $0 <project_id>"
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+WORK_ROOT="$(project_work_root "$PROJECT_ID")"
+ORG_GOV_DIR="$(org_gov_clone "$PROJECT_ID")"
+GOV_REMOTE_URL=$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || echo "")
+[[ -n "$GOV_REMOTE_URL" ]] || hard_stop "No 'origin' remote on the governance repo."
+
+echo "=== join: $PROJECT_ID"
+echo "    Branch: $BRANCH"
+echo ""
+
+mkdir -p "$WORK_ROOT"
+
+# ── 1. Per-project ORG GOVERNANCE worktree (carries the project branch + manifest) ──
+# ADR-0001 Phase 2: a worktree of one shared base clone, not a full per-project
+# clone. ensure_repo_worktree is backward compatible with an existing clone.
+info "Setting up ORG GOVERNANCE worktree → $ORG_GOV_DIR ('$BRANCH')..."
+ensure_repo_worktree "$GOV_REMOTE_URL" "$ORG_GOV_DIR" "$BRANCH" \
+  || hard_stop "Could not set up the governance worktree for '$BRANCH' — has $PROJECT_ID been seeded and pushed?"
+
+# Carry the joining developer's git identity into the per-project workspace so
+# commits + C01 authorization here reflect them, not the ambient global.
+set_clone_identity "$ORG_GOV_DIR"
+
+PROJECT_YAML="$ORG_GOV_DIR/projects/$PROJECT_ID/project.yaml"
+[[ -f "$PROJECT_YAML" ]] || hard_stop "project.yaml not found on branch '$BRANCH'."
+
+# ── 2. Authorization + status (per-task / team model) ──
+ASSIGNED_TO=$(yaml_get "$PROJECT_YAML" "assigned_to")        # display/audit cache
+GH_PROJECT=$(yaml_get "$PROJECT_YAML" "github_project")
+is_authorized_for_project "$GH_PROJECT" "$ASSIGNED_TO" \
+  || hard_stop "You are not authorized to join '$PROJECT_ID' — you need write access to its GitHub Project ($GH_PROJECT)."
+require_any_project_status "$PROJECT_YAML" "active" "paused"
+
+# ── 3. Code-repo worktrees on the project branch ──
+while IFS= read -r repo_url; do
+  [[ -z "$repo_url" || "$repo_url" == "~" ]] && continue
+  REPO_NAME=$(get_repo_name "$repo_url")
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$REPO_NAME")"
+  info "Setting up $REPO_NAME worktree → $REPO_DIR ('$BRANCH')..."
+  if ensure_repo_worktree "$repo_url" "$REPO_DIR" "$BRANCH"; then
+    set_clone_identity "$REPO_DIR"
+  else
+    warn "Could not set up worktree for $REPO_NAME — skipping."
+  fi
+done < <(get_project_repos "$PROJECT_YAML")
+
+echo ""
+echo "=== Joined $PROJECT_ID  (branch '$BRANCH')."
+echo "    No NNN allocated; assigned_to / seeded_by unchanged."
+echo ""
+echo "── How to start work ──────────────────────────────────────────────────"
+echo ""
+echo "  1. Enter your per-project workspace:"
+echo "       cd $ORG_GOV_DIR"
+echo "     (governance clone on '$BRANCH'; code repos are under $WORK_ROOT/)"
+echo ""
+echo "  2. Read the start-up guidance already on this branch:"
+echo "       projects/$PROJECT_ID/agent.md     — project entrypoint"
+echo "       CLAUDE.md / AGENTS.md             — universal session-start protocol"
+echo ""
+echo "  3. Load the knowledge layers fresh (highest priority first):"
+echo "       knowledge/                                      (org-wide, read-only)"
+echo "       projects/$PROJECT_ID/knowledge/                 (this project)"
+echo "       <repo>/knowledge/                               (each code repo)"
+echo "       $AGENT_WORK_ROOT/preferences/<your-gh-login>.md (your preferences)"
+echo ""
+echo "  4. Confirm authorization: you have write access to the project's GitHub"
+echo "     Project board (project status must be active or paused)."
+echo ""
+echo "  5. Claim work — open a task sub-branch for a board issue:"
+echo "       ./prj task <issue-url>      (or run ./prj start)"
+echo ""
+echo "  Coordinate via the shared '$BRANCH' branch; close is run once by any member."