Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

fix(scripts): harden bash scripts β€” escape, compat, and error handling (#1869)

Pierluigi Lenoci9c0c1446ecc7
diff --git a/scripts/bash/check-prerequisites.sh b/scripts/bash/check-prerequisites.sh
index 6f7c99e03..88a555946 100644
--- a/scripts/bash/check-prerequisites.sh
+++ b/scripts/bash/check-prerequisites.sh
@@ -168,7 +168,7 @@ if $JSON_MODE; then
if [[ ${#docs[@]} -eq 0 ]]; then
json_docs="[]"
else
- json_docs=$(printf '"%s",' "${docs[@]}")
+ json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
json_docs="[${json_docs%,}]"
fi
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
index 52e363e6d..826e740f0 100644
--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -161,7 +161,7 @@ has_jq() {
}
# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
-# Handles backslash, double-quote, and control characters (newline, tab, carriage return).
+# Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
json_escape() {
local s="$1"
s="${s//\\/\\\\}"
@@ -169,6 +169,10 @@ json_escape() {
s="${s//$'\n'/\\n}"
s="${s//$'\t'/\\t}"
s="${s//$'\r'/\\r}"
+ s="${s//$'\b'/\\b}"
+ s="${s//$'\f'/\\f}"
+ # Strip remaining control characters (U+0000–U+001F) not individually escaped above
+ s=$(printf '%s' "$s" | tr -d '\000-\007\013\016-\037')
printf '%s' "$s"
}
@@ -194,9 +198,11 @@ resolve_template() {
if [ -d "$presets_dir" ]; then
local registry_file="$presets_dir/.registry"
if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
- # Read preset IDs sorted by priority (lower number = higher precedence)
- local sorted_presets
- sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+ # Read preset IDs sorted by priority (lower number = higher precedence).
+ # The python3 call is wrapped in an if-condition so that set -e does not
+ # abort the function when python3 exits non-zero (e.g. invalid JSON).
+ local sorted_presets=""
+ if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
import json, sys, os
try:
with open(os.environ['SPECKIT_REGISTRY']) as f:
@@ -206,14 +212,17 @@ try:
print(pid)
except Exception:
sys.exit(1)
-" 2>/dev/null)
- if [ $? -eq 0 ] && [ -n "$sorted_presets" ]; then
- while IFS= read -r preset_id; do
- local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
- [ -f "$candidate" ] && echo "$candidate" && return 0
- done <<< "$sorted_presets"
+" 2>/dev/null); then
+ if [ -n "$sorted_presets" ]; then
+ # python3 succeeded and returned preset IDs β€” search in priority order
+ while IFS= read -r preset_id; do
+ local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+ [ -f "$candidate" ] && echo "$candidate" && return 0
+ done <<< "$sorted_presets"
+ fi
+ # python3 succeeded but registry has no presets β€” nothing to search
else
- # python3 returned empty list β€” fall through to directory scan
+ # python3 failed (missing, or registry parse error) β€” fall back to unordered directory scan
for preset in "$presets_dir"/*/; do
[ -d "$preset" ] || continue
local candidate="$preset/templates/${template_name}.md"
@@ -246,8 +255,9 @@ except Exception:
local core="$base/${template_name}.md"
[ -f "$core" ] && echo "$core" && return 0
- # Return success with empty output so callers using set -e don't abort;
- # callers check [ -n "$TEMPLATE" ] to detect "not found".
- return 0
+ # Template not found in any location.
+ # Return 1 so callers can distinguish "not found" from "found".
+ # Callers running under set -e should use: TEMPLATE=$(resolve_template ...) || true
+ return 1
}
diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh
index 0823cca27..f7f59884a 100644
--- a/scripts/bash/create-new-feature.sh
+++ b/scripts/bash/create-new-feature.sh
@@ -162,17 +162,6 @@ clean_branch_name() {
echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
}
-# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
-json_escape() {
- local s="$1"
- s="${s//\\/\\\\}"
- s="${s//\"/\\\"}"
- s="${s//$'\n'/\\n}"
- s="${s//$'\t'/\\t}"
- s="${s//$'\r'/\\r}"
- printf '%s' "$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.
@@ -308,9 +297,14 @@ fi
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
mkdir -p "$FEATURE_DIR"
-TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT")
+TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+ cp "$TEMPLATE" "$SPEC_FILE"
+else
+ echo "Warning: Spec template not found; created empty spec file" >&2
+ touch "$SPEC_FILE"
+fi
# Inform the user how to persist the feature variable in their own shell
printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.sh
index 2a044c679..9f5523149 100644
--- a/scripts/bash/setup-plan.sh
+++ b/scripts/bash/setup-plan.sh
@@ -39,7 +39,7 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
mkdir -p "$FEATURE_DIR"
# Copy plan template if it exists
-TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT")
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
cp "$TEMPLATE" "$IMPL_PLAN"
echo "Copied plan template to $IMPL_PLAN"
diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh
index e0f285484..b4b901fb1 100644
--- a/scripts/bash/update-agent-context.sh
+++ b/scripts/bash/update-agent-context.sh
@@ -686,56 +686,67 @@ update_specific_agent() {
esac
}
-update_all_existing_agents() {
- local found_agent=false
- local _updated_paths=()
-
- # Helper: skip non-existent files and files already updated (dedup by
- # realpath so that variables pointing to the same file β€” e.g. AMP_FILE,
- # KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE β€” are only written once).
- # Uses a linear array instead of associative array for bash 3.2 compatibility.
- update_if_new() {
- local file="$1" name="$2"
- [[ -f "$file" ]] || return 0
- local real_path
- real_path=$(realpath "$file" 2>/dev/null || echo "$file")
- local p
- if [[ ${#_updated_paths[@]} -gt 0 ]]; then
- for p in "${_updated_paths[@]}"; do
- [[ "$p" == "$real_path" ]] && return 0
- done
- fi
- update_agent_file "$file" "$name" || return 1
- _updated_paths+=("$real_path")
- found_agent=true
- }
+# Helper: skip non-existent files and files already updated (dedup by
+# realpath so that variables pointing to the same file β€” e.g. AMP_FILE,
+# KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE β€” are only written once).
+# Uses a linear array instead of associative array for bash 3.2 compatibility.
+# Note: defined at top level because bash 3.2 does not support true
+# nested/local functions. _updated_paths, _found_agent, and _all_ok are
+# initialised exclusively inside update_all_existing_agents so that
+# sourcing this script has no side effects on the caller's environment.
+
+_update_if_new() {
+ local file="$1" name="$2"
+ [[ -f "$file" ]] || return 0
+ local real_path
+ real_path=$(realpath "$file" 2>/dev/null || echo "$file")
+ local p
+ if [[ ${#_updated_paths[@]} -gt 0 ]]; then
+ for p in "${_updated_paths[@]}"; do
+ [[ "$p" == "$real_path" ]] && return 0
+ done
+ fi
+ # Record the file as seen before attempting the update so that:
+ # (a) aliases pointing to the same path are not retried on failure
+ # (b) _found_agent reflects file existence, not update success
+ _updated_paths+=("$real_path")
+ _found_agent=true
+ update_agent_file "$file" "$name"
+}
- update_if_new "$CLAUDE_FILE" "Claude Code"
- update_if_new "$GEMINI_FILE" "Gemini CLI"
- update_if_new "$COPILOT_FILE" "GitHub Copilot"
- update_if_new "$CURSOR_FILE" "Cursor IDE"
- update_if_new "$QWEN_FILE" "Qwen Code"
- update_if_new "$AGENTS_FILE" "Codex/opencode"
- update_if_new "$AMP_FILE" "Amp"
- update_if_new "$KIRO_FILE" "Kiro CLI"
- update_if_new "$BOB_FILE" "IBM Bob"
- update_if_new "$WINDSURF_FILE" "Windsurf"
- update_if_new "$KILOCODE_FILE" "Kilo Code"
- update_if_new "$AUGGIE_FILE" "Auggie CLI"
- update_if_new "$ROO_FILE" "Roo Code"
- update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI"
- update_if_new "$SHAI_FILE" "SHAI"
- update_if_new "$TABNINE_FILE" "Tabnine CLI"
- update_if_new "$QODER_FILE" "Qoder CLI"
- update_if_new "$AGY_FILE" "Antigravity"
- update_if_new "$VIBE_FILE" "Mistral Vibe"
- update_if_new "$KIMI_FILE" "Kimi Code"
+update_all_existing_agents() {
+ _found_agent=false
+ _updated_paths=()
+ local _all_ok=true
+
+ _update_if_new "$CLAUDE_FILE" "Claude Code" || _all_ok=false
+ _update_if_new "$GEMINI_FILE" "Gemini CLI" || _all_ok=false
+ _update_if_new "$COPILOT_FILE" "GitHub Copilot" || _all_ok=false
+ _update_if_new "$CURSOR_FILE" "Cursor IDE" || _all_ok=false
+ _update_if_new "$QWEN_FILE" "Qwen Code" || _all_ok=false
+ _update_if_new "$AGENTS_FILE" "Codex/opencode" || _all_ok=false
+ _update_if_new "$AMP_FILE" "Amp" || _all_ok=false
+ _update_if_new "$KIRO_FILE" "Kiro CLI" || _all_ok=false
+ _update_if_new "$BOB_FILE" "IBM Bob" || _all_ok=false
+ _update_if_new "$WINDSURF_FILE" "Windsurf" || _all_ok=false
+ _update_if_new "$KILOCODE_FILE" "Kilo Code" || _all_ok=false
+ _update_if_new "$AUGGIE_FILE" "Auggie CLI" || _all_ok=false
+ _update_if_new "$ROO_FILE" "Roo Code" || _all_ok=false
+ _update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI" || _all_ok=false
+ _update_if_new "$SHAI_FILE" "SHAI" || _all_ok=false
+ _update_if_new "$TABNINE_FILE" "Tabnine CLI" || _all_ok=false
+ _update_if_new "$QODER_FILE" "Qoder CLI" || _all_ok=false
+ _update_if_new "$AGY_FILE" "Antigravity" || _all_ok=false
+ _update_if_new "$VIBE_FILE" "Mistral Vibe" || _all_ok=false
+ _update_if_new "$KIMI_FILE" "Kimi Code" || _all_ok=false
# If no agent files exist, create a default Claude file
- if [[ "$found_agent" == false ]]; then
+ if [[ "$_found_agent" == false ]]; then
log_info "No existing agent files found, creating default Claude file..."
update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
fi
+
+ [[ "$_all_ok" == true ]]
}
print_summary() {
echo