pi-usereq 0.13.0 → 0.33.0

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.13.0";
+export const VERSION = "0.33.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -110,6 +110,7 @@ import {
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
   DEFAULT_DEBUG_STATUS_CHANGES,
+  DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
   logDebugPromptEvent,
   logDebugPromptWorkflowEvent,
@@ -119,6 +120,7 @@ import {
   normalizeDebugLogFile,
   normalizeDebugLogOnStatus,
   normalizeDebugStatusChanges,
+  normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
   shouldLogDebugPromptWorkflowState,
   type DebugLogOnStatus,
@@ -268,6 +270,125 @@ function loadProjectConfig(cwd: string): UseReqConfig {
   return normalizeConfigPaths(projectBase, loadConfig(projectBase));
 }
 
+/**
+ * @brief Describes the execute-result surface reused by debug tool wrapper commands.
+ * @details Narrows debug slash-command handlers to the same monolithic content-plus-execution wrapper returned by agent tools so editor output and notifications can reuse shared extraction helpers. The alias is compile-time only and introduces no runtime cost.
+ */
+type DebugToolCommandExecuteResult = ReturnType<typeof buildMonolithicToolExecuteResult>;
+
+/**
+ * @brief Tests whether debug tool wrapper commands should be registered for one runtime cwd.
+ * @details Loads the effective project configuration for the supplied cwd and returns `true` only when `DEBUG_TOOL_COMMANDS_ENABLED` resolves to `enable`. Malformed or unreadable config payloads degrade to `false` so extension activation never aborts while deciding whether to register optional debug commands. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
+ * @param[in] cwd {string} Candidate runtime working directory.
+ * @return {boolean} `true` when debug tool wrapper commands should be registered.
+ * @satisfies REQ-323
+ */
+function shouldRegisterDebugToolCommands(cwd: string): boolean {
+  try {
+    return normalizeDebugToolCommandsEnabled(loadProjectConfig(cwd).DEBUG_TOOL_COMMANDS_ENABLED) === "enable";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @brief Writes one debug tool-wrapper result into the editor and emits a status notification.
+ * @details Extracts the primary monolithic content text from the wrapped tool result, forwards that exact text to the editor, and emits an informational or error notification keyed by the tool exit code. Runtime is O(n) in output length. Side effects include editor-text mutation and UI notifications.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+ * @param[in] result {DebugToolCommandExecuteResult} Wrapped tool execution result.
+ * @return {void} No return value.
+ * @satisfies REQ-324
+ */
+function writeDebugToolCommandResultToEditor(
+  ctx: ExtensionCommandContext,
+  commandName: string,
+  result: DebugToolCommandExecuteResult,
+): void {
+  const outputText = getMonolithicToolText(result);
+  ctx.ui.setEditorText(outputText);
+  const succeeded = result.details.execution.code === 0;
+  ctx.ui.notify(
+    succeeded
+      ? `Wrote /${commandName} output to the editor.`
+      : `FAILED: Wrote /${commandName} output to the editor.`,
+    succeeded ? "info" : "error",
+  );
+}
+
+/**
+ * @brief Executes one config-gated debug tool wrapper slash command.
+ * @details Resolves a live cwd for the invoking command context, refreshes runtime path state, loads the effective project configuration, rejects execution when debug tool wrapper commands are disabled, and otherwise writes the selected wrapped tool output into the editor. Runtime is dominated by the delegated tool runner. Side effects include runtime-path bootstrap, filesystem reads, optional tool side effects, editor-text mutation, and UI notifications.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+ * @param[in] operation {(projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult} Wrapped tool executor.
+ * @return {void} No return value.
+ * @throws {ReqError} Throws when debug tool wrapper commands are disabled for the active project.
+ * @satisfies REQ-324, REQ-325
+ */
+function executeDebugToolCommand(
+  ctx: ExtensionCommandContext,
+  commandName: string,
+  operation: (projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult,
+): void {
+  const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+  syncContextCwdMirror(ctx, commandCwd);
+  bootstrapRuntimePathState(commandCwd, {
+    gitPath: resolveRuntimeGitPath(commandCwd),
+  });
+  const projectBase = getProjectBase(commandCwd);
+  const config = loadProjectConfig(commandCwd);
+  if (normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED) !== "enable") {
+    const message = `ERROR: /${commandName} is disabled by Debug > Enable debug commands for tools.`;
+    ctx.ui.notify(message, "error");
+    throw new ReqError(message, 1);
+  }
+  writeDebugToolCommandResultToEditor(ctx, commandName, operation(projectBase, config));
+}
+
+/**
+ * @brief Registers config-gated debug slash-command wrappers for selected built-in analysis tools.
+ * @details Registers `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` as extension commands that reuse the same runner paths as the corresponding agent tools and write the resulting monolithic text into the editor instead of the LLM content channel. Re-registering the same commands is idempotent because pi keeps the latest same-extension command definition per name. Runtime is O(1) for registration; handler cost depends on the selected runner. Side effects include command registration.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @return {void} No return value.
+ * @satisfies DES-015, REQ-323, REQ-324, REQ-325
+ */
+function registerDebugToolCommands(pi: ExtensionAPI): void {
+  const registerDebugToolCommand = (
+    commandName: string,
+    description: string,
+    operation: (projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult,
+  ): void => {
+    pi.registerCommand(commandName, {
+      description,
+      handler: async (_args, ctx) => {
+        executeDebugToolCommand(ctx, commandName, operation);
+      },
+    });
+  };
+
+  registerDebugToolCommand(
+    "debug-compress",
+    "Run compress and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runCompress(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-references",
+    "Run references and write the tool output into the editor",
+    (projectBase, config) => executeStatusTool(() => runReferences(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-static-check",
+    "Run static-check and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runProjectStaticCheck(projectBase, config)),
+  );
+  registerDebugToolCommand(
+    "debug-tokens",
+    "Run tokens and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runTokens(projectBase, config)),
+  );
+}
+
 /**
  * @brief Persists effective project configuration from the extension runtime.
  * @details Resolves the project base, normalizes configured local directory paths into project-relative form, and delegates split local/global persistence to `saveConfig` without serializing runtime-derived path metadata. Runtime is O(n) in config size. Side effects include config-file writes.
@@ -1411,16 +1532,17 @@ function getDebugToolToggleNames(): PiUsereqStartupToolName[] {
 
 /**
  * @brief Restores the debug configuration subtree to its documented defaults.
- * @details Resets global debug enablement, log path, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
+ * @details Resets global debug enablement, log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {void} No return value.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322
  */
 function resetDebugConfigToDefaults(config: UseReqConfig): void {
   config.DEBUG_ENABLED = "disable";
   config.DEBUG_LOG_FILE = DEFAULT_DEBUG_LOG_FILE;
   config.DEBUG_STATUS_CHANGES = DEFAULT_DEBUG_STATUS_CHANGES;
   config.DEBUG_WORKFLOW_EVENTS = DEFAULT_DEBUG_WORKFLOW_EVENTS;
+  config.DEBUG_TOOL_COMMANDS_ENABLED = DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
   config.DEBUG_LOG_ON_STATUS = DEFAULT_DEBUG_LOG_ON_STATUS;
   config.DEBUG_ENABLED_TOOLS = [];
   config.DEBUG_ENABLED_PROMPTS = [];
@@ -1502,10 +1624,10 @@ async function selectDebugLogOnStatus(
 
 /**
  * @brief Builds the shared settings-menu choices for debug logging configuration.
- * @details Serializes global debug controls plus workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
+ * @details Serializes global debug controls plus tool-wrapper command registration, workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered debug-menu choices.
- * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277
+ * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277, REQ-321, REQ-322
  */
 function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const debugEnabled = config.DEBUG_ENABLED === "enable";
@@ -1528,6 +1650,16 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       },
       debugEnabled,
     ),
+    buildDebugMenuChoice(
+      {
+        id: "debug-tool-commands-enabled",
+        label: "Enable debug commands for tools",
+        value: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED),
+        values: ["enable", "disable"],
+        description: "Enable or disable slash-command wrappers for `compress`, `references`, `static-check`, and `tokens`.",
+      },
+      debugEnabled,
+    ),
     buildDebugMenuChoice(
       {
         id: "debug-log-on-status",
@@ -1587,17 +1719,28 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
 
 /**
  * @brief Runs the interactive Debug submenu.
- * @details Lets the user toggle global debug enablement, edit debug file and workflow filters, toggle dedicated workflow-event logging, mutate per-tool and per-prompt debug selectors, and restore subtree defaults while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user toggle global debug enablement, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323
  */
 async function configureDebugMenu(
+  pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
   onConfigChange: () => void,
 ): Promise<void> {
+  const updateDebugToolCommandsEnabled = (nextValue: unknown): void => {
+    config.DEBUG_TOOL_COMMANDS_ENABLED = normalizeDebugToolCommandsEnabled(nextValue);
+    onConfigChange();
+    if (config.DEBUG_TOOL_COMMANDS_ENABLED === "enable") {
+      registerDebugToolCommands(pi);
+    }
+    ctx.ui.notify(`Debug tool commands ${config.DEBUG_TOOL_COMMANDS_ENABLED}`, "info");
+  };
+
   let focusedChoiceId: string | undefined;
   while (true) {
     const choice = await showPiUsereqSettingsMenu(ctx, "Debug", buildDebugMenuChoices(config), {
@@ -1610,6 +1753,10 @@ async function configureDebugMenu(
           ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
           return;
         }
+        if (choiceId === "debug-tool-commands-enabled") {
+          updateDebugToolCommandsEnabled(newValue);
+          return;
+        }
         if (choiceId === "debug-status-changes") {
           config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(newValue);
           onConfigChange();
@@ -1670,6 +1817,7 @@ async function configureDebugMenu(
       const resetPreview: ResetConfirmationChange[] = [
         { label: "Debug", previousValue: config.DEBUG_ENABLED, nextValue: "disable" },
         { label: "Log file", previousValue: config.DEBUG_LOG_FILE, nextValue: DEFAULT_DEBUG_LOG_FILE },
+        { label: "Enable debug commands for tools", previousValue: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED), nextValue: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED },
         { label: "Status changes", previousValue: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES), nextValue: DEFAULT_DEBUG_STATUS_CHANGES },
         { label: "Workflow events", previousValue: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS), nextValue: DEFAULT_DEBUG_WORKFLOW_EVENTS },
         { label: "Log on status", previousValue: config.DEBUG_LOG_ON_STATUS, nextValue: DEFAULT_DEBUG_LOG_ON_STATUS },
@@ -1705,6 +1853,12 @@ async function configureDebugMenu(
       }
       continue;
     }
+    if (choice === "debug-tool-commands-enabled") {
+      updateDebugToolCommandsEnabled(
+        config.DEBUG_TOOL_COMMANDS_ENABLED === "enable" ? "disable" : "enable",
+      );
+      continue;
+    }
     if (choice === "debug-status-changes") {
       config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(
         config.DEBUG_STATUS_CHANGES === "enable" ? "disable" : "enable",
@@ -4163,7 +4317,7 @@ async function configurePiUsereq(
       continue;
     }
     if (choice === "debug") {
-      await configureDebugMenu(ctx, config, persistConfigChange);
+      await configureDebugMenu(pi, ctx, config, persistConfigChange);
       continue;
     }
     if (choice === "reset-defaults") {
@@ -4232,10 +4386,10 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
+ * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
+ * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();
@@ -4243,6 +4397,9 @@ export default function piUsereqExtension(pi: ExtensionAPI): void {
   registerReqResetCommand(pi, statusController);
   registerReqReferencesCommand(pi, statusController);
   registerPromptCommands(pi, statusController);
+  if (shouldRegisterDebugToolCommands(getProcessCwdSafe())) {
+    registerDebugToolCommands(pi);
+  }
   registerAgentTools(pi);
   registerConfigCommands(pi, statusController);
   registerPiNotifyShortcut(pi, statusController);

package/tests/extension-registration.test.ts

@@ -24,6 +24,7 @@ import {
   DEBUG_PROMPT_NAMES,
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
+  DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
 } from "../src/core/debug-runtime.js";
 import { PROMPT_COMMAND_NAMES } from "../src/core/prompt-command-catalog.js";
@@ -838,6 +839,10 @@ test("extension registers prompt and config commands while exposing tool capabil
     "tokens",
     "files-static-check",
     "static-check",
+    "debug-compress",
+    "debug-references",
+    "debug-static-check",
+    "debug-tokens",
     "pi-usereq-show-config",
     "test-static-check",
   ]) {
@@ -862,6 +867,54 @@ test("extension registers prompt and config commands while exposing tool capabil
   }
 });
 
+/**
+ * @brief Verifies debug tool wrapper commands register only when the local debug flag is enabled.
+ * @details Activates the extension once from a default-disabled fixture and once from a fixture whose local config enables debug tool wrapper commands, then asserts the four debug slash commands appear only in the enabled runtime. Runtime is dominated by fixture setup and extension registration. Side effects are limited to temporary filesystem mutation and process cwd changes.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when command registration ignores the local debug tool wrapper flag.
+ * @satisfies TST-115
+ */
+test("debug tool commands register only when enabled in local config", () => {
+  const disabledFixture = initFixtureRepo({ fixtures: [] });
+  const enabledFixture = initFixtureRepo({ fixtures: [] });
+  const debugCommandNames = [
+    "debug-compress",
+    "debug-references",
+    "debug-static-check",
+    "debug-tokens",
+  ];
+
+  try {
+    writeProjectConfigOverrides(enabledFixture.projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "enable",
+    });
+
+    const previousCwd = process.cwd();
+    try {
+      process.chdir(disabledFixture.projectBase);
+      const disabledPi = createFakePi();
+      piUsereqExtension(disabledPi);
+      const disabledCommandNames = [...disabledPi.commands.keys()];
+      for (const commandName of debugCommandNames) {
+        assert.equal(disabledCommandNames.includes(commandName), false, `unexpected command ${commandName}`);
+      }
+
+      process.chdir(enabledFixture.projectBase);
+      const enabledPi = createFakePi();
+      piUsereqExtension(enabledPi);
+      const enabledCommandNames = [...enabledPi.commands.keys()];
+      for (const commandName of debugCommandNames) {
+        assert.ok(enabledCommandNames.includes(commandName), `missing command ${commandName}`);
+      }
+    } finally {
+      process.chdir(previousCwd);
+    }
+  } finally {
+    fs.rmSync(disabledFixture.projectBase, { recursive: true, force: true });
+    fs.rmSync(enabledFixture.projectBase, { recursive: true, force: true });
+  }
+});
+
 /**
  * @brief Verifies `req-references` registration is independent from bundled prompt inventory.
  * @details Confirms `references` is absent from `PROMPT_COMMAND_NAMES` while extension activation still registers `req-references` with the fixed dedicated description. Runtime is O(1). Side effects are limited to extension registration.
@@ -1551,6 +1604,80 @@ test("static-check tools return monolithic text payloads with minimal execution
   }
 });
 
+/**
+ * @brief Verifies debug tool wrapper commands mirror tool content and reject when disabled.
+ * @details Enables debug tool wrapper commands for one fixture project, compares each debug slash-command editor payload against the matching tool `content[0].text`, then disables the flag and verifies the already-registered wrapper rejects further execution. Runtime is dominated by tool execution plus temporary git fixture setup. Side effects are limited to temporary filesystem mutation, editor-text capture, and process cwd changes.
+ * @return {Promise<void>} Promise resolved when the verification completes.
+ * @throws {AssertionError} Throws when a debug wrapper output diverges from the wrapped tool text or disabled execution is accepted.
+ * @satisfies TST-116
+ */
+test("debug tool wrapper commands mirror tool content and reject when disabled", async () => {
+  const { projectBase } = initFixtureRepo({
+    fixtures: [],
+    staticCheck: {
+      TypeScript: createStaticCheckLanguageConfig([{ module: "Dummy" }], "enable"),
+    },
+  });
+  fs.writeFileSync(path.join(projectBase, "src", "check.ts"), "export const VALUE = 1;\n", "utf8");
+  const add = spawnSync("git", ["add", "."], { cwd: projectBase, encoding: "utf8" });
+  assert.equal(add.status, 0, add.stderr);
+  const commit = spawnSync("git", ["commit", "-m", "add debug tool inputs"], { cwd: projectBase, encoding: "utf8" });
+  assert.equal(commit.status, 0, commit.stderr);
+
+  const previousCwd = process.cwd();
+  try {
+    writeProjectConfigOverrides(projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "enable",
+    });
+
+    process.chdir(projectBase);
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+
+    const compressToolResult = await executeRegisteredTool(pi, "compress", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const referencesToolResult = await executeRegisteredTool(pi, "references", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const staticCheckToolResult = await executeRegisteredTool(pi, "static-check", projectBase) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const tokensToolResult = await executeRegisteredTool(pi, "tokens", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+
+    const compressCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-compress")!.handler("", compressCtx);
+    assert.equal(compressCtx.__state.editorText, compressToolResult.content?.[0]?.text ?? "");
+
+    const referencesCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-references")!.handler("", referencesCtx);
+    assert.equal(referencesCtx.__state.editorText, referencesToolResult.content?.[0]?.text ?? "");
+
+    const staticCheckCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-static-check")!.handler("", staticCheckCtx);
+    assert.equal(staticCheckCtx.__state.editorText, staticCheckToolResult.content?.[0]?.text ?? "");
+
+    const tokensCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-tokens")!.handler("", tokensCtx);
+    assert.equal(tokensCtx.__state.editorText, tokensToolResult.content?.[0]?.text ?? "");
+
+    writeProjectConfigOverrides(projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "disable",
+    });
+    const disabledCtx = createFakeCtx(projectBase);
+    await assert.rejects(
+      async () => pi.commands.get("debug-tokens")!.handler("", disabledCtx),
+      /disabled by Debug > Enable debug commands for tools/u,
+    );
+    assert.equal(disabledCtx.__state.editorText, "");
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
 test("configuration menu saves updated docs-dir in project config", async () => {
   const cwd = createTempDir("pi-usereq-menu-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
@@ -1821,6 +1948,7 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
       "Debug",
       "Debug",
       "Log file",
+      "Enable debug commands for tools",
       "Log on status",
       "any",
       "Status changes",
@@ -1839,24 +1967,31 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
   const persistedConfig = readProjectConfigJson(cwd);
   const debugCalls = ctx.__state.selectCalls.filter((call) => call.title === "Debug");
   assert.match(renderedInitialDebugMenu, /<dim>Log file/);
+  assert.match(renderedInitialDebugMenu, /<dim>Enable debug commands for tools/);
   assert.match(renderedInitialDebugMenu, /<dim>Log on status/);
   assert.match(renderedInitialDebugMenu, /<dim>Status changes/);
   assert.match(renderedInitialDebugMenu, /<dim>Workflow events/);
   assert.match(renderedInitialDebugMenu, /<dim>compress/);
   assert.equal(persistedConfig.DEBUG_ENABLED, "enable");
   assert.equal(persistedConfig.DEBUG_LOG_FILE, "logs/debug-output.json");
+  assert.equal(persistedConfig.DEBUG_TOOL_COMMANDS_ENABLED, "enable");
   assert.equal(persistedConfig.DEBUG_STATUS_CHANGES, "enable");
   assert.equal(persistedConfig.DEBUG_WORKFLOW_EVENTS, "enable");
   assert.equal(persistedConfig.DEBUG_LOG_ON_STATUS, "any");
+  assert.ok(pi.commands.get("debug-compress"));
+  assert.ok(pi.commands.get("debug-references"));
+  assert.ok(pi.commands.get("debug-static-check"));
+  assert.ok(pi.commands.get("debug-tokens"));
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_TOOLS, ["files-tokens"]);
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_PROMPTS, ["req-analyze"]);
   assert.equal(debugCalls[1]?.selectedChoiceId, "debug-enabled");
   assert.equal(debugCalls[2]?.selectedChoiceId, "debug-log-file");
-  assert.equal(debugCalls[3]?.selectedChoiceId, "debug-log-on-status");
-  assert.equal(debugCalls[4]?.selectedChoiceId, "debug-status-changes");
-  assert.equal(debugCalls[5]?.selectedChoiceId, "debug-workflow-events");
-  assert.equal(debugCalls[6]?.selectedChoiceId, "debug-tool:files-tokens");
-  assert.equal(debugCalls[7]?.selectedChoiceId, "debug-prompt:req-analyze");
+  assert.equal(debugCalls[3]?.selectedChoiceId, "debug-tool-commands-enabled");
+  assert.equal(debugCalls[4]?.selectedChoiceId, "debug-log-on-status");
+  assert.equal(debugCalls[5]?.selectedChoiceId, "debug-status-changes");
+  assert.equal(debugCalls[6]?.selectedChoiceId, "debug-workflow-events");
+  assert.equal(debugCalls[7]?.selectedChoiceId, "debug-tool:files-tokens");
+  assert.equal(debugCalls[8]?.selectedChoiceId, "debug-prompt:req-analyze");
 
   const resetCtx = createFakeCtx(cwd, {
     selects: ["Debug", "Reset defaults", "Approve reset", "Save and close"],
@@ -1865,6 +2000,7 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
   const resetConfig = readProjectConfigJson(cwd);
   assert.equal(resetConfig.DEBUG_ENABLED, "disable");
   assert.equal(resetConfig.DEBUG_LOG_FILE, DEFAULT_DEBUG_LOG_FILE);
+  assert.equal(resetConfig.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
   assert.equal(resetConfig.DEBUG_STATUS_CHANGES, "disable");
   assert.equal(resetConfig.DEBUG_WORKFLOW_EVENTS, DEFAULT_DEBUG_WORKFLOW_EVENTS);
   assert.equal(resetConfig.DEBUG_LOG_ON_STATUS, DEFAULT_DEBUG_LOG_ON_STATUS);
@@ -1888,6 +2024,7 @@ test("debug menu rows derive from canonical tool and prompt inventories", async
   assert.deepEqual(ctx.__state.selectCalls[1]?.items ?? [], [
     "Debug",
     "Log file",
+    "Enable debug commands for tools",
     "Log on status",
     "Status changes",
     "Workflow events",
@@ -5386,6 +5523,7 @@ test("default configuration applies the documented static-check, debug, notify,
   assert.deepEqual(config["static-check"].Ruby, createStaticCheckLanguageConfig([], "disable"));
   assert.equal(config.DEBUG_ENABLED, "disable");
   assert.equal(config.DEBUG_LOG_FILE, DEFAULT_DEBUG_LOG_FILE);
+  assert.equal(config.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
   assert.equal(config.DEBUG_WORKFLOW_EVENTS, DEFAULT_DEBUG_WORKFLOW_EVENTS);
   assert.equal(config.DEBUG_LOG_ON_STATUS, DEFAULT_DEBUG_LOG_ON_STATUS);
   assert.deepEqual(config.DEBUG_ENABLED_TOOLS, []);
@@ -5409,6 +5547,7 @@ test("default configuration applies the documented static-check, debug, notify,
   const globalConfig = readGlobalConfigJson();
   assert.equal((localConfig["static-check"] as Record<string, any>).Python.enabled, "enable");
   assert.equal((localConfig["static-check"] as Record<string, any>).Ruby.enabled, "disable");
+  assert.equal(localConfig.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
   assert.deepEqual((globalConfig["static-check"] as Record<string, any>).Python.checkers, [
     { module: "Command", cmd: "pyright", params: ["--outputjson"] },
     { module: "Command", cmd: "ruff", params: ["check"] },

package/tests/release-workflow.test.ts

@@ -94,11 +94,12 @@ test(
 );
 
 test(
-  "release workflow installs dependencies, publishes to npm, and creates the GitHub release",
+  "release workflow pins Node.js 24.15.0, publishes to npm, and creates the GitHub release",
   () => {
     const workflow = readReleaseWorkflow();
 
-    assert.ok(workflow.includes("uses: actions/setup-node@v4"));
+    assert.match(workflow, /NODE_VERSION:\s+'24\.15\.0'/);
+    assert.ok(workflow.includes("uses: actions/setup-node@v5"));
     assert.ok(workflow.includes("registry-url: 'https://registry.npmjs.org'"));
     assert.ok(workflow.includes("run: npm ci"));
     assert.ok(workflow.includes("run: npm pkg delete private"));