dsh-cc-loader 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cc-loader",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Shared parse layer for the dsh-cc ecosystem: parses Claude Code .claude/ (project + global) into a standalone .dsh intermediate representation (IR), classifying every component DIRECT/ADAPTED/UNSUPPORTED/BLOCKED and filtering unsupported ones out.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -42,3 +42,8 @@ export {
 // Session event-log readers. `Session.events` was removed in DSH 0.1.2-alpha.4
 // and is gone in 0.1.5; every plugin read of the log goes through these.
 export { sessionEvents, sessionEventAt, sessionLastEvent } from './session-compat.js'
+// "A session has started" moved from `agent/session-start` (0.1.5) to
+// `agent/created` + `source` (0.2.0). This boundary is the only place that knows.
+export { onSessionStart } from './session-start-compat.js'
+// What `source` an injected message must carry for the host's v4 admission gate.
+export { injectedSource } from './message-source.js'

package/src/message-source.js

@@ -0,0 +1,46 @@
+// message-source.js — the single place that knows what `source` a message this
+// ecosystem injects must carry for the host to admit it.
+//
+// WHY THIS EXISTS
+// ---------------
+// DSH's session format v4 has an admission gate that validates the `source` of
+// EVERY durable message slot before the event is adopted. Its whole rule
+// (`lib/types/message-sources.js`) is:
+//
+//   function source(message) {
+//     const value = message["source"]
+//     if (!isSessionFormatJsonObject(value)
+//         || typeof value["kind"] !== "string"
+//         || value["kind"].length === 0
+//         || value["kind"] === "plugin")
+//       throw new SessionFormatError("format v4 message requires a producer-owned source kind")
+//   }
+//
+// The line of policy above it settles what that means: "Native source admission
+// PRESERVES UNKNOWN ATTRIBUTION and REFUSES RETIRED PLUGIN WRAPPERS." So any
+// non-empty `kind` other than `plugin` is admitted and kept verbatim — you do
+// not have to register your name with the host. The single refused form is the
+// V3 plugin wrapper `{ kind: 'plugin', plugin: '<name>' }`, and refusing it
+// fails the whole TURN, not just that message.
+//
+// `kind` doubles as the context-row label, so it should name the producer.
+//
+// WHAT WENT WRONG
+// ---------------
+// cc-hooks and cc-agents shipped the V3 wrapper, so the first time either one
+// injected anything — SessionStart context, hook-injected context, the catalog
+// reminder, a prompt/agent hook result — the turn died with
+// "format v4 message requires a producer-owned source kind". The constant was
+// duplicated across three files, which is why the shape can drift again; this
+// module is the one place it is written down.
+
+/**
+ * Build the `source` for a message this ecosystem injects.
+ *
+ * @param {string} kind - the producing plugin; also the context-row label.
+ *   Must be non-empty and must not be `'plugin'`.
+ * @returns {{ kind: string }} an admitted source.
+ */
+export function injectedSource(kind) {
+  return { kind }
+}

package/src/patterns.js

@@ -10,6 +10,9 @@
 //   `./` or bare = relative to cwd.
 // - Domain (WebFetch): `*` matches text between dots (a leading `*.` spans
 //   any subdomain depth; a bare `*` matches everything).
+//
+// `[...]` character classes belong to the PATH dialect alone: CC's command and
+// domain patterns have no class syntax, so `[` is a literal character there.
 
 /** Escape a literal string for use inside a RegExp. */
 export function escapeRegExp(s) {
@@ -35,9 +38,10 @@ export function globToRegexBody(pattern, { segment = '/' } = {}) {
     } else if (ch === '?') {
       out += seg === null ? '.' : `[^${seg}]`
       i++
-    } else if (ch === '[') {
+    } else if (ch === '[' && seg === '/') {
       const close = pattern.indexOf(']', i + 1)
-      if (close > 0) { out += pattern.slice(i, close + 1); i = close + 1 }
+      const cls = close > 0 ? pattern.slice(i, close + 1) : ''
+      if (cls !== '' && isUsableCharClass(cls)) { out += cls; i = close + 1 }
       else { out += '\\['; i++ }
     } else {
       out += escapeRegExp(ch)
@@ -47,6 +51,20 @@ export function globToRegexBody(pattern, { segment = '/' } = {}) {
   return out
 }
 
+/**
+ * Whether a glob `[...]` slice is simultaneously a VALID regex character class.
+ *
+ * Gitignore classes and JS regex classes mostly agree, but a reversed range
+ * such as `[11-04-54]` (read as `1-0`) is tolerated by gitignore and rejected
+ * by `new RegExp`. Class compilation happens on every tool call, so letting one
+ * such class throw would take down the whole permission gate; an unusable class
+ * degrades to a literal `[` instead.
+ * @param {string} cls - the slice from `[` through `]` inclusive.
+ */
+function isUsableCharClass(cls) {
+  try { new RegExp(cls); return true } catch { return false }
+}
+
 /**
  * Compile a Bash/PowerShell command pattern.
  *

package/src/session-start-compat.js

@@ -0,0 +1,72 @@
+// session-start-compat.js — the single compatibility boundary for the
+// "a session has started" extension point.
+//
+// WHY THIS EXISTS
+// ---------------
+// DSH 0.2.0 moved this extension point and enriched its payload:
+//
+//   0.1.5-rc.2   agent/session-start  { agent, source }
+//   0.2.0-rc.2   agent/created        { agent, source, signal? }
+//
+// `agent/session-start` is simply GONE in 0.2.0 — a listener on that name is
+// never called, with no error at any point, so a plugin loads, passes the
+// install gate, and silently loses the feature. `agent/created` does exist on
+// 0.1.5, but there the payload is `{ agent }` alone: no `source`. The two names
+// are therefore NOT aliases, and a plain rename trades one silent break for
+// another (the SessionStart hook payload would lose its `source`).
+//
+// The discriminator is `source`: 0.2.0's `agent/created` always carries one (the
+// registry announces as `announce(agent, source, signal)`), 0.1.5's never does,
+// and 0.1.5's `agent/session-start` always does. Listening on both and acting
+// only on a payload that carries `source` fires the handler exactly once on
+// either generation, with no bookkeeping: the host calls its publication entry
+// once per agent (`publish(source)`), and 0.2.0's registry rejects a second
+// announce for the same entry.
+//
+// The official `@deepseek-ai/dsh-hooks-claude-code@0.2.0-rc.2` bridge makes the
+// same move, dropping its `agent/session-start` listener for `agent/created`.
+//
+// SECOND HAZARD: 0.2.0's `agent/created` is a SERIAL event — its listeners are
+// awaited, and a listener rejection vetoes session publication. 0.1.5's was
+// synchronous and fire-and-forget. Session-start work here is slow (filesystem
+// discovery, spawned hook processes), so this boundary deliberately does NOT
+// return the handler's promise and never lets a throw escape: a plugin must not
+// be able to stall or veto the host's session publication.
+
+/**
+ * Subscribe to "a session has started", on either host generation.
+ *
+ * The handler runs at most once per agent with `{ agent, source, signal }`.
+ * `source` is one of `'startup' | 'resume' | 'clear' | 'compact'` and is
+ * present on both generations this boundary supports.
+ *
+ * The handler runs detached and its result is ignored — neither a throw nor a
+ * rejection reaches the host (see the header). A failure is logged instead.
+ *
+ * @param {{ on: Function, logger?: any }} ctx - the plugin context.
+ * @param {(payload: { agent: any, source: string, signal?: AbortSignal }) => unknown} handler
+ */
+export function onSessionStart(ctx, handler) {
+  const invoke = (payload) => {
+    try {
+      const result = handler(payload)
+      if (result !== null && typeof result === 'object' && typeof result.then === 'function') {
+        result.then(undefined, (error) => warn(ctx, error))
+      }
+    } catch (error) {
+      warn(ctx, error)
+    }
+  }
+  ctx.on('agent/session-start', invoke)
+  ctx.on('agent/created', (payload) => {
+    // 0.1.5's `agent/created` is registration-only and carries no `source`;
+    // the session-start event that does carry one follows it immediately.
+    // Acting here as well would run the handler twice.
+    if (payload === null || typeof payload !== 'object' || payload.source === undefined) return
+    invoke(payload)
+  })
+}
+
+function warn(ctx, error) {
+  ctx.logger?.warn?.(`dsh-cc-loader: session-start listener failed: ${String(error)}`)
+}