dsh-cc-loader 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cc-loader",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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/agents.js

@@ -57,7 +57,7 @@ export async function discoverAgents(agentsDir, scope, rank, warnings = []) {
     }
     const raw = await readTextSafe(path)
     if (raw === undefined) continue
-    const parsed = parseFrontmatter(raw)
+    const parsed = parseFrontmatter(raw, warnings, `agent "${path}"`)
     if (parsed === undefined) {
       warnings.push(`agent "${path}" skipped: no frontmatter`)
       continue

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/load.js

@@ -66,8 +66,9 @@ export async function loadClaude(opts = {}) {
   }
 
   // Agents: merge project + global into one catalog (project wins on name clash).
+  // mergeAgentCatalog reports into the array it was handed, so there is nothing
+  // to merge back — repeating that push duplicated every agent warning.
   const catalog = await mergeAgentCatalog(agentRoots, warnings)
-  warnings.push(...catalog.warnings)
 
   // Permissions: discover the three settings files and merge.
   const discovered = await discoverSettings(cwd, {

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/plugin.js

@@ -445,7 +445,7 @@ async function isFile(path) {
 async function discoverCommandFile(filePath, source, rank, warnings = []) {
   const raw = await readTextSafe(filePath)
   if (raw === undefined) return undefined
-  const parsed = parseFrontmatter(raw)
+  const parsed = parseFrontmatter(raw, warnings, `command "${filePath}"`)
   const stem = filePath.split(/[\\/]/).pop().replace(/\.md$/, '')
   if (!isSkillName(stem)) {
     warnings.push(`command "${filePath}" skipped: name not kebab-case`)
@@ -478,7 +478,7 @@ async function discoverCommandFile(filePath, source, rank, warnings = []) {
 async function discoverAgentFile(filePath, scope, rank, warnings = []) {
   const raw = await readTextSafe(filePath)
   if (raw === undefined) return undefined
-  const parsed = parseFrontmatter(raw)
+  const parsed = parseFrontmatter(raw, warnings, `agent "${filePath}"`)
   if (parsed === undefined) {
     warnings.push(`agent "${filePath}" skipped: no frontmatter`)
     return undefined

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)}`)
+}

package/src/skills.js

@@ -81,10 +81,11 @@ export async function readTextSafe(path) {
 /**
  * Collect skills + commands from one `.claude` dir into `out` (project or
  * global). Each entry carries its IR status; unsupported entries are filtered.
+ * @param {string[]} [warnings] - collector, shared with the callers that have
+ *   their own warnings to report (load.js). Omit to get a fresh array back.
  * @returns {Promise<{skills: object[], commands: object[], warnings: string[]}>}
  */
-export async function collectClaudeDir(claudeDir, source, rank) {
-  const warnings = []
+export async function collectClaudeDir(claudeDir, source, rank, warnings = []) {
   const skills = await discoverSkills(join(claudeDir, 'skills'), source, rank, warnings)
   const commands = await discoverCommands(join(claudeDir, 'commands'), source, rank, warnings)
   return { skills, commands, warnings }
@@ -156,7 +157,7 @@ export async function discoverCommands(rootDir, source, rank, warnings = []) {
     }
     const raw = await readTextSafe(path)
     if (raw === undefined) continue
-    const parsed = parseFrontmatter(raw)
+    const parsed = parseFrontmatter(raw, warnings, `command "${entry.name}"`)
     const description = parsed === undefined ? stem : (stringField(parsed.data, 'description') ?? stem)
     // Command tool-scope fields (CC kebab-case, same shape as skills).
     const allowedTools = parsed === undefined ? [] : stringList(parsed.data, 'allowed-tools')
@@ -185,7 +186,7 @@ export async function discoverCommands(rootDir, source, rank, warnings = []) {
 async function parseSkillCandidateFile(path, source, rank, flatName, warnings = []) {
   const raw = await readTextSafe(path)
   if (raw === undefined) return undefined
-  const parsed = parseFrontmatter(raw)
+  const parsed = parseFrontmatter(raw, warnings, `skill "${path}"`)
   if (parsed === undefined) {
     warnings.push(`skill "${path}" skipped: no frontmatter`)
     return undefined
@@ -235,20 +236,83 @@ async function parseSkillCandidateFile(path, source, rank, flatName, warnings =
 
 // ─── frontmatter helpers ─────────────────────────────────────────────────────
 
-export function parseFrontmatter(raw) {
+/**
+ * Read the `---`-delimited block at the top of a `.claude` markdown file.
+ *
+ * Claude Code tolerates frontmatter that strict YAML rejects, so dropping a
+ * file on a parse error loses assets CC reads happily. The recurring shape is
+ * an unquoted `description` carrying a second `: ` — community agent files
+ * produce it by putting `Context: …` or `user: '…'` inside `<example>` blocks.
+ * A failed strict parse therefore falls back to flat `key: value` lines, and
+ * says so through `warnings` rather than degrading in silence.
+ *
+ * @param {string} raw - whole file.
+ * @param {string[]} [warnings] - collector for the lenient-parse notice.
+ * @param {string} [label] - what to call the file in that notice. Callers own
+ *   the path, so they supply it (`agent "/…/x.md"`).
+ * @returns {{ data: object, body: string } | undefined}
+ */
+export function parseFrontmatter(raw, warnings, label) {
   const firstLineEnd = raw.indexOf('\n')
   if (firstLineEnd < 0) return undefined
   if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined
   const start = firstLineEnd + 1
   const closing = findClosingFrontmatter(raw, start)
   if (closing === undefined) return undefined
+  const block = raw.slice(start, closing.start)
   let parsed
-  try { parsed = parse(raw.slice(start, closing.start)) }
-  catch { return undefined }
+  let reason
+  try {
+    parsed = parse(block)
+  } catch (error) {
+    parsed = parseLenient(block)
+    if (parsed === undefined) return undefined
+    reason = firstLineOf(String(error?.message ?? error))
+  }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined
+  if (reason !== undefined && warnings !== undefined) {
+    warnings.push(`${label ?? 'frontmatter'} has frontmatter strict YAML rejects (${reason}) — read as flat key: value; only top-level fields survive`)
+  }
   return { data: parsed, body: raw.slice(closing.bodyStart) }
 }
 
+// Fields Claude Code documents as comma-separated lists. Strict YAML turns them
+// into real arrays on its own, so this set matters only on the lenient path —
+// without it `tools: Read, Bash` arrives as one bogus entry named "Read, Bash".
+const COMMA_LIST_FIELDS = new Set([
+  'tools', 'disallowedTools', 'skills', 'allowed-tools', 'disallowed-tools',
+])
+
+/**
+ * Flat `key: value` reader for a frontmatter block strict YAML rejected. Every
+ * value stays a string except the documented comma lists above — coercing
+ * numbers would turn `description: 2024` into a number and lose the field. Only
+ * top-level unindented lines are read, so anything needing nesting or
+ * multi-line syntax is lost; this is a last resort, not a general YAML parser.
+ */
+function parseLenient(block) {
+  const data = {}
+  let found = false
+  for (const line of block.split('\n')) {
+    const m = /^([A-Za-z][\w-]*):[ \t]?(.*)$/.exec(line.replace(/\r$/, ''))
+    if (m === null) continue
+    const value = m[2].trim()
+    if (value.length === 0) continue
+    found = true
+    data[m[1]] = COMMA_LIST_FIELDS.has(m[1])
+      ? value.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
+      : value
+  }
+  return found ? data : undefined
+}
+
+function firstLineOf(message) {
+  const end = message.indexOf('\n')
+  const line = (end < 0 ? message : message.slice(0, end)).trim()
+  // YAML's first line ends with the colon that introduces its code frame.
+  return line.endsWith(':') ? line.slice(0, -1).trim() : line
+}
+
 function findClosingFrontmatter(raw, start) {
   let lineStart = start
   while (lineStart <= raw.length) {