pi-usereq 0.12.0 → 0.32.0

package/src/core/debug-runtime.ts

@@ -45,6 +45,13 @@ export const DEFAULT_DEBUG_STATUS_CHANGES = "disable" as const;
  */
 export const DEFAULT_DEBUG_WORKFLOW_EVENTS = "disable" as const;
 
+/**
+ * @brief Defines the default debug-tool command-wrapper mode.
+ * @details New configs suppress debug slash-command wrappers for selected built-in tools until the user explicitly enables them from the `Debug` submenu. Access complexity is O(1).
+ * @satisfies CTN-019, REQ-322
+ */
+export const DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED = "disable" as const;
+
 /**
  * @brief Defines the default workflow-status filter used by debug logging.
  * @details New configs log only entries whose workflow state equals `running` until the user selects a broader or different workflow-state filter. Access complexity is O(1).
@@ -98,6 +105,12 @@ export type DebugStatusChanges = "enable" | "disable";
  */
 export type DebugWorkflowEvents = "enable" | "disable";
 
+/**
+ * @brief Represents one persisted debug-tool command-wrapper flag.
+ * @details Restricts debug slash-command wrapper registration to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
+ */
+export type DebugToolCommandsEnabled = "enable" | "disable";
+
 /**
  * @brief Represents one persisted workflow-status filter value.
  * @details Restricts debug log filtering to `any` or one explicit documented workflow state. The alias is compile-time only and introduces no runtime cost.
@@ -191,6 +204,17 @@ export function normalizeDebugWorkflowEvents(value: unknown): DebugWorkflowEvent
   return value === "enable" ? "enable" : DEFAULT_DEBUG_WORKFLOW_EVENTS;
 }
 
+/**
+ * @brief Normalizes one persisted debug-tool command-wrapper flag.
+ * @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED` for all other payloads. Runtime is O(1). No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted debug-tool command-wrapper payload.
+ * @return {DebugToolCommandsEnabled} Canonical debug-tool command-wrapper flag.
+ * @satisfies CTN-019, REQ-322
+ */
+export function normalizeDebugToolCommandsEnabled(value: unknown): DebugToolCommandsEnabled {
+  return value === "enable" ? "enable" : DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
+}
+
 /**
  * @brief Normalizes one persisted debug workflow-status filter.
  * @details Accepts only the documented `any` token or one explicit workflow state and falls back to `DEFAULT_DEBUG_LOG_ON_STATUS` for all other payloads. Runtime is O(1). No external state is mutated.

package/src/core/extension-status.ts

@@ -689,7 +689,7 @@ export function setPiUsereqStatusConfig(
 
 /**
  * @brief Returns the active runtime sound level tracked by the status controller.
- * @details Exposes the in-memory runtime sound state so shortcut handlers and prompt-end notification dispatch can stay decoupled from the persisted boot value stored in `.pi-usereq.json`. Runtime is O(1). No external state is mutated.
+ * @details Exposes the in-memory runtime sound state so shortcut handlers and prompt-end notification dispatch can stay decoupled from the persisted boot value stored in global configuration. Runtime is O(1). No external state is mutated.
  * @param[in] controller {PiUsereqStatusController} Mutable status controller.
  * @return {PiNotifySoundLevel} Active runtime sound level.
  * @satisfies REQ-180, REQ-285
@@ -702,7 +702,7 @@ export function getPiUsereqRuntimeSoundLevel(
 
 /**
  * @brief Stores one new runtime sound level and refreshes the status bar.
- * @details Mutates only the in-memory runtime sound state so shortcut-driven sound changes do not update `.pi-usereq.json`, then re-renders the footer when an active extension context is available. Runtime is O(1). Side effect: mutates `controller.state.runtimeSoundLevel` and may update `ctx.ui` status.
+ * @details Mutates only the in-memory runtime sound state so shortcut-driven sound changes do not update persisted local or global configuration, then re-renders the footer when an active extension context is available. Runtime is O(1). Side effect: mutates `controller.state.runtimeSoundLevel` and may update `ctx.ui` status.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] runtimeSoundLevel {PiNotifySoundLevel} Next active runtime sound level.
  * @param[in] ctx {ExtensionContext | undefined} Optional active extension context.

package/src/core/path-context.ts

@@ -11,11 +11,17 @@ import { fileURLToPath } from "node:url";
 import type { UseReqConfig } from "./config.js";
 
 /**
- * @brief Defines the per-project configuration file name.
- * @details The file lives directly under `base-path` and stores only persisted project configuration. Access complexity is O(1).
+ * @brief Defines the per-project local configuration file name.
+ * @details The file lives directly under `base-path` and stores only persisted project-scoped configuration. Access complexity is O(1).
  */
 export const PROJECT_CONFIG_FILENAME = ".pi-usereq.json";
 
+/**
+ * @brief Defines the home-relative global configuration file path.
+ * @details The path is resolved against the current user home directory and stores persisted cross-project configuration. Access complexity is O(1).
+ */
+export const GLOBAL_CONFIG_RELATIVE_PATH = ".config/pi-usereq/config.json";
+
 /**
  * @brief Defines the bundled resources directory name under the installation path.
  * @details The directory contains prompts, templates, and guidelines shipped with the installed extension payload. Access complexity is O(1).
@@ -155,15 +161,24 @@ export function normalizeRelativeDirContract(value: string): string {
 }
 
 /**
- * @brief Computes the absolute project config path for one base path.
+ * @brief Computes the absolute local project config path for one base path.
  * @details Appends `.pi-usereq.json` to the supplied base path using the canonical repository-local configuration layout. Runtime is O(1). No external state is mutated.
  * @param[in] basePath {string} Absolute or relative base path.
- * @return {string} Absolute config-file path.
+ * @return {string} Absolute local config-file path.
  */
 export function getConfigPath(basePath: string): string {
   return path.join(path.resolve(basePath), PROJECT_CONFIG_FILENAME);
 }
 
+/**
+ * @brief Computes the absolute global config path for the current user.
+ * @details Resolves `~/.config/pi-usereq/config.json` from the current user home directory without consulting project state. Runtime is O(1). No external state is mutated.
+ * @return {string} Absolute global config-file path.
+ */
+export function getGlobalConfigPath(): string {
+  return path.join(os.homedir(), GLOBAL_CONFIG_RELATIVE_PATH);
+}
+
 /**
  * @brief Tests whether one path is identical to or an ancestor of another path.
  * @details Resolves both inputs, computes a relative traversal from the candidate ancestor to the candidate child, and accepts only exact matches or descendant traversals that stay within the ancestor subtree. Runtime is O(p) in path length. No external state is mutated.