forge-workflow 0.0.5 → 0.0.6

package/scripts/beads-context.sh

@@ -7,13 +7,18 @@
 #   set-acceptance   <issue-id> "<criteria-text>"
 #   update-progress  <issue-id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>
 #   parse-progress   <issue-id>
-#   stage-transition <issue-id> <completed-stage> <next-stage>
+#   stage-transition <issue-id> <completed-stage> <next-stage> [--summary "..."] [--decisions "..."] [--artifacts "..."] [--next "..."]
+#   validate         <issue-id>
 #
 # Cross-platform: works on Windows (Git Bash), macOS, and Linux.
 # OWASP A03: All variables properly quoted to prevent shell injection.
 
 set -euo pipefail
 
+# Source shared sanitize library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/sanitize.sh"
+
 # ── Helpers ──────────────────────────────────────────────────────────────
 
 usage() {
@@ -25,7 +30,8 @@ Subcommands:
   set-acceptance   <issue-id> "<criteria-text>"
   update-progress  <issue-id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>
   parse-progress   <issue-id>
-  stage-transition <issue-id> <completed-stage> <next-stage>
+  stage-transition <issue-id> <completed-stage> <next-stage> [--summary "..."] [--decisions "..."] [--artifacts "..."] [--next "..."]
+  validate         <issue-id>
 EOF
   exit 1
 }
@@ -35,24 +41,6 @@ die() {
   exit 1
 }
 
-# Sanitize a string: strip shell-injection patterns (OWASP A03)
-# Removes: double quotes, $(...), backticks, semicolons, and newlines
-sanitize() {
-  local val="$1"
-  # Remove double quotes
-  val="${val//\"/}"
-  # Remove $(...) command substitution patterns (loop handles nested)
-  # Use newline-separated commands for BSD sed compatibility (macOS)
-  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
-  # Remove backtick command substitution
-  val="${val//\`/}"
-  # Remove semicolons (command chaining)
-  val="${val//;/}"
-  # Replace newlines with spaces
-  val="$(printf '%s' "$val" | tr '\n' ' ')"
-  printf '%s' "$val"
-}
-
 # Run bd update and check for errors in both exit code and output.
 # bd update exits 0 even for non-existent issues, so we check stdout too.
 bd_update() {
@@ -250,7 +238,7 @@ cmd_parse_progress() {
 
 cmd_stage_transition() {
   if [[ $# -lt 3 ]]; then
-    echo "Usage: beads-context.sh stage-transition <issue-id> <completed-stage> <next-stage>" >&2
+    echo "Usage: beads-context.sh stage-transition <issue-id> <completed-stage> <next-stage> [--summary \"...\"] [--decisions \"...\"] [--artifacts \"...\"] [--next \"...\"]" >&2
     exit 1
   fi
 
@@ -259,9 +247,56 @@ cmd_stage_transition() {
   completed="$(sanitize "$2")"
   local next
   next="$(sanitize "$3")"
-
+  shift 3
+
+  # Parse optional flags
+  local flag_summary="" flag_decisions="" flag_artifacts="" flag_next=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --summary)
+        shift
+        flag_summary="$(sanitize "${1:-}")"
+        ;;
+      --decisions)
+        shift
+        flag_decisions="$(sanitize "${1:-}")"
+        ;;
+      --artifacts)
+        shift
+        flag_artifacts="$(sanitize "${1:-}")"
+        ;;
+      --next)
+        shift
+        flag_next="$(sanitize "${1:-}")"
+        ;;
+      *)
+        # Ignore unknown flags for forward compatibility
+        ;;
+    esac
+    shift
+  done
+
+  # Build comment: header line always present
   local comment="Stage: ${completed} complete → ready for ${next}"
 
+  # Append structured fields only if provided
+  if [[ -n "$flag_summary" ]]; then
+    comment="${comment}
+Summary: ${flag_summary}"
+  fi
+  if [[ -n "$flag_decisions" ]]; then
+    comment="${comment}
+Decisions: ${flag_decisions}"
+  fi
+  if [[ -n "$flag_artifacts" ]]; then
+    comment="${comment}
+Artifacts: ${flag_artifacts}"
+  fi
+  if [[ -n "$flag_next" ]]; then
+    comment="${comment}
+Next: ${flag_next}"
+  fi
+
   if ! bd_comment "$issue_id" "$comment" > /dev/null; then
     die "Failed to record stage transition on issue ${issue_id}"
   fi
@@ -269,6 +304,105 @@ cmd_stage_transition() {
   echo "Stage transition recorded on ${issue_id}: ${completed} → ${next}"
 }
 
+cmd_validate() {
+  if [[ $# -lt 1 ]]; then
+    echo "Usage: beads-context.sh validate <issue-id>" >&2
+    exit 1
+  fi
+
+  local issue_id="$1"
+  local warnings=0
+
+  # Get issue JSON
+  local json
+  json="$(bd show "$issue_id" --json 2>&1)" || {
+    echo "Error: Failed to retrieve issue ${issue_id}" >&2
+    exit 1
+  }
+
+  # Check for bd error patterns
+  if printf '%s' "$json" | grep -Eqi '^Error|Error resolving|Error fetching'; then
+    echo "Error: Issue not found: ${issue_id}" >&2
+    exit 1
+  fi
+
+  if [[ -z "$json" || "$json" == "[]" || "$json" == "null" ]]; then
+    echo "Error: Issue not found: ${issue_id}" >&2
+    exit 1
+  fi
+
+  # Extract fields — prefer jq, fall back to grep/sed
+  local description="" design=""
+  if command -v jq &>/dev/null; then
+    description="$(printf '%s' "$json" | jq -r 'if type == "array" then .[0].description else .description end // empty' 2>/dev/null || true)"
+    design="$(printf '%s' "$json" | jq -r 'if type == "array" then .[0].design else .design end // empty' 2>/dev/null || true)"
+  else
+    description="$(printf '%s' "$json" | grep -o '"description": *"[^"]*"' | head -1 | sed 's/^"description": *"//;s/"$//' || true)"
+    design="$(printf '%s' "$json" | grep -o '"design": *"[^"]*"' | head -1 | sed 's/^"design": *"//;s/"$//' || true)"
+  fi
+
+  # Check 1: Issue has description
+  if [[ -z "$description" ]]; then
+    echo "Warning: Issue ${issue_id} has no description"
+    warnings=$((warnings + 1))
+  fi
+
+  # Get comments to check for stage transitions
+  local comments
+  comments="$(bd comments list "$issue_id" 2>/dev/null || true)"
+
+  # Check 2: At least one stage transition exists
+  local has_transition=false
+  if echo "$comments" | grep -q 'Stage:.*complete'; then
+    has_transition=true
+  fi
+
+  if [[ "$has_transition" == "false" ]]; then
+    echo "Warning: No stage transition found on issue ${issue_id}"
+    warnings=$((warnings + 1))
+  fi
+
+  # Check 3: Most recent transition has summary
+  # Isolate the last transition block to avoid false-positives from earlier summaries
+  if [[ "$has_transition" == "true" ]]; then
+    local has_summary=false
+    local last_block
+    last_block="$(echo "$comments" | awk '/Stage:.*complete/{found=1; block=""} found{block=block"\n"$0} END{print block}')"
+    if echo "$last_block" | grep -q 'Summary:'; then
+      has_summary=true
+    fi
+    if [[ "$has_summary" == "false" ]]; then
+      echo "Warning: Most recent stage transition has no summary on issue ${issue_id}"
+      warnings=$((warnings + 1))
+    fi
+  fi
+
+  # Check 4: Design metadata is set if past plan stage
+  # "Past plan" means there's a transition FROM plan or any later stage
+  local past_plan=false
+  if echo "$comments" | grep -q 'Stage: plan complete'; then
+    past_plan=true
+  fi
+  if echo "$comments" | grep -Eq 'Stage: (dev|validate|ship|review|premerge) complete'; then
+    past_plan=true
+  fi
+
+  if [[ "$past_plan" == "true" && -z "$design" ]]; then
+    echo "Warning: Design metadata not set on issue ${issue_id} (past plan stage)"
+    warnings=$((warnings + 1))
+  fi
+
+  # Summary
+  if [[ $warnings -eq 0 ]]; then
+    echo "All context fields present on issue ${issue_id}"
+  else
+    echo "${warnings} warning(s) found on issue ${issue_id}"
+  fi
+
+  # Always exit 0 — advisory only
+  exit 0
+}
+
 # ── Main dispatcher ──────────────────────────────────────────────────────
 
 if [[ $# -lt 1 ]]; then
@@ -284,6 +418,7 @@ case "$subcommand" in
   update-progress)  cmd_update_progress "$@" ;;
   parse-progress)   cmd_parse_progress "$@" ;;
   stage-transition) cmd_stage_transition "$@" ;;
+  validate)         cmd_validate "$@" ;;
   *)
     echo "Error: Unknown subcommand '${subcommand}'" >&2
     usage

package/scripts/beads-context.test.js

@@ -8,10 +8,14 @@ const { resolveBashCommand } = require('../test/helpers/bash.js');
 const SCRIPT_PATH = path.join(__dirname, 'beads-context.sh');
 const WORKTREE_ROOT = path.resolve(__dirname, '..');
 
-// Check if bd CLI is available (not installed in CI)
+// Check if bd CLI is available AND Dolt database is reachable (not just binary exists).
+// Prevents tests from hanging when Dolt is dead. BD_TIMEOUT env var overrides default.
 function isBdAvailable() {
 	try {
 		execFileSync('bd', ['--version'], { stdio: 'ignore' });
+		// Also verify Dolt database is reachable (not just binary exists)
+		const timeout = parseInt(process.env.BD_TIMEOUT || '3000', 10);
+		execFileSync('bd', ['list', '--limit=1'], { stdio: 'ignore', timeout });
 		return true;
 	} catch {
 		return false;

package/scripts/check-forge-token.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const path = require('node:path');
+
+const TOKEN_FILENAME = '.forge-push-token';
+const MAX_AGE_MS = 30000; // 30 seconds
+
+/**
+ * Get the absolute path to the token file.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string} Token file path
+ */
+function tokenPath(projectRoot) {
+  return path.join(projectRoot, TOKEN_FILENAME);
+}
+
+/**
+ * Write a one-time nonce token to disk.
+ * Called by `forge push` right before `git push` so lefthook hooks
+ * can detect that checks already passed and skip re-running them.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{nonce: string, timestamp: number}} The written token data
+ */
+function write(projectRoot) {
+  const data = {
+    nonce: crypto.randomUUID(),
+    timestamp: Date.now(),
+  };
+  fs.writeFileSync(tokenPath(projectRoot), JSON.stringify(data), 'utf-8');
+  return data;
+}
+
+/**
+ * Check if a valid (fresh, well-formed) forge push token exists.
+ * Does NOT delete the token — use `consume()` for one-time validation.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if a valid, fresh token exists
+ */
+function isValid(projectRoot) {
+  try {
+    const raw = fs.readFileSync(tokenPath(projectRoot), 'utf-8');
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Validate and delete the token in one atomic operation (one-time use).
+ * Always attempts to delete the file, even if the token is stale or invalid.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if the token was valid before deletion
+ */
+function consume(projectRoot) {
+  const tp = tokenPath(projectRoot);
+  try {
+    const raw = fs.readFileSync(tp, 'utf-8');
+    // Always delete after reading — whether valid or not
+    try { fs.unlinkSync(tp); } catch (_e) { /* already gone */ }
+
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    // File doesn't exist or isn't readable — try cleanup anyway
+    try { fs.unlinkSync(tp); } catch (_e) { /* nothing to clean */ }
+    return false;
+  }
+}
+
+module.exports = { write, isValid, consume };
+
+// When run directly as a script (e.g., from lefthook skip check):
+// Exit 0 = token valid (skip hooks), Exit 1 = run hooks normally.
+// Uses isValid() (non-destructive) so multiple lefthook commands can
+// each check the same token. The token expires after 30s automatically.
+if (require.main === module) {
+  const projectRoot = process.cwd();
+  if (isValid(projectRoot)) {
+    console.log('forge push token valid — skipping pre-push hooks');
+    process.exit(0);
+  }
+  process.exit(1);
+}

package/scripts/conflict-detect.sh

@@ -19,12 +19,12 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source file-index helpers (file_index_read, file_index_get)
-source "$SCRIPT_DIR/file-index.sh"
+source "$SCRIPT_DIR/file-index.sh" || { echo "FATAL: failed to source file-index.sh" >&2; exit 2; }
 
 # Source sync-utils (get_session_identity, sanitize_config_value)
 # Only source if available (tests may not need all utils)
 if [[ -f "$SCRIPT_DIR/sync-utils.sh" ]]; then
-  source "$SCRIPT_DIR/sync-utils.sh"
+  source "$SCRIPT_DIR/sync-utils.sh" || { echo "FATAL: failed to source sync-utils.sh" >&2; exit 2; }
 fi
 
 # ── Input Validation ─────────────────────────────────────────────────────

package/scripts/dep-guard.sh

@@ -12,6 +12,10 @@
 
 set -euo pipefail
 
+# Source shared sanitize library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/sanitize.sh"
+
 # ── Helpers ──────────────────────────────────────────────────────────────
 
 usage() {
@@ -64,24 +68,6 @@ rollback_and_die() {
   die "$message"
 }
 
-# Sanitize a string: strip shell-injection patterns (OWASP A03)
-# Removes: double quotes, $(...), backticks, semicolons, and newlines
-sanitize() {
-  local val="$1"
-  # Remove double quotes
-  val="${val//\"/}"
-  # Remove $(...) command substitution patterns (loop handles nested)
-  # Use newline-separated commands for BSD sed compatibility (macOS)
-  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
-  # Remove backtick command substitution
-  val="${val//\`/}"
-  # Remove semicolons (command chaining)
-  val="${val//;/}"
-  # Replace newlines with spaces
-  val="$(printf '%s' "$val" | tr '\n' ' ')"
-  printf '%s' "$val"
-}
-
 # Run bd update and check for errors in both exit code and output.
 # bd update exits 0 even for non-existent issues, so we check stdout too.
 bd_update() {
@@ -628,17 +614,9 @@ cmd_apply_decision() {
     die "Failed to add dependency ${dependent_issue} -> ${depends_on_issue}"
   }
 
-  local cycles_output
-  cycles_output="$(${BD_CMD:-bd} dep cycles 2>&1)" || {
-    rollback_dependency "$dependent_issue" "$depends_on_issue"
-    echo "$cycles_output" >&2
-    die "Failed to validate dependency cycles"
-  }
-
-  if printf '%s' "$cycles_output" | grep -Eqi 'cycle' \
-    && ! cycles_output_is_safe "$cycles_output"; then
+  # Check for cycles — use exit code as primary signal
+  if ! ${BD_CMD:-bd} dep cycles &>/dev/null; then
     rollback_dependency "$dependent_issue" "$depends_on_issue"
-    echo "$cycles_output" >&2
     die "Cycle detected for ${dependent_issue} -> ${depends_on_issue}"
   fi
 

package/scripts/file-index.sh

@@ -19,6 +19,13 @@ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
   set -euo pipefail
 fi
 
+# Source shared libraries
+_FI_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$_FI_SCRIPT_DIR/lib/sanitize.sh"
+if [[ -f "$_FI_SCRIPT_DIR/lib/jsonl-lock.sh" ]]; then
+  source "$_FI_SCRIPT_DIR/lib/jsonl-lock.sh"
+fi
+
 # ── Helpers ──────────────────────────────────────────────────────────────
 
 # Resolve the JSONL file path.
@@ -28,24 +35,6 @@ _file_index_path() {
   printf '%s' "$root/.beads/file-index.jsonl"
 }
 
-# Sanitize a string: strip shell-injection patterns (OWASP A03)
-# Reused from dep-guard.sh pattern.
-# Removes: double quotes, $(...), backticks, semicolons, and newlines
-sanitize() {
-  local val="$1"
-  # Remove double quotes
-  val="${val//\"/}"
-  # Remove $(...) command substitution patterns (loop handles nested)
-  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
-  # Remove backtick command substitution
-  val="${val//\`/}"
-  # Remove semicolons (command chaining)
-  val="${val//;/}"
-  # Replace newlines with spaces
-  val="$(printf '%s' "$val" | tr '\n' ' ')"
-  printf '%s' "$val"
-}
-
 # Validate issue_id: alphanumeric + hyphens only
 _validate_issue_id() {
   local id="$1"
@@ -127,7 +116,11 @@ file_index_add() {
   # Ensure parent directory exists
   mkdir -p "$(dirname "$jsonl_path")"
 
-  printf '%s\n' "$json_line" >> "$jsonl_path"
+  if command -v atomic_jsonl_append &>/dev/null; then
+    atomic_jsonl_append "$jsonl_path" "$json_line"
+  else
+    printf '%s\n' "$json_line" >> "$jsonl_path"
+  fi
 }
 
 # file_index_remove <issue_id>
@@ -163,7 +156,11 @@ file_index_remove() {
   local jsonl_path
   jsonl_path="$(_file_index_path)"
   mkdir -p "$(dirname "$jsonl_path")"
-  printf '%s\n' "$json_line" >> "$jsonl_path"
+  if command -v atomic_jsonl_append &>/dev/null; then
+    atomic_jsonl_append "$jsonl_path" "$json_line"
+  else
+    printf '%s\n' "$json_line" >> "$jsonl_path"
+  fi
 }
 
 # file_index_read
@@ -320,12 +317,28 @@ file_index_update_from_tasks() {
   # Build deduplicated JSON arrays using jq (no associative arrays needed)
   local files_json modules_json
   if [[ -n "$sanitized_paths" ]]; then
-    files_json="$(printf '%s' "$sanitized_paths" | grep -v '^$' | jq -R . | jq -s -c 'unique')"
+    # Save and restore pipefail state to avoid side effects
+    local _prev_pipefail
+    _prev_pipefail="$(set +o | grep pipefail)" || true
+    set -o pipefail
+
+    files_json="$(printf '%s' "$sanitized_paths" | grep -v '^$' | jq -R . | jq -s -c 'unique')" || {
+      eval "$_prev_pipefail"
+      echo "Error: failed to build files JSON array" >&2
+      return 1
+    }
     modules_json="$(printf '%s' "$sanitized_paths" | grep -v '^$' | while IFS= read -r p; do
       local d
       d="$(dirname "$p")"
       if [[ "$d" == "." ]]; then printf '%s\n' "./"; else printf '%s\n' "${d}/"; fi
-    done | jq -R . | jq -s -c 'unique')"
+    done | jq -R . | jq -s -c 'unique')" || {
+      eval "$_prev_pipefail"
+      echo "Error: failed to build modules JSON array" >&2
+      return 1
+    }
+
+    # Restore pipefail state
+    eval "$_prev_pipefail"
   else
     files_json="[]"
     modules_json="[]"
@@ -358,13 +371,92 @@ file_index_update_from_tasks() {
         tombstone: false,
         confidence: $conf
       }')"
-    printf '%s\n' "$json_line" >> "$jsonl_path"
+    if command -v atomic_jsonl_append &>/dev/null; then
+      atomic_jsonl_append "$jsonl_path" "$json_line"
+    else
+      printf '%s\n' "$json_line" >> "$jsonl_path"
+    fi
   else
     # Normal entry via file_index_add (no confidence field needed)
     file_index_add "$issue_id" "$developer" "$files_json" "$modules_json"
   fi
 }
 
+# file_index_auto_update <issue_id> [--from-git]
+# Update the file index with the current set of changed files.
+# Files come from: --from-git flag (git diff HEAD~1) or stdin.
+file_index_auto_update() {
+  local raw_issue_id="$1"
+  shift
+  local from_git=0
+
+  # Parse flags
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --from-git) from_git=1; shift ;;
+      *) echo "Error: unknown flag '$1'" >&2; return 1 ;;
+    esac
+  done
+
+  # Sanitize and validate issue_id
+  local issue_id
+  issue_id="$(sanitize "$raw_issue_id")"
+  issue_id="$(printf '%s' "$issue_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  _validate_issue_id "$issue_id" || return 1
+
+  # Get file list
+  local -a files=()
+  if [[ "$from_git" -eq 1 ]]; then
+    while IFS= read -r f; do
+      [[ -n "$f" ]] && files+=("$f")
+    done < <(git diff --name-only HEAD~1 2>/dev/null || true)
+  else
+    # Read from stdin (non-blocking check)
+    if [[ ! -t 0 ]]; then
+      while IFS= read -r f; do
+        [[ -n "$f" ]] && files+=("$f")
+      done
+    else
+      echo "Error: no file list provided (use --from-git or pipe files via stdin)" >&2
+      return 1
+    fi
+  fi
+
+  # Empty file list = nothing to do
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "No files changed"
+    return 0
+  fi
+
+  # Get session identity
+  local developer
+  if ! command -v get_session_identity &>/dev/null; then
+    local script_dir
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    if [[ -f "$script_dir/sync-utils.sh" ]]; then
+      source "$script_dir/sync-utils.sh"
+    fi
+  fi
+  developer="$(get_session_identity)" || {
+    echo "Error: could not determine session identity" >&2
+    return 1
+  }
+
+  # Build JSON arrays using jq
+  local files_json modules_json
+  files_json="$(printf '%s\n' "${files[@]}" | jq -R . | jq -s -c 'unique')"
+  modules_json="$(printf '%s\n' "${files[@]}" | while IFS= read -r p; do
+    local d
+    d="$(dirname "$p")"
+    if [[ "$d" == "." ]]; then printf '%s\n' "./"; else printf '%s\n' "${d}/"; fi
+  done | jq -R . | jq -s -c 'unique')"
+
+  # Append via file_index_add (which uses atomic locking)
+  file_index_add "$issue_id" "$developer" "$files_json" "$modules_json"
+
+  echo "File index updated for $issue_id (${#files[@]} files)"
+}
+
 # ── Main dispatcher (when run as a script) ────────────────────────────────
 
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
@@ -378,6 +470,7 @@ Subcommands:
   read
   get              <issue_id>
   update-from-tasks <issue_id> <task_file_path> [action]
+  auto-update      <issue_id> [--from-git]
 EOF
     exit 1
   fi
@@ -391,6 +484,7 @@ EOF
     read)              file_index_read ;;
     get)               file_index_get "$@" ;;
     update-from-tasks) file_index_update_from_tasks "$@" ;;
+    auto-update)       file_index_auto_update "$@" ;;
     *)
       echo "Error: Unknown subcommand '${subcommand}'" >&2
       exit 1