@xth26/dsh-plan-build-mode 0.4.0 → 0.5.0

package/lib/permissions.js

@@ -0,0 +1,351 @@
+/**
+ * OpenCode-style tool permission engine for `dsh-plan-build-mode`.
+ *
+ * Models OpenCode's `permission` system — allow | ask | deny per tool
+ * category, object-syntax rules with last-match-wins, `~`/`$HOME` expansion,
+ * and the `external_directory` gate that asks for any path outside the
+ * session workspace — as pure, testable functions evaluated by the plugin's
+ * `tools/pre-execute` hook.
+ *
+ * The DSH sandbox stays the hard enforcement floor: a permission grant can
+ * never widen what the sandbox permits, and the gate only ever `ask`s for
+ * targets the sandbox can actually allow (the single-prompt principle — an
+ * external write the sandbox rejects goes straight to the existing
+ * sandbox-escalation flow instead of asking here first).
+ *
+ * @module dsh-plan-build-mode/permissions
+ */
+import { canonicalPath } from '@deepseek-ai/dsh-sandbox';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, relative, resolve } from 'node:path';
+/** Scalar default action per category (the fallback when no value is given). */
+export const DEFAULT_ACTIONS = {
+    read: 'allow',
+    edit: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    bash: 'allow',
+    pwsh: 'allow',
+    webfetch: 'allow',
+    websearch: 'allow',
+};
+/** Global default actions, mirroring OpenCode (most allow; `.env*` reads denied). */
+export const DEFAULT_PERMISSION = {
+    read: { '*': 'allow', '**/.env': 'deny', '**/.env.*': 'deny', '**/.env.example': 'allow' },
+    edit: DEFAULT_ACTIONS.edit,
+    glob: DEFAULT_ACTIONS.glob,
+    grep: DEFAULT_ACTIONS.grep,
+    bash: DEFAULT_ACTIONS.bash,
+    pwsh: DEFAULT_ACTIONS.pwsh,
+    webfetch: DEFAULT_ACTIONS.webfetch,
+    websearch: DEFAULT_ACTIONS.websearch,
+};
+/** Default Plan-mode overrides (write tools denied, commands ask). */
+export const DEFAULT_PLAN_OVERRIDES = {
+    edit: 'deny',
+    bash: 'ask',
+    pwsh: 'ask',
+};
+/**
+ * Default `external_directory` action. Reads of files outside the workspace
+ * stay permitted (DSH reads pass through every sandbox mode); only writes are
+ * gated. Set to `'ask'` for full OpenCode behavior (external access prompts).
+ */
+export const DEFAULT_EXTERNAL_DEFAULT = 'allow';
+/** Tools gated under the `read` category. */
+const READ_TOOLS = ['read', 'read_image', 'pdf_read', 'docx_read', 'pptx_read', 'xlsx_read'];
+/** Tools gated under the `edit` category (OpenCode: `write` is controlled by `edit`). */
+const WRITE_TOOLS = [
+    'write',
+    'edit',
+    'pdf_create',
+    'docx_create',
+    'pptx_create',
+    'xlsx_write',
+    'pptx_edit',
+    'xlsx_edit',
+];
+/** Path argument keys per tool name (verified against the DSH tool schemas). */
+const TOOL_PATH_KEYS = {
+    read: ['file_path'],
+    read_image: ['file_path'],
+    pdf_read: ['file_path'],
+    docx_read: ['file_path'],
+    pptx_read: ['file_path'],
+    xlsx_read: ['file_path'],
+    write: ['file_path'],
+    edit: ['file_path'],
+    pptx_edit: ['file_path'],
+    xlsx_edit: ['file_path'],
+    pdf_create: ['destination_path'],
+    docx_create: ['destination_path'],
+    pptx_create: ['destination_path'],
+    xlsx_write: ['file_path'],
+    glob: ['path'],
+    grep: ['path'],
+};
+/** Map a tool name to its permission category, or undefined for ungated tools. */
+export function categoryOf(name) {
+    if (READ_TOOLS.includes(name))
+        return 'read';
+    if (WRITE_TOOLS.includes(name))
+        return 'edit';
+    switch (name) {
+        case 'glob':
+            return 'glob';
+        case 'grep':
+            return 'grep';
+        case 'bash':
+            return 'bash';
+        case 'pwsh':
+            return 'pwsh';
+        case 'web_fetch':
+            return 'webfetch';
+        case 'web_search':
+            return 'websearch';
+        default:
+            return undefined;
+    }
+}
+/** The static directory prefix of a glob pattern (`src/**\/*.ts` → `src`). */
+function patternBaseDir(pattern) {
+    const firstWild = pattern.search(/[*?]/);
+    const head = firstWild === -1 ? pattern : pattern.slice(0, firstWild);
+    const idx = head.lastIndexOf('/');
+    if (idx <= 0)
+        return undefined;
+    return head.slice(0, idx);
+}
+/**
+ * Extract the model-controlled path targets from one tool call's parsed
+ * arguments. Unknown or malformed arguments yield no targets: the category
+ * gate still applies, and the sandbox remains the floor for writes.
+ */
+export function extractTargets(name, args) {
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return [];
+    const record = args;
+    const targets = [];
+    const keys = TOOL_PATH_KEYS[name];
+    if (keys !== undefined) {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === 'string' && value.trim() !== '')
+                targets.push(value);
+        }
+    }
+    if (name === 'glob' || name === 'grep') {
+        const pattern = record.pattern;
+        if (typeof pattern === 'string' && pattern.trim() !== '') {
+            const base = patternBaseDir(pattern);
+            if (base !== undefined && base !== '')
+                targets.push(base);
+        }
+    }
+    return targets;
+}
+/** Extract the raw command text for bash/pwsh tools (used for prefix rules). */
+export function extractCommand(name, args) {
+    if (name !== 'bash' && name !== 'pwsh')
+        return undefined;
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return undefined;
+    const value = args.command;
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** Normalize a path/pattern for cross-platform wildcard matching (forward slashes). */
+export function normalizePath(p) {
+    return p.replace(/\\/g, '/');
+}
+/** Expand `~` / `$HOME` at the start of a pattern to the user home directory. */
+export function expandHome(pattern, home) {
+    if (pattern === '~')
+        return normalizePath(home);
+    if (pattern.startsWith('~/') || pattern.startsWith('~\\'))
+        return normalizePath(home + pattern.slice(1));
+    if (pattern.startsWith('$HOME'))
+        return normalizePath(home + pattern.slice('$HOME'.length));
+    return normalizePath(pattern);
+}
+/** OpenCode wildcard match: `*` = any run, `?` = one char, everything else literal. */
+export function wildcardMatch(pattern, value) {
+    let re = '';
+    for (const ch of pattern) {
+        if (ch === '*')
+            re += '.*';
+        else if (ch === '?')
+            re += '.';
+        else
+            re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`).test(value);
+}
+/** Whether one permission pattern matches a value under the match context. */
+export function ruleMatches(pattern, value, ctx = {}) {
+    const home = ctx.home ?? homedir();
+    const cs = ctx.caseSensitive ?? true;
+    const p = expandHome(pattern, home);
+    const v = normalizePath(value);
+    return wildcardMatch(cs ? p : p.toLowerCase(), cs ? v : v.toLowerCase());
+}
+/**
+ * Evaluate an ordered rule list against any of several subjects, last matching
+ * rule wins (OpenCode's evaluation order). Returns undefined when nothing matches.
+ */
+export function matchRules(rules, subjects, ctx = {}) {
+    if (rules === undefined || rules.length === 0 || subjects.length === 0)
+        return undefined;
+    let hit;
+    for (const subject of subjects) {
+        for (const rule of rules) {
+            if (ruleMatches(rule.pattern, subject, ctx))
+                hit = rule.action;
+        }
+    }
+    return hit;
+}
+/**
+ * Normalize a `PermissionValue` into a scalar action plus ordered rules. The
+ * object form's `*` key becomes the catch-all default; later matching
+ * non-`*` rules override it (last-match-wins).
+ */
+export function resolveCategory(value, fallback) {
+    if (value === undefined)
+        return { action: fallback };
+    if (typeof value === 'string')
+        return { action: value };
+    const rules = [];
+    let action = fallback;
+    for (const [pattern, ruleAction] of Object.entries(value)) {
+        if (pattern === '*') {
+            action = ruleAction;
+        }
+        else {
+            rules.push({ pattern, action: ruleAction });
+        }
+    }
+    return rules.length > 0 ? { action, rules } : { action };
+}
+/** Canonicalize a path (resolve symlinks of the deepest existing ancestor). */
+export function canonicalize(path) {
+    return canonicalPath(path);
+}
+/** Resolve a model-provided path against the session working directory. */
+export function resolveTarget(path, cwd) {
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+/** Whether `target` is `root` or lies beneath it (lexical, canonical spellings). */
+export function isUnder(target, root, caseSensitive) {
+    const t = normalizePath(target);
+    const r = normalizePath(root);
+    if (t === r)
+        return true;
+    const prefix = r.endsWith('/') ? r : `${r}/`;
+    const a = caseSensitive ? t : t.toLowerCase();
+    const b = caseSensitive ? prefix : prefix.toLowerCase();
+    return a.startsWith(b);
+}
+/** Host filesystem case sensitivity (Windows paths compare case-insensitively). */
+export function caseSensitiveHost() {
+    return process.platform !== 'win32';
+}
+/**
+ * Whether the effective sandbox mode would permit a WRITE to the given
+ * canonical target — the single-prompt principle: the gate only asks for
+ * writes the sandbox can actually allow.
+ */
+export function sandboxAllowsWrite(mode, target, workspaceRoot, tempRoots = ['/tmp', tmpdir()]) {
+    if (mode === 'danger-full-access')
+        return true;
+    if (mode === 'workspace-write') {
+        const cs = caseSensitiveHost();
+        return [workspaceRoot, ...tempRoots].some((root) => isUnder(target, canonicalize(root), cs));
+    }
+    return false;
+}
+/** Subjects category rules are matched against: relative and absolute forms. */
+export function matchSubjectsFor(name, targets, workspaceRoot, command) {
+    if (name === 'bash' || name === 'pwsh') {
+        return command === undefined ? [] : [command];
+    }
+    const first = targets[0];
+    if (first === undefined)
+        return [];
+    return [normalizePath(relative(workspaceRoot, first)), normalizePath(first)];
+}
+/**
+ * Pure decision procedure. Order: plans-dir carve-out → external-directory
+ * gate → category gate. `ask` is only returned when an approval channel can
+ * resolve it; writes the sandbox cannot permit never ask (single-prompt
+ * principle — they surface as a `external-write-escalation` denial instead).
+ */
+export function gateDecision(input) {
+    const { mode, category, targets, workspaceRoot, plansDir } = input;
+    const cs = caseSensitiveHost();
+    // 1. Plan-mode plans-directory carve-out (OpenCode `.opencode/plans/`).
+    if (mode === 'plan' &&
+        category === 'edit' &&
+        targets.length > 0 &&
+        targets.every((t) => isUnder(t, plansDir, cs))) {
+        return { kind: 'allow' };
+    }
+    // 2. External-directory gate.
+    const external = targets.filter((t) => !isUnder(t, workspaceRoot, cs));
+    if (external.length > 0) {
+        const context = { caseSensitive: cs };
+        const subject = external[0];
+        if (input.allowlist.some((pattern) => ruleMatches(pattern, subject, context)))
+            return { kind: 'allow' };
+        const action = matchRules(input.externalRules, external, context) ?? input.externalDefault;
+        if (action === 'deny')
+            return { kind: 'deny', code: 'external-deny', target: subject };
+        if (action === 'ask') {
+            if (category === 'edit' && !external.every((t) => input.sandboxAllowsWrite(t))) {
+                return { kind: 'deny', code: 'external-write-escalation', target: subject };
+            }
+            return { kind: 'ask' };
+        }
+        // allow → fall through to the category gate.
+    }
+    // 3. Category gate.
+    if (category === undefined)
+        return { kind: 'allow' };
+    const categoryContext = { caseSensitive: cs };
+    const subject = input.matchSubjects[0];
+    const action = matchRules(input.categorySpec.rules, input.matchSubjects, categoryContext) ?? input.categorySpec.action;
+    if (action === 'deny')
+        return { kind: 'deny', code: 'category-deny', subject };
+    if (action === 'ask') {
+        if (category === 'edit' && targets.length > 0 && !targets.every((t) => input.sandboxAllowsWrite(t))) {
+            return { kind: 'deny', code: 'external-write-escalation', target: targets[0] };
+        }
+        return { kind: 'ask' };
+    }
+    return { kind: 'allow' };
+}
+/** Denial wording: Plan-mode write (keeps the historical `forbidden in Plan Mode` phrase). */
+export function planWriteDenyReason(toolName) {
+    return `Tool '${toolName}' is forbidden in Plan Mode (write permission denied). Only files under the configured plans directory may be written in Plan Mode; run /plan-build (or /plan-build switch build) to leave Plan Mode before editing elsewhere.`;
+}
+/** Denial wording: an explicit external-directory deny rule matched. */
+export function externalDenyReason(toolName, target) {
+    return `external path access denied for '${target}' (${toolName}) under the external-directory permission. Use /permission allow <pattern> to allowlist this path for the current session, or configure externalDirectory.rules.`;
+}
+/** Denial wording: a write the sandbox cannot permit (single-prompt handoff). */
+export function externalWriteEscalationReason(toolName, target) {
+    return `writing outside the workspace ('${target}') is not permitted by the current sandbox (${toolName}). Retry this ${toolName} call once with sandbox_permissions + justification to request approval, or configure buildSandbox: danger-full-access for full write control.`;
+}
+/** Denial wording: a category rule denied the call. */
+export function categoryDenyReason(toolName, subject) {
+    const what = subject === undefined || subject === '' ? '' : ` for '${subject}'`;
+    return `Tool '${toolName}' is denied by the configured permission${what}. Adjust the permission config, or use /permission allow <pattern> to allowlist this path.`;
+}
+/** Denial wording: the approval channel rejected/aborted the ask. */
+export function approvalDenyReason(toolName, outcome) {
+    return `Tool '${toolName}' requires approval and the request was ${outcome}.`;
+}
+/** Denial wording: no approval channel is composed to resolve an ask. */
+export function noApprovalChannelReason(toolName) {
+    return `Tool '${toolName}' requires approval, but no approval channel is composed.`;
+}
+//# sourceMappingURL=permissions.js.map

package/lib/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -3,7 +3,21 @@
  * @module dsh-plan-build-mode/types
  */
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { ExternalDirectoryConfig, ModePermissionConfig, PermissionValue, ToolCategory } from './permissions.ts';
 declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * The session's Plan/Build mode was switched. Owned by this plugin: under
+         * the OpenCode-aligned configuration both Plan and Build can share the
+         * same sandbox mode (e.g. `workspace-write`), so the `sandbox/mode` event
+         * alone can no longer distinguish them — this event is the durable mode
+         * carrier. `sandbox/mode` is still appended for sandbox enforcement when
+         * the target sandbox actually differs from the current one.
+         */
+        'plan-build/mode': {
+            mode: 'plan' | 'build';
+        };
+    }
 }
 /**
  * Deployment configuration for the Plan/Build mode plugin.
@@ -11,6 +25,9 @@ declare module '@deepseek-ai/dsh-session/types' {
 export interface PlanBuildModeConfig {
     /**
      * Sandbox mode enforced while Plan mode is active.
+     * Under the OpenCode-aligned config this may equal `buildSandbox`
+     * (e.g. both `workspace-write`): read-only is then enforced by the
+     * permission gate instead of the sandbox.
      * @default 'read-only'
      */
     planSandbox?: SandboxMode;
@@ -20,7 +37,8 @@ export interface PlanBuildModeConfig {
      */
     buildSandbox?: SandboxMode;
     /**
-     * Whether to deny known write tools while in Plan mode + read-only sandbox.
+     * Whether Plan mode denies write-category tools (via the permission gate).
+     * When false, Plan mode does not restrict writes by policy.
      * @default true
      */
     denyWriteTools?: boolean;
@@ -29,5 +47,30 @@ export interface PlanBuildModeConfig {
      * @default true
      */
     section?: boolean;
+    /**
+     * Workspace-relative directory writable in Plan mode — the OpenCode
+     * `.opencode/plans/` analog. Must stay inside the workspace.
+     * @default '.opencode/plans'
+     */
+    plansDirectory?: string;
+    /**
+     * Global tool permission categories (OpenCode `permission`). Scalar
+     * `allow | ask | deny`, or object-syntax rules (`{ pattern: action, ... }`,
+     * last-match-wins, `*` catch-all, `~`/`$HOME` expansion).
+     */
+    permission?: Partial<Record<ToolCategory, PermissionValue>>;
+    /**
+     * External-directory access gate (OpenCode `external_directory`): paths
+     * outside the session workspace are read freely by default
+     * (`default: 'allow'`); set `default: 'ask'` to prompt for every external
+     * access. Writes outside the workspace remain governed by the sandbox.
+     */
+    externalDirectory?: ExternalDirectoryConfig;
+    /**
+     * Per-mode permission overrides, applied over the global `permission`
+     * (OpenCode agent-over-global precedence). `plan` defaults to write-deny +
+     * command-ask; `build` defaults to allow.
+     */
+    modes?: ModePermissionConfig;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,QAAQ,gCAAgC,CAAC;CAG/C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACb,MAAM,kBAAkB,CAAA;AAEzB,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,eAAe;QACvB;;;;;;;WAOG;QACH,iBAAiB,EAAE;YACjB,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;SACvB,CAAA;KACF;CACF;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAA;IAC3D;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,uBAAuB,CAAA;IAC3C;;;;OAIG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAA;CAC7B"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xth26/dsh-plan-build-mode",
   "description": "OpenCode-style Plan / Build hard permission model for DSH",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },