pi-usereq 0.6.0 → 0.10.0

package/pi.dev-src/pi-mono/web-ui/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}

package/scripts/lib/extension-debug-harness.ts

@@ -210,23 +210,16 @@ const PROMPT_COMMAND_EXAMPLES: Record<string, string> = {
  * @details Maps each known registered tool to a stable `npm run debug:ext:tool` example used by the generated manual. Access complexity is O(1).
  */
 const TOOL_EXAMPLES: Record<string, string> = {
-  "git-path": "npm run debug:ext:tool -- --name git-path --cwd . --format pretty",
-  "get-base-path": "npm run debug:ext:tool -- --name get-base-path --cwd . --format pretty",
   "files-tokens": `npm run debug:ext:tool -- --name files-tokens --params '{"files":["pi-usereq/docs/REQUIREMENTS.md","pi-usereq/docs/WORKFLOW.md"]}' --cwd . --format json`,
   "files-references": `npm run debug:ext:tool -- --name files-references --params '{"files":["src/index.ts","src/core/tool-runner.ts"]}' --cwd . --format pretty`,
   "files-compress": `npm run debug:ext:tool -- --name files-compress --params '{"files":["src/index.ts"],"enableLineNumbers":true}' --cwd . --format json`,
-  "files-find": `npm run debug:ext:tool -- --name files-find --params '{"tag":"FUNCTION|METHOD","pattern":"^run","files":["src/core/tool-runner.ts"],"enableLineNumbers":true}' --cwd . --format pretty`,
+  "files-search": `npm run debug:ext:tool -- --name files-search --params '{"tag":"FUNCTION|METHOD","pattern":"^run","files":["src/core/tool-runner.ts"],"enableLineNumbers":true}' --cwd . --format pretty`,
   references: "npm run debug:ext:tool -- --name references --cwd . --format pretty",
   compress: `npm run debug:ext:tool -- --name compress --params '{"enableLineNumbers":true}' --cwd . --format json`,
-  find: `npm run debug:ext:tool -- --name find --params '{"tag":"FUNCTION","pattern":"^run","enableLineNumbers":true}' --cwd . --format pretty`,
+  search: `npm run debug:ext:tool -- --name search --params '{"tag":"FUNCTION","pattern":"^run","enableLineNumbers":true}' --cwd . --format pretty`,
   tokens: "npm run debug:ext:tool -- --name tokens --cwd . --format json",
   "files-static-check": `npm run debug:ext:tool -- --name files-static-check --params '{"files":["src/index.ts"]}' --cwd . --format pretty`,
   "static-check": "npm run debug:ext:tool -- --name static-check --cwd . --format pretty",
-  "git-check": "npm run debug:ext:tool -- --name git-check --cwd . --format pretty",
-  "docs-check": "npm run debug:ext:tool -- --name docs-check --cwd . --format pretty",
-  "git-wt-name": "npm run debug:ext:tool -- --name git-wt-name --cwd . --format pretty",
-  "git-wt-create": `npm run debug:ext:tool -- --name git-wt-create --params '{"wtName":"useReq-demo-main-20260101010101"}' --cwd . --format pretty`,
-  "git-wt-delete": `npm run debug:ext:tool -- --name git-wt-delete --params '{"wtName":"useReq-demo-main-20260101010101"}' --cwd . --format pretty`,
 };
 
 /**
@@ -244,7 +237,7 @@ export function buildDebugManual(snapshot: RecordingExtensionSnapshot): string {
     "- Inspect offline registrations: `npm run debug:ext:inspect -- --cwd . --format pretty`",
     '- Replay session_start offline: `npm run debug:ext:session -- --cwd . --format pretty`',
     '- Replay a command handler offline: `npm run debug:ext:command -- --name req-analyze --args "Analyze src/index.ts" --cwd . --format pretty`',
-    '- Replay a tool handler offline: `npm run debug:ext:tool -- --name git-path --cwd . --format pretty`',
+    `- Replay a tool handler offline: \`npm run debug:ext:tool -- --name files-tokens --params '{"files":["pi-usereq/docs/REQUIREMENTS.md"]}' --cwd . --format pretty\``, 
     '- Run SDK parity smoke: `npm run debug:ext:sdk -- --extension ./src/index.ts --cwd . --format pretty`',
     "",
     "## Prompt commands",

package/scripts/lib/recording-extension-api.ts

@@ -4,6 +4,7 @@
  * @details Provides a minimal pi-compatible extension API plus command-context UI recorder used by the standalone debug harness. The module captures registered commands, registered tools, event handlers, active-tool state, user-message payloads, and UI side effects without invoking the official pi runtime. Runtime cost is O(n) in the number of recorded registrations and side effects. Side effects are limited to in-memory state mutation.
  */
 
+import fs from "node:fs";
 import path from "node:path";
 import {
   PI_USEREQ_DEFAULT_EMBEDDED_TOOL_NAMES,
@@ -258,6 +259,46 @@ function buildBuiltinToolDefinition(name: string): RecordingToolDefinition & { s
   };
 }
 
+/**
+ * @brief Creates one minimal persisted session file for offline command replay.
+ * @details Writes a deterministic session-header-only JSONL file under the requested cwd so prompt-command session switching can exercise `ctx.switchSession(...)` with real session paths during harness replay. Runtime is O(n) in header size. Side effects include filesystem writes.
+ * @param[in] cwd {string} Working directory stored in the session header.
+ * @return {string} Persisted session file path.
+ */
+function createRecordingSessionFile(cwd: string): string {
+  const sessionDir = path.join("/tmp", "pi-usereq-recording-sessions");
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const sessionFile = path.join(
+    sessionDir,
+    `session-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`,
+  );
+  fs.writeFileSync(sessionFile, `${JSON.stringify({
+    type: "session",
+    version: 3,
+    id: path.basename(sessionFile, ".jsonl"),
+    timestamp: new Date(0).toISOString(),
+    cwd,
+  })}\n`, "utf8");
+  return sessionFile;
+}
+
+/**
+ * @brief Reads the cwd encoded in one persisted session header.
+ * @details Parses only the first JSONL line and falls back to the supplied cwd when the file is unreadable or malformed. Runtime is O(n) in header size. Side effects are limited to filesystem reads.
+ * @param[in] sessionFile {string} Persisted session file path.
+ * @param[in] fallbackCwd {string} Fallback cwd when header parsing fails.
+ * @return {string} Parsed session cwd or the fallback cwd.
+ */
+function readRecordingSessionCwd(sessionFile: string, fallbackCwd: string): string {
+  try {
+    const headerLine = fs.readFileSync(sessionFile, "utf8").split(/\r?\n/)[0] ?? "";
+    const header = JSON.parse(headerLine) as { cwd?: unknown };
+    return typeof header.cwd === "string" && header.cwd !== "" ? header.cwd : fallbackCwd;
+  } catch {
+    return fallbackCwd;
+  }
+}
+
 /**
  * @brief Encodes one fake themed fragment for offline status capture.
  * @details Wraps the requested color and text in stable XML-like markers so offline replay can preserve color intent in serialized status snapshots without terminal escape sequences. Runtime is O(n) in text length. No external state is mutated.
@@ -289,9 +330,18 @@ function formatRecordedThemeBackgroundFromForeground(color: string, text: string
 export class RecordingCommandContext {
   /**
    * @brief Stores the working directory exposed to handlers through `ctx.cwd`.
-   * @details The value is immutable after construction and is consumed by extension code that resolves project-local configuration and prompt paths. Access complexity is O(1).
+   * @details The value starts at the requested replay cwd and is updated whenever offline `ctx.switchSession(...)` changes the active session file so extension code can re-read cwd semantics deterministically. Access complexity is O(1).
+   */
+  public cwd: string;
+
+  /**
+   * @brief Exposes the minimal session-manager probes consumed by prompt-command replay.
+   * @details Returns the currently active session cwd and session-file path so extension code can derive session-switch targets without the full runtime session implementation. Access complexity is O(1).
    */
-  public readonly cwd: string;
+  public readonly sessionManager: {
+    getCwd: () => string;
+    getSessionFile: () => string | undefined;
+  };
 
   /**
    * @brief Exposes the recorded UI adapter consumed by extension handlers.
@@ -312,6 +362,7 @@ export class RecordingCommandContext {
 
   private readonly selectQueue: string[];
   private readonly inputQueue: string[];
+  private currentSessionFile: string;
   private readonly notifications: RecordingNotification[] = [];
   private readonly statuses = new Map<string, string>();
   private readonly statusUpdates: RecordingStatusUpdate[] = [];
@@ -334,9 +385,14 @@ export class RecordingCommandContext {
    */
   public constructor(cwd: string, plan?: RecordingUiPlan, recordSessionUserMessage?: (content: JsonValue) => void) {
     this.cwd = cwd;
+    this.currentSessionFile = createRecordingSessionFile(cwd);
     this.selectQueue = [...(plan?.selects ?? [])];
     this.inputQueue = [...(plan?.inputs ?? [])];
     this.recordSessionUserMessage = recordSessionUserMessage ?? (() => undefined);
+    this.sessionManager = {
+      getCwd: () => this.cwd,
+      getSessionFile: () => this.currentSessionFile,
+    };
     this.ui = {
       theme: {
         fg: (color: string, text: string) => formatRecordedThemeForeground(color, text),
@@ -398,6 +454,19 @@ export class RecordingCommandContext {
     return { cancelled: false };
   }
 
+  /**
+   * @brief Simulates `ctx.switchSession(...)` for offline replay.
+   * @details Updates the recorded active session file, rereads the session-header cwd, and mirrors the resulting cwd into `process.cwd()` so prompt-command replay can verify documented session-switch semantics deterministically. Runtime is O(n) in header size. Side effects include process-cwd mutation.
+   * @param[in] sessionPath {string} Target session file path.
+   * @return {Promise<{ cancelled: boolean }>} Deterministic non-cancelled result.
+   */
+  public async switchSession(sessionPath: string): Promise<{ cancelled: boolean }> {
+    this.currentSessionFile = path.resolve(sessionPath);
+    this.cwd = readRecordingSessionCwd(this.currentSessionFile, this.cwd);
+    process.chdir(this.cwd);
+    return { cancelled: false };
+  }
+
   /**
    * @brief Captures one `select` interaction and returns the next scripted response.
    * @details Dequeues one response from the FIFO select plan, records the offered items, and returns `undefined` when no scripted response remains. Runtime is O(m) in item count for defensive copying. Side effects mutate recorder state.

package/scripts/pi-usereq-debug.sh

@@ -96,7 +96,7 @@ 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 tool files-search --args 'FUNCTION ^run src/index.ts --enable-line-numbers'
   ./scripts/pi-usereq-debug.sh raw command --name req-analyze --args "Review REQ-004"
 EOF
 }

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

@@ -97,14 +97,9 @@ function takeBooleanFlag(tokens: string[], flag: string): { tokens: string[]; pr
 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);
       }
@@ -117,10 +112,10 @@ export function buildToolParamsFromArgsText(toolName: string, argsText: string):
       const { tokens: remaining, present } = takeBooleanFlag(tokens, "--enable-line-numbers");
       return present ? { files: remaining, enableLineNumbers: true } : { files: remaining };
     }
-    case "files-find": {
+    case "files-search": {
       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);
+        throw new ReqError("Error: tool files-search requires <tag> <pattern> <file...> in --args text.", 1);
       }
       const [tag, pattern, ...files] = remaining;
       return present ? { tag, pattern, files, enableLineNumbers: true } : { tag, pattern, files };
@@ -132,20 +127,14 @@ export function buildToolParamsFromArgsText(toolName: string, argsText: string):
       }
       return present ? { enableLineNumbers: true } : {};
     }
-    case "find": {
+    case "search": {
       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);
+        throw new ReqError("Error: tool search 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);
   }

package/src/cli.ts

@@ -7,24 +7,23 @@
 
 import process from "node:process";
 import { ReqError } from "./core/errors.js";
-import { loadConfig, normalizeConfigPaths, saveConfig, type UseReqConfig } from "./core/config.js";
+import {
+  createStaticCheckLanguageConfig,
+  loadConfig,
+  normalizeConfigPaths,
+  saveConfig,
+  type UseReqConfig,
+} from "./core/config.js";
 import {
   loadAndRepairConfig,
   resolveProjectBase,
   runCompress,
-  runDocsCheck,
   runFilesCompress,
-  runFilesFind,
+  runFilesSearch,
   runFilesReferences,
   runFilesStaticCheck,
   runFilesTokens,
-  runFind,
-  runGetBasePath,
-  runGitCheck,
-  runGitPath,
-  runGitWtCreate,
-  runGitWtDelete,
-  runGitWtName,
+  runSearch,
   runProjectStaticCheck,
   runReferences,
   runTokens,
@@ -49,20 +48,13 @@ interface ParsedArgs {
   filesTokens?: string[];
   filesReferences?: string[];
   filesCompress?: string[];
-  filesFind?: string[];
+  filesSearch?: string[];
   references?: boolean;
   compress?: boolean;
-  find?: [string, string];
+  search?: [string, string];
   tokens?: boolean;
   filesStaticCheck?: string[];
   staticCheck?: boolean;
-  gitCheck?: boolean;
-  docsCheck?: boolean;
-  gitWtName?: boolean;
-  gitWtCreate?: string;
-  gitWtDelete?: string;
-  gitPath?: boolean;
-  getBasePath?: boolean;
   testStaticCheck?: string[];
 }
 
@@ -128,7 +120,7 @@ function parseArgs(argv: string[]): ParsedArgs {
       }
       case "--files-find": {
         const [values, next] = takeUntilOption(index + 1);
-        parsed.filesFind = values;
+        parsed.filesSearch = values;
         index = next;
         break;
       }
@@ -141,7 +133,7 @@ function parseArgs(argv: string[]): ParsedArgs {
         index += 1;
         break;
       case "--find":
-        parsed.find = [argv[index + 1]!, argv[index + 2]!];
+        parsed.search = [argv[index + 1]!, argv[index + 2]!];
         index += 3;
         break;
       case "--tokens":
@@ -158,34 +150,6 @@ function parseArgs(argv: string[]): ParsedArgs {
         parsed.staticCheck = true;
         index += 1;
         break;
-      case "--git-check":
-        parsed.gitCheck = true;
-        index += 1;
-        break;
-      case "--docs-check":
-        parsed.docsCheck = true;
-        index += 1;
-        break;
-      case "--git-wt-name":
-        parsed.gitWtName = true;
-        index += 1;
-        break;
-      case "--git-wt-create":
-        parsed.gitWtCreate = argv[index + 1];
-        index += 2;
-        break;
-      case "--git-wt-delete":
-        parsed.gitWtDelete = argv[index + 1];
-        index += 2;
-        break;
-      case "--git-path":
-        parsed.gitPath = true;
-        index += 1;
-        break;
-      case "--get-base-path":
-        parsed.getBasePath = true;
-        index += 1;
-        break;
       case "--test-static-check":
         parsed.testStaticCheck = argv.slice(index + 1);
         index = argv.length;
@@ -246,18 +210,18 @@ function loadMutableProjectConfig(projectBase: string): { base: string; config:
 
 /**
  * @brief Applies repeatable `--enable-static-check` specifications to project config.
- * @details Parses each specification, validates command-backed entries before persistence, appends only non-duplicate identities in argument order, preserves existing entries, and writes the merged config once after all validations succeed. Runtime is O(s + e) plus PATH probing where s is spec count and e is existing entry count. Side effects include config writes.
+ * @details Parses each specification, validates command-backed entries before persistence, appends only non-duplicate identities in argument order, preserves existing per-language checker lists, forces each targeted language enable flag to `enable`, and writes the merged config once after all validations succeed. Runtime is O(s + e) plus PATH probing where s is spec count and e is existing entry count. Side effects include config writes.
  * @param[in] projectBase {string} Candidate project root path.
  * @param[in] specs {string[]} Raw `--enable-static-check` specifications in CLI order.
  * @return {UseReqConfig} Persisted merged project configuration.
  * @throws {ReqError} Throws when parsing or validation fails.
- * @satisfies REQ-035, REQ-036, REQ-037
+ * @satisfies REQ-035, REQ-036, REQ-037, REQ-253
  */
 function applyEnableStaticCheckSpecs(projectBase: string, specs: string[]): UseReqConfig {
   const { base, config } = loadMutableProjectConfig(projectBase);
   const seen = new Set<string>();
-  for (const [language, entries] of Object.entries(config["static-check"] ?? {})) {
-    for (const entry of entries) {
+  for (const [language, languageConfig] of Object.entries(config["static-check"] ?? {})) {
+    for (const entry of languageConfig.checkers) {
       seen.add(buildStaticCheckEntryIdentity(language, entry));
     }
   }
@@ -269,8 +233,9 @@ function applyEnableStaticCheckSpecs(projectBase: string, specs: string[]): UseR
     if (seen.has(identity)) {
       continue;
     }
-    config["static-check"][language] ??= [];
-    config["static-check"][language]!.push(entry);
+    config["static-check"][language] ??= createStaticCheckLanguageConfig([]);
+    config["static-check"][language]!.enabled = "enable";
+    config["static-check"][language]!.checkers.push(entry);
     seen.add(identity);
   }
   saveConfig(base, config);
@@ -291,14 +256,12 @@ export function main(argv = process.argv.slice(2)): number {
     }
     const args = parseArgs(argv);
     const hereOnlyProjectCommand = !!(
-      args.references || args.compress || args.tokens || args.find || args.staticCheck ||
-      args.gitCheck || args.docsCheck || args.gitWtName || args.gitWtCreate || args.gitWtDelete ||
-      args.gitPath || args.getBasePath
+      args.references || args.compress || args.tokens || args.search || args.staticCheck
     );
     if (hereOnlyProjectCommand) {
       if (args.base) {
         throw new ReqError(
-          "Error: --references, --compress, --tokens, --find, --static-check, --git-check, --docs-check, --git-wt-name, --git-wt-create, and --git-wt-delete, --git-path, and --get-base-path do not allow --base; use --here.",
+          "Error: --references, --compress, --tokens, --find, and --static-check do not allow --base; use --here.",
           1,
         );
       }
@@ -320,21 +283,14 @@ export function main(argv = process.argv.slice(2)): number {
     if (args.filesTokens) return writeResult(runFilesTokens(args.filesTokens));
     if (args.filesReferences) return writeResult(runFilesReferences(args.filesReferences, process.cwd(), args.verbose));
     if (args.filesCompress) return writeResult(runFilesCompress(args.filesCompress, process.cwd(), args.enableLineNumbers, args.verbose));
-    if (args.filesFind) return writeResult(runFilesFind(args.filesFind, args.enableLineNumbers, args.verbose));
+    if (args.filesSearch) return writeResult(runFilesSearch(args.filesSearch, args.enableLineNumbers, args.verbose));
     if (args.testStaticCheck) return runStaticCheck(args.testStaticCheck);
     if (args.filesStaticCheck) return writeResult(runFilesStaticCheck(args.filesStaticCheck, projectBase, config));
     if (args.references) return writeResult(runReferences(projectBase, config, args.verbose));
     if (args.compress) return writeResult(runCompress(projectBase, config, args.enableLineNumbers, args.verbose));
-    if (args.find) return writeResult(runFind(projectBase, args.find[0], args.find[1], config, args.enableLineNumbers, args.verbose));
+    if (args.search) return writeResult(runSearch(projectBase, args.search[0], args.search[1], config, args.enableLineNumbers, args.verbose));
     if (args.tokens) return writeResult(runTokens(projectBase, config));
     if (args.staticCheck) return writeResult(runProjectStaticCheck(projectBase, config));
-    if (args.gitCheck) return writeResult(runGitCheck(projectBase, config));
-    if (args.docsCheck) return writeResult(runDocsCheck(projectBase, config));
-    if (args.gitWtName) return writeResult(runGitWtName(projectBase, config));
-    if (args.gitWtCreate) return writeResult(runGitWtCreate(projectBase, args.gitWtCreate, config));
-    if (args.gitWtDelete) return writeResult(runGitWtDelete(projectBase, args.gitWtDelete, config));
-    if (args.gitPath) return writeResult(runGitPath(projectBase, config));
-    if (args.getBasePath) return writeResult(runGetBasePath(projectBase, config));
     return 0;
   } catch (error) {
     const err = error as ReqError & { stdout?: string; stderr?: string };