pi-usereq 0.4.0

package/scripts/pi-usereq-debug.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+# @file
+# @brief Provides a bash wrapper for the standalone extension debug harness.
+# @details Resolves repository-local execution paths, preserves the caller working directory as the default debug target, exposes convenience subcommands for registration inspection plus prompt and tool replay, resolves a repository-visible `tsx` runner, materializes a shared `node_modules` symlink for worktrees when required, converts tool `--args` text into `--params` JSON when requested, and delegates execution to `scripts/debug-extension.ts`. Runtime is O(n) in CLI argument count plus delegated harness cost. Side effects include spawning Node subprocesses and temporarily changing the wrapper subshell cwd to the repository root.
+
+set -euo pipefail
+
+# @brief Resolves the absolute directory containing `pi-usereq-debug.sh`.
+# @details Uses `BASH_SOURCE[0]` so invocation through relative paths or symlinks still anchors repository-relative lookups. Runtime is O(p) in path length. No filesystem mutation occurs.
+readonly SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+
+# @brief Resolves the repository root that owns the debug wrapper.
+# @details Moves one level above `SCRIPT_DIR` so delegated Node execution can load the repository-local `tsx` dependency and extension entry. Runtime is O(p) in path length. No filesystem mutation occurs.
+readonly REPO_ROOT="$(CDPATH= cd -- "${SCRIPT_DIR}/.." && pwd)"
+
+# @brief Stores the default extension entry path used by the wrapper.
+# @details Binds all convenience subcommands to the repository's `src/index.ts` entry unless the caller provides a later `--extension` override. Runtime is O(1). No filesystem mutation occurs.
+readonly DEFAULT_EXTENSION="${REPO_ROOT}/src/index.ts"
+
+# @brief Stores the caller working directory used as the default debug cwd.
+# @details Captures the shell cwd before the wrapper enters the repository root so replayed commands and tools observe the caller-selected project context. Runtime is O(1). No filesystem mutation occurs.
+readonly CALLER_CWD="${PWD}"
+
+# @brief Resolves the `tsx` executable visible to the wrapper.
+# @details Searches the active repository install first, then the shared git-common checkout used by worktrees, and finally the process `PATH`. When a shared checkout provides `node_modules`, the function links that directory into the worktree before returning the executable path. Runtime is O(1) plus one git subprocess. Side effects may include creating `REPO_ROOT/node_modules` as a symlink.
+# @return {string} Absolute or PATH-resolved `tsx` executable path.
+# @throws {shell-error} Returns non-zero when no usable `tsx` executable is available.
+resolve_tsx_binary() {
+  local local_tsx="${REPO_ROOT}/node_modules/.bin/tsx"
+  if [[ -x "${local_tsx}" ]]; then
+    printf '%s\n' "${local_tsx}"
+    return 0
+  fi
+
+  local git_common_dir=""
+  git_common_dir="$(git -C "${REPO_ROOT}" rev-parse --git-common-dir 2>/dev/null || true)"
+  if [[ -n "${git_common_dir}" ]]; then
+    local shared_root
+    local shared_tsx
+    shared_root="$(CDPATH= cd -- "${git_common_dir}/.." && pwd)"
+    shared_tsx="${shared_root}/node_modules/.bin/tsx"
+    if [[ -x "${shared_tsx}" ]]; then
+      if [[ ! -e "${REPO_ROOT}/node_modules" && ! -L "${REPO_ROOT}/node_modules" ]]; then
+        ln -s "${shared_root}/node_modules" "${REPO_ROOT}/node_modules"
+      fi
+      printf '%s\n' "${shared_tsx}"
+      return 0
+    fi
+  fi
+
+  if command -v tsx >/dev/null 2>&1; then
+    command -v tsx
+    return 0
+  fi
+
+  printf 'Error: tsx executable not found in repository or PATH.\n' >&2
+  return 1
+}
+
+# @brief Stores the resolved `tsx` executable path.
+# @details Captures the executable once during wrapper startup so later dispatch paths do not repeat repository lookup logic. Runtime is dominated by `resolve_tsx_binary()`. Side effects may include creating a worktree-local `node_modules` symlink.
+readonly TSX_BIN="$(resolve_tsx_binary)"
+
+# @brief Prints the wrapper usage contract.
+# @details Emits subcommand semantics, override rules, and concrete examples covering registrations, session replay, prompt replay, tool replay, and raw pass-through. Runtime is O(1). Side effect: writes to stdout.
+# @return {void} No return value.
+# @satisfies REQ-061, REQ-062, REQ-065
+print_usage() {
+  cat <<EOF
+Usage: ./scripts/pi-usereq-debug.sh <subcommand> [options]
+
+Subcommands:
+  inspect [debug-extension options...]
+      Inspect command, tool, and event registrations.
+  session [debug-extension options...]
+      Replay session_start handlers via session-start.
+  command <name> [--args <text> | debug-extension options...]
+      Replay one registered command.
+  prompt <name> [--args <text> | debug-extension options...]
+      Replay one req-* prompt command; bare names are auto-prefixed.
+  tool <name> [--args <text> | --params <json> | debug-extension options...]
+      Replay one registered tool; defaults params to {}.
+  sdk [debug-extension options...]
+      Run sdk-smoke parity inspection.
+  raw <debug-extension arguments...>
+      Forward arguments directly to scripts/debug-extension.ts.
+  help
+      Show this usage text.
+
+Default forwarding:
+  - Adds --cwd "${CALLER_CWD}" before forwarded arguments.
+  - Adds --extension "${DEFAULT_EXTENSION}" before forwarded arguments.
+  - Later --cwd or --extension arguments override the defaults.
+
+Examples:
+  ./scripts/pi-usereq-debug.sh inspect --format pretty
+  ./scripts/pi-usereq-debug.sh session --format json
+  ./scripts/pi-usereq-debug.sh prompt analyze --args "Inspect prompt rendering"
+  ./scripts/pi-usereq-debug.sh tool files-find --args 'FUNCTION ^run src/index.ts --enable-line-numbers'
+  ./scripts/pi-usereq-debug.sh raw command --name req-analyze --args "Review REQ-004"
+EOF
+}
+
+# @brief Tests whether one exact option token is present in an argument list.
+# @details Performs a linear scan over forwarded tokens and returns success when any token equals the requested option string. Runtime is O(n) in argument count. No external state is mutated.
+# @param[in] needle {string} Exact option token to match.
+# @param[in] ... {string[]} Forwarded CLI tokens.
+# @return {int} Shell status `0` when the option exists; `1` otherwise.
+contains_exact_option() {
+  local needle="$1"
+  shift
+  local token
+  for token in "$@"; do
+    if [[ "${token}" == "${needle}" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# @brief Tests whether an argument list already contains any long option token.
+# @details Detects tokens beginning with `--` so the wrapper can avoid inferring positional payloads when the caller is already using the underlying debug-harness option grammar. Runtime is O(n) in argument count. No external state is mutated.
+# @param[in] ... {string[]} Forwarded CLI tokens.
+# @return {int} Shell status `0` when a long option exists; `1` otherwise.
+contains_long_option() {
+  local token
+  for token in "$@"; do
+    if [[ "${token}" == --* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# @brief Normalizes prompt aliases to registered `req-*` command names.
+# @details Returns the input unchanged when it already begins with `req-`; otherwise prepends the prefix required by extension registration. Runtime is O(p) in prompt-name length. No external state is mutated.
+# @param[in] prompt_name {string} Prompt command alias supplied by the caller.
+# @return {string} Registered prompt command name.
+# @satisfies REQ-062
+normalize_prompt_name() {
+  local prompt_name="$1"
+  if [[ "${prompt_name}" == req-* ]]; then
+    printf '%s\n' "${prompt_name}"
+    return 0
+  fi
+  printf 'req-%s\n' "${prompt_name}"
+}
+
+# @brief Executes `scripts/debug-extension.ts` with wrapper defaults.
+# @details Enters the repository root so the resolved `tsx` dependency and shared `node_modules` tree remain visible, prepends default `--cwd` and `--extension` values, and forwards all remaining arguments unchanged so later overrides win. Runtime is dominated by the delegated Node process. Side effects include spawning one subprocess.
+# @param[in] ... {string[]} Debug-harness CLI tokens beginning with the target subcommand.
+# @return {int} Exit status produced by the delegated Node process.
+# @satisfies REQ-060, REQ-062
+run_debug_extension() {
+  (
+    cd -- "${REPO_ROOT}"
+    "${TSX_BIN}" ./scripts/debug-extension.ts --cwd "${CALLER_CWD}" --extension "${DEFAULT_EXTENSION}" "$@"
+  )
+}
+
+# @brief Converts wrapper tool `--args` text into a JSON `--params` payload.
+# @details Executes the repository-local TypeScript converter so shell callers can reuse the same structured tool-parameter mapping as the debug interface without hand-writing JSON. Runtime is dominated by the helper subprocess. Side effects include spawning one subprocess.
+# @param[in] tool_name {string} Registered tool name.
+# @param[in] args_text {string} Raw wrapper `--args` payload.
+# @return {string} JSON object serialized on stdout.
+# @satisfies REQ-065
+build_tool_params_json() {
+  local tool_name="$1"
+  local args_text="${2-}"
+  (
+    cd -- "${REPO_ROOT}"
+    "${TSX_BIN}" ./scripts/tool-args-to-params.ts --name "${tool_name}" --args "${args_text}"
+  )
+}
+
+# @brief Replays one tool subcommand with wrapper-level `--args` normalization.
+# @details Preserves direct `--params` passthrough, rewrites wrapper `--args` values into JSON `--params` payloads, forwards unrelated debug-harness options unchanged, and keeps the legacy single-positional-JSON shortcut. Runtime is O(n) in forwarded argument count plus delegated subprocess cost. Side effects include stdout/stderr writes and subprocess execution.
+# @param[in] tool_name {string} Registered tool name.
+# @param[in] ... {string[]} Forwarded wrapper tokens after the tool name.
+# @return {int} Exit status propagated from the delegated harness or local validation.
+# @satisfies REQ-060, REQ-062, REQ-065
+forward_tool_subcommand() {
+  local tool_name="$1"
+  shift
+  local -a forwarded=()
+  local saw_args=0
+  local saw_params=0
+  local option_value=""
+  local tool_params_json=""
+
+  if [[ $# -eq 0 ]]; then
+    run_debug_extension tool --name "${tool_name}" --params '{}'
+    return 0
+  fi
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --args)
+        if [[ ${saw_params} -eq 1 ]]; then
+          printf 'Error: tool subcommand cannot combine --args with --params.\n' >&2
+          return 1
+        fi
+        saw_args=1
+        option_value="${2-}"
+        tool_params_json="$(build_tool_params_json "${tool_name}" "${option_value}")" || return 1
+        forwarded+=("--params" "${tool_params_json}")
+        if [[ $# -ge 2 ]]; then
+          shift 2
+        else
+          shift
+        fi
+        ;;
+      --params)
+        if [[ ${saw_args} -eq 1 ]]; then
+          printf 'Error: tool subcommand cannot combine --args with --params.\n' >&2
+          return 1
+        fi
+        saw_params=1
+        forwarded+=("$1")
+        if [[ $# -ge 2 ]]; then
+          forwarded+=("$2")
+          shift 2
+        else
+          forwarded+=("")
+          shift
+        fi
+        ;;
+      *)
+        forwarded+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  if [[ ${saw_args} -eq 1 || ${saw_params} -eq 1 ]] || contains_long_option "${forwarded[@]}"; then
+    run_debug_extension tool --name "${tool_name}" "${forwarded[@]}"
+  elif [[ ${#forwarded[@]} -eq 1 ]]; then
+    run_debug_extension tool --name "${tool_name}" --params "${forwarded[0]}"
+  else
+    printf 'Error: tool JSON must be one shell argument or use --args/--params.\n' >&2
+    return 1
+  fi
+}
+
+# @brief Validates that one required subcommand operand is present.
+# @details Emits a deterministic stderr error when the caller omits a required positional name such as a command or tool identifier. Runtime is O(1). Side effect: writes to stderr on failure.
+# @param[in] label {string} Human-readable operand label.
+# @param[in] value {string} Operand value.
+# @return {int} Shell status `0` when the operand exists; `1` otherwise.
+require_value() {
+  local label="$1"
+  local value="${2-}"
+  if [[ -n "${value}" ]]; then
+    return 0
+  fi
+  printf 'Error: missing %s.\n' "${label}" >&2
+  return 1
+}
+
+# @brief Dispatches wrapper subcommands to the standalone TypeScript harness.
+# @details Implements the convenience grammar documented by `print_usage`, including session and SDK aliases, prompt-name normalization, tool `--args` to `--params` rewriting, default tool params, and raw pass-through mode. Runtime is O(n) in wrapper argument count plus delegated harness cost. Side effects include stdout/stderr writes and subprocess execution.
+# @param[in] ... {string[]} Wrapper CLI arguments excluding the script path.
+# @return {int} Exit status propagated from the delegated harness or local validation.
+# @satisfies REQ-060, REQ-061, REQ-062, REQ-065
+main() {
+  local subcommand="${1-}"
+  if [[ $# -eq 0 ]]; then
+    print_usage
+    return 0
+  fi
+  shift
+
+  case "${subcommand}" in
+    help|-h|--help)
+      print_usage
+      ;;
+    inspect)
+      run_debug_extension inspect "$@"
+      ;;
+    session)
+      run_debug_extension session-start "$@"
+      ;;
+    command)
+      local command_name="${1-}"
+      require_value "command name" "${command_name}" || return 1
+      shift
+      if [[ $# -eq 0 ]]; then
+        run_debug_extension command --name "${command_name}"
+      elif contains_exact_option --args "$@" || contains_long_option "$@"; then
+        run_debug_extension command --name "${command_name}" "$@"
+      else
+        run_debug_extension command --name "${command_name}" --args "$*"
+      fi
+      ;;
+    prompt)
+      local prompt_name="${1-}"
+      local normalized_prompt_name
+      require_value "prompt name" "${prompt_name}" || return 1
+      normalized_prompt_name="$(normalize_prompt_name "${prompt_name}")"
+      shift
+      if [[ $# -eq 0 ]]; then
+        run_debug_extension command --name "${normalized_prompt_name}"
+      elif contains_exact_option --args "$@" || contains_long_option "$@"; then
+        run_debug_extension command --name "${normalized_prompt_name}" "$@"
+      else
+        run_debug_extension command --name "${normalized_prompt_name}" --args "$*"
+      fi
+      ;;
+    tool)
+      local tool_name="${1-}"
+      require_value "tool name" "${tool_name}" || return 1
+      shift
+      forward_tool_subcommand "${tool_name}" "$@"
+      ;;
+    sdk)
+      run_debug_extension sdk-smoke "$@"
+      ;;
+    raw)
+      require_value "raw subcommand" "${1-}" || return 1
+      run_debug_extension "$@"
+      ;;
+    *)
+      printf 'Error: unknown pi-usereq-debug subcommand: %s\n' "${subcommand}" >&2
+      print_usage >&2
+      return 1
+      ;;
+  esac
+}
+
+main "$@"

package/scripts/tool-args-to-params.ts

@@ -0,0 +1,208 @@
+/**
+ * @file
+ * @brief Converts pi-usereq-debug tool `--args` text into the JSON object expected by `--params`.
+ * @details Parses the wrapper-only tool-argument grammar, tokenizes shell-style text without invoking a shell, validates the argument shape for the current registered tool set, and emits one compact JSON object for `scripts/pi-usereq-debug.sh`. Runtime is O(n) in argument length. Side effects are limited to stdout and stderr writes.
+ */
+
+import process from "node:process";
+import { ReqError } from "../src/core/errors.js";
+import { shellSplit } from "../src/core/utils.js";
+
+/**
+ * @brief Describes the normalized CLI request consumed by the tool-argument converter.
+ * @details Captures the target tool name, raw `--args` text, and help-mode state for the standalone converter entrypoint. The interface is compile-time only and introduces no runtime side effects.
+ */
+interface ParsedToolArgsCli {
+  toolName?: string;
+  argsText: string;
+  help: boolean;
+}
+
+/**
+ * @brief Stores the standalone converter usage text.
+ * @details Provides a deterministic help payload for invalid or incomplete invocations of `scripts/tool-args-to-params.ts`. Access complexity is O(1).
+ */
+const USAGE_TEXT = `Usage: node --import tsx ./scripts/tool-args-to-params.ts --name <tool> --args <text>
+
+Options:
+  --name <tool>           Registered tool name.
+  --args <text>           Raw pi-usereq-debug tool argument text.
+  --help                  Show this help text.
+`;
+
+/**
+ * @brief Parses CLI flags for the standalone tool-argument converter.
+ * @details Performs one left-to-right scan, records the last `--name` and `--args` values, and ignores unrelated tokens so the wrapper can compose deterministic invocations. Runtime is O(n) in argument count. No external state is mutated.
+ * @param[in] argv {string[]} Raw CLI arguments excluding executable and script path.
+ * @return {ParsedToolArgsCli} Parsed converter request.
+ */
+function parseCliArgs(argv: string[]): ParsedToolArgsCli {
+  const parsed: ParsedToolArgsCli = {
+    argsText: "",
+    help: false,
+  };
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index]!;
+    switch (token) {
+      case "--name":
+        parsed.toolName = argv[index + 1];
+        index += 2;
+        break;
+      case "--args":
+        parsed.argsText = argv[index + 1] ?? "";
+        index += 2;
+        break;
+      case "--help":
+        parsed.help = true;
+        index += 1;
+        break;
+      default:
+        index += 1;
+        break;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * @brief Removes one boolean flag from a shell-token array.
+ * @details Preserves token order for all non-matching items and reports whether the requested flag appeared at least once. Runtime is O(n) in token count. No external state is mutated.
+ * @param[in] tokens {string[]} Tokenized `--args` payload.
+ * @param[in] flag {string} Flag token to remove.
+ * @return {{ tokens: string[]; present: boolean }} Remaining tokens plus presence marker.
+ */
+function takeBooleanFlag(tokens: string[], flag: string): { tokens: string[]; present: boolean } {
+  const remaining: string[] = [];
+  let present = false;
+  for (const token of tokens) {
+    if (token === flag) {
+      present = true;
+      continue;
+    }
+    remaining.push(token);
+  }
+  return { tokens: remaining, present };
+}
+
+/**
+ * @brief Converts one pi-usereq-debug tool `--args` string into a tool-parameter object.
+ * @details Tokenizes shell-style text with `shellSplit`, applies tool-specific positional and flag mappings, and rejects unsupported or structurally incomplete argument layouts before wrapper forwarding. Runtime is O(n) in token count. No external state is mutated.
+ * @param[in] toolName {string} Registered tool name selected by `scripts/pi-usereq-debug.sh`.
+ * @param[in] argsText {string} Raw wrapper `--args` payload.
+ * @return {Record<string, unknown>} JSON-serializable tool-parameter object compatible with `--params`.
+ * @throws {ReqError} Throws when the selected tool has no supported `--args` mapping or when the token layout is invalid.
+ * @satisfies REQ-065
+ */
+export function buildToolParamsFromArgsText(toolName: string, argsText: string): Record<string, unknown> {
+  const tokens = shellSplit(argsText);
+  switch (toolName) {
+    case "git-path":
+    case "get-base-path":
+    case "references":
+    case "tokens":
+    case "static-check":
+    case "git-check":
+    case "docs-check":
+    case "git-wt-name":
+      if (tokens.length !== 0) {
+        throw new ReqError(`Error: tool ${toolName} does not accept --args values.`, 1);
+      }
+      return {};
+    case "files-tokens":
+    case "files-references":
+    case "files-static-check":
+      return { files: tokens };
+    case "files-compress": {
+      const { tokens: remaining, present } = takeBooleanFlag(tokens, "--enable-line-numbers");
+      return present ? { files: remaining, enableLineNumbers: true } : { files: remaining };
+    }
+    case "files-find": {
+      const { tokens: remaining, present } = takeBooleanFlag(tokens, "--enable-line-numbers");
+      if (remaining.length < 3) {
+        throw new ReqError("Error: tool files-find requires <tag> <pattern> <file...> in --args text.", 1);
+      }
+      const [tag, pattern, ...files] = remaining;
+      return present ? { tag, pattern, files, enableLineNumbers: true } : { tag, pattern, files };
+    }
+    case "compress": {
+      const { tokens: remaining, present } = takeBooleanFlag(tokens, "--enable-line-numbers");
+      if (remaining.length !== 0) {
+        throw new ReqError("Error: tool compress accepts only --enable-line-numbers in --args text.", 1);
+      }
+      return present ? { enableLineNumbers: true } : {};
+    }
+    case "find": {
+      const { tokens: remaining, present } = takeBooleanFlag(tokens, "--enable-line-numbers");
+      if (remaining.length !== 2) {
+        throw new ReqError("Error: tool find requires <tag> <pattern> in --args text.", 1);
+      }
+      const [tag, pattern] = remaining;
+      return present ? { tag, pattern, enableLineNumbers: true } : { tag, pattern };
+    }
+    case "git-wt-create":
+    case "git-wt-delete":
+      if (tokens.length !== 1) {
+        throw new ReqError(`Error: tool ${toolName} requires exactly one wtName value in --args text.`, 1);
+      }
+      return { wtName: tokens[0] };
+    default:
+      throw new ReqError(`Error: unsupported --args conversion for tool ${toolName}. Use --params with JSON.`, 1);
+  }
+}
+
+/**
+ * @brief Writes non-empty text to stdout.
+ * @details Skips zero-length payloads so callers can compose CLI output without duplicate blank writes. Runtime is O(n) in text length. Side effects are limited to stdout writes.
+ * @param[in] text {string} Text payload.
+ * @return {void} No return value.
+ */
+function writeStdout(text: string): void {
+  if (text.length > 0) {
+    process.stdout.write(text);
+  }
+}
+
+/**
+ * @brief Writes non-empty text to stderr with a trailing newline.
+ * @details Appends a newline when absent and suppresses zero-length payloads. Runtime is O(n) in text length. Side effects are limited to stderr writes.
+ * @param[in] text {string} Text payload.
+ * @return {void} No return value.
+ */
+function writeStderr(text: string): void {
+  if (text.length === 0) {
+    return;
+  }
+  process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+/**
+ * @brief Executes one standalone tool-argument conversion request.
+ * @details Parses converter CLI flags, validates the presence of `--name`, transforms wrapper `--args` text into a JSON object, and writes the serialized payload for shell consumption while converting `ReqError` failures into stderr plus exit codes. Runtime is O(n) in argument length. Side effects are limited to stdout and stderr writes.
+ * @param[in] argv {string[]} Raw CLI arguments. Defaults to `process.argv.slice(2)`.
+ * @return {Promise<number>} Process exit code.
+ * @throws {ReqError} Internally catches `ReqError` and returns its exit code.
+ * @satisfies REQ-065
+ */
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+  try {
+    const args = parseCliArgs(argv);
+    if (args.help || !args.toolName) {
+      writeStdout(USAGE_TEXT);
+      return 0;
+    }
+    const params = buildToolParamsFromArgsText(args.toolName, args.argsText);
+    writeStdout(`${JSON.stringify(params)}\n`);
+    return 0;
+  } catch (error) {
+    const reqError = error as ReqError;
+    writeStderr(reqError.message ?? String(error));
+    return reqError.code ?? 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  void main().then((code) => {
+    process.exitCode = code;
+  });
+}