@thebassclef/lite 1.9.4 → 1.9.5

package/dist/lite/scripts/interpret-input/extract-repo.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# tier: lite
+# scripts/interpret-input/extract-repo.sh — Phase C repo extractor.
+#
+# Walks a local repo directory and extracts:
+# - README excerpt (first 30 lines of README.md or equivalent)
+# - Title (first H1 in README, or repo dirname)
+# - Domain entity candidates (Prisma models + directory-pattern heuristic)
+# - Boundary objects (Next.js routes, pages, API endpoints)
+# - Actor candidates (role/auth keywords in source)
+#
+# Outputs JSON to stdout. Wrapper composes into the InputArtifact.
+#
+# Usage:
+#   bash scripts/interpret-input/extract-repo.sh <local-repo-path>
+#
+# Exit codes:
+#   0 = success (even partial extraction is success — empty arrays for missing signals)
+#   2 = bad input (missing path or not a directory)
+#
+# Pairs with: scripts/interpret-input.sh + standards/input-handler-interface.md
+
+set -u
+
+REPO_PATH="${1:-}"
+
+if [ -z "$REPO_PATH" ]; then
+  echo "extract-repo: requires <repo-path>" >&2
+  exit 2
+fi
+
+if [ ! -d "$REPO_PATH" ]; then
+  echo "extract-repo: $REPO_PATH is not a directory" >&2
+  exit 2
+fi
+
+# Use absolute path so cd doesn't break relative output
+REPO_PATH="$(cd "$REPO_PATH" && pwd)"
+cd "$REPO_PATH" || { echo "extract-repo: cannot cd to $REPO_PATH" >&2; exit 2; }
+
+# === README excerpt + title ===
+README_EXCERPT=""
+README_PATH=""
+for candidate in README.md README.MD readme.md README.rst README.txt; do
+  if [ -f "$candidate" ]; then
+    README_PATH="$candidate"
+    README_EXCERPT=$(head -30 "$candidate")
+    break
+  fi
+done
+
+TITLE=""
+if [ -n "$README_PATH" ]; then
+  TITLE=$(grep -m1 '^# ' "$README_PATH" 2>/dev/null | sed 's/^# *//')
+fi
+if [ -z "$TITLE" ]; then
+  TITLE=$(basename "$REPO_PATH")
+fi
+
+# === Entity candidates ===
+
+# Strategy 1: Prisma models
+ENTITIES_PRISMA=()
+for schema in prisma/schema.prisma prisma/*.prisma; do
+  if [ -f "$schema" ]; then
+    while IFS= read -r model_name; do
+      [ -z "$model_name" ] && continue
+      ENTITIES_PRISMA+=("$model_name")
+    done < <(grep -E '^model [A-Z][a-zA-Z]+' "$schema" 2>/dev/null | awk '{print $2}')
+  fi
+done
+
+# Strategy 2: directory-pattern entities
+# A directory containing >=3 files/subdirs of consistent shape suggests a collection.
+# The singularized dirname is a candidate entity.
+ENTITIES_DIR=()
+
+# Collect candidate dirs at depth <=4, skipping known noise
+CANDIDATE_DIRS=$(find . -maxdepth 4 -mindepth 1 -type d \
+  -not -path '*/node_modules*' \
+  -not -path '*/.git*' \
+  -not -path '*/.next*' \
+  -not -path '*/dist*' \
+  -not -path '*/build*' \
+  -not -path '*/coverage*' \
+  -not -path '*/__pycache__*' \
+  2>/dev/null)
+
+while IFS= read -r dir; do
+  [ -z "$dir" ] && continue
+  DIRNAME=$(basename "$dir")
+  case "$DIRNAME" in
+    .|..|node_modules|.git|.next|dist|build|coverage|__tests__|tests|test|src|lib|components|utils|public|static|scripts|bin|hooks) continue ;;
+  esac
+  # Only consider directories whose name suggests a collection (plural-ish)
+  case "$DIRNAME" in
+    *s|*ies)
+      # Count direct children
+      COUNT=$(find "$dir" -maxdepth 1 -mindepth 1 \
+        \( -type d -o -name '*.md' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.json' -o -name '*.yml' -o -name '*.yaml' \) \
+        2>/dev/null | wc -l | tr -d ' ')
+      if [ "$COUNT" -ge 3 ]; then
+        # Singularize: ies → y; ses/xes/zes/ches/shes → strip "es"; else strip "s"
+        case "$DIRNAME" in
+          *ies)                       SINGULAR="${DIRNAME%ies}y" ;;
+          *ses|*xes|*zes|*ches|*shes) SINGULAR="${DIRNAME%es}" ;;
+          *s)                         SINGULAR="${DIRNAME%s}" ;;
+        esac
+        # Skip too-short or too-noisy singulars
+        if [ "${#SINGULAR}" -ge 3 ]; then
+          ENTITIES_DIR+=("$SINGULAR")
+        fi
+      fi
+      ;;
+  esac
+done <<<"$CANDIDATE_DIRS"
+
+# Combine + dedupe entities
+ALL_ENTITIES=()
+SEEN=""
+for e in "${ENTITIES_PRISMA[@]:-}" "${ENTITIES_DIR[@]:-}"; do
+  [ -z "$e" ] && continue
+  case " $SEEN " in
+    *" $e "*) ;;
+    *) ALL_ENTITIES+=("$e"); SEEN="$SEEN $e" ;;
+  esac
+done
+
+# === Boundary objects (routes + pages + API endpoints) ===
+BOUNDARY_OBJECTS=()
+
+# Next.js App Router routes (app/**/page.{ts,tsx,js,jsx})
+for app_dir in app src/app; do
+  if [ -d "$app_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      # Convert path to route: app/deals/page.tsx → /deals
+      ROUTE=$(echo "$f" | sed -E "s|^./${app_dir}||" | sed 's|/page\.[a-zA-Z]*$||')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("route:$ROUTE")
+    done < <(find "./$app_dir" -maxdepth 6 \( -name 'page.tsx' -o -name 'page.ts' -o -name 'page.js' -o -name 'page.jsx' \) 2>/dev/null | head -50)
+  fi
+done
+
+# Next.js Pages Router routes (pages/**/*.{ts,tsx,js,jsx})
+for pages_dir in pages src/pages; do
+  if [ -d "$pages_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      ROUTE=$(echo "$f" | sed -E "s|^./${pages_dir}||" | sed 's/\.[a-zA-Z]*$//')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("page:$ROUTE")
+    done < <(find "./$pages_dir" -maxdepth 6 -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.js' -o -name '*.jsx' \) -not -name '_*' -not -name 'api' 2>/dev/null | head -30)
+  fi
+done
+
+# API routes
+for api_dir in app/api src/app/api pages/api src/pages/api; do
+  if [ -d "$api_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      ROUTE=$(echo "$f" | sed -E "s|^./${api_dir}||" | sed 's|/route\.[a-zA-Z]*$||' | sed 's/\.[a-zA-Z]*$//')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("api:$ROUTE")
+    done < <(find "./$api_dir" -maxdepth 6 -type f \( -name 'route.ts' -o -name 'route.tsx' -o -name 'route.js' -o -name '*.ts' \) 2>/dev/null | head -20)
+  fi
+done
+
+# === Actor candidates ===
+# Heuristic: grep role/auth keywords in source code
+ACTOR_CANDIDATES=()
+ACTOR_RAW=$(grep -rEho \
+  '\b(admin|owner|operator|viewer|editor|guest|member|customer|client|reviewer|approver|manager)\b' \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.prisma' --include='*.md' \
+  --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next --exclude-dir=dist --exclude-dir=build \
+  . 2>/dev/null | tr '[:upper:]' '[:lower:]' | sort -u | head -10)
+
+while IFS= read -r kw; do
+  [ -z "$kw" ] && continue
+  ACTOR_CANDIDATES+=("$kw")
+done <<<"$ACTOR_RAW"
+
+# === Compose extracted_text prose ===
+ENTITY_LIST=$(IFS=,; echo "${ALL_ENTITIES[*]:-}")
+ACTOR_LIST=$(IFS=,; echo "${ACTOR_CANDIDATES[*]:-}")
+BOUNDARY_COUNT=${#BOUNDARY_OBJECTS[@]}
+
+EXTRACTED_TEXT="Repository: $TITLE
+Path: $REPO_PATH
+
+Detected entities (${#ALL_ENTITIES[@]}): ${ENTITY_LIST:-none}
+Detected actors (${#ACTOR_CANDIDATES[@]}): ${ACTOR_LIST:-none}
+Detected boundary objects: ${BOUNDARY_COUNT} routes/pages/api endpoints"
+
+if [ -n "$README_EXCERPT" ]; then
+  EXTRACTED_TEXT="${EXTRACTED_TEXT}
+
+README excerpt:
+${README_EXCERPT}"
+fi
+
+# === Build JSON output ===
+# Convert arrays to JSON; handle empty arrays explicitly (bash 3.x compat — no namerefs).
+if [ ${#ALL_ENTITIES[@]} -eq 0 ]; then
+  ENTITIES_JSON='[]'
+else
+  ENTITIES_JSON=$(printf '%s\n' "${ALL_ENTITIES[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+if [ ${#ACTOR_CANDIDATES[@]} -eq 0 ]; then
+  ACTORS_JSON='[]'
+else
+  ACTORS_JSON=$(printf '%s\n' "${ACTOR_CANDIDATES[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+if [ ${#BOUNDARY_OBJECTS[@]} -eq 0 ]; then
+  BOUNDARY_JSON='[]'
+else
+  BOUNDARY_JSON=$(printf '%s\n' "${BOUNDARY_OBJECTS[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+# Output
+jq -n \
+  --arg extracted_text "$EXTRACTED_TEXT" \
+  --arg title "$TITLE" \
+  --arg readme_excerpt "$README_EXCERPT" \
+  --argjson entities_seen "$ENTITIES_JSON" \
+  --argjson actor_candidates "$ACTORS_JSON" \
+  --argjson boundary_objects "$BOUNDARY_JSON" \
+  '{
+    extracted_text: $extracted_text,
+    structural_hints: {
+      entities_seen: $entities_seen,
+      actor_candidates: $actor_candidates,
+      boundary_objects: $boundary_objects,
+      readme_excerpt: $readme_excerpt,
+      title: $title
+    }
+  }'

package/dist/lite/scripts/interpret-input.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# tier: lite
+# scripts/interpret-input.sh — input-handler CLI wrapper.
+#
+# Phase B: text-mode fully; other modes return stub InputArtifacts
+# (schema-valid; extracted_text="deferred to Phase C").
+#
+# Usage:
+#   bash scripts/interpret-input.sh "<source>" [--type=auto|text|url|image|repo|transcript|napkin|mixed] [--persist] [--slug=<slug>]
+#
+# Output:
+#   --persist OFF (default): InputArtifact JSON to stdout
+#   --persist ON: JSON written to docs/input-artifacts/<slug>.json; stdout = path
+#
+# Exit codes:
+#   0 = success
+#   2 = invalid input
+#   3 = jq construction failed
+#   4 = filesystem error (overwrite or mkdir)
+#   5 = repo extraction setup failed (clone error, mktemp error)
+#
+# Pairs with: standards/input-handler-interface.md + .claude/skills/interpret-input/SKILL.md
+
+set -u
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+usage() {
+  cat <<'EOF'
+/interpret-input — produce schema-validated InputArtifact from any input
+
+Usage:
+  bash scripts/interpret-input.sh "<source>" [flags]
+
+Flags:
+  --type=<type>     text|url|image|repo|transcript|napkin|mixed (default: auto)
+  --persist         write to docs/input-artifacts/<slug>.json
+  --slug=<slug>     override auto-generated slug
+  --help            show this message
+
+Auto-detection:
+  ^https?://                                → url
+  \.(png|jpg|jpeg|gif|webp|svg)$            → image
+  \.git$ or contains github.com             → repo
+  (else)                                    → text
+
+Phase B: text fully; other modes stub (extracted_text="deferred to Phase C").
+EOF
+}
+
+SOURCE=""
+TYPE="auto"
+PERSIST=0
+SLUG=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --type=*) TYPE="${1#--type=}"; shift ;;
+    --persist) PERSIST=1; shift ;;
+    --slug=*) SLUG="${1#--slug=}"; shift ;;
+    --help|-h) usage; exit 0 ;;
+    --*) echo "interpret-input: unknown flag '$1'" >&2; usage >&2; exit 2 ;;
+    *)
+      if [ -z "$SOURCE" ]; then SOURCE="$1"; shift
+      else echo "interpret-input: multiple positional sources not supported in v0" >&2; exit 2
+      fi
+      ;;
+  esac
+done
+
+if [ -z "$SOURCE" ]; then
+  echo "interpret-input: requires <source>" >&2
+  usage >&2
+  exit 2
+fi
+
+# Auto-detect type
+if [ "$TYPE" = "auto" ]; then
+  if echo "$SOURCE" | grep -qE '^https?://'; then
+    TYPE="url"
+  elif echo "$SOURCE" | grep -qiE '\.(png|jpg|jpeg|gif|webp|svg)$'; then
+    TYPE="image"
+  elif echo "$SOURCE" | grep -qE '\.git$'; then
+    TYPE="repo"
+  elif [ -d "$SOURCE" ] && [ -d "$SOURCE/.git" ]; then
+    # Local directory that's a git repo
+    TYPE="repo"
+  else
+    TYPE="text"
+  fi
+fi
+
+# Validate type against schema enum
+case "$TYPE" in
+  text|url|image|repo|transcript|napkin|mixed) ;;
+  *)
+    echo "interpret-input: unknown type '$TYPE' (must be: text|url|image|repo|transcript|napkin|mixed)" >&2
+    exit 2
+    ;;
+esac
+
+# Generate slug if not provided
+if [ -z "$SLUG" ]; then
+  TS=$(date -u +%Y-%m-%d)
+  HASH=$(printf '%s' "$SOURCE" | md5 -q 2>/dev/null \
+       || printf '%s' "$SOURCE" | md5sum 2>/dev/null | cut -c1-6 \
+       || echo "abc123")
+  HASH="${HASH:0:6}"
+  SLUG="${TS}-${TYPE}-${HASH}"
+fi
+
+# Validate slug pattern (matches schema's id pattern)
+if ! echo "$SLUG" | grep -qE '^[a-z0-9][a-z0-9-]*$'; then
+  echo "interpret-input: slug '$SLUG' does not match required pattern ^[a-z0-9][a-z0-9-]*$" >&2
+  exit 2
+fi
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+STRUCTURAL_HINTS='{}'
+
+case "$TYPE" in
+  text)
+    EXTRACTED_TEXT="$SOURCE"
+    EXTERNAL_URLS=$(printf '%s' "$SOURCE" | grep -oE 'https?://[^[:space:]<>"`]+' \
+      | sed 's/[.,;:)]*$//' \
+      | jq -R . | jq -s -c . 2>/dev/null || echo '[]')
+    ;;
+  repo)
+    # Phase C: walk a local repo or clone a URL, extract structural signals.
+    # Resolve source to a local path. If the source isn't a URL or an existing
+    # directory, fall back to stub mode (preserves Phase B contract for
+    # not-yet-extractable sources).
+    CLEANUP_TMP=0
+    REPO_LOCAL=""
+    if echo "$SOURCE" | grep -qE '^https?://'; then
+      TMP_DIR=$(mktemp -d 2>/dev/null) || { echo "interpret-input: mktemp failed" >&2; exit 5; }
+      if ! git clone --depth=1 --quiet "$SOURCE" "$TMP_DIR" 2>/dev/null; then
+        rm -rf "$TMP_DIR"
+        echo "interpret-input: git clone failed for $SOURCE" >&2
+        exit 5
+      fi
+      REPO_LOCAL="$TMP_DIR"
+      CLEANUP_TMP=1
+    elif [ -d "$SOURCE" ]; then
+      REPO_LOCAL="$SOURCE"
+    fi
+
+    if [ -z "$REPO_LOCAL" ]; then
+      # Source can't be resolved; return Phase B-style stub (still valid InputArtifact)
+      EXTRACTED_TEXT="deferred to Phase C"
+      STRUCTURAL_HINTS='{}'
+    else
+      EXTRACT_OUT=$(bash "$REPO_ROOT/scripts/interpret-input/extract-repo.sh" "$REPO_LOCAL" 2>/dev/null)
+      EXTRACT_RC=$?
+
+      if [ "$CLEANUP_TMP" = "1" ]; then
+        rm -rf "$TMP_DIR"
+      fi
+
+      if [ "$EXTRACT_RC" != "0" ] || [ -z "$EXTRACT_OUT" ]; then
+        EXTRACTED_TEXT="repo extraction returned no signal for $SOURCE"
+        STRUCTURAL_HINTS='{}'
+      else
+        EXTRACTED_TEXT=$(echo "$EXTRACT_OUT" | jq -r '.extracted_text')
+        STRUCTURAL_HINTS=$(echo "$EXTRACT_OUT" | jq -c '.structural_hints')
+      fi
+    fi
+    EXTERNAL_URLS='[]'
+    ;;
+  *)
+    EXTRACTED_TEXT="deferred to Phase C"
+    EXTERNAL_URLS='[]'
+    ;;
+esac
+
+ARTIFACT=$(jq -n \
+  --arg id "$SLUG" \
+  --arg type "$TYPE" \
+  --arg source "$SOURCE" \
+  --arg extracted_text "$EXTRACTED_TEXT" \
+  --arg created_at "$NOW" \
+  --argjson external_urls "$EXTERNAL_URLS" \
+  --argjson structural_hints "$STRUCTURAL_HINTS" \
+  '{
+    id: $id,
+    type: $type,
+    source: $source,
+    extracted_text: $extracted_text,
+    structural_hints: $structural_hints,
+    external_urls: $external_urls,
+    created_at: $created_at
+  }')
+
+if [ -z "$ARTIFACT" ]; then
+  echo "interpret-input: jq failed to construct InputArtifact JSON" >&2
+  exit 3
+fi
+
+if [ "$PERSIST" = "1" ]; then
+  TARGET_DIR="docs/input-artifacts"
+  TARGET_PATH="${TARGET_DIR}/${SLUG}.json"
+  if [ -f "$TARGET_PATH" ]; then
+    echo "interpret-input: $TARGET_PATH already exists; --slug=<new> to write a different one" >&2
+    exit 4
+  fi
+  mkdir -p "$TARGET_DIR" || { echo "interpret-input: mkdir $TARGET_DIR failed" >&2; exit 4; }
+  echo "$ARTIFACT" | jq . > "$TARGET_PATH" || { echo "interpret-input: write $TARGET_PATH failed" >&2; exit 4; }
+  echo "$TARGET_PATH"
+else
+  echo "$ARTIFACT" | jq .
+fi

package/dist/lite/scripts/launch/local-serve-stop.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# tier: lite
+# local-serve-stop.sh — stop a local-serve.sh server by slug
+#
+# Per bassclef#923 A2. Companion to scripts/launch/local-serve.sh.
+#
+# Usage:
+#   bash scripts/launch/local-serve-stop.sh <gallery-slug>
+#
+# If a server is running for the slug, kills the PID and removes the
+# state file. If no server is running, exits 0 silently.
+
+set -e
+
+SLUG="${1:-}"
+if [ -z "$SLUG" ]; then
+  echo "ERROR: gallery-slug required" >&2
+  echo "usage: $0 <gallery-slug>" >&2
+  exit 2
+fi
+
+STATE_DIR="${REPO_ROOT:-$(pwd)}/state/markers/local-serve"
+STATE_FILE="$STATE_DIR/${SLUG}.state"
+
+if [ ! -f "$STATE_FILE" ]; then
+  echo "local-serve-stop: no state file for $SLUG — nothing to stop" >&2
+  exit 0
+fi
+
+PID=$(awk -F= '/^pid=/{print $2}' "$STATE_FILE" 2>/dev/null)
+URL=$(awk -F= '/^url=/{print $2}' "$STATE_FILE" 2>/dev/null)
+
+if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
+  kill "$PID" 2>/dev/null || true
+  echo "local-serve-stop: stopped server at $URL (pid=$PID)" >&2
+else
+  echo "local-serve-stop: state file present but PID $PID not alive — cleaning up" >&2
+fi
+
+rm -f "$STATE_FILE" "${STATE_DIR}/${SLUG}.log"
+exit 0

package/dist/lite/scripts/launch/local-serve.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+# tier: lite
+# local-serve.sh — serve a /launch local-mode prototype gallery via python http.server
+#
+# Per bassclef#923 A2: when /launch runs with --local flag, the Phase 12
+# bind-subdomain step is replaced with this helper. Gallery served on
+# localhost; no vendor accounts required.
+#
+# Usage:
+#   bash scripts/launch/local-serve.sh <gallery-dir> [port-hint]
+#
+# Args:
+#   gallery-dir — path to the directory containing the gallery (e.g.
+#                 docs/prototypes/<sprint-slug>/)
+#   port-hint   — optional starting port; defaults to 8000. Helper walks
+#                 up from this port until it finds an open one.
+#
+# What this does:
+#   1. Verifies python3 is on the path
+#   2. Verifies gallery-dir exists and contains at least an index.html
+#   3. Finds an open port starting from port-hint (default 8000)
+#   4. Starts python -m http.server in background, bound to 127.0.0.1
+#   5. Writes the PID + URL to state/markers/local-serve/<slug>.state
+#   6. Prints the URL to stdout (one line) for the caller to capture
+#
+# Idempotent: safe to re-run. If a server is already running for the
+# same gallery (state file exists, PID still alive), prints the
+# existing URL and exits 0.
+#
+# Cleanup: rely on the operator running scripts/launch/local-serve-stop.sh
+# or just killing the PID. State file lists the PID for reference.
+
+set -e
+
+GALLERY_DIR="${1:-}"
+PORT_HINT="${2:-8000}"
+
+if [ -z "$GALLERY_DIR" ]; then
+  echo "ERROR: gallery-dir required" >&2
+  echo "usage: $0 <gallery-dir> [port-hint]" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "ERROR: python3 not on PATH. Install python3 first." >&2
+  exit 1
+fi
+
+if [ ! -d "$GALLERY_DIR" ]; then
+  echo "ERROR: gallery directory does not exist: $GALLERY_DIR" >&2
+  exit 1
+fi
+
+if [ ! -f "$GALLERY_DIR/index.html" ]; then
+  echo "WARN: $GALLERY_DIR has no index.html — serving anyway, but the gallery may not render cleanly" >&2
+fi
+
+# Derive a slug for the state file from the gallery dir's basename
+GALLERY_SLUG=$(basename "$GALLERY_DIR")
+STATE_DIR="${REPO_ROOT:-$(pwd)}/state/markers/local-serve"
+STATE_FILE="$STATE_DIR/${GALLERY_SLUG}.state"
+mkdir -p "$STATE_DIR"
+
+# Idempotency check: if state file exists and PID is alive, return existing URL
+if [ -f "$STATE_FILE" ]; then
+  EXISTING_PID=$(awk -F= '/^pid=/{print $2}' "$STATE_FILE" 2>/dev/null || true)
+  EXISTING_URL=$(awk -F= '/^url=/{print $2}' "$STATE_FILE" 2>/dev/null || true)
+  if [ -n "$EXISTING_PID" ] && kill -0 "$EXISTING_PID" 2>/dev/null; then
+    echo "local-serve: already running for $GALLERY_SLUG (pid=$EXISTING_PID)" >&2
+    echo "$EXISTING_URL"
+    exit 0
+  fi
+  # Stale state file — remove
+  rm -f "$STATE_FILE"
+fi
+
+# Find an open port starting from PORT_HINT
+PORT="$PORT_HINT"
+MAX_PORT=$((PORT_HINT + 100))
+
+while [ "$PORT" -lt "$MAX_PORT" ]; do
+  if ! nc -z 127.0.0.1 "$PORT" 2>/dev/null; then
+    break
+  fi
+  PORT=$((PORT + 1))
+done
+
+if [ "$PORT" -ge "$MAX_PORT" ]; then
+  echo "ERROR: could not find open port in range $PORT_HINT..$MAX_PORT" >&2
+  exit 1
+fi
+
+# Start http.server in background, bound to 127.0.0.1 only (no external exposure)
+LOG_FILE="$STATE_DIR/${GALLERY_SLUG}.log"
+nohup python3 -m http.server "$PORT" --bind 127.0.0.1 --directory "$GALLERY_DIR" \
+  > "$LOG_FILE" 2>&1 &
+SERVER_PID=$!
+
+# Brief sleep to let server bind; verify by checking PID
+sleep 1
+if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+  echo "ERROR: http.server failed to start. Log: $LOG_FILE" >&2
+  exit 1
+fi
+
+URL="http://127.0.0.1:${PORT}/"
+
+# Write state file
+cat > "$STATE_FILE" <<EOF
+slug=${GALLERY_SLUG}
+pid=${SERVER_PID}
+port=${PORT}
+url=${URL}
+gallery_dir=${GALLERY_DIR}
+started_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+EOF
+
+echo "local-serve: gallery serving at $URL (pid=$SERVER_PID)" >&2
+echo "local-serve: stop with: kill $SERVER_PID  OR  bash scripts/launch/local-serve-stop.sh $GALLERY_SLUG" >&2
+
+# Print URL to stdout for the caller
+echo "$URL"