pi-usereq 0.85.0 → 0.86.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.85.0)
+# PI-useReq/pi-usereq (0.86.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/command-report-entry.ts

@@ -0,0 +1,182 @@
+/**
+ * @file
+ * @brief Persists durable non-agentic command execution reports as custom session entries.
+ * @details Defines the stable custom-entry type, machine-readable report payload, builders for `req-references` outcome lines, and the pi guarded helpers that append the report entry and register its transcript renderer. Custom entries are stored in the session file, excluded from LLM context, rendered live through `entry_appended`, and re-rendered after any session restore, so transient UI-notification collapsing or chat rebuilds never lose the executed-commands outcome report. Runtime is O(n) in report-line count. Side effects are limited to session-entry persistence and renderer registration through the pi extension API.
+ */
+
+import type {
+  CustomEntry,
+  EntryRenderOptions,
+  EntryRenderer,
+  ExtensionAPI,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { formatRuntimePathForDisplay } from "./path-context.js";
+import type { ReqReferencesCommandExecutionResult } from "./req-references-command.js";
+
+/**
+ * @brief Declares the stable custom-entry type used for durable command execution reports.
+ * @details Identifies `pi-usereq` report entries inside the persisted session file so interactive mode renders them through the registered entry renderer after reload, resume, fork, and session switches. Lookup complexity is O(1).
+ */
+export const COMMAND_REPORT_ENTRY_TYPE = "pi-usereq.command-report";
+
+/**
+ * @brief Describes one durable command execution report entry payload.
+ * @details Stores the originating slash-command name, the report severity, the terminal outcome, and the ordered per-operation outcome lines rendered in the transcript. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface CommandReportEntryData {
+  command: string;
+  level: "info" | "error";
+  outcome: "success" | "error";
+  lines: string[];
+}
+
+/**
+ * @brief Describes the loosely-typed pi runtime surface required for durable report entries.
+ * @details Narrows the extension API to the optional `registerEntryRenderer(...)` and `appendEntry(...)` methods consumed by the guarded report helpers so legacy hosts and offline harnesses without custom-entry support degrade silently instead of throwing. The interface is compile-time only and introduces no runtime cost.
+ */
+interface CommandReportEntryRegistrar {
+  registerEntryRenderer?: (
+    customType: string,
+    renderer: EntryRenderer<CommandReportEntryData>,
+  ) => void;
+  appendEntry?: (customType: string, data?: CommandReportEntryData) => void;
+}
+
+/**
+ * @brief Validates one loosely-typed payload as a command report entry payload.
+ * @details Accepts only payloads with a non-empty command string, the documented `info|error` level, the documented `success|error` outcome, and a string-only lines array so malformed session data never reaches the transcript renderer. Runtime is O(n) in line count. No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted payload.
+ * @return {boolean} `true` when the payload satisfies the report entry contract.
+ */
+function isCommandReportEntryData(value: unknown): value is CommandReportEntryData {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<CommandReportEntryData>;
+  return typeof candidate.command === "string"
+    && candidate.command.trim() !== ""
+    && (candidate.level === "info" || candidate.level === "error")
+    && (candidate.outcome === "success" || candidate.outcome === "error")
+    && Array.isArray(candidate.lines)
+    && candidate.lines.every((line) => typeof line === "string");
+}
+
+/**
+ * @brief Builds the ordered per-operation outcome lines for one completed `req-references` run.
+ * @details Emits one machine-readable line per executed operation — terminal outcome, references-file regeneration result, guarded git-commit result, and post-run repository cleanliness — so the durable report states exactly which commands ran and with which outcome. Runtime is O(n) in path length. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {string[]} Ordered report lines starting with the terminal outcome.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportLines(
+  executionResult: ReqReferencesCommandExecutionResult,
+): string[] {
+  const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
+  return [
+    `outcome: success`,
+    `references file ${referencesDisplayPath}: ${
+      executionResult.referencesChanged ? "updated" : "already matched the generated content"
+    }`,
+    `git commit: ${
+      executionResult.commitCreated
+        ? `created "${executionResult.commitMessage}"`
+        : "skipped (references content matched HEAD)"
+    }`,
+    "repository: clean after run",
+  ];
+}
+
+/**
+ * @brief Builds the durable report entry payload for one completed `req-references` run.
+ * @details Pairs the invokable command name with the per-operation outcome lines and the `success` outcome. Runtime is O(n) in report-line count. No external state is mutated.
+ * @param[in] executionResult {ReqReferencesCommandExecutionResult} Per-operation outcome facts of the completed run.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ * @satisfies REQ-436, REQ-437, REQ-438
+ */
+export function buildReqReferencesCommandReportEntryData(
+  executionResult: ReqReferencesCommandExecutionResult,
+): CommandReportEntryData {
+  return {
+    command: "req-references",
+    level: "info",
+    outcome: "success",
+    lines: buildReqReferencesCommandReportLines(executionResult),
+  };
+}
+
+/**
+ * @brief Builds the durable report entry payload for one failed non-agentic command run.
+ * @details Records the invokable command name, the `error` outcome, and the surfaced failure diagnostic so failed runs keep their outcome evidence in the transcript. Runtime is O(n) in message length. No external state is mutated.
+ * @param[in] command {string} Invokable slash-command name that failed.
+ * @param[in] errorMessage {string} Surfaced failure diagnostic.
+ * @return {CommandReportEntryData} Report entry payload for session persistence.
+ */
+export function buildCommandReportErrorEntryData(
+  command: string,
+  errorMessage: string,
+): CommandReportEntryData {
+  return {
+    command,
+    level: "error",
+    outcome: "error",
+    lines: [`outcome: error`, `error: ${errorMessage}`],
+  };
+}
+
+/**
+ * @brief Appends one durable command report entry to the active session when the host supports custom entries.
+ * @details Probes the optional `pi.appendEntry(...)` surface before use so legacy hosts and offline harnesses without custom-entry support skip persistence silently; supported hosts persist the payload as a `custom` session entry that survives session restore while remaining excluded from LLM context. Runtime is O(1) plus delegated session-entry persistence. Side effects include session-file entry persistence on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] data {CommandReportEntryData} Report entry payload to persist.
+ * @return {boolean} `true` when the entry was appended; `false` when the host lacks the custom-entry surface.
+ */
+export function appendCommandReportEntry(pi: ExtensionAPI, data: CommandReportEntryData): boolean {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.appendEntry !== "function") {
+    return false;
+  }
+  registrar.appendEntry(COMMAND_REPORT_ENTRY_TYPE, data);
+  return true;
+}
+
+/**
+ * @brief Renders one durable command report entry as a transcript component.
+ * @details Maps the report payload into a themed multi-line `Text` — header colored `error` for failed runs and `accent` otherwise, body lines colored `error` for failed runs and `muted` otherwise — and returns `undefined` for malformed payloads so the host transcript skips undisplayable entries. Runtime is O(n) in aggregate report-line length. No external state is mutated.
+ * @param[in] entry {CustomEntry<CommandReportEntryData>} Persisted custom report entry.
+ * @param[in] _options {EntryRenderOptions} Host render options; retained for renderer-signature compatibility.
+ * @param[in] theme {Theme} Active pi theme used for color tokens.
+ * @return {Component | undefined} Transcript component, or `undefined` when the payload is malformed.
+ */
+function renderCommandReportEntry(
+  entry: CustomEntry<CommandReportEntryData>,
+  _options: EntryRenderOptions,
+  theme: Theme,
+): Component | undefined {
+  if (!isCommandReportEntryData(entry.data)) {
+    return undefined;
+  }
+  const data = entry.data;
+  const isError = data.level === "error";
+  const headerColor = isError ? "error" : "accent";
+  const bodyColor = isError ? "error" : "muted";
+  const header = theme.fg(headerColor, `pi-usereq ${data.command}: execution report`);
+  const body = data.lines.map((line) => theme.fg(bodyColor, line)).join("\n");
+  return new Text(`${header}\n${body}`, 1, 0);
+}
+
+/**
+ * @brief Registers the durable command report transcript renderer when the host supports entry rendering.
+ * @details Probes the optional `pi.registerEntryRenderer(...)` surface before use so legacy hosts and offline harnesses without custom-entry rendering skip registration silently; supported hosts bind the renderer for `pi-usereq.command-report` entries so appended reports render in the live transcript and re-render after every session restore. Runtime is O(1). Side effects include entry-renderer registration on supported hosts.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @return {void} No return value.
+ */
+export function registerCommandReportEntryRenderer(pi: ExtensionAPI): void {
+  const registrar = pi as ExtensionAPI & CommandReportEntryRegistrar;
+  if (typeof registrar.registerEntryRenderer !== "function") {
+    return;
+  }
+  registrar.registerEntryRenderer(COMMAND_REPORT_ENTRY_TYPE, renderCommandReportEntry);
+}

package/src/index.ts

@@ -174,6 +174,12 @@ import {
   shouldReplayDeferredNotificationsOnSessionStart,
 } from "./core/notification-replay.js";
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
+import {
+  appendCommandReportEntry,
+  buildCommandReportErrorEntryData,
+  buildReqReferencesCommandReportEntryData,
+  registerCommandReportEntryRenderer,
+} from "./core/command-report-entry.js";
 import { ReqError } from "./core/errors.js";
 import {
   PI_USEREQ_STATUS_HOOK_NAMES,
@@ -3493,11 +3499,11 @@ function registerReqResetCommand(
 
 /**
  * @brief Registers the specialized `req-references` slash command.
- * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, and user notifications.
+ * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, and user notifications.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-437, REQ-438, REQ-441
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-436, REQ-437, REQ-438, REQ-441
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3526,6 +3532,7 @@ function registerReqReferencesCommand(
         const executionResult = executeReqReferencesCommandExecution(executionPlan, config);
         setPiUsereqWorkflowState(statusController, "idle", ctx);
         const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
+        appendCommandReportEntry(pi, buildReqReferencesCommandReportEntryData(executionResult));
         notifyContextSafely(
           ctx,
           executionResult.referencesChanged
@@ -3553,6 +3560,7 @@ function registerReqReferencesCommand(
         statusController.state.activePromptRequest = undefined;
         setPiUsereqWorkflowState(statusController, "error", ctx);
         const message = error instanceof Error ? error.message : String(error);
+        appendCommandReportEntry(pi, buildCommandReportErrorEntryData("req-references", message));
         notifyContextSafely(ctx, message, "error");
         throw error;
       }
@@ -5361,13 +5369,14 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, 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, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
+ * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, registers the durable `pi-usereq.command-report` transcript entry renderer, then validates installation-owned bundled resources, schedules a best-effort idle-time shared-tokenizer plus canonical-context-file measurement pre-warm so the first configuration-menu render never pays the one-time `js-tiktoken` module load or first content encodes synchronously, 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, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @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, REQ-326, REQ-327
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   writePersistedPromptCommandRuntimeApi(pi as unknown as PersistedPromptCommandRuntimeApi);
+  registerCommandReportEntryRenderer(pi);
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
   try {