autonomous-sdlc-harness 0.4.2 → 0.6.0

package/templates/scripts/create-worktree.sh

@@ -9,6 +9,21 @@
 #                bootstrap it, then PUSH the branch so the remote has it from
 #                the first moment. This is what the watcher calls when a prompt
 #                arrives for a branch that does not exist yet.
+#   --no-bootstrap  Skip the bootstrap. Alone, a variant of default mode: cut
+#                and push the new branch the same way. With `--existing`, check
+#                out the existing branch and never push. Its callers are
+#                `remote-run.sh start` (a new branch) and `remote-run.sh review`
+#                (an existing one), each of which only places and commits one
+#                file: such a copy runs nothing, so a dependency install would
+#                cost minutes and could fail the placement for a reason
+#                unrelated to the task. It installs no worktree-scoped pre-push
+#                backstop — the push a caller makes is of a branch it has
+#                already judged not protected, and every later commit goes
+#                through `commit-on-branch.sh` and `push-branch.sh`, which refuse
+#                a protected branch themselves. An existing branch's copy that a
+#                person or a local run works in still wants the bootstrap, so
+#                `--existing` alone keeps it; `--no-bootstrap` is for a copy that
+#                only places and commits one file.
 #   --existing   Check out an EXISTING branch — local, or DWIM-created from
 #                `origin/<branch>` when only the remote ref exists — bootstrap
 #                it, and NEVER push. This is what the watcher calls to recreate
@@ -33,7 +48,8 @@
 # probe stops doing its job. This one is a short, strictly ordered sequence in
 # which every step is a precondition of the next: bootstrapping a half-created
 # worktree, or pushing a branch whose dependency install failed, is worse than
-# stopping. So a failing step aborts the script with that step's own status —
+# stopping (a `--no-bootstrap` cut simply has no bootstrap step in its
+# sequence). So a failing step aborts the script with that step's own status —
 # and the worktree it had already created is LEFT IN PLACE for inspection,
 # because removing a working copy is a decision this script does not get to
 # make silently.
@@ -62,20 +78,25 @@
 # is neither a descriptor duplication (`2>&1`, `>&2`, `2>&-`) nor a redirection
 # to the literal `/dev/null`.
 #
-# Usage: create-worktree.sh [--existing] <branch-name> [worktree-dir]
+# Usage: create-worktree.sh [--existing] [--no-bootstrap] <branch-name> [worktree-dir]
 #   --existing     check out an existing branch instead of creating a new one
+#   --no-bootstrap skip the bootstrap: alone, create and push a new branch; with
+#                  --existing, check out the existing branch and never push
 #   <branch-name>  the branch to run on
 #   [worktree-dir] optional override; relative paths resolve against $PWD
 #
 # Exit map a caller can switch on:
 #
-#   0  the worktree is ready (and, in default mode, the branch was pushed)
+#   0  the worktree is ready (and, in default mode or under `--no-bootstrap`
+#      without `--existing`, the branch was pushed)
 #   1  usage error / the library or the configuration could not be read
 #   2  refusal — nothing was created: `--existing` and the branch is nowhere;
 #      the branch is already checked out in another working copy (which is
 #      named); or default mode with no `origin` remote, or no
 #      `origin/<default branch>` to branch from
-#   4  the working copy was created but could not be bootstrapped — it has no
+#   4  the working copy was created but could not be bootstrapped (never under
+#      `--no-bootstrap`, with or without `--existing`, which resolves no
+#      bootstrap) — it has no
 #      dependency install and no pre-push backstop, is LEFT IN PLACE for
 #      inspection, and in default mode the branch was NOT pushed, because this
 #      exit precedes the push step. In default mode the local
@@ -104,6 +125,13 @@
 #   new branch     bash "$d/scripts/create-worktree.sh" feat/x
 #                  -> "$w/demo-feat-x" on feat/x, bootstrapped, and `git -C "$b"
 #                     branch` now lists feat/x
+#   no-bootstrap   bash "$d/scripts/create-worktree.sh" --no-bootstrap feat/q
+#                  -> "$w/demo-feat-q" on feat/q, no deps.marker, and
+#                     `git -C "$b" branch` lists feat/q
+#   existing, no bootstrap   git -C "$d" worktree remove "$w/demo-feat-q"
+#                  git -C "$d" branch -D feat/q
+#                  bash "$d/scripts/create-worktree.sh" --existing --no-bootstrap feat/q
+#                  -> "$w/demo-feat-q" on feat/q, no deps.marker, "$b" UNCHANGED
 #   already there  bash "$d/scripts/create-worktree.sh" --existing feat/x
 #                  -> exit 2 naming "$w/demo-feat-x"; nothing created
 #   recreate       git -C "$d" worktree remove "$w/demo-feat-x"
@@ -150,15 +178,18 @@ fi
 . "$hr_lib"
 
 usage() {
-  echo "  usage: create-worktree.sh [--existing] <branch-name> [worktree-dir]" >&2
+  echo "  usage: create-worktree.sh [--existing] [--no-bootstrap] <branch-name> [worktree-dir]" >&2
 }
 
 existing=0
-if [ "${1:-}" = "--existing" ]; then
-  existing=1
-  shift
-fi
-
+no_bootstrap=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --existing) existing=1; shift ;;
+    --no-bootstrap) no_bootstrap=1; shift ;;
+    *) break ;;
+  esac
+done
 if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
   echo "create-worktree.sh: no branch name given" >&2
   usage
@@ -325,6 +356,17 @@ fi
 # checkout's own copy is not run instead — setup-worktree.sh anchors on its own
 # location and takes no arguments, so running it would bootstrap THIS checkout
 # rather than the new one.
+if [ "$no_bootstrap" -eq 1 ]; then
+  if [ "$existing" -eq 1 ]; then
+    echo "create-worktree.sh: worktree ready at $worktree_dir (not bootstrapped)"
+    echo "create-worktree.sh: branch $branch (existing branch; not pushed)"
+  else
+    git -C "$worktree_dir" push -u origin "$branch"
+    echo "create-worktree.sh: worktree ready at $worktree_dir (not bootstrapped)"
+    echo "create-worktree.sh: branch $branch (pushed to origin)"
+  fi
+  exit 0
+fi
 scripts_rel="$(hr_scripts_dir "$worktree_dir")" || scripts_rel=""
 if [ -z "$scripts_rel" ]; then
   scripts_rel="$script_dir_rel"

package/templates/scripts/docs-search-server.sh

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
 # docs-search-server.sh — start the docs-retrieval MCP server for the checkout
-# this script sits in, by `exec`ing the machine-shared retrieval runtime's
-# `docs serve`.
+# this script sits in, on the backend `docs.retrievalBackend` selects.
 #
 # WHO RUNS IT. The agent runner, from the `harness-docs` entry `init` writes into
 # `.mcp.json` when `docs.retrieval` is on — never a dispatched agent's Bash call,
@@ -9,29 +8,52 @@
 # `agentInvocable: false` and the generated permission profile carries no entry
 # for it.
 #
-# STDOUT BELONGS TO THE MCP TRANSPORT. Nothing here may print to stdout before
-# the `exec`: a stray byte there is a malformed frame for the client. Every
-# diagnostic goes to stderr.
+# STDOUT BELONGS TO THE MCP TRANSPORT. Nothing here may print to stdout: a stray
+# byte there is a malformed frame for the client. Every diagnostic goes to
+# stderr.
 #
-# THE RUNTIME IS THE ONLY THING THIS RUNS, with no fallback to any other
-# installation: a committed `.mcp.json` cannot know where an adopter's own CLI
-# lives. `doctor`'s `retrieval-dependencies` check and `init`'s install both key
-# on the same entry file this script tests. `PATH` is settled through the
-# library's fallback list before the `exec`, because the starter is the agent
-# runner rather than a login shell.
+# WHICH SERVER. Two backends, chosen by `docs.retrievalBackend` read at run
+# time, with no fallback between them and no fallback to any other
+# installation. The key is read ONLY WHEN `phases.docs` and `docs.retrieval` are
+# both `true` (`hr_docs_retrieval_applies`, the shell mirror of
+# `retrievalApplies`): `init` merges `.mcp.json` and removes nothing, so this
+# entry outlives turning retrieval off, and with the gate closed the TypeScript
+# runtime is `exec`ed whatever the key holds. `typescript`, or the key absent,
+# `exec`s the machine-shared runtime's `docs serve`; `doctor`'s
+# `retrieval-dependencies` check and `init`'s install both key on the same entry
+# file this script tests. `python` starts the Python package's stdio server.
+# This script checks no database and runs no `self-check`: grading the backend's
+# prerequisites is `doctor`'s. `PATH` is settled through the library's fallback
+# list first, because the starter is the agent runner rather than a login shell.
+#
+# WHY THE PYTHON BRANCH IS NOT `exec`ED. Its failure must surface as exit 3,
+# which an `exec` could not report. It runs as a child with stdin passed
+# explicitly, and a `TERM` or an `INT` the launcher receives is passed on to it
+# as `TERM`, the signal the server stops on: bash starts a background child with
+# `SIGINT` ignored when job control is off, and Python installs no handler over
+# an ignored `SIGINT`, so an `INT` passed on as itself would never arrive.
 #
 # MIRRORS — a change to any owner below is an edit here too:
 #   `retrieval/runtime` and `node_modules/autonomous-sdlc-harness/dist/cli.js`
 #     mirror `RETRIEVAL_CACHE_DIRNAME`, `RETRIEVAL_RUNTIME_DIRNAME` and
 #     `RUNTIME_CLI_RELATIVE` in `cli/src/retrieval/runtime.ts`;
-#   `hr_cache_dir` mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`.
+#   `hr_cache_dir` mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`;
+#   `harness-docs-retrieval`, `serve-mcp`, `HARNESS_DOCS_RETRIEVAL_DATABASE_URL`,
+#     the default connection string and exit 3 mirror `PYTHON_RETRIEVAL_COMMAND`,
+#     `PYTHON_SERVE_SUB_COMMAND`, `PYTHON_DATABASE_URL_VARIABLE`,
+#     `PYTHON_DEFAULT_DATABASE_URL` and `PYTHON_BACKEND_UNAVAILABLE_EXIT` in
+#     `cli/src/retrieval/pythonBackend.ts`.
 #
 # Exit contract:
-#   1    no runtime entry at the resolved path, no cache directory to resolve
-#        it under, or no repository at this script's location; stderr names
-#        which
-#   N    otherwise `docs serve`'s own status, through `exec`; a failure to
-#        source the library exits non-zero before that, on stderr only
+#   0    the Python backend exited 0
+#   1    no repository at this script's location; `docs.retrievalBackend`
+#        outside the enum; or, on the TypeScript backend, no runtime entry at
+#        the resolved path or no cache directory to resolve it under; stderr
+#        names which
+#   3    the Python backend is selected but cannot serve: its command does not
+#        resolve on `PATH`, or it exited non-zero; stderr names which
+#   N    on the TypeScript backend, `docs serve`'s own status, through `exec`; a
+#        failure to source the library exits non-zero before that, on stderr only
 
 set -euo pipefail
 
@@ -50,6 +72,55 @@ if ! root="$(hr_repo_root "$script_dir")"; then
   exit 1
 fi
 
+backend=typescript
+config_status=0
+hr_config_load "$root" || config_status=$?
+if [ "$config_status" -eq 2 ]; then
+  echo "docs-search-server: $root/harness.config.json could not be read, so the default backend (typescript) was taken" >&2
+elif [ "$config_status" -eq 0 ] && hr_docs_retrieval_applies "$root"; then
+  backend_status=0
+  backend="$(hr_docs_retrieval_backend "$root")" || backend_status=$?
+  if [ "$backend_status" -ne 0 ]; then
+    echo "docs-search-server: docs.retrievalBackend in $root/harness.config.json is neither \`typescript\` nor \`python\`; set one of them, then run \`npx autonomous-sdlc-harness doctor\`" >&2
+    exit 1
+  fi
+fi
+
+if [ "$backend" = python ]; then
+  if ! command -v harness-docs-retrieval >/dev/null 2>&1; then
+    echo "docs-search-server: the Python backend is selected but \`harness-docs-retrieval\` does not resolve on PATH (interpreter or package missing); see docs/retrieval.md and run \`npx autonomous-sdlc-harness doctor\`" >&2
+    exit 3
+  fi
+  if [ -z "${HARNESS_DOCS_RETRIEVAL_DATABASE_URL-}" ]; then
+    HARNESS_DOCS_RETRIEVAL_DATABASE_URL='postgresql://harness:harness@127.0.0.1:5432/docs_retrieval'
+  fi
+  export HARNESS_DOCS_RETRIEVAL_DATABASE_URL
+
+  # A background job's stdin is /dev/null unless it is passed explicitly.
+  harness-docs-retrieval serve-mcp --repo "$root" <&0 &
+  child=$!
+  trapped=0
+  trap 'trapped=1; kill -TERM "$child" 2>/dev/null || true' TERM
+  trap 'trapped=1; kill -TERM "$child" 2>/dev/null || true' INT
+
+  # A trapped signal interrupts `wait` before the child's status is collected, so wait again. 127
+  # means the first `wait` had already collected it.
+  child_status=0
+  wait "$child" || child_status=$?
+  while [ "$trapped" -eq 1 ]; do
+    trapped=0
+    again=0
+    wait "$child" 2>/dev/null || again=$?
+    [ "$again" -eq 127 ] || child_status=$again
+  done
+
+  if [ "$child_status" -eq 0 ]; then
+    exit 0
+  fi
+  echo "docs-search-server: the Python backend exited with status $child_status before or while serving; the line above (\`harness-docs-retrieval: …\`) names why; run \`npx autonomous-sdlc-harness doctor\`" >&2
+  exit 3
+fi
+
 if ! cache_dir="$(hr_cache_dir)"; then
   echo "docs-search-server: neither XDG_CACHE_HOME nor HOME is set, so the retrieval runtime cannot be located" >&2
   exit 1