specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/scripts/bash/create-new-feature.sh

@@ -0,0 +1,336 @@
+#!/usr/bin/env bash
+
+# ============================================================================
+# NOT LEGACY — this script is ON the standard workflow path.
+# ============================================================================
+#
+# ⚠️ **This header used to read "LEGACY SCRIPT - NO LONGER USED IN STANDARD
+# WORKFLOW", and that statement was false** (`T144` / `ISS-50`). What the old text
+# described was this script's ORIGIN, not its behaviour: the filename and the
+# branch-numbering code below come from the speckit era, when every feature got its own
+# `specs/<NNN>-<short-name>/` subdirectory.
+#
+# What it actually does today is the CURRENT layout, and that is what its callers
+# depend on:
+#   - it writes `specs/spec.md` **directly**; no branch subdirectory is created
+#   - branch names are still computed and reported, but they direct NO directory
+#   - `commands/specpro.specify.md` calls it to obtain `SPEC_FILE`
+#
+# ⇒ **"kept for backwards compatibility" was the wrong frame.** The `-` numbering feature
+# is the legacy part, and it is inert. ⚠️ **Before deleting this file, check its callers**
+# — `grep -rn 'create-new-feature' commands/` — because deleting it breaks the standard
+# workflow, which is the opposite of what its old header invited.
+#
+# ⚠️ The PowerShell twin (`scripts/powershell/create-new-feature.ps1`) had already
+# recorded this discrepancy; the shell side had not. Two twins, one corrected.
+# ============================================================================
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specpro" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune 2>/dev/null || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            # `${word^^}` is a Bash 4.0+ expansion. On macOS's stock /bin/bash (3.2)
+            # it raises `bad substitution` — and because it sits in a `grep` condition
+            # inside an `elif`, the failure is SILENT: the branch simply never fires,
+            # the acronym word is dropped, and the script still exits 0 with a
+            # plausible-looking but wrong branch name. `tr` is the 3.2 equivalent.
+            elif echo "$description" | grep -q "\b$(echo "$word" | tr '[:lower:]' '[:upper:]')\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+# No longer creating Git branches for specifications
+# Each application has one spec.md that evolves over time
+FEATURE_DIR="$SPECS_DIR"
+mkdir -p "$FEATURE_DIR"
+
+SPEC_FILE="$FEATURE_DIR/spec.md"
+
+# Create spec.md from template if it doesn't exist
+if [[ ! -f "$SPEC_FILE" ]]; then
+    TEMPLATE="$REPO_ROOT/.specpro/templates/spec-template.md"
+    if [[ -f "$TEMPLATE" ]]; then
+        cp "$TEMPLATE" "$SPEC_FILE"
+        >&2 echo "[specify] Created initial specification: $SPEC_FILE"
+    else
+        touch "$SPEC_FILE"
+        >&2 echo "[specify] Created empty specification: $SPEC_FILE"
+    fi
+else
+    >&2 echo "[specify] Specification already exists: $SPEC_FILE"
+    >&2 echo "[specify] Use /specpro-specify with update intent to evolve the existing spec"
+fi
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi

specpro_cli/assets/scripts/bash/qc-auto-fix.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+#
+# QC write-back — the ONE write path for `/specpro-qc`
+#
+# Why this exists (T186 / ISS-143, settled 2026-09-19): these bodies used to live
+# inside `commands/specpro.qc.md` as bash fences. That put an EXECUTABLE
+# IMPLEMENTATION in a Markdown document, which the landing policy (`plan.md` ->
+# 落点政策 §1) forbids: only verifiers reach a script, and an implementation that
+# lives in prose can only be verified by EXTRACTING it — an extraction that
+# depends on the Markdown's shape and returns an empty string, silently, the
+# moment that shape changes. T164 verified its own guard exactly that way.
+#
+# ⚠️⚠️ **SCOPE NARROWED 2026-09-19 (`ISS-186` / `T220`) — two subcommands were
+# REMOVED, and their removal was a DECISION, not a cleanup.**
+#
+#   * `implementation-details` rewrote `spec.md` prose. Gone.
+#   * `require-owner` authorised repairing another command's artifact. Gone.
+#
+# **Why**: the 2026-09-19 ruling made `/specpro-qc` a checker that **does not repair**
+# (`FR-058`). Its write surface is exactly two artifacts — its own checklist, and the
+# ledger entries it routes. With no repair there is nothing for an authorisation guard
+# to guard, so the guard went with the path it protected.
+#
+# ⚠️ **What was tried first, and rejected** (`ISS-38` / `ISS-163` / `T203`): letting a
+# CALLER name the artifact it owned. The distinction was real — delegation does not
+# widen a write face, and the three callers were never equivalent (`specify` owns the
+# whole of `spec.md`; `plan` and `tasks` own only its Lifecycle fields). But it made a
+# boundary violation **declarable** rather than **impossible**, and a command that
+# repairs what it judged has spent the verdict (Principle III). **The ruling removed
+# the repair instead of licensing it.**
+#
+# ⚠️ **What the move must not lose.** `apply_fix` is still the ONE write-back path, and
+# its value is entirely in three guards that were added the hard way (T164):
+#
+#   1. **The destination is a REQUIRED argument.** A defaulted parameter once
+#      delivered the CHECKLIST's content into `spec.md` — observed: a 202-byte
+#      spec.md replaced by the 100-byte checklist template. An omitted target
+#      ABORTS; it does not guess.
+#   2. **A non-zero transformer status aborts** — the producer failed, so its
+#      buffer says nothing about the artifact.
+#   3. **An empty result aborts.** Every producer's output derives from an input
+#      it had to READ, so a zero-byte result means that read failed.
+#
+#   …and then exactly ONE `mv`. Two `mv`s would make "which write happened" a
+#   function of the path taken rather than of the code.
+#
+# Usage:
+#   scripts/bash/qc-auto-fix.sh apply-fix <tmp> <gen-status> <dest>
+# Exit:  0 = the write happened;  1 = aborted, nothing written
+#
+# ⚠️ NOT `set -e`: the guards below READ the exit status of the transformer they
+# were handed, and `set -e` would end the script before the reading happens
+# (宪法 2.2.2, second carve-out).
+#
+# ⚠️ **The FILENAME is now narrower than the file, and that was considered.** It is
+# kept deliberately: the PowerShell twin and the parity suite both address it by this
+# name, and a rename would be a second change riding along with a substantive one —
+# the exact shape this repository keeps finding. Recorded here so the next reader knows
+# the name was weighed rather than overlooked.
+
+set -uo pipefail
+
+usage() {
+    # ⚠️ The usage names the COMMAND, not this file: the twin prints the same text, and
+    # a usage line that spells its own filename makes the pair disagree on stderr for
+    # every invocation that reaches it (FR-008).
+    cat >&2 <<'USAGE'
+usage: qc-auto-fix apply-fix <tmp> <gen-status> <dest>
+USAGE
+}
+
+# =======================================================================================
+# apply_fix — the ONE write-back path
+# =======================================================================================
+apply_fix() {
+    local tmp=$1 gen_status=$2 target="${3:-}"
+
+    # ⚠️ Guarded BEFORE the destination test and with its own message: "no source" and
+    # "nowhere to write it" are different mistakes, and a shared message would send the
+    # reader to look at the argument they did pass.
+    if [ -z "$tmp" ]; then
+        echo "      ✗ fix aborted: no result to write — apply_fix needs a source" >&2
+        return 1
+    fi
+
+    if [ -z "$target" ]; then
+        echo "      ✗ fix aborted: no destination given — apply_fix does not guess" >&2
+        rm -f "$tmp"; return 1
+    fi
+
+    if [ "$gen_status" -ne 0 ]; then
+        echo "      ✗ fix aborted: the transformer exited $gen_status — $target left untouched" >&2
+        rm -f "$tmp"; return 1
+    fi
+
+    # An empty result is a failure, not a fix: every caller's output is derived
+    # from an input it had to READ, so a zero-byte result means that read failed.
+    if [ ! -s "$tmp" ]; then
+        echo "      ✗ fix aborted: the result is empty — $target left untouched" >&2
+        rm -f "$tmp"; return 1
+    fi
+
+    mv "$tmp" "$target"
+}
+
+# =======================================================================================
+
+# =======================================================================================
+# dispatch — one subcommand, and that is the whole surface now
+# =======================================================================================
+case "${1:-}" in
+    apply-fix)
+        shift
+        tmp=${1:-}; gen_status=${2:-0}; dest=${3:-}
+        if [ -z "$tmp" ]; then usage; exit 1; fi
+        apply_fix "$tmp" "$gen_status" "$dest"
+        ;;
+    *)
+        usage; exit 1
+        ;;
+esac

specpro_cli/assets/scripts/bash/setup-plan.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Ensure the specs directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specpro/templates/plan-template.md"
+if [[ -f "$IMPL_PLAN" ]]; then
+    echo "Using existing plan at $IMPL_PLAN"
+elif [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Created plan from template at $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+