dsh-cc-loader 0.1.0

package/src/lsp.js

@@ -0,0 +1,84 @@
+// dsh-cc-loader — LSP server config discovery (.lsp.json) — PLACEHOLDER.
+//
+// Claude Code plugins may ship `.lsp.json` at the plugin root:
+//   { "<language>": { "command": "typescript-language-server", "args": ["--stdio"],
+//                     "extensionToLanguage": { "tsx": "typescript" } } }
+//
+// The LSP adapter (dsh-cc-lsp, M3b) is deferred: the ecosystem has ~zero
+// .lsp.json plugins today, and the bridge (mcpls) is only Windows-verified.
+// This module still PARSES and CLASSIFIES the component so the IR inventory
+// is complete and a future adapter has the parse layer ready. Every entry is
+// classified UNSUPPORTED with a clear reason — never silently ignored.
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pathExists } from './skills.js'
+import { STATUS } from './classify.js'
+
+/**
+ * Parse `.lsp.json` text into classified LSP entries. Every entry is
+ * UNSUPPORTED (LSP adapter deferred, M3b) — parsed for IR inventory only.
+ * @param {string} text - raw .lsp.json text.
+ * @param {string} [sourcePath] - for warning messages.
+ * @param {(msg: string) => void} [warn]
+ * @returns {object[]} entries, each { language, command?, args, extensionToLanguage?, status, reason? }
+ */
+export function parseLspText(text, sourcePath = '.lsp.json', warn = () => {}) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    warn(`${sourcePath}: invalid JSON: ${error.message}`)
+    return []
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    warn(`${sourcePath}: config must be a JSON object`)
+    return []
+  }
+  const servers = []
+  for (const [language, raw] of Object.entries(parsed)) {
+    const entry = {
+      language,
+      command: typeof raw?.command === 'string' ? raw.command : undefined,
+      args: Array.isArray(raw?.args) ? raw.args.map(String) : [],
+      extensionToLanguage: (typeof raw?.extensionToLanguage === 'object' && raw.extensionToLanguage !== null && !Array.isArray(raw.extensionToLanguage))
+        ? raw.extensionToLanguage : undefined,
+      status: STATUS.UNSUPPORTED,
+      reason: 'LSP adapter not implemented (M3b deferred; bridge candidate mcpls)',
+    }
+    if (entry.command === undefined) {
+      warn(`${sourcePath}: language "${language}" missing "command" — recorded with reason`)
+    }
+    servers.push(entry)
+  }
+  return servers
+}
+
+/** @returns {Promise<{ servers: object[], sources: string[], warnings: string[] }>} */
+export async function discoverLspConfig(dir, opts = {}) {
+  const warn = opts.warn ?? (() => {})
+  const warnings = []
+  const localWarn = (m) => { warnings.push(m); warn(m) }
+  const sources = []
+  const servers = []
+
+  const lspPath = join(dir, '.lsp.json')
+  if (!(await pathExists(lspPath))) return { servers, sources, warnings }
+
+  let text
+  try {
+    text = await readFile(lspPath, 'utf8')
+  } catch (error) {
+    warnings.push(`cannot read ${lspPath}: ${String(error)}`)
+    warn(`cannot read ${lspPath}: ${String(error)}`)
+    return { servers, sources, warnings }
+  }
+  sources.push(lspPath)
+
+  const entries = parseLspText(text, lspPath, localWarn)
+  for (const entry of entries) {
+    servers.push(entry)
+    localWarn(`LSP language "${entry.language}" (command ${entry.command ?? '?'}) — ${entry.reason}`)
+  }
+  return { servers, sources, warnings }
+}

package/src/map-tools.js

@@ -0,0 +1,122 @@
+// Map DSH tool names to Claude Code tool buckets.
+//
+// CC permission rules are written against CC tool names (Bash, Read, Edit,
+// WebFetch, Agent, Skill, MCP servers…). DSH tools use their own names
+// (bash, pwsh, read, write, glob, grep, web_fetch, subagent, terminal_*…).
+// This module owns the mapping in both directions.
+//
+// Verified against DSH's shipped tool inventory (packages/core/tools
+// gen-tool-catalog) and CC permissions reference (code.claude.com/docs/permissions).
+
+/** Exact-name mapping: DSH tool name → CC bucket. */
+const BUCKET_BY_TOOL = Object.freeze({
+  bash: 'Bash',
+  pwsh: 'PowerShell',
+  read: 'Read',
+  read_image: 'Read',
+  write: 'Write',
+  edit: 'Edit',
+  str_replace_editor: 'Edit',
+  glob: 'Glob',
+  grep: 'Grep',
+  web_fetch: 'WebFetch',
+  subagent: 'Agent',
+  skill: 'Skill',
+  ask_user_question: 'AskUserQuestion',
+})
+
+/** Tools CC's Read rules best-effort cover (read-like built-in tools). */
+const READ_COVERED = Object.freeze(['read', 'read_image', 'glob', 'grep'])
+/** Tools CC's Edit rules cover (write/edit-like built-in tools). */
+const EDIT_COVERED = Object.freeze(['edit', 'str_replace_editor', 'write'])
+
+/** Bash file commands CC's Read deny rules intercept (cat, head, tail, sed…). */
+const BASH_READ_COMMANDS = new Set([
+  'cat', 'head', 'tail', 'sed', 'less', 'more', 'nl', 'od', 'strings', 'tac', 'wc',
+])
+/** Bash file commands CC's Edit deny rules intercept (write-capable). */
+const BASH_WRITE_COMMANDS = new Set([
+  'sed', 'awk', 'tee', 'dd', 'cp', 'mv', 'rm', 'truncate', 'touch', 'mkdir', 'ln',
+])
+
+/**
+ * Map one DSH tool name to the CC bucket its rules were written for.
+ * MCP tools are their own bucket (rule tool names are full `mcp__…` names).
+ * @returns {string|null} CC bucket name, or null when unmappable (rules may
+ *   still match by exact DSH tool name).
+ */
+export function ccBucket(toolName) {
+  if (typeof toolName !== 'string') return null
+  if (toolName.startsWith('mcp__')) return toolName
+  if (toolName.startsWith('terminal_')) return 'Bash'
+  return BUCKET_BY_TOOL[toolName] ?? null
+}
+
+/**
+ * Whether a rule's tool target (CC bucket or exact name, may contain `*`)
+ * denotes `toolName`. Used for bare rules and tool-glob rules.
+ */
+export function ruleTargetsTool(ruleTool, toolName) {
+  if (ruleTool.includes('*')) {
+    let out = ''
+    for (const ch of ruleTool) out += ch === '*' ? '.*' : ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    return new RegExp(`^${out}$`).test(toolName)
+  }
+  if (ruleTool.startsWith('mcp__')) {
+    // `mcp__server` matches every tool of that server (`mcp__server__tool`).
+    return toolName === ruleTool || toolName.startsWith(`${ruleTool}__`)
+  }
+  const bucket = ccBucket(toolName)
+  return ruleTool === toolName || (bucket !== null && ruleTool === bucket)
+}
+
+/** Is `toolName` in the set CC's `Read` rules cover (incl. read-like tools)? */
+export function isReadCoveredTool(toolName) {
+  return READ_COVERED.includes(toolName)
+}
+
+/** Is `toolName` in the set CC's `Edit` rules cover (incl. write tools)? */
+export function isEditCoveredTool(toolName) {
+  return EDIT_COVERED.includes(toolName)
+}
+
+/** Is this a Bash file command whose paths CC's Read deny rules intercept? */
+export function isBashReadCommand(command) {
+  return BASH_READ_COMMANDS.has(firstWord(command))
+}
+
+/** Is this a Bash file command whose paths CC's Edit deny rules intercept? */
+export function isBashWriteCommand(command) {
+  return BASH_WRITE_COMMANDS.has(firstWord(command))
+}
+
+/**
+ * Extract candidate file paths from a Bash command's arguments, skipping
+ * flags. Best-effort, mirroring CC's "file commands Claude Code recognizes
+ * in Bash".
+ */
+export function extractBashPaths(command) {
+  if (typeof command !== 'string') return []
+  const tokens = command.split(/\s+/).filter((t) => t.length > 0)
+  const out = []
+  let skipNext = false
+  for (const tok of tokens) {
+    if (skipNext) { skipNext = false; continue }
+    if (tok === '--') continue
+    if (tok.startsWith('-') && tok.length > 1) {
+      // Flags that take a value consume the next token (`-n 5`); inline
+      // values (`--count=5`) already carry theirs.
+      if (/^-[a-zA-Z](?!=)/.test(tok) && !tok.includes('=')) skipNext = true
+      continue
+    }
+    out.push(tok)
+  }
+  return out
+}
+
+/** First whitespace-separated word of a command string. */
+function firstWord(command) {
+  if (typeof command !== 'string') return ''
+  const w = command.trim().split(/\s+/)[0]
+  return w ?? ''
+}

package/src/mcp.js

@@ -0,0 +1,218 @@
+// dsh-cc-loader — MCP server config discovery (.mcp.json / plugin.json inline).
+//
+// Claude Code surfaces MCP servers in three places, all sharing the mcpServers
+// JSON shape used by Cursor and VS Code:
+//   1. Project root .mcp.json            — { "mcpServers": { "<name>": {...} } }
+//   2. Plugin root .mcp.json             — official plugin form is a BARE server
+//      map { "<name>": {...} }; community plugins also wrap in mcpServers
+//   3. plugin.json inline                — { ..., "mcpServers": { "<name>": {...} } }
+//
+// This module accepts BOTH the bare-map and the mcpServers-wrapped forms
+// everywhere (detected structurally), so the same code covers project and
+// plugin sources. It is a pure parse layer: nothing is written, env values
+// are NEVER inlined — `${NAME}` placeholders are kept verbatim and the names
+// they reference are recorded (envNames) for the adapter to bind at runtime.
+//
+// Classification (same vocabulary as the rest of the loader):
+//   DIRECT      — stdio (command) and http (url) transports DSH can bridge
+//   UNSUPPORTED — sse / ws transports the DSH MCP client does not speak
+//   INVALID     — shape errors (skipped with a warning, never fatal)
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pathExists } from './skills.js'
+import { STATUS } from './classify.js'
+
+/** CC server names are simple identifiers; same bound as dsh-mcp-client. */
+export const VALID_SERVER_NAME = /^[A-Za-z0-9_-]{1,32}$/
+/** Environment placeholders CC expands: ${NAME}. */
+export const ENV_PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/**
+ * Parse .mcp.json text into the raw servers map, accepting both forms:
+ *   { "mcpServers": {...} }  (wrapped; project-level + community plugins)
+ *   { "<name>": {...} }      (bare; official plugin form)
+ * @returns {Record<string, unknown>} servers map
+ * @throws {Error} invalid JSON / missing map
+ */
+export function parseMcpText(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`invalid JSON: ${error.message}`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('config must be a JSON object')
+  }
+  if (typeof parsed.mcpServers === 'object' && parsed.mcpServers !== null && !Array.isArray(parsed.mcpServers)) {
+    return parsed.mcpServers
+  }
+  // Bare map form: every value is a server config object (no "mcpServers" key).
+  const values = Object.values(parsed)
+  if (values.some((v) => typeof v !== 'object' || v === null || Array.isArray(v))) {
+    throw new Error('expected "mcpServers" object or a bare server map')
+  }
+  return parsed
+}
+
+/**
+ * Normalize one servers map into ordered, classified server entries.
+ * Invalid entries are skipped with warnings (never thrown).
+ * @param {Record<string, unknown>} servers - raw map from parseMcpText
+ * @param {object} [opts] - { pluginName?, warn? }
+ * @returns {object[]} entries, each:
+ *   { serverName, pluginName?, transport: 'stdio'|'http'|'sse'|'ws',
+ *     command?, args?, cwd?, env (placeholders kept), envNames: string[],
+ *     url?, headers?, toolCallTimeoutMs?, idleTimeoutMs?, override?,
+ *     status, reason? }
+ */
+export function serverEntries(servers, opts = {}) {
+  const warn = opts.warn ?? (() => {})
+  const entries = []
+  for (const [serverName, raw] of Object.entries(servers)) {
+    const base = { serverName, pluginName: opts.pluginName }
+    if (!VALID_SERVER_NAME.test(serverName)) {
+      warn(`MCP server name ${JSON.stringify(serverName)} invalid (need 1-32 of [A-Za-z0-9_-]) — skipped`)
+      continue
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      warn(`MCP server ${serverName}: config must be an object — skipped`)
+      continue
+    }
+    const hasCommand = typeof raw.command === 'string' && raw.command.length > 0
+    const hasUrl = typeof raw.url === 'string' && raw.url.length > 0
+    if (hasCommand && hasUrl) {
+      warn(`MCP server ${serverName}: provide exactly one of "command" (stdio) or "url" (remote) — skipped`)
+      continue
+    }
+    if (!hasCommand && !hasUrl) {
+      warn(`MCP server ${serverName}: missing both "command" and "url" — skipped`)
+      continue
+    }
+    const type = typeof raw.type === 'string' ? raw.type.toLowerCase() : undefined
+    let transport
+    if (hasCommand) transport = 'stdio'
+    else if (type === 'sse') transport = 'sse'
+    else if (type === 'ws' || type === 'websocket') transport = 'ws'
+    else transport = 'http' // url without type, or type http → streamable-http
+
+    // env: keep placeholders verbatim, record referenced names only.
+    const env = {}
+    const envNames = []
+    if (raw.env !== undefined) {
+      if (typeof raw.env !== 'object' || raw.env === null || Array.isArray(raw.env)) {
+        warn(`MCP server ${serverName}: env must be an object — skipped`)
+        continue
+      }
+      for (const [k, v] of Object.entries(raw.env)) {
+        const value = String(v)
+        env[k] = value
+        for (const match of value.matchAll(ENV_PLACEHOLDER)) {
+          if (!envNames.includes(match[1])) envNames.push(match[1])
+        }
+      }
+    }
+    const headers = {}
+    if (raw.headers !== undefined) {
+      if (typeof raw.headers !== 'object' || raw.headers === null || Array.isArray(raw.headers)) {
+        warn(`MCP server ${serverName}: headers must be an object — skipped`)
+        continue
+      }
+      for (const [k, v] of Object.entries(raw.headers)) headers[k] = String(v)
+    }
+
+    const entry = {
+      ...base,
+      transport,
+      command: hasCommand ? raw.command : undefined,
+      args: Array.isArray(raw.args) ? raw.args.map(String) : [],
+      cwd: typeof raw.cwd === 'string' && raw.cwd.length > 0 ? raw.cwd : undefined,
+      env,
+      envNames,
+      url: hasUrl ? raw.url : undefined,
+      headers,
+      toolCallTimeoutMs: Number.isFinite(raw.toolCallTimeoutMs) ? raw.toolCallTimeoutMs : undefined,
+      idleTimeoutMs: Number.isFinite(raw.idleTimeoutMs) ? raw.idleTimeoutMs : undefined,
+      override: raw.override === true,
+      status: transport === 'stdio' || transport === 'http' ? STATUS.DIRECT : STATUS.UNSUPPORTED,
+      reason: transport === 'stdio' || transport === 'http' ? undefined
+        : `transport "${transport}" is not supported by the DSH MCP client (stdio/streamable-http only)`,
+    }
+    entries.push(entry)
+  }
+  return entries
+}
+
+/**
+ * Discover MCP config from one directory: `.mcp.json` first, then plugin.json
+ * inline `mcpServers` (unless opts.includePluginJson === false). Both parse
+ * under the same dual-form parser.
+ * @param {string} dir - project root or plugin root
+ * @param {object} [opts] - { pluginName?, includePluginJson?, warn? }
+ * @returns {Promise<{ servers: object[], sources: string[], warnings: string[] }>}
+ */
+export async function discoverMcpConfig(dir, opts = {}) {
+  const warn = opts.warn ?? (() => {})
+  const includePluginJson = opts.includePluginJson !== false
+  const warnings = []
+  const localWarn = (m) => { warnings.push(m); warn(m) }
+  const sources = []
+  const servers = []
+
+  const mcpPath = join(dir, '.mcp.json')
+  if (await pathExists(mcpPath)) {
+    let text
+    try {
+      text = await readFile(mcpPath, 'utf8')
+    } catch (error) {
+      warnings.push(`cannot read ${mcpPath}: ${String(error)}`)
+      warn(`cannot read ${mcpPath}: ${String(error)}`)
+    }
+    if (text !== undefined) {
+      try {
+        const map = parseMcpText(text)
+        servers.push(...serverEntries(map, { pluginName: opts.pluginName, warn: localWarn }))
+        sources.push(mcpPath)
+      } catch (error) {
+        warnings.push(`${mcpPath}: ${error.message}`)
+        warn(`${mcpPath}: ${error.message}`)
+      }
+    }
+  }
+
+  const pluginJsonPath = join(dir, 'plugin.json')
+  if (includePluginJson && await pathExists(pluginJsonPath)) {
+    let text
+    try {
+      text = await readFile(pluginJsonPath, 'utf8')
+    } catch (error) {
+      warnings.push(`cannot read ${pluginJsonPath}: ${String(error)}`)
+      warn(`cannot read ${pluginJsonPath}: ${String(error)}`)
+    }
+    if (text !== undefined) {
+      let parsed
+      try {
+        parsed = JSON.parse(text)
+      } catch (error) {
+        warnings.push(`${pluginJsonPath}: invalid JSON: ${error.message}`)
+        warn(`${pluginJsonPath}: invalid JSON: ${error.message}`)
+      }
+      if (parsed && typeof parsed.mcpServers === 'object' && parsed.mcpServers !== null && !Array.isArray(parsed.mcpServers)) {
+        servers.push(...serverEntries(parsed.mcpServers, { pluginName: opts.pluginName, warn: localWarn }))
+        sources.push(pluginJsonPath)
+      }
+    }
+  }
+
+  return { servers, sources, warnings }
+}
+
+/**
+ * Project-level MCP: `<projectRoot>/.mcp.json` (plugin.json is a
+ * plugin-package concern, excluded here).
+ * @returns {Promise<{ servers: object[], sources: string[], warnings: string[] }>}
+ */
+export async function discoverProjectMcp(projectRoot, opts = {}) {
+  return discoverMcpConfig(projectRoot, { ...opts, includePluginJson: false })
+}

package/src/parse-rule.js

@@ -0,0 +1,98 @@
+// CC permission rule syntax parser: `Tool` or `Tool(specifier)`.
+//
+// Verified against code.claude.com/docs/permissions ("Permission rule syntax",
+// "Match by input parameter", "Tool name wildcards", per-tool rules).
+// A rule is parsed into a structured object with a `kind`:
+//   bare        — `Bash` / `Bash(*)` / any tool without specifier
+//   tool-glob   — glob in tool-name position (`mcp__*`, `B*`…)
+//   command     — Bash/PowerShell command pattern
+//   path        — Read/Edit/Cd gitignore path pattern
+//   domain      — WebFetch `domain:…`
+//   agent-name  — `Agent(Name)` subagent restriction
+//   param       — `Tool(param:value)` top-level input-parameter match
+//   unknown     — spec we cannot faithfully evaluate (reported, not enforced)
+
+import { compileCommandPattern, compilePathPattern, compileDomainPattern } from './patterns.js'
+
+const TOOL_RE = /^([A-Za-z_*][A-Za-z0-9_*]*(?:__[A-Za-z0-9_*:-]+)*)(?:\(([^)]*)\))?$/
+
+/** Tool input fields that cannot be matched via `Tool(param:value)` (CC warns and ignores). */
+const PRIMARY_FIELDS = new Set(['command', 'file_path', 'path', 'url', 'notebook_path'])
+
+/**
+ * Parse one CC rule string.
+ * @param {string} raw
+ * @param {{ scope?: string, path?: string }} [meta] - source scope/file for reporting.
+ * @returns {object|null} structured rule, or null when unparseable.
+ */
+export function parseRule(raw, meta = {}) {
+  const text = String(raw).trim()
+  const m = TOOL_RE.exec(text)
+  if (!m) return { raw: text, tool: null, spec: null, kind: 'unknown', invalid: true, reason: `unparseable rule "${text}"`, ...meta }
+  const tool = m[1]
+  const spec = m[2] === undefined ? null : m[2].trim()
+  const base = { raw: text, tool, spec, scope: meta.scope, path: meta.path }
+
+  // Tool-name glob (`*`, `mcp__*`, `mcp__server__*`, `B*`).
+  if (tool.includes('*')) return { ...base, kind: 'tool-glob', glob: compileToolGlob(tool) }
+
+  if (spec === null || spec === '') return { ...base, kind: 'bare' }
+
+  // `Tool(*)` on Bash/PowerShell is equivalent to a bare rule.
+  if ((tool === 'Bash' || tool === 'PowerShell') && (spec === '*' || spec === ':*')) {
+    return { ...base, kind: 'bare' }
+  }
+
+  // Tool-specific specifiers FIRST so they win over the generic param:value
+  // shape: `Bash(ls:*)` is a command pattern (the `:*` trailing suffix), and
+  // `WebFetch(domain:…)` is a domain rule — neither is a param match.
+  if (tool === 'Bash' || tool === 'PowerShell') {
+    if (spec.endsWith(':*')) {
+      return { ...base, kind: 'command', command: compileCommandPattern(spec, { icase: tool === 'PowerShell' }), icase: tool === 'PowerShell' }
+    }
+  }
+  if (tool === 'WebFetch' && spec.startsWith('domain:')) {
+    return { ...base, kind: 'domain', domain: spec.slice(7), domainRe: compileDomainPattern(spec.slice(7)) }
+  }
+
+  // param:value — before remaining tool-specific handling so `Agent(model:opus)`
+  // and `Bash(run_in_background:true)` parse as param rules.
+  const pm = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/.exec(spec)
+  if (pm) {
+    const param = pm[1]
+    const value = pm[2]
+    if (PRIMARY_FIELDS.has(param)) {
+      return { ...base, kind: 'unknown', invalid: true, reason: `cannot match primary field via param syntax (${tool}(${param}:…))` }
+    }
+    return { ...base, kind: 'param', param, value }
+  }
+
+  switch (tool) {
+    case 'WebFetch':
+      return { ...base, kind: 'unknown', invalid: true, reason: `WebFetch rules require a domain: specifier` }
+    case 'Agent':
+      // Agent(AgentName) restricts a subagent by name.
+      return { ...base, kind: 'agent-name', name: spec }
+    case 'Skill':
+      // Skill(name) restricts a skill invocation by name.
+      return { ...base, kind: 'skill-name', name: spec }
+    case 'Read':
+    case 'Edit':
+    case 'Cd':
+      return { ...base, kind: 'path', pathPattern: compilePathPattern(spec) }
+    case 'Bash':
+    case 'PowerShell':
+      return { ...base, kind: 'command', command: compileCommandPattern(spec, { icase: tool === 'PowerShell' }), icase: tool === 'PowerShell' }
+    default:
+      // A spec on an unknown tool: CC only supports param:value there (handled
+      // above) or tool-specific syntax we do not know — report, don't enforce.
+      return { ...base, kind: 'unknown', invalid: true, reason: `unsupported specifier on tool ${tool}` }
+  }
+}
+
+function compileToolGlob(tool) {
+  // Full-name match; `*` spans everything (CC: pattern must match the full tool name).
+  let out = ''
+  for (const ch of tool) out += ch === '*' ? '.*' : ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^${out}$`)
+}

package/src/patterns.js

@@ -0,0 +1,121 @@
+// Glob pattern compilation for CC permission rules.
+//
+// Three pattern dialects:
+// - Command (Bash/PowerShell): `*` spans any chars incl. spaces; a trailing
+//   `:*` is equivalent to a trailing ` *`; a trailing ` *` (space-star)
+//   requires the prefix to be followed by a space or end-of-string.
+// - Path (Read/Edit/Cd): gitignore-style. `**` spans directories, `*` spans
+//   one path segment, `?` one char, `[...]` char classes. Anchors: `//` =
+//   filesystem root, `~/` = home, `/` = relative to the settings source,
+//   `./` or bare = relative to cwd.
+// - Domain (WebFetch): `*` matches text between dots (a leading `*.` spans
+//   any subdomain depth; a bare `*` matches everything).
+
+/** Escape a literal string for use inside a RegExp. */
+export function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Translate a glob to a regex body (no anchors).
+ * @param {string} pattern
+ * @param {{ segment?: string|null }} [opts] - segment separator: '/' for
+ *   paths, '.' for domains, null for commands (`*` then spans everything).
+ */
+export function globToRegexBody(pattern, { segment = '/' } = {}) {
+  let out = ''
+  let i = 0
+  const seg = segment === null ? null : segment
+  while (i < pattern.length) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') { out += '.*'; i += 2; continue }
+      out += seg === null ? '.*' : `[^${seg}]*`
+      i++
+    } else if (ch === '?') {
+      out += seg === null ? '.' : `[^${seg}]`
+      i++
+    } else if (ch === '[') {
+      const close = pattern.indexOf(']', i + 1)
+      if (close > 0) { out += pattern.slice(i, close + 1); i = close + 1 }
+      else { out += '\\['; i++ }
+    } else {
+      out += escapeRegExp(ch)
+      i++
+    }
+  }
+  return out
+}
+
+/**
+ * Compile a Bash/PowerShell command pattern.
+ *
+ * CC semantics for a trailing ` *` (space-star, or the `:*` suffix): it
+ * matches commands STARTING WITH the prefix — with or without following
+ * arguments — while still enforcing a word boundary (a rule `ls *` matches
+ * `ls`, `ls -la`, but not `lsof`).
+ * @param {string} pattern
+ * @param {{ icase?: boolean }} [opts] - PowerShell matching is case-insensitive.
+ */
+export function compileCommandPattern(pattern, { icase = false } = {}) {
+  let p = pattern
+  if (p.endsWith(':*')) p = p.slice(0, -2) + ' *'
+  let trailing = false
+  if (p.endsWith(' *')) { trailing = true; p = p.slice(0, -2) }
+  const body = globToRegexBody(p, { segment: null })
+  const re = trailing
+    ? new RegExp(`^${body}(?: .*)?$`, icase ? 'i' : undefined)
+    : new RegExp(`^${body}$`, icase ? 'i' : undefined)
+  return re
+}
+
+/**
+ * Compile a Read/Edit/Cd path pattern into its anchored shape.
+ * @returns {{ kind: 'absolute'|'home'|'source'|'cwd', re: RegExp,
+ *            singleSegment: boolean, prefixAny: boolean }}
+ */
+export function compilePathPattern(pattern) {
+  let p = pattern
+  let kind = 'cwd'
+  if (p.startsWith('//')) { kind = 'absolute'; p = p.slice(2) }
+  else if (p.startsWith('~/')) { kind = 'home'; p = p.slice(2) }
+  else if (p.startsWith('/')) { kind = 'source'; p = p.slice(1) }
+  else if (p.startsWith('./')) { kind = 'cwd'; p = p.slice(2) }
+  let trailingAny = false
+  if (p.endsWith('/**')) { trailingAny = true; p = p.slice(0, -3) }
+  let prefixAny = false
+  if (p.startsWith('**/')) { prefixAny = true; p = p.slice(3) }
+  const singleSegment = kind === 'cwd' && !p.includes('/')
+  const body = globToRegexBody(p, { segment: '/' })
+  // Absolute patterns match the full POSIX path, so keep the leading slash.
+  const head = kind === 'absolute' ? '/' : ''
+  const re = trailingAny ? new RegExp(`^${head}${body}(?:/.*)?$`) : new RegExp(`^${head}${body}$`)
+  return { kind, re, singleSegment, prefixAny }
+}
+
+/**
+ * Compile a WebFetch domain pattern.
+ * @param {string} domain - the text after `domain:`.
+ */
+export function compileDomainPattern(domain) {
+  const d = String(domain).trim().toLowerCase().replace(/\.$/, '')
+  if (d === '*') return /.*/
+  if (d.startsWith('*.')) {
+    const rest = escapeRegExp(d.slice(2))
+    // any subdomain at any depth, but not the bare domain
+    return new RegExp(`^(.+\\.)+${rest}$`)
+  }
+  const body = globToRegexBody(d, { segment: '.' })
+  return new RegExp(`^${body}$`)
+}
+
+/**
+ * Normalize a Windows path to POSIX form for path-rule matching
+ * (`C:\Users\alice` → `/c/Users/alice`), mirroring CC's Windows behavior.
+ */
+export function winPathToPosix(p) {
+  if (typeof p !== 'string') return p
+  if (!/^[A-Za-z]:[\\/]/.test(p)) return p.replace(/\\/g, '/')
+  const drive = p[0].toLowerCase()
+  return `/${drive}${p.slice(2).replace(/\\/g, '/')}`
+}