dsh-perm-gate 2.1.2 → 2.6.2

package/lib/command-dispatcher.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Command dispatcher - routes commands to appropriate parsers.
+ * Runs parsers in priority order, returns first match.
+ */
+import type { CommandParser, ClassificationResult } from './command-semantics.js';
+/**
+ * Register a parser manually (for testing or custom parsers).
+ */
+export declare function registerParser(parser: CommandParser): void;
+/**
+ * Clear all registered parsers (for testing).
+ */
+export declare function clearParsers(): void;
+/**
+ * Dispatch a command to the appropriate parser.
+ * Returns classification result or null if no parser matches.
+ */
+export declare function dispatchCommand(command: string): ClassificationResult | null;
+/**
+ * Get all registered parsers (for inspection/testing).
+ */
+export declare function getParsers(): readonly CommandParser[];

package/lib/command-dispatcher.js

@@ -0,0 +1,97 @@
+/**
+ * Command dispatcher - routes commands to appropriate parsers.
+ * Runs parsers in priority order, returns first match.
+ */
+import { GitParser } from './parsers/git.js';
+import { ShellDangerousParser } from './parsers/shell-cmds.js';
+/** Registered parsers (loaded lazily) */
+const parsers = [];
+/** Parser registry flag */
+let initialized = false;
+/**
+ * Lazy-load all parsers.
+ * Called once on first dispatch.
+ */
+function initParsers() {
+    if (initialized)
+        return;
+    initialized = true;
+    // P0: Git parser (highest priority)
+    parsers.push(new GitParser());
+    // P1: Shell dangerous commands
+    parsers.push(new ShellDangerousParser());
+    // P2: Package managers (TODO: implement)
+    // parsers.push(new PkgManagerParser())
+    // P3: Docker (TODO: implement)
+    // parsers.push(new DockerParser())
+    // P4: SQL (TODO: implement)
+    // parsers.push(new SqlParser())
+}
+/**
+ * Register a parser manually (for testing or custom parsers).
+ */
+export function registerParser(parser) {
+    // Insert in priority order (lower priority number = higher priority)
+    const idx = parsers.findIndex(p => p.priority > parser.priority);
+    if (idx === -1) {
+        parsers.push(parser);
+    }
+    else {
+        parsers.splice(idx, 0, parser);
+    }
+}
+/**
+ * Clear all registered parsers (for testing).
+ */
+export function clearParsers() {
+    parsers.length = 0;
+    initialized = false;
+}
+/**
+ * Dispatch a command to the appropriate parser.
+ * Returns classification result or null if no parser matches.
+ */
+export function dispatchCommand(command) {
+    initParsers();
+    const startTime = performance.now();
+    for (const parser of parsers) {
+        if (parser.canParse(command)) {
+            const semantics = parser.parse(command);
+            if (semantics) {
+                const parseTimeMs = performance.now() - startTime;
+                return {
+                    semantics,
+                    confidence: 1.0, // Static parsers have high confidence
+                    parser: parser.name,
+                    parseTimeMs,
+                };
+            }
+        }
+    }
+    // No parser matched - return unknown semantics
+    const parseTimeMs = performance.now() - startTime;
+    return {
+        semantics: {
+            family: 'unknown',
+            destructiveness: 0,
+            destructiveFlags: false,
+            targets: [],
+            flags: [],
+            requiresConfirmation: false,
+            compound: false,
+            gitOperation: false,
+            targetsSharedBranch: false,
+            rawCommand: command,
+        },
+        confidence: 0,
+        parser: 'none',
+        parseTimeMs,
+    };
+}
+/**
+ * Get all registered parsers (for inspection/testing).
+ */
+export function getParsers() {
+    initParsers();
+    return parsers;
+}

package/lib/command-semantics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Unified command semantics output from all classifiers.
+ * Every parser (git, shell-dangerous, docker, sql, pkg-manager)
+ * returns this interface — the evaluator does one matching pass.
+ */
+/** Command families supported by static parsers */
+export type CommandFamily = 'git' | 'shell-dangerous' | 'docker' | 'sql' | 'pkg-manager' | 'unknown';
+/** Destructiveness rating (0=safe, 5=extremely destructive) */
+export type DestructivenessLevel = 0 | 1 | 2 | 3 | 4 | 5;
+/** Unified semantics output */
+export interface CommandSemantics {
+    /** Command family (git, shell-dangerous, docker, sql, pkg-manager, unknown) */
+    family: CommandFamily;
+    /** Subcommand (e.g. 'push', 'rm', 'run') */
+    subcommand?: string;
+    /** Specific operation (e.g. 'force-push', 'recursive-delete') */
+    operation?: string;
+    /** Destructiveness level 0-5 */
+    destructiveness: DestructivenessLevel;
+    /** Whether destructive flags are present (--force, --recursive, etc.) */
+    destructiveFlags: boolean;
+    /** Target identifiers (branch names, file paths, container IDs, table names, package names) */
+    targets: string[];
+    /** All parsed flags (normalized) */
+    flags: string[];
+    /** Whether the command requires explicit confirmation */
+    requiresConfirmation: boolean;
+    /** Whether the command is compound (contains &&, ||, |) */
+    compound: boolean;
+    /** Whether the command involves git operations */
+    gitOperation: boolean;
+    /** Branch name (extracted from git commands) */
+    branch?: string;
+    /** Remote name (for git push/fetch) */
+    remote?: string;
+    /** Whether the command targets shared/protected branches */
+    targetsSharedBranch: boolean;
+    /** Raw command string */
+    rawCommand?: string;
+}
+/** Classification result with confidence */
+export interface ClassificationResult {
+    /** The semantics object */
+    semantics: CommandSemantics;
+    /** Parser confidence (0-1) */
+    confidence: number;
+    /** Parser used */
+    parser: string;
+    /** Parse time in milliseconds */
+    parseTimeMs: number;
+}
+/** Parser interface - all parsers implement this */
+export interface CommandParser {
+    /** Parser name */
+    readonly name: string;
+    /** Priority (lower = runs first) */
+    readonly priority: number;
+    /** Try to parse the command. Return null if not applicable. */
+    parse(command: string): CommandSemantics | null;
+    /** Check if this parser can handle the command */
+    canParse(command: string): boolean;
+}

package/lib/command-semantics.js

@@ -0,0 +1,6 @@
+/**
+ * Unified command semantics output from all classifiers.
+ * Every parser (git, shell-dangerous, docker, sql, pkg-manager)
+ * returns this interface — the evaluator does one matching pass.
+ */
+export {};

package/lib/compiler.d.ts

@@ -56,6 +56,17 @@ export declare function compilePortSpec(spec: string): (port: number) => boolean
  * Returns a {@link CompiledPattern} whose `.re` is the anchored RegExp.
  */
 export declare function compileDomainPattern(pattern: string): CompiledPattern;
+/**
+ * Compile a git branch-name pattern into a matcher.
+ *
+ * Branch names are path-like (`release/1.0`) but a rule author thinks in
+ * segments-with-globs terms (`release*`), so this is a **non-segment** glob:
+ * `*` crosses `/` on purpose, matching how `args` patterns behave.
+ *
+ * Rejects a pattern that is nothing but a separator so a typo can not degrade
+ * into "matches everything".
+ */
+export declare function compileBranchPattern(pattern: string): CompiledPattern;
 /**
  * Compile a list of patterns (possibly `!`-prefixed) into param matchers.
  * Returns `{ pattern, negated, compiled }` entries for the params dimension.

package/lib/compiler.js

@@ -217,6 +217,22 @@ export function compileDomainPattern(pattern) {
     const re = new RegExp(`^(?:.*\\.)?${escaped}$`, 'u');
     return { source: pattern, re };
 }
+/**
+ * Compile a git branch-name pattern into a matcher.
+ *
+ * Branch names are path-like (`release/1.0`) but a rule author thinks in
+ * segments-with-globs terms (`release*`), so this is a **non-segment** glob:
+ * `*` crosses `/` on purpose, matching how `args` patterns behave.
+ *
+ * Rejects a pattern that is nothing but a separator so a typo can not degrade
+ * into "matches everything".
+ */
+export function compileBranchPattern(pattern) {
+    if (!/[A-Za-z0-9_*?[\]]/.test(pattern)) {
+        throw new PatternError(`branch pattern ${JSON.stringify(pattern)} has no matchable character`);
+    }
+    return compileGlob(pattern, { segments: false, maxStars: DEFAULT_MAX_STARS });
+}
 /**
  * Compile a list of patterns (possibly `!`-prefixed) into param matchers.
  * Returns `{ pattern, negated, compiled }` entries for the params dimension.

package/lib/config.d.ts

@@ -1,5 +1,6 @@
 import z from '@deepseek-ai/schemastery';
 import type { RuleAction } from './rule.js';
+import { DEFAULT_GATE_PRESETS, resolveGatePresets } from './preset.js';
 /**
  * The DSH home directory: an explicit `dshHome`, else `$DSH_HOME`, else
  * `~/.dsh`. A profile entry that omits `config` must still get a writable data
@@ -186,9 +187,9 @@ export interface PermGateConfig {
      * Default 1800000 (30 min).
      */
     readonly networkGrantTtlMs?: number;
-    /** Enable file watching for rule hot-reload. Default true. */
+    /** @deprecated Rules now live in the `dsh-perm-gate-rules` settings namespace; file watching was removed. Accepted (ignored) for composition compatibility. */
     readonly watch?: boolean;
-    /** Debounce interval for rule file changes in ms. Default 300. */
+    /** @deprecated See {@link watch}. */
     readonly watchDebounceMs?: number;
 }
 /** Backend combinable approval strategies for the Permissive tier (all opt-in). */
@@ -217,18 +218,78 @@ export interface PermissiveStrategies {
     readonly trustEscalation: boolean;
 }
 export declare const DEFAULT_PERMISSIVE_STRATEGIES: Readonly<PermissiveStrategies>;
-/**
- * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
- * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
- * same approval behaviour) — so a user can have the gate without inheriting a
- * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
- * preset, including the hard-deny layer).
- */
-export declare const DEFAULT_GATE_PRESETS: readonly string[];
-/** Normalize the gate scope: an unset/empty list means the default. */
-export declare function resolveGatePresets(configured?: readonly string[]): readonly string[];
+export { DEFAULT_GATE_PRESETS, resolveGatePresets };
 /** Normalize a backend strategy bag to fully-specified booleans (backend-part combinable). */
 export declare function resolvePermissiveStrategies(bag?: Partial<PermissiveStrategies>): PermissiveStrategies;
+/**
+ * One rule entry as stored in settings. Deliberately permissive (`z.any()`
+ * fields): strict validation happens in `parseRuleEntry` at compile time (fail
+ * loud), and the stored form must round-trip BOTH the raw YAML shape (string
+ * scalars, `params` as a key→patterns mapping) and the parsed document shape
+ * (parsed dimensions), so a file migration can be seeded without lossy
+ * normalization. Schemastery preserves unknown keys in non-strict object mode.
+ */
+export declare const RuleEntrySchema: z<unknown>;
+/**
+ * The rules structure stored in the DSH settings namespace — the JSON form of
+ * rules.yml. Unknown extra keys on the document itself are preserved too.
+ */
+export declare const RulesSchema: z<RulesConfig>;
+/** One rule entry in the settings-stored rules document (JSON form; all optional). */
+export interface RulesEntryConfig {
+    readonly tools?: readonly string[];
+    readonly command?: readonly string[];
+    readonly args?: readonly string[];
+    readonly paths?: readonly string[];
+    readonly params?: unknown;
+    readonly absent?: readonly string[];
+    readonly agents?: readonly string[];
+    readonly when?: unknown;
+    readonly argv?: unknown;
+    readonly network?: {
+        readonly domains?: readonly string[];
+        readonly ips?: readonly string[];
+        readonly ports?: readonly string[];
+        readonly schemes?: readonly string[];
+    };
+    readonly branch?: {
+        readonly target?: readonly string[];
+        readonly remote?: readonly string[];
+        readonly shared?: boolean;
+    };
+    readonly reason?: string;
+    readonly enabled?: boolean;
+}
+/**
+ * The rules document stored in the settings namespace. The action lists are
+ * `unknown[]` on purpose: entries may be the raw YAML shape or the parsed
+ * document shape, and strict validation belongs to `parseRuleEntry` at compile
+ * time — see {@link RulesEntryConfig} for the documented JSON form. (Mutable
+ * arrays: the type doubles as the Schemastery input face of {@link RulesSchema},
+ * which validates in place.)
+ */
+export interface RulesConfig {
+    readonly defaultAction?: RuleAction;
+    readonly deny?: unknown[];
+    readonly allow?: unknown[];
+    readonly ask?: unknown[];
+}
+/** Settings namespace for rules (separate from the main perm-gate namespace). */
+export declare const RULES_NAMESPACE = "dsh-perm-gate-rules";
+/**
+ * Whether a settings-sourced rules document carries a REAL configuration —
+ * entries or a non-default `defaultAction`. A namespace still holding bare
+ * schema defaults is "not configured" and must not shadow the rules file
+ * (the dual-source contract: settings first, file fallback).
+ */
+export declare function isRulesConfigured(value: unknown): boolean;
+/**
+ * Read the rules from a settings scope: the document when the namespace is
+ * configured, otherwise `undefined` so the caller falls back to the rules file.
+ */
+export declare function readRulesFromSettings(scope: {
+    get(): unknown;
+} | undefined): RulesConfig | undefined;
 export declare const Config: z<PermGateConfig>;
 export type ResolvedPermGateConfig = Required<Pick<PermGateConfig, 'caseInsensitivePaths' | 'grantTtlMs' | 'grantMaxUses' | 'permissive' | 'riskTimeoutMs' | 'riskLearning' | 'riskThreshold'>> & Pick<PermGateConfig, 'rulesFile' | 'dshHome' | 'defaultAction' | 'classifierEnabled' | 'classifierEndpoint' | 'classifierModel' | 'classifierApiKey' | 'learningFile' | 'eventsFile'> & {
     readonly permissiveStrategies: PermissiveStrategies;

package/lib/config.js

@@ -5,6 +5,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
+import { DEFAULT_GATE_PRESETS, resolveGatePresets } from './preset.js';
 /**
  * The DSH home directory: an explicit `dshHome`, else `$DSH_HOME`, else
  * `~/.dsh`. A profile entry that omits `config` must still get a writable data
@@ -42,20 +43,10 @@ export const DEFAULT_PERMISSIVE_STRATEGIES = {
     // bulk) — the escalation-worthy ones — auto-deny rather than allow.
     trustEscalation: true,
 };
-/**
- * Presets in which the gate is active. It owns both 自动审查 tiers — the plain
- * one (file sandbox kept) and the full-access one (sandbox restriction lifted,
- * same approval behaviour) — so a user can have the gate without inheriting a
- * sandbox that breaks `git` / Cygwin tools. `'*'` makes it global (every
- * preset, including the hard-deny layer).
- */
-export const DEFAULT_GATE_PRESETS = ['permissive', 'permissive-full'];
-/** Normalize the gate scope: an unset/empty list means the default. */
-export function resolveGatePresets(configured) {
-    if (configured === undefined || configured.length === 0)
-        return DEFAULT_GATE_PRESETS;
-    return configured.filter((name) => typeof name === 'string' && name !== '');
-}
+// The scope constants live in the dependency-free `preset` module (the browser
+// half renders them); bound locally AND re-exported so every existing
+// `./config.js` import keeps resolving.
+export { DEFAULT_GATE_PRESETS, resolveGatePresets };
 /** Normalize a backend strategy bag to fully-specified booleans (backend-part combinable). */
 export function resolvePermissiveStrategies(bag = {}) {
     return {
@@ -65,6 +56,57 @@ export function resolvePermissiveStrategies(bag = {}) {
         trustEscalation: bag.trustEscalation ?? DEFAULT_PERMISSIVE_STRATEGIES.trustEscalation,
     };
 }
+// ─── Rules Schema (for settings namespace) ──────────────────────────────────
+// The JSON twin of the rules.yml permissions document, stored in its own DSH
+// settings namespace so the gate loads without any file on disk.
+/**
+ * One rule entry as stored in settings. Deliberately permissive (`z.any()`
+ * fields): strict validation happens in `parseRuleEntry` at compile time (fail
+ * loud), and the stored form must round-trip BOTH the raw YAML shape (string
+ * scalars, `params` as a key→patterns mapping) and the parsed document shape
+ * (parsed dimensions), so a file migration can be seeded without lossy
+ * normalization. Schemastery preserves unknown keys in non-strict object mode.
+ */
+export const RuleEntrySchema = z.any();
+/**
+ * The rules structure stored in the DSH settings namespace — the JSON form of
+ * rules.yml. Unknown extra keys on the document itself are preserved too.
+ */
+export const RulesSchema = z.object({
+    defaultAction: z.union(['allow', 'ask', 'deny']).default('ask'),
+    deny: z.array(RuleEntrySchema).default([]),
+    allow: z.array(RuleEntrySchema).default([]),
+    ask: z.array(RuleEntrySchema).default([]),
+});
+/** Settings namespace for rules (separate from the main perm-gate namespace). */
+export const RULES_NAMESPACE = 'dsh-perm-gate-rules';
+/**
+ * Whether a settings-sourced rules document carries a REAL configuration —
+ * entries or a non-default `defaultAction`. A namespace still holding bare
+ * schema defaults is "not configured" and must not shadow the rules file
+ * (the dual-source contract: settings first, file fallback).
+ */
+export function isRulesConfigured(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const doc = value;
+    if (doc.defaultAction !== undefined && doc.defaultAction !== 'ask')
+        return true;
+    for (const key of ['deny', 'allow', 'ask']) {
+        const list = doc[key];
+        if (Array.isArray(list) && list.length > 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Read the rules from a settings scope: the document when the namespace is
+ * configured, otherwise `undefined` so the caller falls back to the rules file.
+ */
+export function readRulesFromSettings(scope) {
+    const value = scope?.get();
+    return isRulesConfigured(value) ? value : undefined;
+}
 export const Config = z.object({
     rulesFile: z.string(),
     dshHome: z.string(),

package/lib/dry-run.d.ts

@@ -0,0 +1,87 @@
+import type { RuleAction } from './rule.js';
+import { PermGateRuntime } from './runtime.js';
+export interface DryRunInput {
+    /** Tool name to evaluate, e.g. `shell`, `read`, `write`. */
+    readonly tool: string;
+    /** The tool call's arguments; `command` is what the shell dimensions read. */
+    readonly args?: Record<string, unknown>;
+    /** Rules file to load. Unset = the default chain (cwd upward, then the data home). */
+    readonly rulesFile?: string;
+    /** Working directory the call is evaluated in. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** Evaluate with the independent Permissive tier on. */
+    readonly permissive?: boolean;
+    /**
+     * Also run the **host-facing** decision path and report its own view.
+     *
+     * That path appends audit entries, records decision events, tracks asks and
+     * clears call clearances — so it is opt-in, and a read-only caller must never
+     * request it against a live runtime. Only the CLI asks for it, to keep its
+     * historic output byte for byte.
+     */
+    readonly hostView?: boolean;
+}
+/** The host-facing decision path's own view (`decideExecution`) and its audit count. */
+export interface DryRunHostView {
+    readonly verdict: RuleAction;
+    /** The waterfall's reason, or the historic `(default/passthrough)` placeholder. */
+    readonly reason: string;
+    readonly audited: number;
+}
+/** The P2 rule chain's own verdict, with the rule that produced it. */
+export interface DryRunRuleLayer {
+    readonly action: RuleAction;
+    readonly reason: string;
+    readonly ruleIndex?: number;
+    /**
+     * The dimensions the matched rule *constrains* — not "the dimension that
+     * caused the match". Dimensions are ANDed and an empty one is no constraint at
+     * all, so a multi-dimension rule cannot be attributed to a single dimension
+     * without lying about which one did the work.
+     */
+    readonly matchedDimensions: readonly string[];
+    /** The raw rule entry as written in the YAML, for display. */
+    readonly source?: Record<string, unknown>;
+}
+export interface DryRunResult {
+    readonly tool: string;
+    readonly rulesFile?: string;
+    /**
+     * The **policy** verdict: what the chain decides for this call, independent of
+     * the session a caller does not have. See {@link PermGateRuntime.explainCall}
+     * for why the session layers are excluded rather than guessed.
+     */
+    readonly verdict: RuleAction;
+    /** Why, in the chain's own words — never a bare placeholder. */
+    readonly reason: string;
+    /** Which layer produced `verdict`. */
+    readonly source: string;
+    readonly defaultAction: RuleAction;
+    readonly ruleCount: number;
+    readonly permissive: boolean;
+    readonly ruleLayer: DryRunRuleLayer;
+    /** Present only when `input.hostView` was set. */
+    readonly host?: DryRunHostView;
+}
+export interface DryRunOptions {
+    readonly rulesFile?: string;
+    readonly permissive?: boolean;
+    /**
+     * Workspace root for the rule CHAIN resolution (cwd upward, then the data
+     * home). `undefined` keeps the runtime default (`process.cwd()`).
+     *
+     * The CLI deliberately does not pass its `--cwd` here: that flag scopes the
+     * evaluated call, and feeding it into chain resolution as well would change
+     * what an existing `--cwd` invocation resolves. A host caller (the rule-test
+     * route) does pass its session workspace, because for a live session "which
+     * rules file applies" is exactly the question being asked.
+     */
+    readonly cwd?: string;
+}
+/**
+ * Build the standalone runtime a dry-run evaluates against. Exported because
+ * `--list` needs the loaded ruleset without deciding anything.
+ */
+export declare function createDryRunRuntime(options?: DryRunOptions): PermGateRuntime;
+/** Evaluate one call against a rules file and report the verdict. */
+export declare function runDryRun(input: DryRunInput, runtime?: PermGateRuntime): DryRunResult;

package/lib/dry-run.js

@@ -0,0 +1,110 @@
+/**
+ * Rule dry-run: evaluate one would-be tool call against a rules file and report
+ * the verdict in a shape both the CLI and the settings-card "rule test" panel can
+ * use.
+ *
+ * The evaluator itself lives in {@link PermGateRuntime}; this module only owns
+ * the standalone construction (no session, no audit feed, no event log, no
+ * persistence paths) and the reporting shape. Nothing here writes to disk or to
+ * the live gate — the runtime it builds is thrown away when the call returns.
+ *
+ * Two verdicts are reported, and they are not the same thing:
+ *
+ * - `verdict` is the *effective* result of the whole chain the live gate runs
+ *   (P0 hard-deny → P1 grant → P2 rules → P3 classifier → P4 ask), minus the
+ *   session-scoped state a dry-run has none of. This is what the user sees.
+ * - `ruleLayer` is what the `permissions` chain decides *on its own*. Only this
+ *   layer can name a rule, so `ruleIndex` belongs to it. A P0 hard-deny or a
+ *   preset deny-keyword fires before it and reports no index; when the two
+ *   differ, that difference is the answer, not an error.
+ */
+import { resolve } from 'node:path';
+import { PermGateRuntime } from './runtime.js';
+/**
+ * The eleven match dimensions, in the order `docs/rules-format.md` documents
+ * them. Used purely for reporting which dimensions a matched rule constrains.
+ */
+const DIMENSION_KEYS = [
+    'tools',
+    'command',
+    'args',
+    'paths',
+    'params',
+    'absent',
+    'agents',
+    'when',
+    'argv',
+    'network',
+    'branch',
+];
+/**
+ * Build the standalone runtime a dry-run evaluates against. Exported because
+ * `--list` needs the loaded ruleset without deciding anything.
+ */
+export function createDryRunRuntime(options = {}) {
+    return new PermGateRuntime({
+        rulesFile: options.rulesFile,
+        cwd: options.cwd,
+        caseInsensitivePaths: true,
+        permissive: options.permissive || undefined,
+    });
+}
+/** Which of the eleven dimensions this rule actually constrains. */
+function constrainedDimensions(source) {
+    return DIMENSION_KEYS.filter((key) => isConstrained(source[key]));
+}
+/**
+ * A dimension constrains when it carries at least one condition. Every shape the
+ * parser produces is covered: pattern lists, key→value maps, condition objects.
+ */
+function isConstrained(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+/** Evaluate one call against a rules file and report the verdict. */
+export function runDryRun(input, runtime) {
+    const rulesFile = input.rulesFile ? resolve(input.rulesFile) : undefined;
+    const gate = runtime ?? createDryRunRuntime({ rulesFile, permissive: input.permissive, cwd: input.cwd });
+    const exec = {
+        name: input.tool,
+        arguments: input.args ?? {},
+        cwd: input.cwd ? resolve(input.cwd) : process.cwd(),
+    };
+    // Pure policy first (the panel's answer); the side-effecting host view only
+    // when explicitly asked for, and it must run last so its audit count is its own.
+    const policy = gate.explainCall(exec);
+    const layer = gate.explainRules(exec);
+    const source = layer.rule?.source;
+    let host;
+    if (input.hostView === true) {
+        const decision = gate.decideExecution(exec);
+        host = {
+            verdict: decision === undefined ? 'allow' : decision.kind,
+            reason: decision?.reason ?? '(default/passthrough)',
+            audited: gate.auditEntries.length,
+        };
+    }
+    return {
+        tool: input.tool,
+        rulesFile,
+        verdict: policy.action,
+        reason: policy.reason,
+        source: policy.source,
+        defaultAction: layer.defaultAction,
+        ruleCount: gate.ruleCount(),
+        permissive: gate.permissive,
+        ruleLayer: {
+            action: layer.action,
+            reason: layer.reason,
+            ruleIndex: layer.ruleIndex,
+            matchedDimensions: source === undefined ? [] : constrainedDimensions(source),
+            source,
+        },
+        ...(host !== undefined ? { host } : {}),
+    };
+}