@salesforce/b2c-tooling-sdk 1.0.1 → 1.2.0

package/dist/esm/safety/safety-middleware.d.ts

@@ -1,3 +1,5 @@
+import type { SafetyRule } from './types.js';
+import type { SafetyEvaluation } from './types.js';
 /**
  * Safety levels for preventing destructive operations.
  *
@@ -7,11 +9,34 @@
  * - READ_ONLY: Block all write operations (only GET allowed)
  */
 export type SafetyLevel = 'NONE' | 'NO_DELETE' | 'NO_UPDATE' | 'READ_ONLY';
+/**
+ * Safety configuration.
+ *
+ * Supports both simple level-based blocking and granular per-rule actions.
+ */
 export interface SafetyConfig {
+    /** The base safety level. */
     level: SafetyLevel;
+    /** When true, operations that the level would block require confirmation instead of hard-blocking. */
+    confirm?: boolean;
+    /** Ordered list of rules. First matching rule wins. */
+    rules?: SafetyRule[];
 }
 /**
- * Safety error thrown when an operation is blocked by safety middleware.
+ * Returns the more restrictive of two safety levels.
+ */
+export declare function maxSafetyLevel(a: SafetyLevel, b: SafetyLevel): SafetyLevel;
+/**
+ * Check if a string is a valid SafetyLevel.
+ */
+export declare function isValidSafetyLevel(value: string): value is SafetyLevel;
+/**
+ * Parse a string to a SafetyLevel, returning undefined for invalid values.
+ * Accepts case-insensitive input and converts dashes to underscores.
+ */
+export declare function parseSafetyLevelString(value: string | undefined): SafetyLevel | undefined;
+/**
+ * Safety error thrown when an operation is blocked by safety configuration.
  */
 export declare class SafetyBlockedError extends Error {
     readonly method: string;
@@ -19,6 +44,28 @@ export declare class SafetyBlockedError extends Error {
     readonly safetyLevel: SafetyLevel;
     constructor(message: string, method: string, url: string, safetyLevel: SafetyLevel);
 }
+/**
+ * Error thrown when an operation requires interactive confirmation.
+ *
+ * Callers can catch this error, prompt the user, and retry the operation
+ * using {@link withSafetyConfirmation}.
+ */
+export declare class SafetyConfirmationRequired extends Error {
+    readonly evaluation: SafetyEvaluation;
+    constructor(evaluation: SafetyEvaluation);
+}
+/**
+ * Checks if an HTTP operation should be blocked based on a safety level.
+ *
+ * This is the low-level level check. For full rule-based evaluation,
+ * use {@link SafetyGuard.evaluate}.
+ *
+ * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE)
+ * @param path - URL pathname
+ * @param level - Safety level to check against
+ * @returns Error message if blocked, undefined if allowed
+ */
+export declare function checkLevelViolation(method: string, path: string, level: SafetyLevel): string | undefined;
 /**
  * Checks if an HTTP operation should be blocked based on safety configuration.
  *
@@ -26,6 +73,7 @@ export declare class SafetyBlockedError extends Error {
  * @param url - Request URL
  * @param config - Safety configuration
  * @returns Error message if blocked, undefined if allowed
+ * @deprecated Use {@link SafetyGuard.evaluate} for full rule-based evaluation.
  */
 export declare function checkSafetyViolation(method: string, url: string, config: SafetyConfig): string | undefined;
 /**
@@ -43,3 +91,40 @@ export declare function getSafetyLevel(defaultLevel?: SafetyLevel): SafetyLevel;
  * Get a user-friendly description of the safety level.
  */
 export declare function describeSafetyLevel(level: SafetyLevel): string;
+/** Validated safety config fragment (shared by global and per-instance). */
+export interface SafetyConfigFragment {
+    level?: SafetyLevel;
+    confirm?: boolean;
+    rules?: SafetyRule[];
+}
+/**
+ * Load global safety configuration from a JSON file.
+ *
+ * Resolution order:
+ * 1. `SFCC_SAFETY_CONFIG` env var — explicit path to a safety config file
+ * 2. `{configDir}/safety.json` — oclif config directory (e.g., `~/.config/b2c/safety.json`)
+ *
+ * The file has the same shape as the `safety` object in dw.json:
+ * ```json
+ * { "level": "NO_DELETE", "confirm": true, "rules": [...] }
+ * ```
+ *
+ * @param configDir - oclif config directory path (e.g., `this.config.configDir`)
+ * @returns Validated safety config fragment, or undefined if no file found
+ */
+export declare function loadGlobalSafetyConfig(configDir?: string): SafetyConfigFragment | undefined;
+/**
+ * Compute effective safety config by merging environment variables, global
+ * safety config, and per-instance config.
+ *
+ * Merge strategy:
+ * - **Level**: `max(env, global, instance)` — most restrictive wins
+ * - **Confirm**: OR across all sources
+ * - **Rules**: instance rules first, then global rules (first-match-wins,
+ *   so instance rules can override global policy)
+ *
+ * @param instanceSafety - Per-instance safety config from dw.json
+ * @param globalSafety - Global safety config from safety.json
+ * @returns Merged SafetyConfig
+ */
+export declare function resolveEffectiveSafetyConfig(instanceSafety?: SafetyConfigFragment, globalSafety?: SafetyConfigFragment): SafetyConfig;

package/dist/esm/safety/safety-middleware.js

@@ -3,9 +3,47 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { getLogger } from '../logging/logger.js';
+import { isValidSafetyAction } from './types.js';
 /**
- * Safety error thrown when an operation is blocked by safety middleware.
+ * Ordering of safety levels from least to most restrictive.
+ */
+const LEVEL_ORDER = {
+    NONE: 0,
+    NO_DELETE: 1,
+    NO_UPDATE: 2,
+    READ_ONLY: 3,
+};
+/**
+ * Valid safety level strings.
+ */
+const VALID_LEVELS = ['NONE', 'NO_DELETE', 'NO_UPDATE', 'READ_ONLY'];
+/**
+ * Returns the more restrictive of two safety levels.
+ */
+export function maxSafetyLevel(a, b) {
+    return LEVEL_ORDER[a] >= LEVEL_ORDER[b] ? a : b;
+}
+/**
+ * Check if a string is a valid SafetyLevel.
+ */
+export function isValidSafetyLevel(value) {
+    return VALID_LEVELS.includes(value);
+}
+/**
+ * Parse a string to a SafetyLevel, returning undefined for invalid values.
+ * Accepts case-insensitive input and converts dashes to underscores.
+ */
+export function parseSafetyLevelString(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.toUpperCase().replace(/-/g, '_');
+    return isValidSafetyLevel(normalized) ? normalized : undefined;
+}
+/**
+ * Safety error thrown when an operation is blocked by safety configuration.
  */
 export class SafetyBlockedError extends Error {
     method;
@@ -20,35 +58,50 @@ export class SafetyBlockedError extends Error {
     }
 }
 /**
- * Checks if an HTTP operation should be blocked based on safety configuration.
+ * Error thrown when an operation requires interactive confirmation.
+ *
+ * Callers can catch this error, prompt the user, and retry the operation
+ * using {@link withSafetyConfirmation}.
+ */
+export class SafetyConfirmationRequired extends Error {
+    evaluation;
+    constructor(evaluation) {
+        super(`Confirmation required: ${evaluation.reason}`);
+        this.evaluation = evaluation;
+        this.name = 'SafetyConfirmationRequired';
+    }
+}
+/**
+ * Checks if an HTTP operation should be blocked based on a safety level.
+ *
+ * This is the low-level level check. For full rule-based evaluation,
+ * use {@link SafetyGuard.evaluate}.
  *
  * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE)
- * @param url - Request URL
- * @param config - Safety configuration
+ * @param path - URL pathname
+ * @param level - Safety level to check against
  * @returns Error message if blocked, undefined if allowed
  */
-export function checkSafetyViolation(method, url, config) {
+export function checkLevelViolation(method, path, level) {
     const upperMethod = method.toUpperCase();
-    const path = new URL(url, 'http://dummy').pathname;
-    switch (config.level) {
+    switch (level) {
         case 'NONE':
-            return undefined; // No restrictions
+            return undefined;
         case 'NO_DELETE':
             if (upperMethod === 'DELETE') {
                 return `Delete operation blocked: DELETE ${path} (NO_DELETE mode prevents deletions)`;
             }
             return undefined;
-        case 'NO_UPDATE':
-            // Block DELETE operations
+        case 'NO_UPDATE': {
             if (upperMethod === 'DELETE') {
                 return `Delete operation blocked: DELETE ${path} (NO_UPDATE mode prevents deletions)`;
             }
-            // Block operations that contain reset, stop, restart in path or might be destructive
             const destructivePatterns = ['/reset', '/stop', '/restart', '/operations'];
             if (destructivePatterns.some((pattern) => path.includes(pattern)) && upperMethod === 'POST') {
                 return `Destructive operation blocked: POST ${path} (NO_UPDATE mode prevents reset/stop/restart)`;
             }
             return undefined;
+        }
         case 'READ_ONLY':
             if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(upperMethod)) {
                 return `Write operation blocked: ${upperMethod} ${path} (READ_ONLY mode prevents all modifications)`;
@@ -58,6 +111,19 @@ export function checkSafetyViolation(method, url, config) {
             return undefined;
     }
 }
+/**
+ * Checks if an HTTP operation should be blocked based on safety configuration.
+ *
+ * @param method - HTTP method (GET, POST, PUT, PATCH, DELETE)
+ * @param url - Request URL
+ * @param config - Safety configuration
+ * @returns Error message if blocked, undefined if allowed
+ * @deprecated Use {@link SafetyGuard.evaluate} for full rule-based evaluation.
+ */
+export function checkSafetyViolation(method, url, config) {
+    const path = new URL(url, 'http://dummy').pathname;
+    return checkLevelViolation(method, path, config.level);
+}
 /**
  * Parse safety level from environment variable.
  *
@@ -71,11 +137,10 @@ export function checkSafetyViolation(method, url, config) {
 export function getSafetyLevel(defaultLevel = 'NONE') {
     const safetyLevelEnv = process.env['SFCC_SAFETY_LEVEL'];
     if (safetyLevelEnv) {
-        const upper = safetyLevelEnv.toUpperCase().replace(/-/g, '_');
-        if (['NONE', 'NO_DELETE', 'NO_UPDATE', 'READ_ONLY'].includes(upper)) {
-            return upper;
-        }
-        getLogger().warn({ envValue: safetyLevelEnv, validValues: ['NONE', 'NO_DELETE', 'NO_UPDATE', 'READ_ONLY'] }, 'SFCC_SAFETY_LEVEL has an invalid value; using default safety level');
+        const parsed = parseSafetyLevelString(safetyLevelEnv);
+        if (parsed)
+            return parsed;
+        getLogger().warn({ envValue: safetyLevelEnv, validValues: VALID_LEVELS }, 'SFCC_SAFETY_LEVEL has an invalid value; using default safety level');
     }
     return defaultLevel;
 }
@@ -96,4 +161,88 @@ export function describeSafetyLevel(level) {
             return 'Unknown safety level';
     }
 }
+/**
+ * Load global safety configuration from a JSON file.
+ *
+ * Resolution order:
+ * 1. `SFCC_SAFETY_CONFIG` env var — explicit path to a safety config file
+ * 2. `{configDir}/safety.json` — oclif config directory (e.g., `~/.config/b2c/safety.json`)
+ *
+ * The file has the same shape as the `safety` object in dw.json:
+ * ```json
+ * { "level": "NO_DELETE", "confirm": true, "rules": [...] }
+ * ```
+ *
+ * @param configDir - oclif config directory path (e.g., `this.config.configDir`)
+ * @returns Validated safety config fragment, or undefined if no file found
+ */
+export function loadGlobalSafetyConfig(configDir) {
+    const logger = getLogger();
+    // 1. Check SFCC_SAFETY_CONFIG env var
+    const envPath = process.env['SFCC_SAFETY_CONFIG'];
+    const filePath = envPath || (configDir ? join(configDir, 'safety.json') : undefined);
+    if (!filePath || !existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        const result = {};
+        if (raw.level) {
+            const parsed = parseSafetyLevelString(raw.level);
+            if (parsed) {
+                result.level = parsed;
+            }
+            else {
+                logger.warn({ level: raw.level, file: filePath }, 'Invalid safety level in global safety config; ignoring');
+            }
+        }
+        if (raw.confirm !== undefined) {
+            result.confirm = raw.confirm === true;
+        }
+        if (raw.rules && Array.isArray(raw.rules)) {
+            result.rules = raw.rules.filter((r) => {
+                if (!isValidSafetyAction(r.action)) {
+                    logger.warn({ rule: r, file: filePath }, 'Invalid safety rule action in global safety config; skipping rule');
+                    return false;
+                }
+                return true;
+            });
+        }
+        logger.trace({ filePath, level: result.level, ruleCount: result.rules?.length }, 'Loaded global safety config');
+        return result;
+    }
+    catch (error) {
+        logger.warn({ error, file: filePath }, 'Failed to load global safety config; ignoring');
+        return undefined;
+    }
+}
+/**
+ * Compute effective safety config by merging environment variables, global
+ * safety config, and per-instance config.
+ *
+ * Merge strategy:
+ * - **Level**: `max(env, global, instance)` — most restrictive wins
+ * - **Confirm**: OR across all sources
+ * - **Rules**: instance rules first, then global rules (first-match-wins,
+ *   so instance rules can override global policy)
+ *
+ * @param instanceSafety - Per-instance safety config from dw.json
+ * @param globalSafety - Global safety config from safety.json
+ * @returns Merged SafetyConfig
+ */
+export function resolveEffectiveSafetyConfig(instanceSafety, globalSafety) {
+    const envLevel = getSafetyLevel('NONE');
+    const envConfirm = process.env['SFCC_SAFETY_CONFIRM'] === 'true' || process.env['SFCC_SAFETY_CONFIRM'] === '1';
+    const instanceLevel = instanceSafety?.level ?? 'NONE';
+    const globalLevel = globalSafety?.level ?? 'NONE';
+    // Merge rules: instance first, then global (first-match-wins)
+    const instanceRules = instanceSafety?.rules ?? [];
+    const globalRules = globalSafety?.rules ?? [];
+    const mergedRules = [...instanceRules, ...globalRules];
+    return {
+        level: maxSafetyLevel(envLevel, maxSafetyLevel(globalLevel, instanceLevel)),
+        confirm: envConfirm || instanceSafety?.confirm === true || globalSafety?.confirm === true,
+        rules: mergedRules.length > 0 ? mergedRules : undefined,
+    };
+}
 //# sourceMappingURL=safety-middleware.js.map

package/dist/esm/safety/safety-middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"safety-middleware.js","sourceRoot":"","sources":["../../../src/safety/safety-middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"safety-middleware.js","sourceRoot":"","sources":["../../../src/safety/safety-middleware.ts"],"names":[],"mappings":"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"}

package/dist/esm/safety/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for the safety evaluation system.
+ *
+ * @module safety/types
+ */
+/**
+ * Action that a safety evaluation can produce.
+ *
+ * - `allow`: Operation is permitted
+ * - `block`: Operation is refused
+ * - `confirm`: Operation requires interactive confirmation before proceeding
+ */
+export type SafetyAction = 'allow' | 'block' | 'confirm';
+/**
+ * A safety rule that matches operations and specifies an action.
+ *
+ * Rules support three matcher types, all using glob patterns (via minimatch):
+ * - `method` + `path`: Matches HTTP requests by method and URL path
+ * - `job`: Matches job execution by job ID (extracted from OCAPI URLs)
+ * - `command`: Matches CLI commands by oclif command ID (e.g., "sandbox:delete")
+ *
+ * @example
+ * ```json
+ * { "job": "sfcc-site-archive-export", "action": "allow" }
+ * { "command": "ecdn:cache:purge", "action": "confirm" }
+ * { "method": "DELETE", "path": "/code_versions/*", "action": "block" }
+ * ```
+ */
+export interface SafetyRule {
+    /** HTTP method pattern (e.g., "POST", "DELETE"). Omit to match any method. */
+    method?: string;
+    /** URL path glob pattern (e.g., "/jobs/*/executions"). Matched with minimatch. */
+    path?: string;
+    /** Job ID glob pattern. Matches OCAPI job execution URLs by job ID. */
+    job?: string;
+    /** CLI command ID glob pattern (e.g., "sandbox:*", "ecdn:cache:purge"). */
+    command?: string;
+    /** Action to take when this rule matches. */
+    action: SafetyAction;
+}
+/**
+ * An operation being evaluated for safety.
+ *
+ * Constructed by the caller (HTTP middleware, CLI command, etc.) and passed
+ * to {@link SafetyGuard.evaluate} for rule matching.
+ */
+export interface SafetyOperation {
+    /** The type of operation being evaluated. */
+    type: 'http' | 'job' | 'command';
+    /** HTTP method (for http operations). */
+    method?: string;
+    /** Full request URL (for http operations). */
+    url?: string;
+    /** Parsed URL pathname (for http operations). */
+    path?: string;
+    /** Job identifier (for job operations, or extracted from http operation URLs). */
+    jobId?: string;
+    /** CLI command ID, e.g., "sandbox:delete" (for command operations). */
+    commandId?: string;
+}
+/**
+ * Result of evaluating an operation against safety rules.
+ */
+export interface SafetyEvaluation {
+    /** The action determined by evaluation. */
+    action: SafetyAction;
+    /** Human-readable explanation of why this action was chosen. */
+    reason: string;
+    /** The operation that was evaluated. */
+    operation: SafetyOperation;
+    /** The rule that matched, or undefined if the level default was used. */
+    rule?: SafetyRule;
+}
+/**
+ * Validated safety actions for use in rule parsing.
+ */
+export declare const VALID_SAFETY_ACTIONS: readonly SafetyAction[];
+/**
+ * Check if a string is a valid SafetyAction.
+ */
+export declare function isValidSafetyAction(value: string): value is SafetyAction;

package/dist/esm/safety/types.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Validated safety actions for use in rule parsing.
+ */
+export const VALID_SAFETY_ACTIONS = ['allow', 'block', 'confirm'];
+/**
+ * Check if a string is a valid SafetyAction.
+ */
+export function isValidSafetyAction(value) {
+    return VALID_SAFETY_ACTIONS.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/safety/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/safety/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgFH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA4B,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAEpG;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,oBAAoB,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AAC9D,CAAC"}

package/dist/esm/safety/with-confirmation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Confirmation flow utility for safety-guarded operations.
+ *
+ * @module safety/with-confirmation
+ */
+import type { SafetyGuard } from './safety-guard.js';
+import type { SafetyEvaluation } from './types.js';
+/**
+ * Handler that prompts a user for confirmation.
+ *
+ * Implementations vary by context:
+ * - CLI: readline-based prompt
+ * - VS Code: `vscode.window.showWarningMessage({ modal: true })`
+ * - MCP/non-interactive: always returns `false`
+ *
+ * @param evaluation - The safety evaluation that triggered confirmation
+ * @returns true if the user confirmed, false to cancel
+ */
+export type ConfirmHandler = (evaluation: SafetyEvaluation) => Promise<boolean>;
+/**
+ * Execute an operation with safety confirmation support.
+ *
+ * If the operation throws {@link SafetyConfirmationRequired}, the
+ * `confirmHandler` is called. If the user confirms, the operation
+ * is retried with a temporary exemption. If the user cancels (or
+ * the handler returns false), a {@link SafetyBlockedError} is thrown.
+ *
+ * Non-confirmation errors are re-thrown as-is.
+ *
+ * @param guard - The SafetyGuard instance
+ * @param operation - The operation to execute
+ * @param confirmHandler - Context-specific confirmation handler
+ * @returns The operation's return value
+ *
+ * @example
+ * ```typescript
+ * // CLI usage
+ * const result = await withSafetyConfirmation(
+ *   guard,
+ *   () => instance.ocapi.POST('/jobs/import/executions', ...),
+ *   async (eval) => {
+ *     if (!process.stdin.isTTY) return false;
+ *     return confirm(`Safety: ${eval.reason}. Proceed?`);
+ *   },
+ * );
+ *
+ * // VS Code usage
+ * const result = await withSafetyConfirmation(
+ *   guard,
+ *   () => runJobImport(),
+ *   async (eval) => {
+ *     const choice = await vscode.window.showWarningMessage(eval.reason, { modal: true }, 'Proceed');
+ *     return choice === 'Proceed';
+ *   },
+ * );
+ * ```
+ */
+export declare function withSafetyConfirmation<T>(guard: SafetyGuard, operation: () => Promise<T>, confirmHandler: ConfirmHandler): Promise<T>;

package/dist/esm/safety/with-confirmation.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { SafetyBlockedError, SafetyConfirmationRequired } from './safety-middleware.js';
+/**
+ * Execute an operation with safety confirmation support.
+ *
+ * If the operation throws {@link SafetyConfirmationRequired}, the
+ * `confirmHandler` is called. If the user confirms, the operation
+ * is retried with a temporary exemption. If the user cancels (or
+ * the handler returns false), a {@link SafetyBlockedError} is thrown.
+ *
+ * Non-confirmation errors are re-thrown as-is.
+ *
+ * @param guard - The SafetyGuard instance
+ * @param operation - The operation to execute
+ * @param confirmHandler - Context-specific confirmation handler
+ * @returns The operation's return value
+ *
+ * @example
+ * ```typescript
+ * // CLI usage
+ * const result = await withSafetyConfirmation(
+ *   guard,
+ *   () => instance.ocapi.POST('/jobs/import/executions', ...),
+ *   async (eval) => {
+ *     if (!process.stdin.isTTY) return false;
+ *     return confirm(`Safety: ${eval.reason}. Proceed?`);
+ *   },
+ * );
+ *
+ * // VS Code usage
+ * const result = await withSafetyConfirmation(
+ *   guard,
+ *   () => runJobImport(),
+ *   async (eval) => {
+ *     const choice = await vscode.window.showWarningMessage(eval.reason, { modal: true }, 'Proceed');
+ *     return choice === 'Proceed';
+ *   },
+ * );
+ * ```
+ */
+export async function withSafetyConfirmation(guard, operation, confirmHandler) {
+    try {
+        return await operation();
+    }
+    catch (err) {
+        if (err instanceof SafetyConfirmationRequired) {
+            const confirmed = await confirmHandler(err.evaluation);
+            if (!confirmed) {
+                throw new SafetyBlockedError(`Operation cancelled: ${err.evaluation.reason}`, err.evaluation.operation.method ?? '', err.evaluation.operation.url ?? '', guard.config.level);
+            }
+            // Temporarily allow this specific operation and retry
+            const cleanup = guard.temporarilyAllow(err.evaluation.operation);
+            try {
+                return await operation();
+            }
+            finally {
+                cleanup();
+            }
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=with-confirmation.js.map

package/dist/esm/safety/with-confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-confirmation.js","sourceRoot":"","sources":["../../../src/safety/with-confirmation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,EAAC,kBAAkB,EAAE,0BAA0B,EAAC,MAAM,wBAAwB,CAAC;AAetF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,KAAkB,EAClB,SAA2B,EAC3B,cAA8B;IAE9B,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,0BAA0B,EAAE,CAAC;YAC9C,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACvD,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,IAAI,kBAAkB,CAC1B,wBAAwB,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,EAC/C,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,EACrC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,EAClC,KAAK,CAAC,MAAM,CAAC,KAAK,CACnB,CAAC;YACJ,CAAC;YAED,sDAAsD;YACtD,MAAM,OAAO,GAAG,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YACjE,IAAI,CAAC;gBACH,OAAO,MAAM,SAAS,EAAE,CAAC;YAC3B,CAAC;oBAAS,CAAC;gBACT,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/esm/ux/confirm.d.ts

@@ -0,0 +1,14 @@
+export interface ConfirmOptions {
+    /** Default to yes when the user presses Enter without typing. Defaults to false (no). */
+    defaultYes?: boolean;
+}
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * Output goes to stderr so it doesn't interfere with structured stdout output.
+ *
+ * @param message - Prompt message (the hint is appended automatically)
+ * @param options - Options to control default behavior
+ * @returns true if user confirmed, false otherwise
+ */
+export declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;

package/dist/esm/ux/confirm.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import * as readline from 'node:readline';
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * Output goes to stderr so it doesn't interfere with structured stdout output.
+ *
+ * @param message - Prompt message (the hint is appended automatically)
+ * @param options - Options to control default behavior
+ * @returns true if user confirmed, false otherwise
+ */
+export async function confirm(message, options) {
+    const defaultYes = options?.defaultYes ?? false;
+    const hint = defaultYes ? '(Y/n)' : '(y/N)';
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} ${hint} `, (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === '') {
+                resolve(defaultYes);
+            }
+            else {
+                resolve(normalized === 'y' || normalized === 'yes');
+            }
+        });
+    });
+}
+//# sourceMappingURL=confirm.js.map

package/dist/esm/ux/confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm.js","sourceRoot":"","sources":["../../../src/ux/confirm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAO1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe,EAAE,OAAwB;IACrE,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,KAAK,CAAC;IAChD,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAE5C,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,EAAE,CAAC,QAAQ,CAAC,GAAG,OAAO,IAAI,IAAI,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE;YAC5C,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC/C,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;gBACtB,OAAO,CAAC,UAAU,CAAC,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,KAAK,CAAC,CAAC;YACtD,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}