@snappedly-tools/shipyard 0.5.0 → 0.6.0

package/dist/templates/sequential-reviewer/setup.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n ${GH_REPO:-} ]]; then
+  [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
+  git remote set-url origin "https://github.com/$GH_REPO.git"
+fi
+
+# Install for this sandbox's checkout. Host node_modules can contain binaries
+# for a different OS and cannot cover dependencies added by the agent later.
+if [[ -f package.json ]]; then
+  manager=$(node -e 'try { const p = require("./package.json").packageManager; process.stdout.write(p ? p.split("@")[0] : "") } catch {}')
+  if [[ -z "$manager" ]]; then
+    if [[ -f bun.lock || -f bun.lockb ]]; then manager=bun
+    elif [[ -f pnpm-lock.yaml ]]; then manager=pnpm
+    elif [[ -f yarn.lock ]]; then manager=yarn
+    else manager=npm; fi
+  fi
+  case "$manager" in
+    npm) npm install ;;
+    pnpm) corepack pnpm install ;;
+    yarn) corepack yarn install ;;
+    bun)
+      if ! command -v bun >/dev/null; then curl -fsSL https://bun.com/install | bash; export PATH="$HOME/.bun/bin:$PATH"; fi
+      bun install ;;
+    *) echo "Unsupported package manager: $manager" >&2; exit 1 ;;
+  esac
+fi
+
+source_dir=$(mktemp -d)
+trap 'rm -rf "$source_dir"' EXIT
+if ! git clone --depth 1 https://github.com/snappedly/skills.git "$source_dir/repo"; then
+  echo "Could not install Snappedly skills; agent work has not started." >&2
+  exit 1
+fi
+
+mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills"
+while IFS= read -r -d '' skill_file; do
+  skill_dir=${skill_file%/SKILL.md}
+  skill_name=${skill_dir##*/}
+  rm -rf "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+  cp -R "$skill_dir" "$HOME/.agents/skills/$skill_name"
+  ln -sfn "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+done < <(find "$source_dir/repo/skills" -name SKILL.md -print0)
+
+for skill in triage implement implement-spec code-cleanup code-review tdd; do
+  if [[ ! -s "$HOME/.agents/skills/$skill/SKILL.md" || -z $(find "$source_dir/repo/skills" -path "*/$skill/SKILL.md" -print -quit) ]]; then
+    echo "Snappedly skill installation incomplete: $skill" >&2
+    exit 1
+  fi
+done

package/dist/templates/sequential-reviewer/template.json

@@ -1,4 +1,4 @@
 {
   "name": "sequential-reviewer",
-  "description": "Implements issues one by one, with a code review step after each"
+  "description": "Implements issues one by one, reviews each branch, then opens review PRs"
 }

package/dist/templates/sequential-reviewer/triage-prompt.md

@@ -0,0 +1,5 @@
+Triage GitHub issue #{{TASK_ID}} before Shipyard implementation.
+
+Follow `/triage` and the repository's `docs/agents/triage.md` label mapping. Read the full issue and comments, verify its claim against the codebase, then apply the appropriate category and state label and post the brief or triage notes required by the skill. The maintainer has authorized Shipyard to apply an evidence-based recommendation during this unattended intake. If a decision requires maintainer judgment, use `needs-triage` and record the question. Do not implement the issue or start a PR in this phase.
+
+Report the applied state and evidence. Shipyard will independently re-read GitHub labels and implement only an open issue carrying both `shipyard` and the sole triage state `ready-for-agent`.

package/dist/templates/sequential-reviewer/verify-triage.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+repo=${2:?GitHub repository required}
+[[ "$issue" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+
+gh issue view "$issue" --repo "$repo" --json state,labels |
+  node -e '
+    const issue = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
+    const labels = new Set(issue.labels.map((label) => label.name));
+    const states = ["needs-triage", "needs-info", "ready-for-agent", "ready-for-human", "wontfix"];
+    if (issue.state !== "OPEN" || !labels.has("shipyard") ||
+        states.filter((state) => labels.has(state)).join() !== "ready-for-agent") {
+      console.error("Issue cannot be implemented: requires an open issue with shipyard and only ready-for-agent as its triage state");
+      process.exit(1);
+    }
+  '

package/dist/templates/shared/block-scope.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=${1:?scope root required}
+failed=${2:?failed issue required}
+repo=${3:?GitHub repository required}
+scope=${4:?scope issue numbers required}
+branch=${5:-shipyard/issue-$root}
+[[ "$root" =~ ^[0-9]+$ && "$failed" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$root" || "$scope" == "$root,"* ) && ",$scope," == *",$failed,"* ]] || {
+  echo "Invalid blocked issue scope" >&2; exit 1;
+}
+[[ "$branch" == "shipyard/issue-$root" || "$branch" == "shipyard/spec-$root" ]] || { echo "Invalid scope branch" >&2; exit 1; }
+reason=$(cat)
+[[ -n "$reason" ]] || { echo "Missing failure reason" >&2; exit 1; }
+reason_hash=$(printf '%s' "$reason" | git hash-object --stdin)
+pending_dir=$(git rev-parse --git-path shipyard-pending)
+mkdir -p "$pending_dir"
+umask 077
+pending_file="$pending_dir/$root-$failed.pending"
+trap 'rm -f "${pending_tmp:-}"' EXIT
+confirmed=""
+if [[ -f "$pending_file" ]]; then
+  IFS=$'\t' read -r old_root old_failed old_repo old_scope old_branch old_confirmed < "$pending_file"
+  if [[ "$old_root" == "$root" && "$old_failed" == "$failed" && "$old_repo" == "$repo" && "$old_scope" == "$scope" && "$old_branch" == "$branch" ]]; then
+    confirmed=${old_confirmed:-}
+  fi
+fi
+write_pending() {
+  pending_tmp=$(mktemp "$pending_file.XXXXXX")
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n%s' "$root" "$failed" "$repo" "$scope" "$branch" "$confirmed" "$reason" > "$pending_tmp"
+  mv "$pending_tmp" "$pending_file"
+}
+confirm_blocked() {
+  if [[ ",$confirmed," != *",$1,"* ]]; then
+    confirmed=${confirmed:+$confirmed,}$1
+    write_pending
+  fi
+}
+write_pending
+
+remove_issue_status() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1" >&2
+    return 75
+  fi
+}
+remove_pr_status() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1" >&2
+    return 75
+  fi
+}
+comment_once() {
+  local comments
+  if comments=$(gh issue view "$1" --repo "$repo" --json comments --jq '.comments[].body'); then
+    if grep -Fq "$3" <<< "$comments"; then return 0; fi
+  fi
+  gh issue comment "$1" --repo "$repo" --body "$2"
+}
+
+gh label create shipyard:blocked --repo "$repo" --color B60205 --description 'Shipyard work needs intervention' --force
+status_synced=true
+IFS=',' read -ra affected_ids <<< "$scope"
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    gh issue edit "$affected_id" --repo "$repo" --add-label shipyard:blocked
+    confirm_blocked "$affected_id"
+  done
+  if ! gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update spec #$root status" >&2
+    status_synced=false
+  fi
+else
+  gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked
+  confirm_blocked "$root"
+fi
+
+status=0
+marker="shipyard:blocked:$root:$failed:$reason_hash"
+comment_once "$failed" "Shipyard could not complete this issue. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:failed -->" "$marker:failed" || status=75
+if [[ "$root" != "$failed" ]]; then
+  comment_once "$root" "Shipyard paused this spec because linked ticket #$failed failed. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to each unfinished ticket.
+
+<!-- $marker:parent -->" "$marker:parent" || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" && "$failed" == "$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    comment_once "$affected_id" "Shipyard could not complete this ticket during the spec attempt. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:ticket:$affected_id -->" "$marker:ticket:$affected_id" || status=75
+  done
+fi
+
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  if ! remove_issue_status "$root" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+  if ! remove_issue_status "$root" shipyard:complete; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+else
+  remove_issue_status "$root" shipyard:outstanding-tasks || status=75
+  remove_issue_status "$root" shipyard:complete || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    remove_issue_status "$affected_id" shipyard:pending || status=75
+  done
+else
+  remove_issue_status "$root" shipyard:pending || status=75
+fi
+
+if ! pr_number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty'); then
+  echo "Warning: could not inspect PR status" >&2
+  status_synced=false
+  pr_number=""
+fi
+if [[ -n "$pr_number" ]]; then
+  if ! gh pr edit "$pr_number" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:complete; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+fi
+if [[ "$status" -eq 0 && "$status_synced" == true ]]; then
+  IFS=',' read -ra scope_ids <<< "$scope"
+  for scope_id in "${scope_ids[@]}"; do
+    labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name')
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard
+    fi
+  done
+  rm -f "$pending_file"
+fi
+exit "$status"

package/dist/templates/shared/handoff.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+branch=${2:?branch required}
+base=${3:?target branch required}
+repo=${4:?GitHub repository required}
+scope=${5:-$issue}
+outstanding=${6:--}
+previously_completed=${7:--}
+[[ "$issue" =~ ^[0-9]+$ && ( "$branch" == "shipyard/issue-$issue" || "$branch" == "shipyard/spec-$issue" ) ]] || {
+  echo "Invalid issue or branch for PR handoff" >&2; exit 1;
+}
+[[ "$base" =~ ^[A-Za-z0-9._/-]+$ ]] || {
+  echo "Invalid target branch for PR handoff" >&2; exit 1;
+}
+
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$issue" || "$scope" == "$issue,"* ) ]] || { echo "Invalid PR scope" >&2; exit 1; }
+[[ "$outstanding" == - || "$outstanding" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid outstanding tickets" >&2; exit 1; }
+[[ "$previously_completed" == - || "$previously_completed" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid completed tickets" >&2; exit 1; }
+evidence=$(cat)
+[[ -n "$evidence" ]] || { echo "Missing verification evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Checks:' <<< "$evidence" || { echo "Missing check evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Review:' <<< "$evidence" || { echo "Missing review evidence" >&2; exit 1; }
+[[ -z $(git status --porcelain) ]] || {
+  echo "Uncommitted changes prevent PR handoff" >&2; exit 1;
+}
+base_ref=$(git rev-parse --verify "refs/remotes/origin/$base^{commit}") || {
+  echo "Target branch is unavailable in the sandbox" >&2; exit 1;
+}
+branch_base=$base_ref
+if ! git merge-base --is-ancestor "$base_ref" HEAD; then
+  branch_base=$(git merge-base "$base_ref" HEAD) || {
+    echo "PR branch has no common base with the target branch" >&2; exit 1;
+  }
+fi
+[[ -n $(git log "$branch_base"..HEAD --format=%H) ]] || {
+  echo "No verified commit to publish" >&2; exit 1;
+}
+
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+remove_issue_label() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+remove_pr_label() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+title=$(gh issue view "$issue" --repo "$repo" --json title --jq .title)
+body=$(mktemp)
+trap 'rm -f "$body"' EXIT
+links=""
+implemented=""
+IFS=',' read -ra scope_ids <<< "$scope"
+for scope_id in "${scope_ids[@]}"; do links+="#$scope_id "; done
+for ((i=1; i<${#scope_ids[@]}; i++)); do implemented+="#${scope_ids[i]} "; done
+if [[ "$previously_completed" != - ]]; then
+  IFS=',' read -ra completed_ids <<< "$previously_completed"
+  for completed_id in "${completed_ids[@]}"; do links+="#$completed_id "; implemented+="#$completed_id "; done
+fi
+if [[ "$outstanding" != - ]]; then
+  IFS=',' read -ra outstanding_ids <<< "$outstanding"
+  for outstanding_id in "${outstanding_ids[@]}"; do links+="#$outstanding_id "; done
+fi
+printf 'Source issues: %s\nImplemented tickets: %s\n\n## Verification and review\n\n%s\n\nHuman review and merge required.\n\n<!-- shipyard:verified-handoff -->\n' "$links" "$implemented" "$evidence" > "$body"
+
+# Keep Git credentials inside the disposable sandbox, not in the host worktree.
+git remote set-url origin "https://github.com/$repo.git"
+git -c credential.helper='!gh auth git-credential' push -u origin "HEAD:refs/heads/$branch"
+number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+if [[ -z "$number" ]]; then
+  gh pr create --repo "$repo" --head "$branch" --base "$base" --title "$title" --body-file "$body" --draft
+  number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+fi
+[[ -n "$number" ]] || { echo "PR publication did not return an open PR" >&2; exit 1; }
+gh pr edit "$number" --repo "$repo" --body-file "$body"
+draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft)
+url=$(gh pr view "$number" --repo "$repo" --json url --jq .url)
+[[ -n "$url" ]] || { echo "PR publication did not return a URL" >&2; exit 1; }
+if [[ "$draft" == true ]]; then gh pr ready "$number" --repo "$repo" || true; fi
+if ! current_draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft) ||
+   ! current_state=$(gh pr view "$number" --repo "$repo" --json state --jq .state); then
+  echo "Could not confirm PR readiness; retry publication when GitHub is available" >&2
+  exit 75
+fi
+if [[ "$current_draft" != false || "$current_state" != OPEN ]]; then
+  echo "PR did not become ready for human review" >&2
+  exit 1
+fi
+for ((i=1; i<${#scope_ids[@]}; i++)); do
+  if ! gh issue edit "${scope_ids[i]}" --repo "$repo" --add-label shipyard:complete; then
+    echo "Could not mark ticket #${scope_ids[i]} complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  remove_issue_label "${scope_ids[i]}" shipyard:blocked
+  remove_issue_label "${scope_ids[i]}" shipyard:pending
+done
+status_label=shipyard:complete
+status_color=0E8A16
+status_description='Shipyard work ready for human review'
+if [[ "$outstanding" != - ]]; then
+  status_label=shipyard:outstanding-tasks
+  status_color=FBCA04
+  status_description='Spec has uncompleted tickets'
+  for outstanding_id in "${outstanding_ids[@]}"; do
+    labels=$(gh issue view "$outstanding_id" --repo "$repo" --json labels --jq '.labels[].name') || exit 75
+    if grep -Fxq shipyard:blocked <<< "$labels" && ! grep -Fxq shipyard:complete <<< "$labels"; then
+      status_label=shipyard:blocked
+      status_color=B60205
+      status_description='Shipyard work needs intervention'
+      break
+    fi
+  done
+fi
+status_synced=true
+if ! gh label create "$status_label" --repo "$repo" --color "$status_color" --description "$status_description" --force; then
+  echo "Warning: could not create $status_label" >&2
+  status_synced=false
+fi
+if ! gh issue edit "$issue" --repo "$repo" --add-label "$status_label"; then
+  if [[ "$branch" == "shipyard/issue-$issue" ]]; then
+    echo "Could not mark ticket #$issue complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  echo "Warning: could not update spec #$issue status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_issue_label "$issue" "$stale_label"; then
+      if [[ "$branch" == "shipyard/issue-$issue" ]]; then exit 75; fi
+      echo "Warning: could not clear $stale_label from spec #$issue" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$branch" == "shipyard/issue-$issue" ]]; then remove_issue_label "$issue" shipyard:pending; fi
+if ! gh pr edit "$number" --repo "$repo" --add-label "$status_label"; then
+  echo "Warning: could not update PR #$number status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_pr_label "$number" "$stale_label"; then
+      echo "Warning: could not clear $stale_label from PR #$number" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$status_synced" == true ]]; then
+  for scope_id in "${scope_ids[@]}"; do
+    if ! labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name'); then
+      echo "Warning: could not inspect activation on issue #$scope_id; the next invocation will retry cleanup" >&2
+      continue
+    fi
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard ||
+        echo "Warning: could not remove activation from issue #$scope_id; the next invocation will retry cleanup" >&2
+    fi
+  done
+else
+  echo "Warning: status labels need reconciliation; retaining ticket activation" >&2
+fi
+printf '%s\n' "$url"