dsh-perm-gate 2.1.0 → 2.1.2

package/lib/shadow.js

@@ -0,0 +1,143 @@
+/**
+ * Detect shadowed rules within a compiled ruleset.
+ *
+ * For each action partition (deny, allow, ask), check if any rule is
+ * dominated by an earlier rule in the same partition. A rule is dominated
+ * when:
+ *   1. Its tools pattern is a subset (or equal) of an earlier rule's tools
+ *   2. Its command pattern is a subset (or equal)
+ *   3. Its args/paths dimensions are subsets
+ *   4. Its new dimensions (params/absent/agents/when/network) are subsets
+ *
+ * This is conservative: it only flags rules that are DEFINITELY unreachable,
+ * not rules that MIGHT be unreachable under certain argument combinations.
+ */
+export function detectShadows(ruleset) {
+    const shadowed = [];
+    const reasons = new Map();
+    for (const partition of [ruleset.deny, ruleset.allow, ruleset.ask]) {
+        for (let i = 0; i < partition.length; i++) {
+            const rule = partition[i];
+            if (!rule.enabled)
+                continue;
+            for (let j = 0; j < i; j++) {
+                const earlier = partition[j];
+                if (!earlier.enabled)
+                    continue;
+                const dominatedBy = isDominated(earlier, rule);
+                if (dominatedBy !== undefined) {
+                    shadowed.push(rule.index);
+                    reasons.set(rule.index, `shadowed by rule #${earlier.index}: ${dominatedBy}`);
+                    break; // already flagged by earliest dominator
+                }
+            }
+        }
+    }
+    return { shadowed, reasons };
+}
+/**
+ * Check if `candidate` is dominated by `dominator` (dominator always
+ * matches a superset of what candidate matches).
+ *
+ * Returns a reason string if dominated, undefined otherwise.
+ */
+function isDominated(dominator, candidate) {
+    // tools: dominator's tools must be a superset (fewer or equal patterns = wider match).
+    // If dominator has no tools constraint (empty = every tool), it's a superset.
+    if (dominator.tools.length > 0 && candidate.tools.length > 0) {
+        // Both have tools: conservatively check if dominator's patterns are broader.
+        // Simple heuristic: if dominator has fewer patterns, it's likely broader.
+        // Full subset analysis would require pattern comparison — too expensive for hot path.
+        // We only flag when dominator has NO tools constraint (empty = every tool).
+        // For non-empty/non-empty, we conservatively don't flag.
+        if (dominator.tools.length <= candidate.tools.length) {
+            // Could be broader — but we need actual pattern comparison.
+            // Conservative: don't flag unless we can prove subset.
+            // Skip this dimension for now.
+        }
+        else {
+            return undefined; // dominator is stricter on tools
+        }
+    }
+    // If dominator has no tools and candidate has tools → dominator is broader ✓
+    // command: same logic — dominator with no command constraint is broader.
+    if (dominator.command.length > 0 && candidate.command.length > 0) {
+        if (dominator.command.length > candidate.command.length)
+            return undefined;
+    }
+    // args: same logic.
+    if (dominator.args.length > 0 && candidate.args.length > 0) {
+        if (dominator.args.length > candidate.args.length)
+            return undefined;
+    }
+    // paths: same logic.
+    if (dominator.paths.length > 0 && candidate.paths.length > 0) {
+        if (dominator.paths.length > candidate.paths.length)
+            return undefined;
+    }
+    // New dimensions: if dominator has fewer constraints, it's broader.
+    // params
+    if (dominator.params.length > 0 && candidate.params.length > 0) {
+        if (dominator.params.length > candidate.params.length)
+            return undefined;
+    }
+    // absent
+    if (dominator.absent.length > 0 && candidate.absent.length > 0) {
+        if (dominator.absent.length > candidate.absent.length)
+            return undefined;
+    }
+    // agents
+    if (dominator.agents.length > 0 && candidate.agents.length > 0) {
+        if (dominator.agents.length > candidate.agents.length)
+            return undefined;
+    }
+    // when: dominator with no when = broader
+    if (dominator.when !== undefined && candidate.when === undefined) {
+        return undefined; // dominator is stricter
+    }
+    // network: dominator with no network = broader
+    if (dominator.network !== undefined && candidate.network === undefined) {
+        return undefined; // dominator is stricter
+    }
+    // If we get here, dominator has no constraints that candidate doesn't also
+    // have (or has fewer/equal constraints). This is a potential shadow.
+    // Only flag if dominator is strictly broader on at least one dimension.
+    const dominatorBroad = isStrictlyBroader(dominator, candidate);
+    if (dominatorBroad !== undefined)
+        return dominatorBroad;
+    return undefined;
+}
+/**
+ * Check if dominator is strictly broader than candidate on at least one dimension.
+ */
+function isStrictlyBroader(dominator, candidate) {
+    // tools: empty = every tool (broader)
+    if (dominator.tools.length === 0 && candidate.tools.length > 0) {
+        return `dominator has no tools constraint (matches all tools)`;
+    }
+    // command: empty = no command constraint (broader)
+    if (dominator.command.length === 0 && candidate.command.length > 0) {
+        return `dominator has no command constraint`;
+    }
+    // args: empty = no args constraint (broader)
+    if (dominator.args.length === 0 && candidate.args.length > 0) {
+        return `dominator has no args constraint`;
+    }
+    // paths: empty = no paths constraint (broader)
+    if (dominator.paths.length === 0 && candidate.paths.length > 0) {
+        return `dominator has no paths constraint`;
+    }
+    // params: empty = no params constraint (broader)
+    if (dominator.params.length === 0 && candidate.params.length > 0) {
+        return `dominator has no params constraint`;
+    }
+    // absent: empty = no absent constraint (broader)
+    if (dominator.absent.length === 0 && candidate.absent.length > 0) {
+        return `dominator has no absent constraint`;
+    }
+    // agents: empty = no agents constraint (broader)
+    if (dominator.agents.length === 0 && candidate.agents.length > 0) {
+        return `dominator has no agents constraint`;
+    }
+    return undefined;
+}

package/lib/watch.d.ts

@@ -0,0 +1,42 @@
+export interface WatcherOptions {
+    /** Debounce interval in ms. Default 300. */
+    readonly debounceMs?: number;
+    /** Maximum number of workspace watchers to keep. Default 10. */
+    readonly maxWatchers?: number;
+    /** Logger sink. */
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/**
+ * Manages file watchers for rule files across workspaces.
+ * Each workspace gets its own watcher set; LRU eviction caps total count.
+ */
+export declare class RuleWatcher {
+    private readonly watchers;
+    private readonly debounceMs;
+    private readonly maxWatchers;
+    private readonly logger;
+    constructor(options?: WatcherOptions);
+    /**
+     * Start watching rule files for a workspace.
+     *
+     * @param cwd - The workspace root.
+     * @param ruleFiles - Absolute paths to the effective rule files (chain).
+     * @param reload - Callback to invoke (debounced) on any change.
+     */
+    watch(cwd: string, ruleFiles: readonly string[], reload: () => void): void;
+    /**
+     * Stop watching a specific workspace.
+     */
+    unwatch(cwd: string): void;
+    /**
+     * Stop all watchers and clear state.
+     */
+    closeAll(): void;
+    /** Number of active workspace watchers. */
+    activeWatcherCount(): number;
+    /** Number of pending (debounced) reloads. */
+    pendingReloadCount(): number;
+    private evictIfNeeded;
+}

package/lib/watch.js

@@ -0,0 +1,170 @@
+/**
+ * File watching for dsh-perm-gate rule hot-reload.
+ *
+ * Watches the effective rules files (the chain resolved for each workspace)
+ * and triggers a debounced `runtime.reload()` when any file changes. Also
+ * monitors candidate files (expected-but-absent files) through their deepest
+ * existing ancestor directory, so mid-session file creation is adopted.
+ *
+ * Design:
+ * - Chokidar for cross-platform reliability (PerryLink-validated).
+ * - Debounce window: multiple rapid writes within `debounceMs` merge into
+ *   one reload.
+ * - Chain-level: any file change triggers a full chain recompilation.
+ * - LRU eviction: workspace watchers are capped; least-recently-used are
+ *   closed when the cap is exceeded.
+ * - All registrations go through `ctx.effect()` for clean teardown.
+ */
+import { watch as chokidarWatch } from 'chokidar';
+import { dirname, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+// ─── RuleWatcher ───────────────────────────────────────────────────────────
+/**
+ * Manages file watchers for rule files across workspaces.
+ * Each workspace gets its own watcher set; LRU eviction caps total count.
+ */
+export class RuleWatcher {
+    watchers = new Map();
+    debounceMs;
+    maxWatchers;
+    logger;
+    constructor(options = { logger: console }) {
+        this.debounceMs = options.debounceMs ?? 300;
+        this.maxWatchers = options.maxWatchers ?? 10;
+        this.logger = options.logger;
+    }
+    /**
+     * Start watching rule files for a workspace.
+     *
+     * @param cwd - The workspace root.
+     * @param ruleFiles - Absolute paths to the effective rule files (chain).
+     * @param reload - Callback to invoke (debounced) on any change.
+     */
+    watch(cwd, ruleFiles, reload) {
+        const key = resolve(cwd).toLowerCase();
+        // If already watching this workspace, just update the access time.
+        const existing = this.watchers.get(key);
+        if (existing !== undefined) {
+            existing.lastAccess = Date.now();
+            return;
+        }
+        // Evict LRU if at capacity.
+        this.evictIfNeeded();
+        // Collect all paths to watch: effective files + candidate file ancestors.
+        const paths = new Set();
+        for (const file of ruleFiles) {
+            paths.add(file);
+            // T3.3: Watch deepest existing ancestor for candidate files.
+            const ancestor = deepestExistingAncestor(file);
+            if (ancestor !== undefined)
+                paths.add(ancestor);
+        }
+        const watcher = chokidarWatch([...paths], {
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        });
+        let timer = null;
+        const debouncedReload = () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                try {
+                    reload();
+                }
+                catch (error) {
+                    this.logger.warn(`[dsh-perm-gate] rule reload failed: ${String(error)}`);
+                }
+            }, this.debounceMs);
+        };
+        watcher.on('change', debouncedReload);
+        watcher.on('add', debouncedReload);
+        watcher.on('unlink', debouncedReload);
+        watcher.on('error', (error) => {
+            this.logger.warn(`[dsh-perm-gate] watcher error: ${String(error)}`);
+        });
+        const entry = { cwd, watcher, timer, lastAccess: Date.now() };
+        this.watchers.set(key, entry);
+    }
+    /**
+     * Stop watching a specific workspace.
+     */
+    unwatch(cwd) {
+        const key = resolve(cwd).toLowerCase();
+        const entry = this.watchers.get(key);
+        if (entry === undefined)
+            return;
+        if (entry.timer !== null)
+            clearTimeout(entry.timer);
+        void entry.watcher.close();
+        this.watchers.delete(key);
+    }
+    /**
+     * Stop all watchers and clear state.
+     */
+    closeAll() {
+        for (const entry of this.watchers.values()) {
+            if (entry.timer !== null)
+                clearTimeout(entry.timer);
+            void entry.watcher.close();
+        }
+        this.watchers.clear();
+    }
+    /** Number of active workspace watchers. */
+    activeWatcherCount() {
+        return this.watchers.size;
+    }
+    /** Number of pending (debounced) reloads. */
+    pendingReloadCount() {
+        let count = 0;
+        for (const entry of this.watchers.values()) {
+            if (entry.timer !== null)
+                count++;
+        }
+        return count;
+    }
+    // ─── LRU eviction ──────────────────────────────────────────────────
+    evictIfNeeded() {
+        if (this.watchers.size < this.maxWatchers)
+            return;
+        // Find the least-recently-used entry.
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.watchers) {
+            if (entry.lastAccess < oldestTime) {
+                oldestTime = entry.lastAccess;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey !== undefined) {
+            this.unwatch(oldestKey);
+        }
+    }
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/**
+ * Find the deepest existing ancestor directory of a file path.
+ * Used to watch for candidate files (expected-but-absent) through their
+ * closest existing parent.
+ */
+function deepestExistingAncestor(filePath) {
+    let dir = dirname(resolve(filePath));
+    let prev = '';
+    while (dir !== prev) {
+        if (existsSafe(dir))
+            return dir;
+        prev = dir;
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+function existsSafe(path) {
+    try {
+        const stat = statSync(path);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "dsh-perm-gate",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "DSH permission-gate for the DeepSeek Harness 0.1.2+ line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
   "type": "module",
   "files": [
     "lib",
+    "scripts/patch-permission-glyph.mjs",
     "cordis.patch.yml",
+    "dsh.plugin.json",
     "assets",
     "examples",
     "README.md",
@@ -54,7 +56,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "dsh-perm-gate": "./lib/cli.js"
+    "dsh-perm-gate": "./lib/cli.js",
+    "dsh-perm-gate-patch-glyph": "./scripts/patch-permission-glyph.mjs"
   },
   "engines": {
     "node": ">=20",
@@ -65,6 +68,7 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.0",
+    "chokidar": "^5.0.0",
     "yaml": "^2.5.0"
   },
   "devDependencies": {
@@ -89,6 +93,8 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
     "lint": "eslint src test scripts tsdown.config.ts eslint.config.mjs",
     "test": "vitest run",
+    "patch:glyph": "node scripts/patch-permission-glyph.mjs",
+    "patch:glyph:check": "node scripts/patch-permission-glyph.mjs --check",
     "verify:line": "node scripts/verify-line.mjs new",
     "verify:lines": "node scripts/verify-line.mjs both",
     "release:latest": "npm publish --tag latest",

package/scripts/patch-permission-glyph.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Add `permissive-full` to the DSH composer's permission-glyph map.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The composer's permission picker renders an icon per preset, looked up in a
+ * CLOSED map inside `@deepseek-ai/dsh-client-ui-conversation`:
+ *
+ *     const permissionGlyphs = new Map([
+ *       ["read-only", <svg …/>],
+ *       ["permissive", <svg …/>],          // the 自动审查 tier's shield+eye
+ *       ["workspace-write", <svg …/>],
+ *       ["danger-full-access", <svg …/>],
+ *     ]);
+ *     function permissionGlyph(value) { return permissionGlyphs.get(value); }
+ *
+ * The source comment states the rule: "host-configured names outside the design
+ * set get none." There is no plugin-facing seam — the option objects the host
+ * supplies carry only `{value, name, description}`, and the map itself is a
+ * closure variable. So a plugin-contributed tier such as `permissive-full`
+ * renders with no icon in the dropdown and falls back to plain text in the
+ * trigger, while the built-in `permissive` tier shows the shield+eye.
+ *
+ * The only way to give our tier the same glyph is to add an entry to that map.
+ * This script does exactly that: it duplicates the `permissive` entry under the
+ * `permissive-full` key, so the two tiers of one plugin look alike.
+ *
+ * VOLUNTARY, NOT AUTOMATIC
+ * ------------------------
+ * This edits a **host** package. It is deliberately NOT wired to `postinstall`:
+ * a plugin must not rewrite the harness it is installed into without being
+ * asked. Run it yourself, and re-run it after every DSH upgrade — a DSH
+ * upgrade replaces the file and the patch is gone. Reinstalling this plugin
+ * does NOT bring it back: `dsh plugin --profile web add …` writes only the
+ * profile's own `node_modules`, and on a stock install the DSH package, the
+ * profile's `node_modules` entry and this bundle are three paths to ONE file
+ * (a symlink and a junction into the same inode).
+ *
+ * USAGE
+ *   npx dsh-perm-gate-patch-glyph              # patch the bundle it finds
+ *   npx dsh-perm-gate-patch-glyph --check      # report only; exit 1 if missing
+ *   node scripts/patch-permission-glyph.mjs <path/to/client.js>
+ *
+ * With no argument it probes the usual global-install locations. The script is
+ * idempotent (a second run is a no-op), backs the file up once, and refuses to
+ * write a bundle it cannot slice correctly, so it can never half-apply.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** The map key whose entry is cloned, and the key it is cloned onto. */
+export const SOURCE_KEY = 'permissive'
+export const TARGET_KEY = 'permissive-full'
+
+/** Relative path from a package root to the bundle holding the map. */
+const BUNDLE = join('@deepseek-ai', 'dsh-client-ui-conversation', 'lib', 'client.js')
+
+/** Thrown for every refusal; the CLI turns it into an exit code 1. */
+export class GlyphPatchError extends Error {}
+
+/**
+ * Candidate bundle paths, most specific first. Pure: no filesystem access, so
+ * the probe order is unit-testable.
+ *
+ * `execDir` is `dirname(process.execPath)`. Deriving from the running node
+ * binary — never from a hardcoded nvm version or install path — is what keeps
+ * the script working across node upgrades and re-pointed install symlinks.
+ *
+ * @param {{ execDir: string, cwd: string, dshHome: string }} where
+ * @returns {string[]} absolute candidate paths
+ */
+export function candidateBundles({ execDir, cwd, dshHome }) {
+  return [
+    // 1. `@deepseek-ai` scope hoisted beside the running node binary.
+    join(execDir, 'node_modules', BUNDLE),
+    // 2. The same scope nested inside the `dsh` package itself.
+    join(execDir, 'node_modules', '@deepseek-ai', 'dsh', 'node_modules', BUNDLE),
+    // 3. Whatever profile the caller is standing in.
+    join(cwd, 'node_modules', BUNDLE),
+    // 4. The hoisted scope shared by every profile under DSH_HOME.
+    join(dshHome, 'profiles', 'node_modules', BUNDLE),
+  ]
+}
+
+/**
+ * Extract the full `["<key>", …]` map entry, by bracket depth.
+ *
+ * The scan starts ON the entry's opening `[` (the one immediately before the
+ * key), so depth returns to zero exactly at that entry's closing `]`. Starting
+ * anywhere else — e.g. at the first `(` of the value expression — ends the
+ * slice in the wrong place and yields a broken bundle.
+ *
+ * Safe here because the entry's only string literals (svg path `d` attributes)
+ * contain no brackets.
+ *
+ * @param {string} source
+ * @param {string} key
+ * @returns {string} the entry, brackets included
+ */
+export function sliceEntry(source, key) {
+  const start = source.indexOf(`["${key}",`)
+  if (start === -1) throw new GlyphPatchError(`anchor not found: ["${key}",`)
+  let depth = 0
+  for (let i = start; i < source.length; i += 1) {
+    const ch = source[i]
+    if (ch === '[' || ch === '(' || ch === '{') depth += 1
+    else if (ch === ']' || ch === ')' || ch === '}') {
+      depth -= 1
+      if (depth === 0) return source.slice(start, i + 1)
+    }
+  }
+  throw new GlyphPatchError(`unterminated entry for ["${key}",`)
+}
+
+/**
+ * Clone the `permissive` glyph entry onto the `permissive-full` key.
+ *
+ * @param {string} source the bundle's text
+ * @returns {{ changed: boolean, source: string, entry: string | null }}
+ *   `changed: false` means the target key was already present (idempotent no-op).
+ */
+export function applyGlyphPatch(source) {
+  if (source.includes(`["${TARGET_KEY}",`)) return { changed: false, source, entry: null }
+  const sourceEntry = sliceEntry(source, SOURCE_KEY)
+  if (!sourceEntry.includes('svg')) {
+    throw new GlyphPatchError(`the ["${SOURCE_KEY}",] entry does not look like a glyph`)
+  }
+  const clonedEntry = sourceEntry.replace(`["${SOURCE_KEY}",`, `["${TARGET_KEY}",`)
+  return { changed: true, source: source.replace(sourceEntry, `${sourceEntry},\n\t\t\t${clonedEntry}`), entry: clonedEntry }
+}
+
+/** Resolve the bundle to patch, or throw with an explanation. */
+export function findBundle(argv, where) {
+  const explicit = argv.slice(2).find((arg) => !arg.startsWith('-'))
+  if (explicit !== undefined && explicit !== '') {
+    const p = resolve(explicit)
+    if (!existsSync(p)) throw new GlyphPatchError(`no such file: ${p}`)
+    return p
+  }
+  for (const candidate of candidateBundles(where)) {
+    if (existsSync(candidate)) return candidate
+  }
+  throw new GlyphPatchError(
+    'could not locate @deepseek-ai/dsh-client-ui-conversation.\n' +
+    'Pass the bundle path explicitly:\n' +
+    `  ${argv[1] ?? 'dsh-perm-gate-patch-glyph'} <…>/dsh-client-ui-conversation/lib/client.js`,
+  )
+}
+
+function main(argv) {
+  const check = argv.includes('--check')
+  const where = {
+    execDir: dirname(process.execPath),
+    cwd: process.cwd(),
+    dshHome: process.env.DSH_HOME ?? join(homedir(), '.dsh'),
+  }
+
+  const bundle = findBundle(argv, where)
+  const original = readFileSync(bundle, 'utf8')
+  const { changed, source: patched } = applyGlyphPatch(original)
+
+  if (!changed) {
+    process.stdout.write(`patch-permission-glyph: ["${TARGET_KEY}",] already present in\n  ${bundle}\n`)
+    return 0
+  }
+  if (check) {
+    process.stdout.write(
+      `patch-permission-glyph: ["${TARGET_KEY}",] is MISSING from\n  ${bundle}\n` +
+      '  (--check: nothing written; re-run without --check to apply)\n',
+    )
+    return 1
+  }
+
+  // Back up once, then write.
+  const backup = `${bundle}.bak-permgate-glyph`
+  if (!existsSync(backup)) copyFileSync(bundle, backup)
+  writeFileSync(bundle, patched, 'utf8')
+
+  // Fail loudly rather than leaving a broken bundle behind.
+  try {
+    execFileSync(process.execPath, ['--check', bundle], { stdio: 'pipe' })
+  } catch (error) {
+    copyFileSync(backup, bundle)
+    throw new GlyphPatchError(`syntax check failed; restored the backup.\n${String(error?.stderr ?? error)}`)
+  }
+
+  process.stdout.write(
+    `patch-permission-glyph: added ["${TARGET_KEY}",] to\n  ${bundle}\n` +
+    `  backup: ${backup}\n` +
+    '  NOTE: this edits a DSH package — re-run after any DSH upgrade or reinstall.\n',
+  )
+  return 0
+}
+
+const invokedDirectly = process.argv[1] !== undefined
+  && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+
+if (invokedDirectly) {
+  try {
+    process.exitCode = main(process.argv)
+  } catch (error) {
+    process.stderr.write(`patch-permission-glyph: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  }
+}