@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/permissions/evaluator.js

@@ -0,0 +1,384 @@
+/**
+ * Runtime permissions evaluator.
+ *
+ * Evaluates tool calls through a layered priority stack. First match wins.
+ */
+import { runSafetyChecks } from './safety-checks.js';
+import { DecisionLog } from './decision-log.js';
+import { evaluatePrefixRule } from './rules/prefix.js';
+import { evaluateArgShapeRule } from './rules/arg-shape.js';
+import { evaluatePathScopeRule } from './rules/path-scope.js';
+import { evaluateNetworkScopeRule } from './rules/network-scope.js';
+import { evaluateModeConstraintRule } from './rules/mode-constraint.js';
+// ── Tool classification ──────────────────────────────────────────────────────────
+const READ_TOOLS = new Set([
+    'read', 'find', 'fetch', 'analyze', 'inspect', 'state', 'registry',
+]);
+const WRITE_TOOLS = new Set([
+    'write', 'edit',
+]);
+const NETWORK_TOOLS = new Set([
+    'fetch', 'http', 'request', 'curl',
+]);
+const ESCALATION_TOOLS = new Set([
+    'agent', 'delegate', 'workflow', 'mcp',
+]);
+/**
+ * classifyTool — Returns the semantic classification of a tool call.
+ * For exec/execute, we classify based on arg content (destructive check
+ * is done in safety layer; here we return 'write' as the baseline).
+ */
+function classifyTool(toolName) {
+    if (NETWORK_TOOLS.has(toolName))
+        return 'network';
+    if (ESCALATION_TOOLS.has(toolName))
+        return 'escalation';
+    if (WRITE_TOOLS.has(toolName))
+        return 'write';
+    if (READ_TOOLS.has(toolName))
+        return 'read';
+    // exec-class tools are treated as 'write' (potentially destructive) by default
+    return 'write';
+}
+/**
+ * evaluateModeLayer — Applies mode-level constraints.
+ *
+ * Returns a deny decision for certain tool/classification combinations
+ * depending on the active mode, or allow for `allow-all` mode.
+ */
+function evaluateModeLayer(mode, toolName, classification) {
+    switch (mode) {
+        case 'allow-all':
+            return {
+                deny: false,
+                allow: true,
+                reason: 'MODE_ALLOW_ALL',
+                step: {
+                    layer: 'mode',
+                    check: 'mode-allow-all',
+                    matched: true,
+                    detail: 'allow-all mode: all tools auto-approved',
+                },
+            };
+        case 'plan':
+            // Plan mode blocks write, network, and destructive
+            if (classification === 'write' || classification === 'network' || classification === 'destructive') {
+                return {
+                    deny: true,
+                    allow: false,
+                    reason: 'MODE_DENY_PLAN',
+                    step: {
+                        layer: 'mode',
+                        check: 'mode-plan-constraint',
+                        matched: true,
+                        detail: `plan mode denies ${classification} tool "${toolName}"`,
+                    },
+                };
+            }
+            break;
+        case 'background-restricted':
+            // Background mode blocks escalation (agent/delegate) tools
+            if (classification === 'escalation') {
+                return {
+                    deny: true,
+                    allow: false,
+                    reason: 'MODE_DENY_BACKGROUND',
+                    step: {
+                        layer: 'mode',
+                        check: 'mode-background-constraint',
+                        matched: true,
+                        detail: `background-restricted mode denies escalation tool "${toolName}"`,
+                    },
+                };
+            }
+            break;
+        case 'remote-restricted':
+            // Remote-restricted mode blocks network tools
+            if (classification === 'network') {
+                return {
+                    deny: true,
+                    allow: false,
+                    reason: 'MODE_DENY_REMOTE_RESTRICTED',
+                    step: {
+                        layer: 'mode',
+                        check: 'mode-remote-restricted-constraint',
+                        matched: true,
+                        detail: `remote-restricted mode denies network tool "${toolName}"`,
+                    },
+                };
+            }
+            break;
+        default:
+            // 'default' and 'custom' modes: no mode-level constraints
+            break;
+    }
+    return {
+        deny: false,
+        allow: false,
+        step: {
+            layer: 'mode',
+            check: `mode-${mode}-constraint`,
+            matched: false,
+            detail: `mode "${mode}" imposes no constraint on "${toolName}" (${classification})`,
+        },
+    };
+}
+/**
+ * dispatchPolicyRule — Routes a PolicyRule to its typed evaluator.
+ */
+function dispatchPolicyRule(rule, toolName, args, activeMode, classification, projectRoot) {
+    let matched = false;
+    let step;
+    switch (rule.type) {
+        case 'prefix': {
+            const result = evaluatePrefixRule(rule, toolName, args);
+            matched = result.matched;
+            step = result.step;
+            break;
+        }
+        case 'arg-shape': {
+            const result = evaluateArgShapeRule(rule, toolName, args);
+            matched = result.matched;
+            step = result.step;
+            break;
+        }
+        case 'path-scope': {
+            const result = evaluatePathScopeRule(rule, toolName, args, projectRoot);
+            matched = result.matched;
+            step = result.step;
+            break;
+        }
+        case 'network-scope': {
+            const result = evaluateNetworkScopeRule(rule, toolName, args);
+            matched = result.matched;
+            step = result.step;
+            break;
+        }
+        case 'mode-constraint': {
+            const result = evaluateModeConstraintRule(rule, toolName, activeMode, classification);
+            matched = result.matched;
+            step = result.step;
+            break;
+        }
+    }
+    const reason = rule.effect === 'allow'
+        ? rule.origin === 'user'
+            ? 'RULE_ALLOW_USER'
+            : 'RULE_ALLOW_MANAGED'
+        : rule.origin === 'user'
+            ? 'RULE_DENY_USER'
+            : 'RULE_DENY_MANAGED';
+    return { matched, effect: rule.effect, reason, step };
+}
+// ── LayeredPolicyEvaluator ───────────────────────────────────────────────────────
+/**
+ * LayeredPolicyEvaluator — Core runtime permissions evaluator.
+ *
+ * Evaluates tool calls through five layers in priority order.
+ * Maintains a session approval cache and a structured audit log.
+ *
+ * Usage:
+ * ```ts
+ * const evaluator = new LayeredPolicyEvaluator({ mode: 'default', rules: [] });
+ * const decision = evaluator.evaluate('write', { path: '/tmp/out.txt' });
+ * ```
+ */
+export class LayeredPolicyEvaluator {
+    mode;
+    rules;
+    defaultEffect;
+    projectRoot;
+    sessionCache = new Map();
+    sessionCacheInsertOrder = [];
+    log;
+    /** GC-PERM-011: Provenance from the loaded policy bundle, if any. */
+    provenance;
+    static MAX_SESSION_CACHE_SIZE = 500;
+    constructor(config, provenance) {
+        this.mode = config.mode ?? 'default';
+        this.rules = config.rules ?? [];
+        this.defaultEffect = config.defaultEffect ?? 'deny';
+        this.projectRoot = config.projectRoot;
+        this.log = new DecisionLog();
+        this.provenance = provenance;
+    }
+    /**
+     * evaluate — Evaluates a tool call and returns a PermissionDecision.
+     *
+     * Runs all five layers in priority order. Populates a full evaluation trace.
+     * Appends the decision to the audit log if `auditLog` is enabled (default: true).
+     *
+     * @param toolName — The tool name being called.
+     * @param args     — The arguments passed to the tool.
+     */
+    evaluate(toolName, args) {
+        const trace = [];
+        const classification = classifyTool(toolName);
+        // ── Layer 1: Safety checks (bypass-immune) ──────────────────────────
+        const safety = runSafetyChecks(toolName, args);
+        trace.push(...safety.steps);
+        if (safety.blocked) {
+            return this.finalize({
+                allowed: false,
+                reason: safety.reason ?? 'SAFETY_DENY_GUARDRAIL',
+                sourceLayer: 'safety',
+                toolName,
+                args,
+                classification: safety.classification ?? classification,
+                trace,
+            });
+        }
+        // ── Layer 2: Mode constraints ───────────────────────────────────
+        const modeResult = evaluateModeLayer(this.mode, toolName, classification);
+        trace.push(modeResult.step);
+        if (modeResult.deny) {
+            return this.finalize({
+                allowed: false,
+                reason: modeResult.reason ?? 'MODE_DENY_PLAN',
+                sourceLayer: 'mode',
+                toolName,
+                args,
+                classification,
+                trace,
+            });
+        }
+        if (modeResult.allow) {
+            return this.finalize({
+                allowed: true,
+                reason: modeResult.reason ?? 'MODE_ALLOW_ALL',
+                sourceLayer: 'mode',
+                toolName,
+                args,
+                classification,
+                trace,
+            });
+        }
+        // ── Layer 3: Session overrides ─────────────────────────────────
+        const sessionKey = this.getSessionKey(toolName, args);
+        const cached = this.sessionCache.get(sessionKey);
+        if (cached !== undefined) {
+            const cacheReason = cached
+                ? 'SESSION_CACHED_ALLOW'
+                : 'SESSION_CACHED_DENY';
+            trace.push({
+                layer: 'session',
+                check: 'session-cache',
+                matched: true,
+                detail: `cache hit for key "${sessionKey}" → ${cached ? 'allow' : 'deny'}`,
+            });
+            return this.finalize({
+                allowed: cached,
+                reason: cacheReason,
+                sourceLayer: 'session',
+                toolName,
+                args,
+                classification,
+                trace,
+            });
+        }
+        trace.push({
+            layer: 'session',
+            check: 'session-cache',
+            matched: false,
+            detail: `no session cache entry for key "${sessionKey}"`,
+        });
+        // ── Layer 4: Policy rules (user before managed, first match wins) ─────
+        const userRules = this.rules.filter((r) => r.origin === 'user');
+        const managedRules = this.rules.filter((r) => r.origin === 'managed');
+        const orderedRules = [...userRules, ...managedRules];
+        for (const rule of orderedRules) {
+            const result = dispatchPolicyRule(rule, toolName, args, this.mode, classification, this.projectRoot);
+            trace.push(result.step);
+            if (result.matched) {
+                return this.finalize({
+                    allowed: result.effect === 'allow',
+                    reason: result.reason,
+                    sourceLayer: 'policy',
+                    toolName,
+                    args,
+                    classification,
+                    trace,
+                });
+            }
+        }
+        // ── Layer 5: Default policy ─────────────────────────────────────
+        // Default: auto-allow reads, apply configured defaultEffect for everything else
+        const defaultAllow = this.defaultEffect === 'allow' || classification === 'read';
+        const defaultReason = defaultAllow ? 'DEFAULT_ALLOW' : 'DEFAULT_DENY';
+        trace.push({
+            layer: 'default',
+            check: 'default-policy',
+            matched: true,
+            detail: `no rule matched; default=${defaultAllow ? 'allow' : 'deny'} (classification=${classification})`,
+        });
+        return this.finalize({
+            allowed: defaultAllow,
+            reason: defaultReason,
+            sourceLayer: 'default',
+            toolName,
+            args,
+            classification,
+            trace,
+        });
+    }
+    /**
+     * recordSessionOverride — Records a user-provided session approval/denial
+     * in the cache (used after a user prompt resolves).
+     *
+     * @param toolName  — Tool name.
+     * @param args      — Tool arguments.
+     * @param approved  — Whether the user approved or denied.
+     * @param remember  — Whether to persist for the session (default: false = once only).
+     */
+    recordSessionOverride(toolName, args, approved, remember = false) {
+        if (remember) {
+            const key = this.getSessionKey(toolName, args);
+            if (!this.sessionCache.has(key)) {
+                // Evict oldest entry if at capacity
+                if (this.sessionCacheInsertOrder.length >= LayeredPolicyEvaluator.MAX_SESSION_CACHE_SIZE) {
+                    const oldest = this.sessionCacheInsertOrder.shift();
+                    this.sessionCache.delete(oldest);
+                }
+                this.sessionCacheInsertOrder.push(key);
+            }
+            this.sessionCache.set(key, approved);
+        }
+    }
+    /**
+     * getMode — Returns the active PermissionMode.
+     */
+    getMode() {
+        return this.mode;
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    finalize(params) {
+        const decision = {
+            allowed: params.allowed,
+            reason: params.reason,
+            sourceLayer: params.sourceLayer,
+            toolName: params.toolName,
+            args: params.args,
+            classification: params.classification,
+            timestamp: Date.now(),
+            evaluationTrace: params.trace,
+            // GC-PERM-011: Attach provenance from the loaded policy bundle
+            ...(this.provenance !== undefined && {
+                policyBundleId: this.provenance.policyBundleId,
+                signatureStatus: this.provenance.signatureStatus,
+                provenanceSource: this.provenance.provenanceSource,
+            }),
+        };
+        this.log.append(decision);
+        return decision;
+    }
+    getSessionKey(toolName, args) {
+        if (typeof args['path'] === 'string')
+            return `${toolName}:path:${args['path']}`;
+        if (typeof args['command'] === 'string')
+            return `${toolName}:cmd:${args['command']}`;
+        if (typeof args['url'] === 'string')
+            return `${toolName}:url:${args['url']}`;
+        const argKeysHash = JSON.stringify(Object.keys(args).sort());
+        return `${toolName}:${argKeysHash}`;
+    }
+}

package/dist/_internal/platform/runtime/permissions/lint.d.ts

@@ -0,0 +1,9 @@
+import type { PermissionsConfig } from './types.js';
+export type PolicyLintSeverity = 'info' | 'warn' | 'error';
+export interface PolicyLintFinding {
+    severity: PolicyLintSeverity;
+    ruleId?: string;
+    message: string;
+}
+export declare function lintPolicyConfig(config: PermissionsConfig): PolicyLintFinding[];
+//# sourceMappingURL=lint.d.ts.map

package/dist/_internal/platform/runtime/permissions/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/lint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,YAAY,CAAC;AAEhE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AA0DD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CA0B/E"}

package/dist/_internal/platform/runtime/permissions/lint.js

@@ -0,0 +1,72 @@
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function isBroadPathPattern(pattern) {
+    return pattern === '**' || pattern === '/' || pattern === '/*' || pattern === '/**';
+}
+function isBroadHostPattern(pattern) {
+    return pattern === '*' || pattern === '*.*' || pattern === '*.com' || pattern === '*:*';
+}
+function lintRule(rule) {
+    const findings = [];
+    if (rule.type === 'path-scope') {
+        if (rule.pathPatterns.some(isBroadPathPattern)) {
+            findings.push({
+                severity: rule.effect === 'allow' ? 'error' : 'warn',
+                ruleId: rule.id,
+                message: `Path scope rule '${rule.id}' uses an overly broad path pattern.`,
+            });
+        }
+    }
+    if (rule.type === 'network-scope') {
+        if (rule.hostPatterns.some(isBroadHostPattern)) {
+            findings.push({
+                severity: rule.effect === 'allow' ? 'error' : 'warn',
+                ruleId: rule.id,
+                message: `Network scope rule '${rule.id}' uses an overly broad host pattern.`,
+            });
+        }
+    }
+    if (rule.type === 'mode-constraint') {
+        if (rule.activeModes.includes('allow-all') && rule.effect === 'allow') {
+            findings.push({
+                severity: 'warn',
+                ruleId: rule.id,
+                message: `Mode constraint rule '${rule.id}' redundantly allows actions in allow-all mode.`,
+            });
+        }
+    }
+    if (rule.type === 'prefix' && rule.effect === 'allow' && toArray(rule.toolPattern).includes('*') && !rule.commandPrefixes?.length) {
+        findings.push({
+            severity: 'error',
+            ruleId: rule.id,
+            message: `Prefix rule '${rule.id}' allows every tool without a command prefix constraint.`,
+        });
+    }
+    return findings;
+}
+export function lintPolicyConfig(config) {
+    const findings = [];
+    const rules = config.rules ?? [];
+    const seenIds = new Set();
+    for (const rule of rules) {
+        if (seenIds.has(rule.id)) {
+            findings.push({
+                severity: 'error',
+                ruleId: rule.id,
+                message: `Duplicate policy rule id '${rule.id}'.`,
+            });
+        }
+        else {
+            seenIds.add(rule.id);
+        }
+        findings.push(...lintRule(rule));
+    }
+    if (config.mode === 'allow-all' && rules.length > 0) {
+        findings.push({
+            severity: 'warn',
+            message: 'Policy rules are loaded while allow-all mode is active; runtime evaluation will still short-circuit to allow-all.',
+        });
+    }
+    return findings;
+}

package/dist/_internal/platform/runtime/permissions/normalization/ast.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shell AST types for compound command parsing.
+ *
+ * Represents the structural tree of a compound shell command after parsing.
+ * The tree preserves operator relationships between segments so that per-segment
+ * policy evaluation has full structural context.
+ *
+ * Node hierarchy:
+ *   ShellNode = CommandNode | PipeNode | SequenceNode | SubshellNode
+ *
+ * @module normalization/ast
+ */
+import type { CommandToken } from './types.js';
+/**
+ * A leaf node: a single simple command with its parsed tokens.
+ */
+export interface CommandNode {
+    /** Discriminant. */
+    kind: 'command';
+    /** The raw source substring for this command. */
+    raw: string;
+    /** Ordered tokens belonging to this command. */
+    tokens: CommandToken[];
+    /** Canonical command name (first token, path-stripped). */
+    command: string;
+    /** Positional arguments. */
+    args: string[];
+    /** Flags and options. */
+    flags: string[];
+    /**
+     * Set when the parser encountered an error and fell back to a flat CommandNode.
+     * Useful for debug-level diagnostics; not set on successful parses.
+     */
+    parseError?: string;
+}
+/**
+ * A pipe expression: left | right.
+ * Both sides may themselves be compound nodes.
+ */
+export interface PipeNode {
+    /** Discriminant. */
+    kind: 'pipe';
+    /** Left-hand side of the pipe. */
+    left: ShellNode;
+    /** Right-hand side of the pipe. */
+    right: ShellNode;
+}
+/**
+ * A sequence expression: left OP right, where OP is &&, || or ;.
+ */
+export interface SequenceNode {
+    /** Discriminant. */
+    kind: 'sequence';
+    /** The operator connecting left and right. */
+    operator: '&&' | '||' | ';';
+    /** Left-hand operand. */
+    left: ShellNode;
+    /** Right-hand operand. */
+    right: ShellNode;
+}
+/**
+ * A subshell expression: $(…) or `…`.
+ * The inner content is stored as a raw string and optionally parsed.
+ */
+export interface SubshellNode {
+    /** Discriminant. */
+    kind: 'subshell';
+    /** Raw subshell expression (including delimiters). */
+    raw: string;
+    /**
+     * Parsed inner tree, if the subshell content could be parsed.
+     * May be undefined for complex or unparseable subshell content.
+     */
+    inner?: ShellNode;
+}
+/** Discriminated union of all shell AST node types. */
+export type ShellNode = CommandNode | PipeNode | SequenceNode | SubshellNode;
+/**
+ * Collects all CommandNode leaves from a ShellNode tree in left-to-right order.
+ *
+ * @param node - The root node to traverse.
+ * @returns Ordered list of CommandNode leaves.
+ */
+export declare function collectCommandNodes(node: ShellNode, acc?: CommandNode[]): CommandNode[];
+/**
+ * Returns the operator chain connecting a node to its siblings, for display
+ * in denial messages.
+ *
+ * @param node - The node to describe.
+ * @returns A human-readable description of the node kind.
+ */
+export declare function describeNode(node: ShellNode): string;
+//# sourceMappingURL=ast.d.ts.map

package/dist/_internal/platform/runtime/permissions/normalization/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/permissions/normalization/ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yBAAyB;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,CAAC;IAC5B,yBAAyB;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,0BAA0B;IAC1B,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAC;AAI7E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,GAAE,WAAW,EAAO,GAAG,WAAW,EAAE,CAiB3F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAOpD"}

package/dist/_internal/platform/runtime/permissions/normalization/ast.js

@@ -0,0 +1,53 @@
+/**
+ * Shell AST types for compound command parsing.
+ *
+ * Represents the structural tree of a compound shell command after parsing.
+ * The tree preserves operator relationships between segments so that per-segment
+ * policy evaluation has full structural context.
+ *
+ * Node hierarchy:
+ *   ShellNode = CommandNode | PipeNode | SequenceNode | SubshellNode
+ *
+ * @module normalization/ast
+ */
+// ── AST utilities ──────────────────────────────────────────────────────────────
+/**
+ * Collects all CommandNode leaves from a ShellNode tree in left-to-right order.
+ *
+ * @param node - The root node to traverse.
+ * @returns Ordered list of CommandNode leaves.
+ */
+export function collectCommandNodes(node, acc = []) {
+    switch (node.kind) {
+        case 'command':
+            acc.push(node);
+            return acc;
+        case 'pipe':
+            collectCommandNodes(node.left, acc);
+            collectCommandNodes(node.right, acc);
+            return acc;
+        case 'sequence':
+            collectCommandNodes(node.left, acc);
+            collectCommandNodes(node.right, acc);
+            return acc;
+        case 'subshell':
+            if (node.inner)
+                collectCommandNodes(node.inner, acc);
+            return acc;
+    }
+}
+/**
+ * Returns the operator chain connecting a node to its siblings, for display
+ * in denial messages.
+ *
+ * @param node - The node to describe.
+ * @returns A human-readable description of the node kind.
+ */
+export function describeNode(node) {
+    switch (node.kind) {
+        case 'command': return `command(${node.command})`;
+        case 'pipe': return `pipe(${describeNode(node.left)} | ${describeNode(node.right)})`;
+        case 'sequence': return `sequence(${describeNode(node.left)} ${node.operator} ${describeNode(node.right)})`;
+        case 'subshell': return `subshell(${node.raw})`;
+    }
+}

package/dist/_internal/platform/runtime/permissions/normalization/canonicalizer.d.ts

@@ -0,0 +1,15 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Resolves a raw command token to its canonical bare command name.
+ *
+ * Processing order:
+ *  1. Strip quotes.
+ *  2. Strip leading environment variable assignments.
+ *  3. Extract the basename (strip directory path).
+ *  4. Lowercase the result.
+ *
+ * @param raw - The raw command token value.
+ * @returns The canonical command name (e.g. "rm", "git", "npm").
+ */
+export declare function canonicalize(raw: string): string;
+//# sourceMappingURL=canonicalizer.d.ts.map

package/dist/_internal/platform/runtime/permissions/normalization/canonicalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalizer.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/permissions/normalization/canonicalizer.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAkCrF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuBhD"}