@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/tools/edit/schema.js

@@ -0,0 +1,235 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/** JSON Schema definition for the edit tool input. */
+export const editSchema = {
+    type: 'object',
+    properties: {
+        edits: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                type: 'object',
+                required: ['path', 'find', 'replace'],
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'File path to edit (relative to project root or absolute within it)',
+                    },
+                    find: {
+                        type: 'string',
+                        description: 'Text to find in the file',
+                    },
+                    find_base64: {
+                        type: 'string',
+                        description: 'Base64-encoded text to find (alternative to find for binary-safe transport)',
+                    },
+                    replace: {
+                        type: 'string',
+                        description: 'Replacement text',
+                    },
+                    replace_base64: {
+                        type: 'string',
+                        description: 'Base64-encoded replacement text (alternative to replace for binary-safe transport)',
+                    },
+                    id: {
+                        type: 'string',
+                        description: 'Optional identifier for this edit, used in result tracking',
+                    },
+                    occurrence: {
+                        oneOf: [
+                            {
+                                type: 'string',
+                                enum: ['first', 'last', 'all'],
+                                description: 'Which occurrence to replace: first, last, or all',
+                            },
+                            {
+                                type: 'integer',
+                                minimum: 1,
+                                description: 'Replace the Nth occurrence (1-based)',
+                            },
+                        ],
+                        description: 'Which occurrence to replace. Default: error if 0 or 2+ matches (ambiguity guard). ' +
+                            'Set to first/last/all/N to override.',
+                    },
+                    hints: {
+                        type: 'object',
+                        properties: {
+                            near_line: {
+                                type: 'integer',
+                                minimum: 1,
+                                description: 'Prefer the occurrence closest to this line number',
+                            },
+                            in_function: {
+                                type: 'string',
+                                description: 'Only match within a function with this name',
+                            },
+                            in_class: {
+                                type: 'string',
+                                description: 'Only match within a class with this name',
+                            },
+                            after: {
+                                type: 'string',
+                                description: 'Only match occurrences that appear after this text anchor in the file',
+                            },
+                            before: {
+                                type: 'string',
+                                description: 'Only match occurrences that appear before this text anchor in the file',
+                            },
+                        },
+                        additionalProperties: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        },
+        match: {
+            type: 'object',
+            properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['exact', 'fuzzy', 'regex', 'ast', 'ast_pattern'],
+                    description: 'Match mode. exact: literal string match. fuzzy: whitespace-insensitive. regex: treat find as regex. ' +
+                        'ast: structural match using tree-sitter (falls back to exact if unavailable). ' +
+                        'ast_pattern: pattern matching using @ast-grep/napi metavariables like $VAR or $$$ARGS (falls back to exact if unavailable).',
+                    default: 'exact',
+                },
+                case_sensitive: {
+                    type: 'boolean',
+                    description: 'Whether matching is case-sensitive. Default: true.',
+                    default: true,
+                },
+                whitespace_sensitive: {
+                    type: 'boolean',
+                    description: 'Whether whitespace differences matter. When false in exact mode, delegates to fuzzy matching algorithm. Default: true.',
+                    default: true,
+                },
+                multiline: {
+                    type: 'boolean',
+                    description: 'When true and mode is regex, adds the s (dotAll) and m (multiline) flags. ' +
+                        's flag: . matches newlines, enabling patterns that span multiple lines. ' +
+                        'm flag: ^ and $ match at line boundaries. Default: false.',
+                    default: false,
+                },
+            },
+            additionalProperties: false,
+        },
+        transaction: {
+            type: 'object',
+            properties: {
+                mode: {
+                    type: 'string',
+                    enum: ['atomic', 'partial', 'none'],
+                    description: 'atomic: all edits succeed or all fail (default). ' +
+                        'partial: apply succeeding edits, skip failures. ' +
+                        'none: apply each edit independently with no rollback.',
+                    default: 'atomic',
+                },
+            },
+            additionalProperties: false,
+        },
+        output: {
+            type: 'object',
+            properties: {
+                format: {
+                    type: 'string',
+                    enum: ['count_only', 'minimal', 'with_diff', 'verbose'],
+                    description: 'count_only: only total edits applied. ' +
+                        'minimal: per-edit success/failure summary (default). ' +
+                        'with_diff: include unified diff per edit. ' +
+                        'verbose: full detail including pre/post content. ' +
+                        'Results include status field: applied | not_found | ambiguous | conflict | failed. ' +
+                        'Failed results include hint field with actionable suggestions.',
+                    default: 'minimal',
+                },
+                diff_context: {
+                    type: 'integer',
+                    minimum: 0,
+                    description: 'Number of context lines to include around each change in unified diffs. Default: 3. ' +
+                        'Reduce to 0 for minimal diffs, increase for more context.',
+                    default: 3,
+                },
+            },
+            additionalProperties: false,
+        },
+        dry_run: {
+            type: 'boolean',
+            description: 'Compute all replacements and return diffs without writing to disk. Default: false.',
+            default: false,
+        },
+        validate: {
+            type: 'object',
+            description: 'Run validators before and/or after applying edits.',
+            properties: {
+                before: {
+                    type: 'array',
+                    description: 'Validators to run before applying edits. If any fail, edits are not applied.',
+                    items: {
+                        type: 'string',
+                        enum: ['typecheck', 'lint', 'test', 'build'],
+                    },
+                },
+                after: {
+                    type: 'array',
+                    description: 'Validators to run after applying edits. If any fail in atomic mode, edits are rolled back.',
+                    items: {
+                        type: 'string',
+                        enum: ['typecheck', 'lint', 'test', 'build'],
+                    },
+                },
+            },
+            additionalProperties: false,
+        },
+        notebook_operations: {
+            type: 'object',
+            description: 'Jupyter notebook (.ipynb) cell operations. Alternative to edits — provide either edits or notebook_operations, not both.',
+            properties: {
+                path: { type: 'string', description: 'Path to .ipynb notebook file' },
+                operations: {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        required: ['op'],
+                        properties: {
+                            op: {
+                                type: 'string',
+                                enum: ['replace', 'insert', 'delete'],
+                                description: 'Cell operation: replace existing cell content, insert a new cell, or delete a cell',
+                            },
+                            cell: {
+                                type: 'integer',
+                                minimum: 0,
+                                description: '0-based cell index (used by replace/delete when cell_id is not provided)',
+                            },
+                            cell_id: {
+                                type: 'string',
+                                description: 'Cell ID targeting — takes precedence over cell index for all operations',
+                            },
+                            after: {
+                                type: 'integer',
+                                minimum: -1,
+                                description: 'For insert: insert after this 0-based index (-1 = insert at beginning). Omit to append at end.',
+                            },
+                            source: {
+                                type: 'string',
+                                description: 'Cell source content (required for replace and insert operations)',
+                            },
+                            cell_type: {
+                                type: 'string',
+                                enum: ['code', 'markdown', 'raw'],
+                                description: 'Cell type (required for insert; optional for replace — if provided, changes the cell type)',
+                            },
+                            clear_outputs: {
+                                type: 'boolean',
+                                description: 'Clear cell outputs on replace (default: false)',
+                            },
+                        },
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ['path', 'operations'],
+            additionalProperties: false,
+        },
+    },
+    additionalProperties: false,
+};

package/dist/_internal/platform/tools/edit/types.d.ts

@@ -0,0 +1,83 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export type OccurrenceSpec = 'first' | 'last' | 'all' | number;
+export interface EditItem {
+    path: string;
+    find: string;
+    find_base64?: string;
+    replace: string;
+    replace_base64?: string;
+    id?: string;
+    occurrence?: OccurrenceSpec;
+    hints?: {
+        near_line?: number;
+        in_function?: string;
+        in_class?: string;
+        after?: string;
+        before?: string;
+    };
+}
+export type ValidatorName = 'typecheck' | 'lint' | 'test' | 'build';
+export interface EditInput {
+    edits?: EditItem[];
+    notebook_operations?: NotebookOperationsInput;
+    match?: {
+        mode?: 'exact' | 'fuzzy' | 'regex' | 'ast' | 'ast_pattern';
+        case_sensitive?: boolean;
+        whitespace_sensitive?: boolean;
+        multiline?: boolean;
+    };
+    transaction?: {
+        mode?: 'atomic' | 'partial' | 'none';
+    };
+    output?: {
+        format?: 'count_only' | 'minimal' | 'with_diff' | 'verbose';
+        diff_context?: number;
+    };
+    dry_run?: boolean;
+    validate?: {
+        before?: ValidatorName[];
+        after?: ValidatorName[];
+    };
+}
+export type EditResultStatus = 'applied' | 'not_found' | 'ambiguous' | 'conflict' | 'failed';
+export interface EditResult {
+    id?: string;
+    path: string;
+    success: boolean;
+    status?: EditResultStatus;
+    occurrencesReplaced?: number;
+    diff?: string;
+    diff_truncated?: boolean;
+    diff_preview?: string;
+    error?: string;
+    hint?: string;
+    warning?: string;
+}
+export interface NotebookCell {
+    cell_type: 'code' | 'markdown' | 'raw';
+    source: string | string[];
+    metadata?: Record<string, unknown>;
+    execution_count?: number | null;
+    outputs?: unknown[];
+    id?: string;
+}
+export interface JupyterNotebook {
+    nbformat: number;
+    nbformat_minor: number;
+    cells: NotebookCell[];
+    metadata?: Record<string, unknown>;
+}
+export interface NotebookOperation {
+    op: 'replace' | 'insert' | 'delete';
+    cell?: number;
+    cell_id?: string;
+    after?: number;
+    source?: string;
+    cell_type?: 'code' | 'markdown' | 'raw';
+    clear_outputs?: boolean;
+}
+export interface NotebookOperationsInput {
+    path: string;
+    operations: NotebookOperation[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/tools/edit/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/edit/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,aAAa,CAAC;QAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;KACtC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;QAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;QACzB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;KACzB,CAAC;CACH;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE7F,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IACvC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC"}

package/dist/_internal/platform/tools/edit/types.js

@@ -0,0 +1,2 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export {};

package/dist/_internal/platform/tools/exec/ast-guard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shell AST guard for the exec tool.
+ *
+ * Integrates the Shell AST normalization pipeline with the exec tool to
+ * provide per-segment verdict evaluation and user-facing denial explanations.
+ *
+ * When the `shell-ast-normalization` feature flag is enabled, every exec
+ * command is parsed into an AST, evaluated segment-by-segment, and denied
+ * with a structured explanation if any segment fails policy.
+ *
+ * When the flag is disabled, this module falls back to the baseline
+ * flat-token segmentation path.
+ *
+ * @module tools/exec/ast-guard
+ */
+import type { CompoundVerdict } from '../../runtime/permissions/normalization/verdict.js';
+import type { CommandClassification } from '../../runtime/permissions/normalization/types.js';
+import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
+type FlagManagerLike = Pick<FeatureFlagManager, 'isEnabled'>;
+/**
+ * The result of an AST guard evaluation for a single exec command.
+ */
+export interface ASTGuardResult {
+    /** Whether the command is permitted by the AST guard. */
+    allowed: boolean;
+    /**
+     * Human-readable denial explanation for user display.
+     * Only set when `allowed` is false.
+     */
+    denialMessage?: string;
+    /**
+     * The full CompoundVerdict, available for upstream audit logging.
+     * Only set when AST normalization is active.
+     */
+    verdict?: CompoundVerdict;
+    /** Whether AST normalization was active. */
+    astModeActive: boolean;
+}
+/**
+ * Evaluates a shell command string through the AST guard.
+ *
+ * Routes to the AST pipeline when the `shell-ast-normalization` feature flag
+ * is enabled, otherwise falls back to the baseline segmentation path.
+ *
+ * @param command        - The raw shell command string to evaluate.
+ * @param allowedClasses - Override for the default allowed classification set.
+ *                         Only used in AST mode.
+ * @returns ASTGuardResult with allow/deny decision and optional denial message.
+ *
+ * @example
+ * const result = guardExecCommand('ls /tmp && rm -rf /');
+ * if (!result.allowed) {
+ *   console.error(result.denialMessage);
+ * }
+ */
+export declare function guardExecCommand(command: string, allowedClasses?: ReadonlySet<CommandClassification>, flagManager?: FlagManagerLike | null): Promise<ASTGuardResult>;
+/**
+ * Formats an ASTGuardResult denial into a structured exec tool error response.
+ *
+ * @param result - A denied ASTGuardResult.
+ * @param cmd    - The original command string (for the error message).
+ * @returns A structured error object suitable for returning from the exec tool.
+ */
+export declare function formatDenialResponse(result: ASTGuardResult, cmd: string): Record<string, unknown>;
+export {};
+//# sourceMappingURL=ast-guard.d.ts.map

package/dist/_internal/platform/tools/exec/ast-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-guard.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/exec/ast-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oDAAoD,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kDAAkD,CAAC;AAC9F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,KAAK,eAAe,GAAG,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;AAY7D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAoED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,WAAW,CAAC,qBAAqB,CAA2B,EAC5E,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,GACnC,OAAO,CAAC,cAAc,CAAC,CAKzB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}

package/dist/_internal/platform/tools/exec/ast-guard.js

@@ -0,0 +1,121 @@
+/**
+ * Shell AST guard for the exec tool.
+ *
+ * Integrates the Shell AST normalization pipeline with the exec tool to
+ * provide per-segment verdict evaluation and user-facing denial explanations.
+ *
+ * When the `shell-ast-normalization` feature flag is enabled, every exec
+ * command is parsed into an AST, evaluated segment-by-segment, and denied
+ * with a structured explanation if any segment fails policy.
+ *
+ * When the flag is disabled, this module falls back to the baseline
+ * flat-token segmentation path.
+ *
+ * @module tools/exec/ast-guard
+ */
+import { parseCommandAST } from '../../runtime/permissions/normalization/parser.js';
+import { evaluateCommandAST, DEFAULT_ALLOWED_CLASSES } from '../../runtime/permissions/normalization/verdict.js';
+import { normalizeCommand } from '../../runtime/permissions/normalization/index.js';
+function isASTNormalizationEnabled(flagManager) {
+    return flagManager?.isEnabled('shell-ast-normalization') ?? false;
+}
+// ── Baseline guard ─────────────────────────────────────────────────────────────
+/**
+ * Evaluates a command using the baseline flat segmentation pipeline.
+ *
+ * Returns `allowed: true` for non-destructive, non-escalation commands.
+ * This mirrors the baseline exec safety path used when AST normalization is off.
+ *
+ * @param command - The raw shell command string.
+ * @returns ASTGuardResult with AST mode disabled.
+ */
+function baselineGuard(command) {
+    const normalized = normalizeCommand(command);
+    const cls = normalized.highestClassification;
+    if (cls === 'destructive' || cls === 'escalation') {
+        return {
+            allowed: false,
+            denialMessage: `Command denied (baseline mode): "${command}"\n` +
+                `Classification: ${cls}\n` +
+                `Highest-risk operation in compound command is classified as ${cls}.`,
+            astModeActive: false,
+        };
+    }
+    return { allowed: true, astModeActive: false };
+}
+// ── AST mode guard ─────────────────────────────────────────────────────────────
+/**
+ * Evaluates a command using the Shell AST pipeline.
+ *
+ * Parses the command into a ShellNode AST, evaluates each segment
+ * independently, and returns a CompoundVerdict.
+ *
+ * @param command        - The raw shell command string.
+ * @param allowedClasses - Classification tiers to allow.
+ * @returns ASTGuardResult with full CompoundVerdict attached.
+ */
+function astGuard(command, allowedClasses) {
+    const ast = parseCommandAST(command);
+    const verdict = evaluateCommandAST(command, ast, allowedClasses);
+    if (!verdict.allowed) {
+        return {
+            allowed: false,
+            denialMessage: verdict.denialExplanation,
+            verdict,
+            astModeActive: true,
+        };
+    }
+    return {
+        allowed: true,
+        verdict,
+        astModeActive: true,
+    };
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+/**
+ * Evaluates a shell command string through the AST guard.
+ *
+ * Routes to the AST pipeline when the `shell-ast-normalization` feature flag
+ * is enabled, otherwise falls back to the baseline segmentation path.
+ *
+ * @param command        - The raw shell command string to evaluate.
+ * @param allowedClasses - Override for the default allowed classification set.
+ *                         Only used in AST mode.
+ * @returns ASTGuardResult with allow/deny decision and optional denial message.
+ *
+ * @example
+ * const result = guardExecCommand('ls /tmp && rm -rf /');
+ * if (!result.allowed) {
+ *   console.error(result.denialMessage);
+ * }
+ */
+export async function guardExecCommand(command, allowedClasses = DEFAULT_ALLOWED_CLASSES, flagManager) {
+    if (isASTNormalizationEnabled(flagManager)) {
+        return astGuard(command, allowedClasses);
+    }
+    return baselineGuard(command);
+}
+/**
+ * Formats an ASTGuardResult denial into a structured exec tool error response.
+ *
+ * @param result - A denied ASTGuardResult.
+ * @param cmd    - The original command string (for the error message).
+ * @returns A structured error object suitable for returning from the exec tool.
+ */
+export function formatDenialResponse(result, cmd) {
+    const segmentDetails = result.verdict?.segments.map((s) => ({
+        command: s.command,
+        classification: s.classification,
+        allowed: s.allowed,
+        reason: s.reason,
+        ...(s.hasObfuscation ? { obfuscation: s.obfuscationPatterns } : {}),
+    }));
+    return {
+        success: false,
+        cmd,
+        denied: true,
+        denial_reason: result.denialMessage ?? 'Command denied by policy',
+        ...(segmentDetails ? { segments: segmentDetails } : {}),
+        ast_mode: result.astModeActive,
+    };
+}

package/dist/_internal/platform/tools/exec/file-ops.d.ts

@@ -0,0 +1,15 @@
+import type { ExecFileOp } from './schema.js';
+export interface FileOpResult {
+    op: string;
+    source: string;
+    destination?: string;
+    dry_run?: boolean;
+    would_delete?: string[];
+    updated_imports?: string[];
+}
+export declare function executeFileOp(op: ExecFileOp, projectRoot: string): FileOpResult;
+export declare function executeFileOperations(fileOps: ExecFileOp[] | undefined, projectRoot: string): Promise<{
+    fileOpResults: FileOpResult[];
+    fileOpError?: string;
+}>;
+//# sourceMappingURL=file-ops.d.ts.map

package/dist/_internal/platform/tools/exec/file-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-ops.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/exec/file-ops.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AA4FD,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAoD/E;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,UAAU,EAAE,GAAG,SAAS,EACjC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,aAAa,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoClE"}