biotonomy 0.1.0

package/commands/pr.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# biotonomy pr command
+
+bt_pr_usage() {
+  cat <<EOF
+Usage: bt pr <feature-name> [options]
+
+Ship a feature by running tests, committing changes, pushing, and creating a PR.
+
+Options:
+  --run         Actually execute push and gh pr create (default: dry-run)
+  --dry-run     Print push and gh commands without executing
+  --draft       Create the PR as a draft
+  --base <ref>  Base branch for the PR (default: remote's HEAD or main)
+  --remote <n>  Remote to push to (default: origin)
+  --no-commit   Skip committing changes (expects they are already committed)
+  -h, --help    Show this help
+EOF
+}
+
+bt_pr_file_size_bytes() {
+  local f="$1"
+  local sz=""
+  # macOS/BSD stat
+  if sz="$(stat -f%z "$f" 2>/dev/null)"; then
+    printf '%s\n' "$sz"
+    return 0
+  fi
+  # GNU stat
+  if sz="$(stat -c%s "$f" 2>/dev/null)"; then
+    printf '%s\n' "$sz"
+    return 0
+  fi
+  # Fallback
+  wc -c <"$f" | tr -d ' '
+}
+
+bt_pr_is_text_file() {
+  local f="$1"
+  # grep -I treats binary as non-matching and exits 1; empty files also exit 1, so handle empties elsewhere.
+  LC_ALL=C grep -Iq . "$f" 2>/dev/null
+}
+
+bt_pr_append_artifact_section() {
+  local out_file="$1"
+  local relpath="$2"
+  local abspath="$3"
+  local max_inline_bytes="$4"
+
+  {
+    # shellcheck disable=SC2016
+    printf '\n### `%s`\n' "$relpath"
+    # shellcheck disable=SC2016
+    printf 'Path: [`%s`](%s)\n\n' "$relpath" "$relpath"
+
+    if [[ ! -f "$abspath" ]]; then
+      printf "_missing_\\n"
+      return 0
+    fi
+
+    local size
+    size="$(bt_pr_file_size_bytes "$abspath")"
+
+    if [[ "$size" -ge "$max_inline_bytes" ]]; then
+      printf "_not inlined (size: %s bytes)_\\n" "$size"
+      return 0
+    fi
+
+    if [[ "$size" -gt 0 ]] && ! bt_pr_is_text_file "$abspath"; then
+      printf "_not inlined (binary or non-text; size: %s bytes)_\\n" "$size"
+      return 0
+    fi
+
+    local fence='```'
+    if grep -q '```' "$abspath" 2>/dev/null; then
+      fence='````'
+    fi
+
+    printf "%s\\n" "$fence"
+    cat "$abspath"
+    # Ensure trailing newline so the closing fence is on its own line.
+    printf "\\n%s\\n" "$fence"
+  } >>"$out_file"
+}
+
+bt_pr_write_artifacts_comment() {
+  local feature="$1"
+  local specs_dir="$2"
+  local out_file="$3"
+
+  local max_inline_bytes=$((20 * 1024))
+  local spec_rel="$specs_dir/$feature/SPEC.md"
+  local review_rel="$specs_dir/$feature/REVIEW.md"
+  local artifacts_dir_rel="$specs_dir/$feature/.artifacts"
+
+  : >"$out_file"
+  {
+    printf "## Artifacts\\n\\n"
+    # shellcheck disable=SC2016
+    printf 'Feature: `%s`\n' "$feature"
+  } >>"$out_file"
+
+  bt_pr_append_artifact_section "$out_file" "$spec_rel" "$spec_rel" "$max_inline_bytes"
+
+  if [[ -f "$review_rel" ]]; then
+    bt_pr_append_artifact_section "$out_file" "$review_rel" "$review_rel" "$max_inline_bytes"
+  fi
+
+  if [[ -d "$artifacts_dir_rel" ]]; then
+    local f
+    while IFS= read -r f; do
+      [[ -n "$f" ]] || continue
+      bt_pr_append_artifact_section "$out_file" "$f" "$f" "$max_inline_bytes"
+    done < <(find "$artifacts_dir_rel" -type f -print | LC_ALL=C sort)
+  fi
+}
+
+bt_cmd_pr() {
+  local feature=""
+  local run_mode="dry-run"
+  local draft=0
+  local base=""
+  local remote="origin"
+  local commit=1
+
+  while [[ $# -gt 0 ]]; do
+    case "${1:-}" in
+      -h|--help) bt_pr_usage; return 0 ;;
+      --run) run_mode="run"; shift ;;
+      --dry-run) run_mode="dry-run"; shift ;;
+      --draft) draft=1; shift ;;
+      --base) base="${2:-}"; shift 2 ;;
+      --remote) remote="${2:-}"; shift 2 ;;
+      --no-commit) commit=0; shift ;;
+      -*)
+        bt_err "unknown flag: $1"
+        return 2
+        ;;
+      *)
+        feature="$1"
+        shift
+        ;;
+    esac
+  done
+
+  if [[ -z "$feature" ]]; then
+    bt_err "feature name is required"
+    return 2
+  fi
+
+  # Ensure BT_PROJECT_ROOT reflects BT_TARGET_DIR / BT_ENV_FILE, and operate within it.
+  bt_env_load || true
+  [[ -n "${BT_PROJECT_ROOT:-}" ]] || bt_die "missing BT_PROJECT_ROOT"
+  cd "$BT_PROJECT_ROOT" || bt_die "failed to cd into BT_PROJECT_ROOT: $BT_PROJECT_ROOT"
+
+  bt_info "shipping feature: $feature"
+
+  # 1. Run Tests & Lint
+  bt_info "running tests..."
+  npm test
+  bt_info "running lint..."
+  npm run lint
+
+  # 2. Determine branch and metadata from SPEC.md
+  local specs_dir="${BT_SPECS_DIR:-specs}"
+  local spec_file="$specs_dir/$feature/SPEC.md"
+  local branch="feat/$feature"
+  local repo=""
+  local issue=""
+
+  if [[ -f "$spec_file" ]]; then
+    local b
+    b="$(awk -F': *' '$1=="branch"{print $2; exit}' "$spec_file" | tr -d '\r')"
+    local r
+    r="$(awk -F': *' '$1=="repo"{print $2; exit}' "$spec_file" | tr -d '\r')"
+    local i
+    i="$(awk -F': *' '$1=="issue"{print $2; exit}' "$spec_file" | tr -d '\r')"
+    [[ -n "${b:-}" ]] && branch="$b"
+    [[ -n "${r:-}" ]] && repo="$r"
+    [[ -n "${i:-}" ]] && issue="$i"
+  fi
+
+  # 3. Create branch if needed
+  if git show-ref --verify --quiet "refs/heads/$branch"; then
+    bt_info "branch $branch already exists, checking it out..."
+    git checkout "$branch"
+  else
+    bt_info "creating and checking out branch $branch..."
+    git checkout -b "$branch"
+  fi
+
+  # 4. Commit changes if requested
+  if [[ "$commit" == "1" ]]; then
+    bt_info "committing changes..."
+    # Add SPEC.md and any tests/implementations related to this feature
+    # We use explicit paths to avoid staging unrelated items
+    local paths_to_add=()
+    [[ -d "$specs_dir/$feature" ]] && paths_to_add+=("$specs_dir/$feature")
+    [[ -d "tests" ]] && paths_to_add+=("tests")
+    [[ -d "lib" ]] && paths_to_add+=("lib")
+    [[ -d "commands" ]] && paths_to_add+=("commands")
+    [[ -d "scripts" ]] && paths_to_add+=("scripts")
+    
+    if [[ ${#paths_to_add[@]} -gt 0 ]]; then
+       git add "${paths_to_add[@]}"
+    fi
+
+    if ! git diff --cached --quiet; then
+      git commit -m "feat($feature): ship implementation"
+    else
+      bt_info "nothing to commit"
+    fi
+  fi
+
+  # 5. Push
+  bt_info "pushing to $remote/$branch..."
+  if [[ "$run_mode" == "run" ]]; then
+    git push -u "$remote" "$branch"
+  else
+    bt_info "[dry-run] git push -u $remote $branch"
+  fi
+
+  # 6. Open PR via gh
+  if [[ -z "$base" ]]; then
+    local ref
+    ref="$(git symbolic-ref -q "refs/remotes/$remote/HEAD" 2>/dev/null || true)"
+    if [[ -n "$ref" ]]; then
+      # refs/remotes/<remote>/<branch> -> <branch>
+      base="${ref##*/}"
+    else
+      base="main"
+    fi
+  fi
+
+  local title="feat: $feature"
+  local body="Feature: $feature"
+  [[ -n "$repo" && -n "$issue" ]] && body+=$'\n'"Issue: https://github.com/$repo/issues/$issue"
+  [[ -f "$spec_file" ]] && body+=$'\n'"Spec: $spec_file"
+
+  bt_info "opening PR on $base..."
+  local pr_args=(pr create --head "$branch" --base "$base" --title "$title" --body "$body")
+  [[ "$draft" == "1" ]] && pr_args+=(--draft)
+
+  if [[ "$run_mode" == "run" ]]; then
+    local pr_out
+    pr_out="$(gh "${pr_args[@]}")"
+    # gh pr create typically prints the PR URL on success.
+    local pr_url
+    pr_url="$(printf '%s\n' "$pr_out" | tail -n 1 | tr -d '\r')"
+    if [[ -n "$pr_url" ]]; then
+      bt_info "posting artifacts comment..."
+      local comment_file
+      comment_file="$(mktemp "${TMPDIR:-/tmp}/bt-pr-comment.XXXXXX")"
+      bt_pr_write_artifacts_comment "$feature" "$specs_dir" "$comment_file"
+      gh pr comment "$pr_url" --body-file "$comment_file"
+      rm -f "$comment_file"
+    else
+      bt_err "gh pr create did not return a PR URL; skipping artifacts comment"
+    fi
+  else
+    bt_info "[dry-run] gh ${pr_args[*]}"
+  fi
+
+  bt_info "ship complete for $feature"
+}

package/commands/research.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_research() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt research <feature>
+
+Runs Codex in full-auto using prompts/research.md and produces specs/<feature>/RESEARCH.md.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local feature
+  feature="$(bt_require_feature "${1:-}")"
+
+  local dir
+  dir="$(bt_feature_dir "$feature")"
+  [[ -d "$dir" ]] || bt_die "missing feature dir: $dir (run: bt spec ...)"
+  mkdir -p "$dir/history"
+
+  local out="$dir/RESEARCH.md"
+  bt_codex_available || bt_die "codex required for research (set BT_CODEX_BIN or install codex)"
+
+  bt_info "running codex (read-only) using prompts/research.md -> $out"
+  local codex_ec=0 codex_logf artifacts_dir
+  artifacts_dir="$dir/.artifacts"
+  mkdir -p "$artifacts_dir"
+  # Deterministic path for reproducible runs and CI artifacts (no mktemp randomness).
+  codex_logf="$artifacts_dir/codex-research.log"
+  : >"$codex_logf"
+  if ! BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_read_only "$BT_ROOT/prompts/research.md" "$out"; then
+    codex_ec=$?
+    bt_warn "codex exited non-zero (research): $codex_ec"
+  fi
+
+  if [[ ! -f "$out" ]]; then
+    local err_tail
+    err_tail="$(tail -n 80 "$codex_logf" 2>/dev/null || true)"
+    cat >"$out" <<EOF
+# Research: $feature
+
+Codex did not create \`$out\`. A stub was generated so the loop can continue.
+
+- codex_exit: $codex_ec
+- feature_dir: $dir
+- prompt: $BT_ROOT/prompts/research.md
+- bt_cmd: bt research $feature
+
+## Codex stderr (tail)
+
+${err_tail:-"(no stderr captured)"}
+
+Next:
+- Run Codex against \`$BT_ROOT/prompts/research.md\`
+- Capture findings here (patterns, pitfalls, test/lint commands, etc)
+EOF
+  fi
+
+  bt_progress_append "$feature" "research: bt research $feature (codex_exit=$codex_ec)"
+  bt_history_write "$feature" "research" "$(cat <<EOF
+# Research Run: $feature
+
+- when: $(date +'%Y-%m-%d %H:%M:%S')
+- bt_cmd: bt research $feature
+- prompt: prompts/research.md
+- codex_exit: $codex_ec
+- output: specs/$feature/RESEARCH.md
+EOF
+)"
+  [[ -f "$out" ]] && bt_info "wrote $out"
+  bt_notify "bt research complete for $feature"
+}

package/commands/reset.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_reset() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt reset
+
+Removes Biotonomy ephemeral state (`.bt/`) and any `specs/**/.lock` files.
+
+Note: v0.1.0 does NOT modify your git working tree.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local state="$BT_PROJECT_ROOT/$BT_STATE_DIR"
+  if [[ -d "$state" ]]; then
+    rm -rf "$state"
+    bt_info "removed $state"
+  fi
+
+  local specs_path
+  specs_path="$(bt_specs_path)"
+  if [[ -d "$specs_path" ]]; then
+    find "$specs_path" -type f -name ".lock" -print -delete 2>/dev/null || true
+  fi
+
+  bt_notify "bt reset complete in $BT_PROJECT_ROOT"
+}
+

package/commands/review.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_review() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt review <feature>
+
+Runs Codex in read-only using prompts/review.md and produces specs/<feature>/REVIEW.md.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local feature
+  feature="$(bt_require_feature "${1:-}")"
+
+  local dir
+  dir="$(bt_feature_dir "$feature")"
+  [[ -d "$dir" ]] || bt_die "missing feature dir: $dir (run: bt spec ...)"
+
+  local out="$dir/REVIEW.md"
+  local artifacts_dir codex_logf
+  artifacts_dir="$dir/.artifacts"
+  mkdir -p "$artifacts_dir"
+  codex_logf="$artifacts_dir/codex-review.log"
+  : >"$codex_logf"
+  local codex_ec=0
+  if ! BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_read_only "$BT_ROOT/prompts/review.md" "$out"; then
+    codex_ec=$?
+    bt_warn "codex exited non-zero (review): $codex_ec"
+  fi
+
+  if [[ ! -f "$out" ]]; then
+    cat >"$out" <<EOF
+# Review: $feature
+
+Verdict: NEEDS_CHANGES
+
+Codex did not produce \`$out\`. A stub was generated so the loop can continue.
+
+- codex_exit: $codex_ec
+- feature_dir: $dir
+- prompt: $BT_ROOT/prompts/review.md
+- bt_cmd: bt review $feature
+EOF
+  elif ! grep -qi '^Verdict:' "$out" 2>/dev/null; then
+    local tmp artifacts_dir
+    artifacts_dir="$dir/.artifacts"
+    mkdir -p "$artifacts_dir"
+    # Deterministic temp path to keep outputs reproducible and scoped to the feature dir.
+    tmp="$artifacts_dir/review.rewrite.tmp.md"
+    cat >"$tmp" <<EOF
+# Review: $feature
+
+Verdict: NEEDS_CHANGES
+
+Codex output was missing the required \`Verdict:\` line. Content preserved below.
+
+EOF
+    cat "$out" >>"$tmp" 2>/dev/null || true
+    mv "$tmp" "$out"
+  fi
+
+  bt_progress_append "$feature" "review: bt review $feature (codex_exit=$codex_ec)"
+  bt_history_write "$feature" "review" "$(cat <<EOF
+# Review Run: $feature
+
+- when: $(date +'%Y-%m-%d %H:%M:%S')
+- bt_cmd: bt review $feature
+- prompt: prompts/review.md
+- codex_exit: $codex_ec
+- output: specs/$feature/REVIEW.md
+EOF
+)"
+  bt_info "wrote $out"
+  bt_notify "bt review complete for $feature"
+}

package/commands/spec.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt__require_cmd() {
+  local cmd="$1"
+  command -v "$cmd" >/dev/null 2>&1 || bt_die "missing required command: $cmd"
+}
+
+bt__summarize_body() {
+  local s="${1:-}"
+  s="${s//$'\r'/}"
+  # Collapse whitespace and cap length so the SPEC stays readable.
+  s="$(printf '%s' "$s" | sed -e 's/[[:space:]][[:space:]]*/ /g' -e 's/^ *//; s/ *$//')"
+  if (( ${#s} > 900 )); then
+    s="${s:0:897}..."
+  fi
+  printf '%s\n' "$s"
+}
+
+bt__json_fields_sep() {
+  # Reads JSON on stdin and prints: title<US>url<US>body (US = 0x1f).
+  # Avoid NUL: bash variables can't reliably hold it.
+  bt__require_cmd node
+  node -e "$(
+    cat <<'NODE'
+const fs = require("fs");
+const j = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+const title = (j.title ?? "").toString();
+const url = (j.url ?? "").toString();
+// Make body newline-free so bash `read` (used by the caller) does not truncate it.
+const body = (j.body ?? "").toString().replace(/[\r\n]+/g, " ");
+// Ensure a terminating newline so bash `read` does not exit non-zero at EOF.
+process.stdout.write(title + "\x1f" + url + "\x1f" + body + "\n");
+NODE
+  )"
+}
+
+bt_cmd_spec() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt spec <issue#>
+  bt spec <feature>
+
+For an <issue#>, requires `gh` and creates `specs/issue-<n>/SPEC.md` using the issue title/body.
+For a <feature>, creates `specs/<feature>/SPEC.md` with a minimal, parseable story list.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local arg="${1:-}"
+  [[ -n "$arg" ]] || bt_die "spec requires <issue#> or <feature>"
+
+  local feature issue
+  issue=""
+  if [[ "$arg" =~ ^[0-9]+$ ]]; then
+    issue="$arg"
+    feature="issue-$arg"
+  else
+    feature="$arg"
+  fi
+
+  local dir
+  dir="$(bt_feature_dir "$feature")"
+  mkdir -p "$dir/history"
+
+  local spec="$dir/SPEC.md"
+  if [[ -f "$spec" ]]; then
+    bt_info "SPEC already exists: $spec"
+    return 0
+  fi
+
+  if [[ -n "$issue" ]]; then
+    bt__require_cmd gh
+
+    local repo
+    repo="$(bt_repo_resolve "$BT_PROJECT_ROOT")"
+
+    local -a gh_cmd
+    gh_cmd=(gh issue view "$issue" -R "$repo" --json "title,body,url")
+
+    local json errf artifacts_dir
+    artifacts_dir="$dir/.artifacts"
+    mkdir -p "$artifacts_dir"
+    # Deterministic stderr capture for reproducible runs (avoid mktemp randomness).
+    errf="$artifacts_dir/gh.stderr"
+    : >"$errf"
+    if ! json="$("${gh_cmd[@]}" 2>"$errf")"; then
+      local ec=$?
+      local err
+      err="$(cat "$errf" 2>/dev/null || true)"
+      bt_die "failed to fetch issue #$issue via gh (exit $ec): $err"
+    fi
+    rm -f "$errf" || true
+
+    local title url body
+    IFS=$'\x1f' read -r title url body < <(printf '%s' "$json" | bt__json_fields_sep)
+    [[ -n "$title" ]] || title="(untitled)"
+    [[ -n "$url" ]] || url="https://github.com/$repo/issues/$issue"
+
+    local summary
+    summary="$(bt__summarize_body "$body")"
+
+    cat >"$spec" <<EOF
+---
+name: $feature
+branch: feat/$feature
+issue: $issue
+repo: $repo
+---
+
+# Problem
+
+## $title
+
+- **issue:** #$issue
+- **link:** $url
+
+$summary
+
+# Stories
+
+## [ID:S1] Confirm repo resolution and env fallback
+- **status:** draft
+- **priority:** 1
+- **acceptance:** bt can determine repo slug from git remote origin; otherwise requires BT_REPO
+- **tests:**
+
+## [ID:S2] Fetch issue details via gh
+- **status:** draft
+- **priority:** 1
+- **acceptance:** bt spec <issue#> uses gh to retrieve title/body/url and handles errors clearly
+- **tests:**
+
+## [ID:S3] Generate a SPEC.md with frontmatter + problem summary
+- **status:** draft
+- **priority:** 1
+- **acceptance:** SPEC includes required frontmatter, a Problem section, and a Stories section (3-7 stories)
+- **tests:**
+
+## [ID:S4] Record exact gh commands used in SPEC footer
+- **status:** draft
+- **priority:** 2
+- **acceptance:** SPEC footer includes the exact gh command(s) executed
+- **tests:**
+
+## [ID:S5] Add tests stubbing gh via PATH
+- **status:** draft
+- **priority:** 1
+- **acceptance:** tests run offline and validate SPEC content generation
+- **tests:**
+
+---
+
+## Footer
+
+### gh
+- \`${gh_cmd[*]}\`
+EOF
+
+    bt_progress_append "$feature" "spec created (from gh issue $repo#$issue)"
+    bt_history_write "$feature" "spec" "Created SPEC.md from $repo#$issue."
+    bt_info "wrote $spec"
+    bt_notify "bt spec created for $feature"
+    return 0
+  fi
+
+  cat >"$spec" <<EOF
+---
+name: $feature
+branch: feat/$feature
+issue: ${issue:-}
+repo:
+---
+
+# Stories
+
+## [ID:S1] Define acceptance criteria
+- **status:** pending
+- **priority:** 1
+- **acceptance:** SPEC.md is filled out with real stories and tests
+- **tests:**
+
+EOF
+
+  bt_progress_append "$feature" "spec created"
+  bt_history_write "$feature" "spec" "Created SPEC.md for $feature."
+  bt_info "wrote $spec"
+  bt_notify "bt spec created for $feature"
+}