pi-usereq 0.41.0 → 0.43.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,7 +1,7 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.73"
+version: "0.0.75"
 date: "2026-07-10"
 author: "OpenAI Codex"
 scope:
@@ -70,6 +70,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **CTN-016**: MUST NOT modify any path under `docs/` during analysis, implementation, verification, or bug fixing.
 - **CTN-017**: MUST NOT modify any path under `pi.dev-src/` during analysis, implementation, verification, or bug fixing.
 - **CTN-019**: MUST persist local `DEBUG_TOOL_COMMANDS_ENABLED` with allowed values `enable` and `disable`, defaulting to `disable`.
+- **CTN-020**: MUST declare `tsx` as a runtime `package.json` dependency so `node --import tsx` package scripts, the `postinstall` checker installer, and the `.ts` extension entry resolve on clean consumer installs.
 
 ## 3. Requirements
 
@@ -90,6 +91,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-011**: MUST implement `.github/workflows/release-npm.yml` as a two-job GitHub Actions pipeline where `check-branch` gates `build-release`, preserving changelog-driven GitHub Release creation while adding npm publication.
 - **DES-015**: MUST implement config-gated `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` slash-command wrappers in `src/index.ts` that reuse existing tool-runner execution paths.
 - **DES-016**: MUST deliver rendered bundled-prompt content to the LLM through `sendMessage` as a `display:false` custom message with `triggerTurn:true` and MUST NOT use `sendUserMessage` when `sendMessage` is available.
+- **DES-017**: MUST declare `pyright`, `ruff`, and `eslint` as pinned caret-range npm dependencies and register a `postinstall` script that installs bundled static checkers.
+- **DES-018**: MUST resolve checker executables by probing bundled `node_modules/.bin` paths relative to the installation path before falling back to `PATH` scan.
 
 ### 3.2 Functions
 - **REQ-001**: MUST access bundled prompts, git execution instructions, templates, and guidelines from `<installation-path>/resources` without requiring user-home resource copies before prompt or tool execution.
@@ -338,7 +341,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-020**: MUST parse user `--enable-static-check` specs in `LANG=Command,CMD[,PARAM...]` format and normalize supported language names plus `Command` case-insensitively.
 - **REQ-021**: MUST reject user `--enable-static-check` specs with missing `=`, missing `Command`, missing `cmd`, unknown language, or any module other than `Command`.
 - **REQ-022**: MUST preserve persisted `Dummy` static-check entries during config loading and execute them only when present in configuration or `--test-static-check dummy` input.
-- **REQ-023**: MUST require `Command`-module executables to exist on `PATH` before static-check execution.
+- **REQ-023**: MUST require `Command`-module executables to resolve via bundled `node_modules/.bin` or `PATH` before static-check execution.
 - **REQ-030**: MUST set static `base-path` from the bootstrap cwd and static `local-config-path` to `<base-path>/.pi-usereq.json`.
 - **REQ-317**: MUST set static `global-config-path` to `~/.config/pi-usereq/config.json`.
 - **REQ-259**: MUST set dynamic `context-path` from the bootstrap cwd and keep it aligned with `ctx.cwd`.
@@ -363,7 +366,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-035**: MUST parse repeatable `--enable-static-check LANG=Command,CMD[,PARAM...]` CLI options before command dispatch and merge resulting entries into persisted global checker lists.
 - **REQ-253**: MUST set `static-check.<language>.enabled=enable` whenever guided or CLI `--enable-static-check` entry creation targets that language.
 - **REQ-036**: MUST preserve existing global `static-check` checker entries, append non-duplicate `--enable-static-check` entries in argument order, and treat canonical language, module, cmd, and params as the duplicate identity.
-- **REQ-037**: MUST reject `--enable-static-check` `Command` entries whose executable is unavailable on `PATH` and MUST NOT modify persisted local or global configuration when validation fails.
+- **REQ-037**: MUST reject `--enable-static-check` `Command` entries whose executable is unresolvable via bundled `node_modules/.bin` or `PATH` and MUST NOT modify persisted local or global configuration when validation fails.
 - **REQ-038**: MUST honor `--verbose` only for `files-summarize`, `files-compress`, `files-find`, `summarize`, `compress`, and `find`, emitting command progress to stderr while leaving stdout payload format unchanged.
 - **REQ-039**: MUST support `--enable-line-numbers` only for `files-compress`, `compress`, `files-find`, and `find`, and MUST leave corresponding outputs unnumbered when the flag is absent.
 - **REQ-040**: MUST store canonical expected CLI result fixtures as UTF-8 text files under `tests/fixtures_attended_results/`, preserving normalized exit code, stdout, and stderr for each archived scenario.
@@ -402,6 +405,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-331**: MUST omit the `%%CONTEXT_FILES%%` section for any disabled flag or missing context file without surfacing an error.
 - **REQ-332**: MUST inject `%%CONTEXT_FILES%%` content verbatim after every other prompt replacement so literal `%%...%%` tokens inside context files are not substituted.
 - **REQ-333**: MUST restore all three `Context Files` flags to disabled when the `Context Files` subtree `Reset defaults` is approved.
+- **REQ-339**: MUST run `scripts/install-static-checkers.ts` as a best-effort exit-code-0 `postinstall` installer that probes bundled npm checkers, attempts `npm install` on miss, prints platform guidance for native checkers, and never modifies git-tracked files.
+- **REQ-340**: MUST default the `TypeScript` static-check `Command` entry to `cmd: "eslint"` with empty `params`.
+- **REQ-341**: MUST emit one warning notification during `session_start` listing missing enabled static checkers without transitioning workflow state or aborting.
+- **REQ-342**: MUST keep `STATIC_CHECK_MODULES`, `dispatchStaticCheckForFile` signature, and `StaticCheckEntry` shape unchanged when adding bundled executable resolution.
+- **REQ-343**: MUST NOT transition workflow state or abort `session_start` when one or more enabled static checkers are missing.
+- **REQ-344**: MUST place the `session_start` missing-checker helper in `src/core/static-check.ts` so `src/index.ts` remains thin.
 
 ## 4. Test Requirements
 - **TST-001**: MUST verify extension activation registers every documented prompt command, agent tool, and configuration command while omitting tool-name slash commands, `test-static-check`, and the removed standalone config-viewer command.
@@ -524,6 +533,9 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-119**: MUST verify `%%CONTEXT_FILES%%` replacement emits one section per enabled existing file in the documented order and omits disabled or missing files.
 - **TST-120**: MUST verify `%%CONTEXT_FILES%%` sections use the file-name heading, the pre-substituted HTML file reference, and four-backtick `markdown` fences around raw content.
 - **TST-122**: MUST verify the command invocation summary renders `none` for `context files`, `static code checks`, and `enabled tools` when no items are enabled in each respective category.
+- **TST-123**: MUST verify `resolveCheckerExecutable` probes bundled `node_modules/.bin` paths before `PATH` scan.
+- **TST-124**: MUST verify `scripts/install-static-checkers.ts` always returns exit code `0` regardless of probe or install outcomes.
+- **TST-125**: MUST verify `session_start` emits one warning notification for missing enabled checkers without aborting or transitioning workflow state.
 
 ## 5. Observed Component Model
 
@@ -545,7 +557,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - `@sinclair/typebox` provides runtime tool parameter schemas and is declared as a peer dependency evidenced by `src/index.ts`, `package.json`, and `package-lock.json`.
 - `js-tiktoken` provides token counting evidence in `src/core/token-counter.ts`, `package.json`, and `package-lock.json`.
 - `fast-glob` provides wildcard expansion for static-check inputs evidence in `src/core/static-check.ts`, `package.json`, and `package-lock.json`.
-- `tsx` is the manifest-declared TypeScript execution runner for tests and CLI scripts evidenced by `package.json` and `package-lock.json`.
+- `tsx` is the manifest-declared runtime dependency and TypeScript execution runner for package scripts, the `postinstall` checker installer, and the `.ts` extension entry, evidenced by `package.json` and `package-lock.json`.
 - `typescript` is the manifest-declared compiler and type-checker evidenced by `package.json`, `package-lock.json`, and `tsconfig.json`.
 - `git` CLI is a runtime dependency for repository discovery, source-file collection, bundled prompt-command worktree orchestration, and direct `req-references` commit orchestration evidenced in `src/core/tool-runner.ts`, `src/core/prompt-command-runtime.ts`, and `src/core/req-references-command.ts`.
 

package/pi-usereq/docs/WORKFLOW.md

@@ -49,6 +49,13 @@
     - `build-release(...)` [`.github/workflows/release-npm.yml`]
   - Parent Process: none
   - Threads: no explicit threads detected
+- ID: `PROC:install-static-checkers`
+  - Type: Process
+  - Role: Best-effort npm `postinstall` installer that probes bundled static-checker executables, attempts `npm install` on miss, and prints platform guidance for native checkers.
+  - Entrypoints:
+    - `main(...)` [`scripts/install-static-checkers.ts`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
 
 ## Execution Units
 ### `PROC:main`
@@ -83,8 +90,9 @@
       - `buildStaticCheckEntryIdentity(...)`: normalize entry duplicate identity [`src/core/static-check.ts`]
       - `parseEnableStaticCheck(...)`: parse one static-check enable specification [`src/core/static-check.ts`]
       - `validateStaticCheckEntry(...)`: validate command-backed entry before config write [`src/core/static-check.ts`]
-        - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
-          - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+        - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or PATH scan [`src/core/static-check.ts`]
+          - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
+            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
       - `saveConfig(...)`: persist split local/global config JSON [`src/core/config.ts`]
         - `saveLocalConfig(...)`: write the local config file [`src/core/config.ts`]
           - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
@@ -208,8 +216,9 @@
           - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
           - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
       - `StaticCheckCommand.run(...)`: iterate resolved files for external command path [`src/core/static-check.ts`]
-        - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-          - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+        - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
+          - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
         - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
           - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
           - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
@@ -227,8 +236,9 @@
             - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
             - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
         - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
-          - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+          - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
+            - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+              - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
           - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
             - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
             - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
@@ -366,8 +376,9 @@
               - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
               - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
           - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
-            - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-              - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+            - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
+              - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
+                - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
             - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
               - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
               - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
@@ -494,6 +505,7 @@
             - `RecordingExtensionAPI.setActiveTools(...)`: replace active-tool set with runtime-visible names [`scripts/lib/recording-extension-api.ts`]
               - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
           - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
+          - `checkDefaultCheckersAvailability(...)`: enumerate missing enabled static-check executables and emit one warning notification without aborting [`src/core/static-check.ts`]
           - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore elapsed timers, load the active runtime sound level from persisted config during `session_start`, reset workflow state for startup/new/reload, and render status text [`src/core/extension-status.ts`]
             - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
               - `RecordingCommandContext.getContextUsage(...)`: return the offline context-usage placeholder [`scripts/lib/recording-extension-api.ts`]
@@ -992,6 +1004,7 @@
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
           - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
         - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
+        - `checkDefaultCheckersAvailability(...)`: enumerate missing enabled static-check executables and emit one warning notification without aborting [`src/core/static-check.ts`]
         - `activatePromptCommandExecution(...)`: re-verify the prepared execution session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse persisted replacement-session contexts when lifecycle hooks omit `switchSession()`, re-align `process.cwd()` to the execution path, confirm `process.cwd()` plus the persisted execution-session file header cwd when the file is already persisted before agent start, and refresh reusable command-context persistence [`src/core/prompt-command-runtime.ts`]
         - `resolveDebugProjectBase(...)`: prefer static `base-path` for debug-log writes during worktree-backed prompt runs and recover a live bootstrap cwd when no prompt plan is active [`src/index.ts`]
         - `notifyContextSafely(...)`: suppress stale replacement-context notification failures after session replacement while preserving closure progress [`src/index.ts`]
@@ -1280,6 +1293,27 @@
 - External Boundaries:
   - GitHub Actions event routing, hosted-runner lifecycle, checkout action, setup-node action, npm CLI, npm registry, changelog-builder action, GitHub Releases API, and repository secrets.
 
+### `PROC:install-static-checkers`
+- Entrypoints:
+  - `main(...)`: best-effort bundled-checker installer root [`scripts/install-static-checkers.ts`]
+- Lifecycle/trigger:
+  - Start trigger: npm invokes the `postinstall` script declared in `package.json` after dependency installation.
+  - Stop trigger: returns numeric exit code `0` unconditionally after probing, optional best-effort installs, and native-checker guidance output.
+  - Looping model: single-pass probe plus optional install with no persistent loop.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `main(...)`: probe each bundled npm checker, attempt best-effort install on miss, print native-checker guidance, and return `0` [`scripts/install-static-checkers.ts`]
+    - `resolveCheckerExecutable(...)`: resolve one checker across bundled `node_modules/.bin` locations and PATH scan [`src/core/static-check.ts`]
+      - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
+        - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+    - `attemptBundledInstall(...)`: best-effort `npm install <pkg>@<range> --no-save --prefix <install-root>` swallowing all errors [`scripts/install-static-checkers.ts`]
+      - `getInstallationPath(...)`: resolve the installed extension root that owns `scripts/` and `src/` [`src/core/path-context.ts`]
+    - `printNativeCheckerGuidance(...)`: emit platform-specific install guidance for native checkers [`scripts/install-static-checkers.ts`]
+- External Boundaries:
+  - Node process APIs for argv, stdout, stderr, and exit code.
+  - Filesystem access for executable probing under the installation path.
+  - npm CLI subprocess spawned best-effort for missing bundled checkers.
+
 ## Communication Edges
 - `PROC:req-debug` -> `PROC:tool-args-to-params`
   - Mechanism: child-process spawn through resolved `tsx` executable.
@@ -1294,4 +1328,4 @@
   - Endpoint/channel: `is_master` job output and shared tag-run context.
   - Payload/data-shape: boolean branch-gate flag derived from `origin/master` containment for the tagged commit [`.github/workflows/release-npm.yml`]
 - Internal thread communication edges: none.
-- Relationship note: `PROC:main`, `PROC:req-debug`, `PROC:tool-args-to-params`, `PROC:debug-ext`, `PROC:pi-host`, `PROC:gh-release-check`, and `PROC:gh-release-build` are distinct runtime entry modes; only `PROC:req-debug` directly spawns child processes, while the GitHub Actions units coordinate through workflow job dependencies.
+- Relationship note: `PROC:main`, `PROC:req-debug`, `PROC:tool-args-to-params`, `PROC:debug-ext`, `PROC:pi-host`, `PROC:install-static-checkers`, `PROC:gh-release-check`, and `PROC:gh-release-build` are distinct runtime entry modes; only `PROC:req-debug` and `PROC:install-static-checkers` directly spawn child processes, while the GitHub Actions units coordinate through workflow job dependencies.

package/scripts/install-static-checkers.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * @file
+ * @brief Implements the best-effort postinstall installer for bundled static checkers.
+ * @details Probes bundled npm-backed static-check executables (`pyright`, `ruff`, `eslint`), attempts a best-effort `npm install --no-save --prefix` on miss, and prints platform-specific guidance for native checkers (`cppcheck`, `clang-format`). Runtime is dominated by child-process probing and optional npm execution. Side effects include stdout/stderr writes, filesystem reads, and best-effort `npm install` subprocess spawning. The script always exits with code `0` and never modifies git-tracked files.
+ */
+
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { resolveCheckerExecutable } from "../src/core/static-check.js";
+import { getInstallationPath } from "../src/core/path-context.js";
+
+/**
+ * @brief Lists the npm-bundled static-check package names that the extension ships as dependencies.
+ * @details Each entry maps to one executable name resolvable through bundled `node_modules/.bin` after `npm install` completes. Access complexity is O(1).
+ */
+export const BUNDLED_NPM_CHECKERS = ["pyright", "ruff", "eslint"] as const;
+
+/**
+ * @brief Lists the native system-package-manager static-check executables that the extension cannot bundle.
+ * @details Each entry maps to one executable name that users must install through their operating system package manager. Access complexity is O(1).
+ */
+export const NATIVE_CHECKERS = ["cppcheck", "clang-format"] as const;
+
+/**
+ * @brief Maps one bundled npm checker name to its pinned caret install range.
+ * @details Returns the caret range matching the package manifest so best-effort installs stay aligned with declared dependencies. Runtime is O(1). No side effects occur.
+ * @param[in] pkg {string} Bundled npm package name.
+ * @return {string} Pinned caret install range.
+ */
+function bundledCheckerRange(pkg: string): string {
+  switch (pkg) {
+    case "pyright":
+      return "^1.1.411";
+    case "ruff":
+      return "^1.5.4";
+    case "eslint":
+      return "^10.2.0";
+    default:
+      return "latest";
+  }
+}
+
+/**
+ * @brief Prints platform-specific install guidance for native checkers.
+ * @details Detects the current platform and emits one consolidated stderr line per native checker describing the recommended system package manager command. Runtime is O(1). Side effect: writes to stderr.
+ * @return {void} No return value.
+ */
+function printNativeCheckerGuidance(): void {
+  const platform = process.platform;
+  let manager: string;
+  let installPrefix: string;
+  if (platform === "linux") {
+    manager = "apt";
+    installPrefix = "sudo apt install";
+  } else if (platform === "darwin") {
+    manager = "brew";
+    installPrefix = "brew install";
+  } else if (platform === "win32") {
+    manager = "choco/scoop";
+    installPrefix = "choco install";
+  } else {
+    manager = "system package manager";
+    installPrefix = "install";
+  }
+  for (const checker of NATIVE_CHECKERS) {
+    process.stderr.write(
+      `Native checker '${checker}' not found. Install via ${manager}: ${installPrefix} ${checker}\n`,
+    );
+  }
+}
+
+/**
+ * @brief Attempts a best-effort `npm install` for one missing bundled checker.
+ * @details Runs `npm install <pkg>@<range> --no-save --prefix <installation-root>` inside the installation parent directory, swallowing all errors so the postinstall flow never fails. Runtime is dominated by npm execution. Side effects include subprocess spawning and optional writes under the installation root.
+ * @param[in] pkg {string} Bundled npm package name.
+ * @return {void} No return value.
+ */
+function attemptBundledInstall(pkg: string): void {
+  const range = bundledCheckerRange(pkg);
+  const installRoot = path.resolve(getInstallationPath(), "..");
+  try {
+    const result = spawnSync(
+      "npm",
+      ["install", `${pkg}@${range}`, "--no-save", "--prefix", installRoot],
+      { encoding: "utf8" },
+    );
+    if (result.error) {
+      process.stderr.write(`Warning: failed to install bundled checker '${pkg}': ${result.error.message}\n`);
+    }
+  } catch (error) {
+    process.stderr.write(
+      `Warning: failed to install bundled checker '${pkg}': ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+  }
+}
+
+/**
+ * @brief Executes the postinstall static-checker installation flow.
+ * @details Probes each bundled npm checker through `resolveCheckerExecutable`, attempts a best-effort install on miss, prints native-checker guidance for unresolvable native checkers, and always returns `0` so `npm install` never fails because of missing optional checkers. Runtime is dominated by PATH probing and optional npm execution. Side effects include stdout/stderr writes and best-effort `npm install` subprocess spawning. The script never modifies git-tracked files.
+ * @param[in] argv {string[]} Raw CLI arguments (unused, retained for CLI convention parity).
+ * @return {number} Always returns `0`.
+ * @satisfies REQ-339, DES-017
+ */
+export function main(argv = process.argv.slice(2)): number {
+  void argv;
+  for (const checker of BUNDLED_NPM_CHECKERS) {
+    if (resolveCheckerExecutable(checker)) {
+      process.stdout.write(`Bundled static checker '${checker}' is available.\n`);
+      continue;
+    }
+    process.stderr.write(`Bundled static checker '${checker}' not found; attempting best-effort install.\n`);
+    attemptBundledInstall(checker);
+  }
+  const missingNative = NATIVE_CHECKERS.filter((checker) => !resolveCheckerExecutable(checker));
+  if (missingNative.length > 0) {
+    printNativeCheckerGuidance();
+  }
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main();
+}

package/src/core/config.ts

@@ -316,8 +316,8 @@ const DEFAULT_STATIC_CHECK_CHECKERS: Record<string, StaticCheckEntry[]> = {
   TypeScript: [
     {
       module: "Command",
-      cmd: "npx",
-      params: ["eslint"],
+      cmd: "eslint",
+      params: [],
     },
   ],
 };

package/src/core/static-check.ts

@@ -9,8 +9,9 @@ import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 import fg from "fast-glob";
-import type { StaticCheckEntry } from "./config.js";
+import type { StaticCheckEntry, UseReqConfig } from "./config.js";
 import { ReqError } from "./errors.js";
+import { getInstallationPath } from "./path-context.js";
 
 /**
  * @brief Maps user-facing language aliases to canonical static-check language names.
@@ -264,7 +265,7 @@ export function validateStaticCheckEntry(entry: StaticCheckEntry): void {
   if (!cmd) {
     throw new ReqError("Error: Command module requires a cmd argument in --enable-static-check. Format: LANG=Command,CMD[,PARAM...]", 1);
   }
-  if (!findExecutable(cmd)) {
+  if (!resolveCheckerExecutable(cmd)) {
     throw new ReqError(`Error: --enable-static-check Command cmd '${cmd}' is not an executable program on this system.`, 1);
   }
 }
@@ -398,7 +399,7 @@ export class StaticCheckCommand extends StaticCheckBase {
    * @throws {ReqError} Throws when the executable cannot be found on PATH.
    */
   constructor(cmd: string, inputs: string[], extraArgs?: string[], failOnly = false) {
-    if (!findExecutable(cmd)) {
+    if (!resolveCheckerExecutable(cmd)) {
       throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
     }
     super(inputs, extraArgs, failOnly);
@@ -460,7 +461,7 @@ function isExecutableFile(candidate: string): boolean {
  * @param[in] cmd {string} Executable name to locate.
  * @return {string | undefined} Absolute executable path, or `undefined` when not found.
  */
-function findExecutable(cmd: string): string | undefined {
+export function findExecutable(cmd: string): string | undefined {
   if (cmd.includes(path.sep)) {
     return isExecutableFile(cmd) ? path.resolve(cmd) : undefined;
   }
@@ -473,6 +474,59 @@ function findExecutable(cmd: string): string | undefined {
   return undefined;
 }
 
+/**
+ * @brief Resolves one checker executable across bundled `node_modules/.bin` locations and PATH.
+ * @details Probes the installation-owned `node_modules/.bin` directory, the project-scope parent `node_modules/.bin` directory used by `--prefix` layouts, and finally the system PATH scan, returning the first executable match. Runtime is O(p) in PATH entry count plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
+ * @param[in] cmd {string} Executable name or relative path to resolve.
+ * @return {string | undefined} Absolute executable path, or `undefined` when not found in any probed location.
+ * @satisfies REQ-023, REQ-037, DES-018
+ */
+export function resolveCheckerExecutable(cmd: string): string | undefined {
+  if (cmd.includes(path.sep)) {
+    return isExecutableFile(cmd) ? path.resolve(cmd) : undefined;
+  }
+  const installationPath = getInstallationPath();
+  const bundledBinCandidates = [
+    path.join(installationPath, "..", "node_modules", ".bin", cmd),
+    path.join(installationPath, "..", "..", "node_modules", ".bin", cmd),
+  ];
+  for (const candidate of bundledBinCandidates) {
+    if (isExecutableFile(candidate)) {
+      return candidate;
+    }
+  }
+  return findExecutable(cmd);
+}
+
+/**
+ * @brief Determines which enabled static-check executables are missing from the runtime environment.
+ * @details Iterates every enabled language checker entry in the effective config, resolves each `Command` entry executable through `resolveCheckerExecutable`, and collects the missing command names so the caller can surface one consolidated warning. Runtime is O(l * c * p) where l is language count, c is checker count, and p is PATH entry count. Side effects are limited to filesystem reads.
+ * @param[in] config {UseReqConfig} Effective merged configuration.
+ * @return {string[]} Unique command names that are enabled but unresolvable.
+ * @satisfies REQ-341, REQ-343, REQ-344
+ */
+export function checkDefaultCheckersAvailability(config: UseReqConfig): string[] {
+  const missing = new Set<string>();
+  for (const languageConfig of Object.values(config["static-check"] ?? {})) {
+    if (languageConfig.enabled !== "enable") {
+      continue;
+    }
+    for (const entry of languageConfig.checkers) {
+      if (String(entry.module ?? "").trim().toLowerCase() !== "command") {
+        continue;
+      }
+      const cmd = typeof entry.cmd === "string" ? entry.cmd.trim() : "";
+      if (!cmd) {
+        continue;
+      }
+      if (!resolveCheckerExecutable(cmd)) {
+        missing.add(cmd);
+      }
+    }
+  }
+  return [...missing];
+}
+
 /**
  * @brief Dispatches one configured static checker for a single file.
  * @details Selects the debug `Dummy` or user-facing `Command` implementation by module name, normalizes parameter arrays, and runs exactly one checker instance against the target file. Runtime is dominated by the selected checker. Side effects include console output and possible process spawning.
@@ -527,6 +581,9 @@ export function runStaticCheck(argv: string[]): number {
         throw new ReqError("Error: --test-static-check command requires a <cmd> argument.", 1);
       }
       const [cmd, ...files] = rest;
+      if (!resolveCheckerExecutable(cmd!)) {
+        throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
+      }
       return new StaticCheckCommand(cmd!, files).run();
     }
     default:

package/src/index.ts

@@ -172,6 +172,7 @@ import {
 } from "./core/tool-runner.js";
 import { LANGUAGE_TAGS } from "./core/find-constructs.js";
 import {
+  checkDefaultCheckersAvailability,
   getSupportedStaticCheckLanguageSupport,
 } from "./core/static-check.js";
 import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
@@ -1282,6 +1283,13 @@ async function handleExtensionStatusEvent(
     const config = loadProjectConfig(startupCwd);
     applyConfiguredPiUsereqTools(pi, config);
     setPiUsereqStatusConfig(statusController, config);
+    const missingCheckers = checkDefaultCheckersAvailability(config);
+    if (missingCheckers.length > 0) {
+      ctx.ui.notify(
+        `Missing static checkers: ${missingCheckers.join(", ")}\nInstall: run 'npm install' or install each missing checker via your system package manager.`,
+        "warning",
+      );
+    }
   }
   if (hookName === "before_agent_start") {
     const requestForActivation = activePromptRequest ?? pendingPromptRequest;

package/tests/extension-registration.test.ts

@@ -5885,7 +5885,7 @@ test("default configuration applies the documented static-check, debug, notify,
     { module: "Command", cmd: "node", params: ["--check"] },
   ], "enable"));
   assert.deepEqual(config["static-check"].TypeScript, createStaticCheckLanguageConfig([
-    { module: "Command", cmd: "npx", params: ["eslint"] },
+    { module: "Command", cmd: "eslint", params: [] },
   ], "enable"));
   assert.deepEqual(config["static-check"].Ruby, createStaticCheckLanguageConfig([], "disable"));
   assert.equal(config.DEBUG_ENABLED, "disable");

package/tests/static-check-bundled.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @file
+ * @brief Verifies bundled static-checker resolution, postinstall exit-code invariants, and session_start missing-checker notification.
+ * @details Exercises `resolveCheckerExecutable` bundled-bin precedence, the `scripts/install-static-checkers.ts` exit-code-0 invariant, and the `checkDefaultCheckersAvailability` helper used during `session_start`. Runtime is dominated by filesystem metadata checks and optional child-process execution. Side effects are limited to temporary filesystem reads and bounded writes under the installation-owned `node_modules/.bin` with cleanup.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import {
+  resolveCheckerExecutable,
+  checkDefaultCheckersAvailability,
+} from "../src/core/static-check.js";
+import { getInstallationPath } from "../src/core/path-context.js";
+import { getDefaultConfig } from "../src/core/config.js";
+import { main as installStaticCheckersMain } from "../scripts/install-static-checkers.ts";
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const TSX_LOADER = require.resolve("tsx", { paths: [ROOT] });
+
+/**
+ * @brief Resolves the bundled `node_modules/.bin` directory probed by `resolveCheckerExecutable`.
+ * @details Computes the first bundled-bin candidate directory derived from the runtime installation path so tests can create and clean up temporary fake executables at the exact probed location. Runtime is O(1). No side effects occur.
+ * @return {string} Absolute bundled `node_modules/.bin` directory path.
+ */
+function getBundledBinDir(): string {
+  return path.join(getInstallationPath(), "..", "node_modules", ".bin");
+}
+
+test("resolveCheckerExecutable probes bundled node_modules/.bin before PATH scan", () => {
+  const binDir = getBundledBinDir();
+  const fakeName = "pi-usereq-fake-checker";
+  const fakeBin = path.join(binDir, fakeName);
+  const dirExisted = fs.existsSync(binDir);
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(fakeBin, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    const resolved = resolveCheckerExecutable(fakeName);
+    assert.ok(resolved, "expected bundled-bin candidate to resolve");
+    assert.equal(resolved, fakeBin);
+  } finally {
+    if (fs.existsSync(fakeBin)) {
+      fs.rmSync(fakeBin, { force: true });
+    }
+    if (!dirExisted && fs.existsSync(binDir)) {
+      fs.rmSync(binDir, { recursive: true, force: true });
+    }
+  }
+});
+
+test("resolveCheckerExecutable falls back to PATH scan for system executables", () => {
+  const resolved = resolveCheckerExecutable("node");
+  assert.ok(resolved, "expected 'node' to resolve via PATH scan");
+});
+
+test("resolveCheckerExecutable returns undefined for non-existent commands", () => {
+  const resolved = resolveCheckerExecutable("pi-usereq-definitely-not-a-real-binary-xyz");
+  assert.equal(resolved, undefined);
+});
+
+test("scripts/install-static-checkers.ts always returns exit code 0", () => {
+  const exitCode = installStaticCheckersMain([]);
+  assert.equal(exitCode, 0);
+  const exitCodeWithArgs = installStaticCheckersMain(["--ignored"]);
+  assert.equal(exitCodeWithArgs, 0);
+});
+
+test("scripts/install-static-checkers.ts exits 0 when invoked as a subprocess", () => {
+  const result = spawnSync(
+    "node",
+    ["--import", TSX_LOADER, path.join(ROOT, "scripts", "install-static-checkers.ts")],
+    { encoding: "utf8" },
+  );
+  assert.equal(result.status, 0);
+});
+
+test("checkDefaultCheckersAvailability returns missing enabled checkers for default config", () => {
+  const config = getDefaultConfig(process.cwd());
+  const missing = checkDefaultCheckersAvailability(config);
+  assert.ok(Array.isArray(missing), "expected an array of missing checker names");
+  for (const checker of ["cppcheck", "clang-format"]) {
+    if (!resolveCheckerExecutable(checker)) {
+      assert.ok(missing.includes(checker), `expected missing checker '${checker}' to be reported`);
+    }
+  }
+});
+
+test("checkDefaultCheckersAvailability returns empty array when all checkers disabled", () => {
+  const config = getDefaultConfig(process.cwd());
+  for (const languageConfig of Object.values(config["static-check"])) {
+    languageConfig.enabled = "disable";
+  }
+  const missing = checkDefaultCheckersAvailability(config);
+  assert.equal(missing.length, 0);
+});