dsh-perm-gate 3.0.0 → 4.0.0

package/lib/events.d.ts

@@ -100,6 +100,13 @@ export declare class EventLog {
     /** Snapshot directory; `undefined` disables diff/revert support. */
     private readonly snapshotsDir;
     private seq;
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    private readonly listeners;
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath: string | undefined, now?: () => number, 
@@ -107,6 +114,15 @@ export declare class EventLog {
     snapshotsDir?: string | undefined);
     /** Append one event; returns it, or undefined when recording is disabled/failed. */
     append(input: GateEventInput): GateEvent | undefined;
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener: (event: GateEvent) => void): () => void;
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since }?: {
         sessionId?: string;
@@ -128,6 +144,7 @@ export interface WebServerLike {
     }): () => void;
 }
 export declare const EVENTS_ROUTE = "/api/dsh-perm-gate/events";
+export declare const STREAM_ROUTE = "/api/dsh-perm-gate/stream";
 export declare const LEARNING_ROUTE = "/api/dsh-perm-gate/learning";
 export declare const HEALTH_ROUTE = "/api/dsh-perm-gate/health";
 export declare const NETWORK_ROUTE = "/api/dsh-perm-gate/network";
@@ -144,6 +161,24 @@ export declare const RULES_ROUTE = "/api/dsh-perm-gate/rules";
  * unavailable — the host keeps running, only the HTTP API is missing).
  */
 export declare function registerEventsRoute(server: unknown, log: EventLog): (() => void) | undefined;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export declare function registerStreamRoute(server: unknown, log: EventLog): (() => void) | undefined;
 /** Delivers a revert instruction into the conversation (see index.ts wiring). */
 export type SessionSender = (sessionId: string, content: string) => Promise<{
     ok: boolean;

package/lib/events.js

@@ -224,6 +224,13 @@ export class EventLog {
     now;
     snapshotsDir;
     seq = -1; // lazily restored from the file on first append
+    /**
+     * Live subscribers, notified once per successfully appended event. They exist
+     * so a browser half can be pushed to instead of re-reading the whole JSONL on
+     * a timer; a subscriber that throws is dropped from the notification only, it
+     * never costs the append its event.
+     */
+    listeners = new Set();
     constructor(
     /** JSONL path; `undefined` disables event recording entirely. */
     filePath, now = Date.now, 
@@ -266,12 +273,34 @@ export class EventLog {
             if ((ev.kind === 'auto' || ev.kind === 'ask') && this.snapshotsDir !== undefined && files !== undefined) {
                 saveEventSnapshots(this.snapshotsDir, ev.id, files, input.baseDir, ev.sessionId, this.now);
             }
+            for (const listener of this.listeners) {
+                try {
+                    listener(ev);
+                }
+                catch {
+                    // A dead subscriber must not fail the append, and must not stop the others.
+                }
+            }
             return ev;
         }
         catch {
             return undefined; // best-effort only
         }
     }
+    /**
+     * Watch events as they are appended. The listener is called once per event,
+     * after the JSONL write, from inside `append` — so it runs on the gate's own
+     * decision path and must stay cheap and non-throwing.
+     *
+     * @param listener - receives each appended event.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
     /** Events with `id > since`, optionally filtered to one session. */
     query({ sessionId, since } = {}) {
         if (this.filePath === undefined)
@@ -349,6 +378,7 @@ function readBody(req, limit = 1024 * 1024) {
     });
 }
 export const EVENTS_ROUTE = '/api/dsh-perm-gate/events';
+export const STREAM_ROUTE = '/api/dsh-perm-gate/stream';
 export const LEARNING_ROUTE = '/api/dsh-perm-gate/learning';
 export const HEALTH_ROUTE = '/api/dsh-perm-gate/health';
 export const NETWORK_ROUTE = '/api/dsh-perm-gate/network';
@@ -395,6 +425,104 @@ export function registerEventsRoute(server, log) {
         },
     });
 }
+/** Keep-alive cadence of {@link registerStreamRoute}: a comment line that keeps an idle stream from being reaped. */
+const STREAM_PING_MS = 15_000;
+/**
+ * Register `GET /api/dsh-perm-gate/stream?sessionId=&since=` on the webServer
+ * service: the same events {@link registerEventsRoute} serves, but pushed.
+ *
+ * The response is `text/event-stream`. On connect the backlog after `since` is
+ * written as one `data: {"events":[…],"backlog":true}` frame, then each event
+ * appended from that moment on is written as it lands as `data: {"events":[…]}` —
+ * so the browser half is never forced to re-read the whole JSONL on a timer.
+ * `: ping` comments hold the connection open while nothing is being decided.
+ *
+ * The session filter applies to both the backlog and the live pushes. Nothing
+ * is buffered for a disconnected client: it reconnects with its own cursor and
+ * the backlog frame restores it.
+ *
+ * Returns the unregister, or `undefined` when the webServer service is
+ * unavailable — the host keeps running, only the HTTP API is missing.
+ */
+export function registerStreamRoute(server, log) {
+    const ws = routeServer(server);
+    if (ws === undefined)
+        return undefined;
+    return ws.register({
+        kind: 'exact',
+        path: STREAM_ROUTE,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'GET') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            if (res.write === undefined) {
+                // A server that cannot stream: fail the handshake instead of hanging the browser's EventSource.
+                res.writeHead(500);
+                res.end();
+                return;
+            }
+            let sessionId;
+            let since;
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                sessionId = url.searchParams.get('sessionId') ?? undefined;
+                const raw = url.searchParams.get('since');
+                if (raw !== null && raw !== '')
+                    since = Number.parseInt(raw, 10) || 0;
+            }
+            catch {
+                // unparseable URL: stream the unfiltered tail
+            }
+            const scoped = sessionId !== undefined && sessionId !== '';
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                'x-accel-buffering': 'no',
+            });
+            const push = (events, backlog = false) => {
+                // The backlog frame is written even when it is empty: it marks where
+                // history stops, so the consumer never mistakes a live event for a replay.
+                if (events.length === 0 && !backlog)
+                    return;
+                try {
+                    res.write?.(`data: ${JSON.stringify(backlog ? { events, backlog: true } : { events })}\n\n`);
+                }
+                catch {
+                    // The socket died between the close event and this write; `close` owns the teardown.
+                }
+            };
+            push(log.query({ sessionId, since }), true);
+            const unsubscribe = log.subscribe((event) => {
+                if (scoped && event.sessionId !== sessionId)
+                    return;
+                push([event]);
+            });
+            const keepAlive = setInterval(() => {
+                try {
+                    res.write?.(': ping\n\n');
+                }
+                catch {
+                    // ignore: `close` owns the teardown
+                }
+            }, STREAM_PING_MS);
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                clearInterval(keepAlive);
+                unsubscribe();
+            };
+            res.on?.('close', close);
+            res.on?.('error', close);
+        },
+    });
+}
 /**
  * Register the review-page routes:
  * `GET  /diff?eventId=&path=`        → before/after line diff for one file

package/lib/index.js

@@ -4,7 +4,7 @@ import { parse } from 'yaml';
 import { Config, RULES_NAMESPACE, RulesSchema, isRulesConfigured, readRulesFromSettings, resolveDshHome, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
 import { appendAllowToSettings, replaceAllowInSettings } from './allowlist.js';
 import { runDryRun } from './dry-run.js';
-import { registerDryRunRoute, registerEventsRoute, registerHealthRoute, registerLearningRoute, registerNetworkRoute, registerReceiverRoute, registerReviewRoutes, registerRulesRoute } from './events.js';
+import { registerDryRunRoute, registerEventsRoute, registerHealthRoute, registerLearningRoute, registerNetworkRoute, registerReceiverRoute, registerReviewRoutes, registerRulesRoute, registerStreamRoute } from './events.js';
 import { buildReceiverInfo } from './receiver-info.js';
 import { readRulesView, readRulesViewFromSettings } from './rules-view.js';
 import { PermGateRuntime } from './runtime.js';
@@ -520,6 +520,11 @@ export function apply(ctx, config = {}) {
             const offEvents = registerEventsRoute(webServer, runtime.eventLog);
             if (offEvents !== undefined)
                 ctx.effect(() => () => { offEvents(); }, 'dsh-perm-gate: events route');
+            // Push plane: the browser half follows decisions over one SSE connection
+            // instead of re-reading the event log on a timer.
+            const offStream = registerStreamRoute(webServer, runtime.eventLog);
+            if (offStream !== undefined)
+                ctx.effect(() => () => { offStream(); }, 'dsh-perm-gate: stream route');
         }
         // Review-page plane (diff / revert / snapshot stats / snapshot clear): the
         // approval-history view's file chips and snapshot bar drive these.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "dsh-perm-gate",
-  "version": "3.0.0",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public",
-    "tag": "dsh-0.1.2"
+  "version": "4.0.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "tag": "dsh-0.1.5"
   },
-  "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.",
+  "description": "DSH permission-gate for the DeepSeek Harness 0.1.5 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",
@@ -66,8 +66,8 @@
     "dsh-perm-gate-patch-glyph": "./scripts/patch-permission-glyph.mjs"
   },
   "engines": {
-    "node": ">=20",
-    "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
+    "node": ">=24",
+    "dsh": ">=0.1.5-rc.1 <0.2.0-0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
@@ -106,7 +106,8 @@
     "check:line": "node scripts/sync-0.1.5-line.mjs check",
     "release:latest": "npm publish --tag latest",
     "release:2x": "npm publish --tag 2.x",
-    "release:legacy": "npm publish --tag legacy"
+    "release:legacy": "npm publish --tag legacy",
+    "release:3x": "npm publish --tag dsh-0.1.5"
   },
   "license": "MIT",
   "repository": {

package/docs/plan-rules-to-settings.md

@@ -1,217 +0,0 @@
-# Plan: rules.yml → DSH Settings Namespace Migration
-
-## Goal
-
-Eliminate the external `rules.yml` file dependency by migrating rules into the DSH settings namespace (`dsh-perm-gate.rules`). This solves the cold-start directory problem at the root cause: settings are managed by the framework and loaded before any plugin `apply()` runs.
-
-## Current Architecture
-
-```
-User edits rules.yml (or allowlist card writes to it)
-  ↓
-resolveRulesFile() → path string
-  ↓
-readFileSafe() → raw YAML text
-  ↓
-parsePermissionsDocument() → structured doc
-  ↓
-compileDocument() → CompiledRuleset
-  ↓
-PermGateRuntime.decide() → verdict
-```
-
-Read-only view:
-```
-GET /api/dsh-perm-gate/rules
-  → readRulesView(rulesFile)
-    → statSync + readFileSync + parse + compile
-    → RulesView { path, exists, bytes, hash, raw, counts, error }
-```
-
-Write path (allowlist card):
-```
-appendAllowCommand() / replaceAllowCommands()
-  → readFileSync → parse → mutate → stringify → writeFileSync
-```
-
-## Target Architecture
-
-```
-User edits via settings card (or API)
-  ↓
-settings.get('dsh-perm-gate.rules') → structured object (already parsed)
-  ↓
-compileDocument(rules) → CompiledRuleset
-  ↓
-PermGateRuntime.decide() → verdict
-```
-
-Read-only view:
-```
-GET /api/dsh-perm-gate/rules
-  → settings.get('dsh-perm-gate.rules')
-    → RulesView { source: 'settings', rules: {...}, counts, hash }
-```
-
-Write path (allowlist card):
-```
-settings.update({ rules: { allow: [...] } })
-  → framework persists to settings.yaml
-  → settings.watch() triggers reload
-```
-
-## Schema (config.ts)
-
-```typescript
-// New settings schema for rules
-const RuleEntrySchema = z.object({
-  command: z.array(z.string()).optional(),
-  args: z.array(z.string()).optional(),
-  tools: z.array(z.string()).optional(),
-  network: z.object({
-    domains: z.array(z.string()),
-  }).optional(),
-  reason: z.string().default(''),
-})
-
-const RulesSchema = z.object({
-  defaultAction: z.enum(['allow', 'deny', 'ask']).default('ask'),
-  deny: z.array(RuleEntrySchema).default([]),
-  allow: z.array(RuleEntrySchema).default([]),
-  ask: z.array(RuleEntrySchema).default([]),
-  network: z.object({
-    domains: z.array(z.string()).default([]),
-  }).optional(),
-}).default({ defaultAction: 'ask', deny: [], allow: [] })
-```
-
-## Migration Steps
-
-### Phase 1: Dual-Source (backward compatible)
-
-1. **Add `rules` to settings schema** — new field in `dsh-perm-gate` namespace
-2. **Runtime reads from settings first, falls back to file** — `settings.get('rules') ?? loadRulesFile()`
-3. **Allowlist card writes to settings** — `settings.update({ rules: { allow: [...] } })`
-4. **Rules view serves from settings** — `readRulesView()` reads from settings object, not file
-5. **Module-level: still create dataDir** — belt-and-suspenders for the transition period
-
-### Phase 2: File Deprecation
-
-6. **Log deprecation warning** — when `rulesFile` is configured, warn that it's deprecated
-7. **Import button** — UI can import existing `rules.yml` into settings
-8. **Export button** — UI can export settings rules as YAML for version control
-
-### Phase 3: File Removal
-
-9. **Remove `rulesFile` config option** — no longer accepted
-10. **Remove file I/O code** — `allowlist.ts`, `rules-view.ts` file operations
-11. **Remove chokidar watcher** — settings has built-in `watch()`
-12. **Remove dataDir bootstrap** — no longer needed
-
-## How the Read-Only View Changes
-
-### Before (file-based)
-
-```json
-{
-  "path": "C:\\Users\\joshua\\.dsh\\perm-gate\\rules.yml",
-  "exists": true,
-  "bytes": 1513,
-  "hash": "abc123...",
-  "lines": 61,
-  "raw": "permissions:\n  defaultAction: ask\n  deny:\n    ...",
-  "truncated": false,
-  "defaultAction": "ask",
-  "counts": { "allow": 11, "deny": 1, "ask": 0 },
-  "error": null
-}
-```
-
-### After (settings-based)
-
-```json
-{
-  "source": "settings",
-  "defaultAction": "ask",
-  "counts": { "allow": 11, "deny": 1, "ask": 0 },
-  "hash": "abc123...",
-  "rules": {
-    "defaultAction": "ask",
-    "deny": [
-      { "tools": ["shell", "pwsh"], "command": ["rm#recursive"], "reason": "destructive" }
-    ],
-    "allow": [
-      { "command": ["grep"], "reason": "permissive allowlist" }
-    ],
-    "network": {
-      "domains": ["github.com", "registry.npmjs.org"]
-    }
-  }
-}
-```
-
-**Key differences:**
-- `path` / `exists` / `bytes` / `raw` / `truncated` → removed (no file)
-- `source: 'settings'` → added (provenance)
-- `rules` → the structured object (already parsed, not raw YAML)
-- `counts` / `defaultAction` / `hash` → kept (useful for UI)
-
-## How the Allowlist Write Path Changes
-
-### Before (file-based)
-
-```typescript
-// appendAllowCommand reads YAML, mutates, writes back
-appendAllowCommand(rulesFile, 'git push', 'permissive allow-everywhere')
-// → readFileSync → parse → push → stringify → writeFileSync
-```
-
-### After (settings-based)
-
-```typescript
-// Direct settings update
-const current = settings.get('dsh-perm-gate.rules')
-const allow = [...(current.allow ?? []), { command: ['git push'], reason: 'permissive allow-everywhere' }]
-settings.update({ rules: { ...current, allow } })
-// → framework persists → settings.watch() triggers reload
-```
-
-## Files Changed
-
-| File | Change |
-|---|---|
-| `src/config.ts` | Add `RulesSchema`, keep `resolveRulesFile` for backward compat |
-| `src/index.ts` | Read from settings first, fall back to file; register settings schema |
-| `src/runtime.ts` | Accept `rules` object directly (no file read) |
-| `src/rules-view.ts` | Add `readRulesViewFromSettings()` |
-| `src/allowlist.ts` | Add `appendAllowToSettings()`, `replaceAllowInSettings()` |
-| `src/events.ts` | Update `registerRulesRoute` to use settings view |
-| `src/watch.ts` | Remove chokidar watcher (settings has built-in watch) |
-
-## Cold-Start Resilience (All Plugins)
-
-The same pattern should be applied to other plugins that read files at startup:
-
-| Plugin | Data | Risk | Fix |
-|---|---|---|---|
-| `dsh-perm-gate` | rules.yml | HIGH | Settings migration (this plan) |
-| `dsh-search-index` | index files | MEDIUM | dataDir bootstrap + try/catch |
-| `dsh-session-guard` | guard config | LOW | Already settings-backed |
-| `dsh-prime-memory` | memory files | MEDIUM | dataDir bootstrap + try/catch |
-| `dsh-context-compression` | config | LOW | Already settings-backed |
-
-**Universal pattern:**
-1. Module-level `ensureDataDir()` — belt
-2. Read paths: `dataDirReady()` check → empty defaults if missing
-3. Write paths: `ensureDataDir()` before first write
-4. All file reads wrapped in try/catch with graceful fallback
-
-## Testing
-
-- [ ] Unit: `compileDocument` with settings-sourced rules (same as YAML-sourced)
-- [ ] Unit: `readRulesViewFromSettings` returns correct `RulesView`
-- [ ] Unit: `appendAllowToSettings` correctly mutates settings object
-- [ ] Integration: settings card reads and displays rules
-- [ ] Integration: allowlist card writes persist to settings
-- [ ] Migration: existing `rules.yml` imports into settings correctly
-- [ ] Cold start: plugin loads with empty settings (no rules configured)