@goodandready/dsh-dsml-artifact-guard 0.1.2 → 0.1.5

package/README.md

@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
 </p>
 
 <p align="center">
@@ -21,6 +21,16 @@
   <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -64,15 +74,15 @@ graph TD
         Audit["Audit Mode<br/>(Emits ctx.logger warning only)"]
     end
 
-    Turn -->|ctx.on('llm/stream')| Hook
+    Turn -->|llm/stream hook| Hook
     Hook --> ScopeCheck
     ScopeCheck -->|No| PassThrough
     ScopeCheck -->|Yes| Buffer
     PassThrough --> ChatUI
     Buffer --> Detector
     Detector -->|No Artifact| ChatUI
-    Detector -->|Artifact Found & sanitize| Sanitize --> ChatUI
-    Detector -->|Artifact Found & audit| Audit --> ChatUI
+    Detector -->|Artifact detected: sanitize| Sanitize --> ChatUI
+    Detector -->|Artifact detected: audit| Audit --> ChatUI
 ```
 
 ---
@@ -150,3 +160,19 @@ npm run check
 ## 📄 License
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## Changed in v0.1.4
+
+#11: schema `mode` default set to `sanitize` for out-of-the-box protection.
+#11: robust open/close tag balancing in `sanitizeDsmlArtifacts` to handle prior closed blocks in prose.
+#11: repo hygiene with tracked `package-lock.json` and design contract.
+
+## Changed in v0.1.5
+
+#15: fix Mermaid diagram edge label syntax on GitHub and add mandatory repository support block.

package/cordis.patch.yml

@@ -1,8 +1,5 @@
-# Host-only DSH bundle.
+# Host-only DSH bundle. Defaults live in Config schema (mode=sanitize).
 - insert:
     - id: dsh-dsml-artifact-guard
       name: '@goodandready/dsh-dsml-artifact-guard'
-      config:
-        mode: sanitize
-        providerId: opencode-go
-        modelId: deepseek-v4-flash
+      config: {}

package/docs/README.ru.md

@@ -12,7 +12,7 @@
 </p>
 
 <p align="center">
-  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
 </p>
 
 <p align="center">
@@ -21,6 +21,16 @@
   <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -64,15 +74,15 @@ graph TD
         Audit["Режим Audit<br/>(Логирование через ctx.logger)"]
     end
 
-    Turn -->|ctx.on('llm/stream')| Hook
+    Turn -->|Хук llm/stream| Hook
     Hook --> ScopeCheck
     ScopeCheck -->|Нет| PassThrough
     ScopeCheck -->|Да| Buffer
     PassThrough --> ChatUI
     Buffer --> Detector
     Detector -->|Нет артефакта| ChatUI
-    Detector -->|Артефакт найден & sanitize| Sanitize --> ChatUI
-    Detector -->|Артефакт найден & audit| Audit --> ChatUI
+    Detector -->|Артефакт найден: sanitize| Sanitize --> ChatUI
+    Detector -->|Артефакт найден: audit| Audit --> ChatUI
 ```
 
 ---
@@ -150,3 +160,19 @@ npm run check
 ## 📄 Лицензия
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## Изменения в v0.1.4
+
+#11: значение `mode` по умолчанию в схеме переведено на `sanitize` для защиты «из коробки».
+#11: балансировка открывающих и закрывающих тегов в `sanitizeDsmlArtifacts` при наличии закрытых блоков в прозе.
+#11: гигиена репозитория с отслеживаемым `package-lock.json` и дизайн-контрактом.
+
+## Изменения в v0.1.5
+
+#15: исправлен синтаксис стрелок диаграммы Mermaid на GitHub и добавлен обязательный блок поддержки репозитория.

package/docs/README.zh.md

@@ -21,6 +21,16 @@
   <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
+      <br><br>
+      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -64,15 +74,15 @@ graph TD
         Audit["审计模式 (Audit)<br/>(仅记录日志不改动文本)"]
     end
 
-    Turn -->|ctx.on('llm/stream')| Hook
+    Turn -->|llm/stream 拦截| Hook
     Hook --> ScopeCheck
     ScopeCheck -->|未命中| PassThrough
     ScopeCheck -->|命中| Buffer
     PassThrough --> ChatUI
     Buffer --> Detector
     Detector -->|无异常| ChatUI
-    Detector -->|检出残留 & sanitize| Sanitize --> ChatUI
-    Detector -->|检出残留 & audit| Audit --> ChatUI
+    Detector -->|检出残留: sanitize| Sanitize --> ChatUI
+    Detector -->|检出残留: audit| Audit --> ChatUI
 ```
 
 ---
@@ -150,3 +160,19 @@ npm run check
 ## 📄 开源许可证
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+
+
+## Changed in v0.1.3
+
+#8: wrap `llm/stream` in `ctx.effect` so unload unsubscribes.
+#9: `cordis.patch.yml` uses `config: {}` — schema defaults (`mode: audit`, provider/model ids) apply unless overridden in host config.
+
+## v0.1.4 变更说明
+
+#11: 将 schema 中 `mode` 默认值设置为 `sanitize`，实现开箱即用的清理保护。
+#11: 在 `sanitizeDsmlArtifacts` 中实现严格的开闭标签深度平衡，精准处理正文中已闭合标签与末尾泄漏标签。
+#11: 纳入 `package-lock.json` 跟踪并完善设计契约。
+
+## v0.1.5 变更说明
+
+#15: 修复 GitHub 上 Mermaid 流程图边标签语法解析错误，并补全标准项目支持引导区。

package/docs/design/DESIGN.md

@@ -0,0 +1,36 @@
+# Design Contract: dsh-dsml-artifact-guard
+
+## 1. Product Purpose & User Scenarios
+- **Purpose**: Host-only streaming guard for DeepSeek Harness that intercepts assistant stream chunks and strips leaked DSML closing tags (`</｜DSML｜parameter>`, `</｜DSML｜invoke>`, `</｜DSML｜tool_calls>`) emitted by upstream providers before text reaches the user interface.
+- **Primary Scenarios**:
+  - Assistant responds through an upstream gateway exhibiting DSML leakage (e.g. `opencode-go` + `deepseek-v4-flash`). Leaked protocol closing tags at the end of the response are stripped automatically.
+  - User and assistant discuss DSML syntax or generate markdown/code examples with DSML tags. Legitimate open tags and their matching closing tags are preserved intact (fail-open).
+  - Out-of-scope providers/models pass through with zero buffering or regex evaluation.
+
+## 2. User Surfaces
+- **Web UI**: UI отсутствует на текущем этапе (host-only middleware plugin).
+- **DSH Configuration**:
+  - `mode`: `"sanitize"` (default, strips tags), `"audit"` (logs to `ctx.logger.info`), `"disabled"` (bypasses).
+  - `providerId`: target provider (default `"opencode-go"`).
+  - `modelId`: target model (default `"deepseek-v4-flash"`).
+- **Documentation**:
+  - Full trilingual documentation: `README.md` (EN), `docs/README.ru.md` (RU), `docs/README.zh.md` (ZH).
+
+## 3. Streaming & Buffering Contract
+- **Synchronous Hook Contract**: The `llm/stream` listener returns an `AsyncIterable` synchronously. Returning a `Promise` breaks the Cordis event dispatcher.
+- **Sliding Buffer (KEEP = 96)**: Preserves the terminal window across chunk splits.
+- **Tag Balancing**: Tracks opening and closing DSML tags across the stream so that only orphaned closing tags at the terminal tail are sanitized, leaving balanced code blocks untouched.
+
+## 4. Do / Don't
+- **Do**:
+  - Preserve fail-open guarantees for all user prose.
+  - Dispose hook registration with `ctx.effect`.
+  - Pass non-target provider/model streams directly through.
+- **Don't**:
+  - Do not make the stream hook async.
+  - Do not drop legitimate DSML discussion in chat.
+  - Do not add heavy client-side UI for simple host middleware.
+
+## 5. Decisions Log
+- **2026-09-06**: Added `ctx.effect` lifecycle wrapper and switched patch to schema-driven defaults (`#8, #9`).
+- **2026-09-12**: Changed schema default mode to `sanitize` for out-of-the-box protection, implemented robust open/close tag balancing across streaming chunks, and tracked `package-lock.json` (`#11`).

package/lib/index.js

@@ -1 +1,105 @@
-import Schema from '@deepseek-ai/schemastery'; const TAIL=/(?:<\/｜DSML｜parameter>\s*)?(?:<\/｜DSML｜invoke>\s*)?<\/｜DSML｜tool_calls>\s*$/u,OPEN=/<｜DSML｜(?:tool_calls|invoke|parameter)>/u,KEEP=96; export const name='@goodandready/dsh-dsml-artifact-guard',inject=['llm'],Config=Schema.object({mode:Schema.string().default('audit'),providerId:Schema.string().default('opencode-go'),modelId:Schema.string().default('deepseek-v4-flash')}); export function matchesScope(o,c){return (o?.providerId??o?.provider?.id??o?.provider)==c.providerId&&(o?.modelId??o?.model?.id??o?.model?.name??o?.model)==c.modelId} export async function* sanitizeDsmlArtifacts(s,{mode,onArtifact}={}){let p='',i,open=false;const flush=async function*(end){if(!p)return;let text=p;if(end&&!open&&TAIL.test(text)){onArtifact?.({mode,removed:1});if(mode==='sanitize')text=text.replace(TAIL,'')}if(text)yield{type:'text-delta',index:i,text};p='';i=undefined};for await(const c of s){if(c?.type==='text-delta'&&typeof c.text==='string'){if(p&&i!==c.index)yield*flush(false);i=c.index;p+=c.text;open||=OPEN.test(c.text);if(p.length>KEEP){const n=p.length-KEEP;yield{type:'text-delta',index:i,text:p.slice(0,n)};p=p.slice(n)}continue}if(c?.type==='finish'){yield*flush(true);yield c;continue}yield*flush(false);yield c}yield*flush(true)} export function apply(ctx,c={}){const e=Config(c)??{};ctx.on('llm/stream',(o,next)=>{const s=next(o);return e.mode==='disabled'||!matchesScope(o,e)?s:sanitizeDsmlArtifacts(s,{mode:e.mode,onArtifact:x=>ctx.logger?.info?.('DSML closing-tag artifact detected',x)})})}
+import Schema from '@deepseek-ai/schemastery';
+
+const TAIL = /(?:<\/｜DSML｜parameter>\s*)?(?:<\/｜DSML｜invoke>\s*)?<\/｜DSML｜tool_calls>\s*$/u;
+const OPEN_TAG = /<｜DSML｜(?:tool_calls|invoke|parameter)[^>]*>/gu;
+const CLOSE_TAG = /<\/｜DSML｜(?:tool_calls|invoke|parameter)>/gu;
+const KEEP = 96;
+const SCAN_BUFFER_SAFE = 64;
+
+export const name = '@goodandready/dsh-dsml-artifact-guard';
+export const inject = ['llm'];
+
+export const Config = Schema.object({
+  mode: Schema.string().default('sanitize'),
+  providerId: Schema.string().default('opencode-go'),
+  modelId: Schema.string().default('deepseek-v4-flash'),
+});
+
+export function matchesScope(o, c) {
+  return (o?.providerId ?? o?.provider?.id ?? o?.provider) == c.providerId
+    && (o?.modelId ?? o?.model?.id ?? o?.model?.name ?? o?.model) == c.modelId;
+}
+
+export async function* sanitizeDsmlArtifacts(s, { mode = 'sanitize', onArtifact } = {}) {
+  let p = '';
+  let i;
+  let scanBuffer = '';
+  let totalOpen = 0;
+  let totalClose = 0;
+
+  const countTags = (str) => {
+    if (!str) return;
+    const opens = str.match(OPEN_TAG);
+    if (opens) totalOpen += opens.length;
+    const closes = str.match(CLOSE_TAG);
+    if (closes) totalClose += closes.length;
+  };
+
+  const flush = async function* (end) {
+    if (!p) return;
+    let text = p;
+    if (end) {
+      if (scanBuffer) {
+        countTags(scanBuffer);
+        scanBuffer = '';
+      }
+      if (TAIL.test(text)) {
+        const tailMatch = text.match(TAIL);
+        const tailCloseCount = tailMatch ? (tailMatch[0].match(CLOSE_TAG) || []).length : 0;
+        const closedBeforeTail = totalClose - tailCloseCount;
+        const unclosedBeforeTail = totalOpen - closedBeforeTail;
+        if (unclosedBeforeTail <= 0) {
+          onArtifact?.({ mode, removed: 1 });
+          if (mode === 'sanitize') text = text.replace(TAIL, '');
+        }
+      }
+    }
+    if (text) yield { type: 'text-delta', index: i, text };
+    p = '';
+    i = undefined;
+  };
+
+  for await (const c of s) {
+    if (c?.type === 'text-delta' && typeof c.text === 'string') {
+      if (p && i !== c.index) yield* flush(false);
+      i = c.index;
+      p += c.text;
+
+      scanBuffer += c.text;
+      if (scanBuffer.length > SCAN_BUFFER_SAFE) {
+        const safe = scanBuffer.slice(0, scanBuffer.length - SCAN_BUFFER_SAFE);
+        scanBuffer = scanBuffer.slice(scanBuffer.length - SCAN_BUFFER_SAFE);
+        countTags(safe);
+      }
+
+      if (p.length > KEEP) {
+        const n = p.length - KEEP;
+        yield { type: 'text-delta', index: i, text: p.slice(0, n) };
+        p = p.slice(n);
+      }
+      continue;
+    }
+    if (c?.type === 'finish') {
+      yield* flush(true);
+      yield c;
+      continue;
+    }
+    yield* flush(false);
+    yield c;
+  }
+  yield* flush(true);
+}
+
+export function apply(ctx, c = {}) {
+  const e = Config(c) ?? {};
+  // #8: dispose with ctx.effect so unload unsubscribes llm/stream
+  ctx.effect(() => ctx.on('llm/stream', (o, next) => {
+    const s = next(o);
+    return e.mode === 'disabled' || !matchesScope(o, e)
+      ? s
+      : sanitizeDsmlArtifacts(s, {
+        mode: e.mode,
+        onArtifact: (x) => ctx.logger?.info?.('DSML closing-tag artifact detected', x),
+      });
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-dsml-artifact-guard",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Sanitizes leaked DeepSeek DSML closing tags from model text streams",
   "type": "module",
   "main": "lib/index.js",