@ubiquity-os/plugin-sdk 3.2.1 → 3.3.0

package/README.md

@@ -5,7 +5,7 @@ This project provides a software development kit (SDK) for creating plugins usin
 - TypeScript
 - Creating a plugin instance
 - Injection of the context
-- Provider with a logger, an authenticated Octokit instance and the event payload
+- Provider with a logger, an authenticated Octokit instance, and the event payload
 
 ## Key Functions
 
@@ -58,3 +58,59 @@ To start Jest tests, run:
 ```sh
 bun run test
 ```
+
+## Markdown Cleaning Utility
+
+`cleanMarkdown` removes top-level HTML comments and configured HTML tags while preserving content inside fenced/indented code blocks, inline code spans, and blockquotes.
+
+### Import
+
+```ts
+import { cleanMarkdown, type CleanMarkdownOptions } from "@ubiquity-os/plugin-sdk/markdown";
+```
+
+### Options (`CleanMarkdownOptions`)
+
+| Option               | Type                              | Default | Description                                                                                                                                                                                 |
+| -------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tags`               | `(keyof HTMLElementTagNameMap)[]` | `[]`    | List of HTML tag names to strip. Whole block tokens that are a single matching root element are removed entirely. Inline self-closing/void-like occurrences (e.g. `<br>`) are also removed. |
+| `collapseEmptyLines` | `boolean`                         | `false` | Collapses runs of 3+ blank lines down to exactly 2.                                                                                                                                         |
+
+### Behavior Summary
+
+- Strips HTML comments (`<!-- ... -->`) outside protected contexts:
+  - Not inside fenced/indented code blocks
+  - Not inside inline code spans
+  - Not inside blockquotes (blockquote content is left untouched)
+- Removes entire HTML block tokens consisting of a single root element whose tag is in `tags`.
+- Removes inline occurrences of any tag in `tags` (void/self-closing style).
+- Leaves everything else unchanged to minimize diff noise.
+- Final output is trimmed (no trailing blank lines).
+
+### Example
+
+```ts
+const input = `
+<!-- build badge -->
+<details>
+<summary>Info</summary>
+Content inside details
+</details>
+
+Paragraph with <br> line break and \`<br>\` in code.
+
+\`\`\`ts
+// Code block with <!-- comment --> and <br>
+const x = 1;
+\`\`\`
+
+> Blockquote with <!-- preserved comment --> and <br>.
+`;
+
+const cleaned = cleanMarkdown(input, {
+  tags: ["details", "br"],
+  collapseEmptyLines: true,
+});
+
+console.log(cleaned);
+```

package/dist/compression.js

@@ -24,15 +24,15 @@ __export(compression_exports, {
   decompressString: () => decompressString
 });
 module.exports = __toCommonJS(compression_exports);
-var import_brotli = require("brotli");
+var import_node_zlib = require("zlib");
 function compressString(str) {
   const input = Buffer.from(str, "utf8");
-  const compressed = (0, import_brotli.compress)(input);
+  const compressed = (0, import_node_zlib.brotliCompressSync)(input);
   return Buffer.from(compressed).toString("base64");
 }
 function decompressString(compressed) {
   const buffer = Buffer.from(compressed, "base64");
-  const decompressed = (0, import_brotli.decompress)(buffer);
+  const decompressed = (0, import_node_zlib.brotliDecompressSync)(buffer);
   return Buffer.from(decompressed).toString("utf8");
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/compression.mjs

@@ -1,13 +1,13 @@
 // src/helpers/compression.ts
-import { compress, decompress } from "brotli";
+import { brotliCompressSync, brotliDecompressSync } from "node:zlib";
 function compressString(str) {
   const input = Buffer.from(str, "utf8");
-  const compressed = compress(input);
+  const compressed = brotliCompressSync(input);
   return Buffer.from(compressed).toString("base64");
 }
 function decompressString(compressed) {
   const buffer = Buffer.from(compressed, "base64");
-  const decompressed = decompress(buffer);
+  const decompressed = brotliDecompressSync(buffer);
   return Buffer.from(decompressed).toString("utf8");
 }
 export {

package/dist/index.d.mts

@@ -116,7 +116,7 @@ interface Context<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSuppor
 type Return = Record<string, unknown> | undefined | void;
 type HandlerReturn = Promise<Return> | Return;
 
-interface Options {
+interface Options$1 {
     kernelPublicKey?: string;
     logLevel?: LogLevel;
     postCommentOnError?: boolean;
@@ -127,10 +127,41 @@ interface Options {
      * @deprecated This disables signature verification - only for local development
      */
     bypassSignatureVerification?: boolean;
+    returnDataToKernel?: boolean;
 }
 
-declare function createActionsPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, options?: Options): Promise<void>;
+declare function createActionsPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, options?: Options$1): Promise<void>;
 
-declare function createPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, manifest: Manifest, options?: Options): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+declare function createPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, manifest: Manifest, options?: Options$1): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { CommentHandler, type Context, type Options, createActionsPlugin, createPlugin };
+/**
+ * Options for cleanMarkdown.
+ *
+ * tags:
+ *   A single list of HTML tag names (keyof HTMLElementTagNameMap) to remove.
+ *   Behavior per tag:
+ *     1. If an HTML block token consists solely of a single root element whose tag matches, the entire block (its content) is removed.
+ *        (e.g. <details> ... </details> when "details" is in tags).
+ *     2. Standalone inline occurrences of that tag treated as void/self-closing (e.g. <br>) are stripped.
+ *
+ * collapseEmptyLines:
+ *   If true, collapses sequences of 3+ blank lines down to exactly 2, preserving paragraph spacing while shrinking payload size.
+ */
+type Options = {
+    tags?: string[];
+    shouldCollapseEmptyLines?: boolean;
+};
+/**
+ * Cleans a GitHub-flavored markdown string by:
+ *  - Removing top‑level HTML comments (<!-- ... -->) (outside code / inline code / blockquote context)
+ *  - Removing blocks for configured tags when the entire html token is a single element of that tag
+ *  - Removing inline occurrences of configured tags treated as void (e.g. \<br\>) outside fenced / inline code
+ *  - Preserving comments and tags inside:
+ *       * fenced or indented code blocks
+ *       * inline code spans
+ *       * blockquotes (their contents unchanged)
+ *  - Optionally collapsing excessive blank lines
+ */
+declare function cleanMarkdown(md: string, options?: Options): string;
+
+export { CommentHandler, type Context, type Options$1 as Options, cleanMarkdown, createActionsPlugin, createPlugin };

package/dist/index.d.ts

@@ -116,7 +116,7 @@ interface Context<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSuppor
 type Return = Record<string, unknown> | undefined | void;
 type HandlerReturn = Promise<Return> | Return;
 
-interface Options {
+interface Options$1 {
     kernelPublicKey?: string;
     logLevel?: LogLevel;
     postCommentOnError?: boolean;
@@ -127,10 +127,41 @@ interface Options {
      * @deprecated This disables signature verification - only for local development
      */
     bypassSignatureVerification?: boolean;
+    returnDataToKernel?: boolean;
 }
 
-declare function createActionsPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, options?: Options): Promise<void>;
+declare function createActionsPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, options?: Options$1): Promise<void>;
 
-declare function createPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, manifest: Manifest, options?: Options): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+declare function createPlugin<TConfig = unknown, TEnv = unknown, TCommand = unknown, TSupportedEvents extends EmitterWebhookEventName = EmitterWebhookEventName>(handler: (context: Context<TConfig, TEnv, TCommand, TSupportedEvents>) => HandlerReturn, manifest: Manifest, options?: Options$1): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { CommentHandler, type Context, type Options, createActionsPlugin, createPlugin };
+/**
+ * Options for cleanMarkdown.
+ *
+ * tags:
+ *   A single list of HTML tag names (keyof HTMLElementTagNameMap) to remove.
+ *   Behavior per tag:
+ *     1. If an HTML block token consists solely of a single root element whose tag matches, the entire block (its content) is removed.
+ *        (e.g. <details> ... </details> when "details" is in tags).
+ *     2. Standalone inline occurrences of that tag treated as void/self-closing (e.g. <br>) are stripped.
+ *
+ * collapseEmptyLines:
+ *   If true, collapses sequences of 3+ blank lines down to exactly 2, preserving paragraph spacing while shrinking payload size.
+ */
+type Options = {
+    tags?: string[];
+    shouldCollapseEmptyLines?: boolean;
+};
+/**
+ * Cleans a GitHub-flavored markdown string by:
+ *  - Removing top‑level HTML comments (<!-- ... -->) (outside code / inline code / blockquote context)
+ *  - Removing blocks for configured tags when the entire html token is a single element of that tag
+ *  - Removing inline occurrences of configured tags treated as void (e.g. \<br\>) outside fenced / inline code
+ *  - Preserving comments and tags inside:
+ *       * fenced or indented code blocks
+ *       * inline code spans
+ *       * blockquotes (their contents unchanged)
+ *  - Optionally collapsing excessive blank lines
+ */
+declare function cleanMarkdown(md: string, options?: Options): string;
+
+export { CommentHandler, type Context, type Options$1 as Options, cleanMarkdown, createActionsPlugin, createPlugin };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   CommentHandler: () => CommentHandler,
+  cleanMarkdown: () => cleanMarkdown,
   createActionsPlugin: () => createActionsPlugin,
   createPlugin: () => createPlugin
 });
@@ -161,7 +162,8 @@ function getPluginOptions(options) {
     envSchema: options?.envSchema,
     commandSchema: options?.commandSchema,
     // eslint-disable-next-line sonarjs/deprecation
-    bypassSignatureVerification: options?.bypassSignatureVerification || false
+    bypassSignatureVerification: options?.bypassSignatureVerification || false,
+    returnDataToKernel: options?.returnDataToKernel ?? true
   };
 }
 
@@ -354,15 +356,15 @@ function getCommand(inputs, pluginOptions) {
 }
 
 // src/helpers/compression.ts
-var import_brotli = require("brotli");
+var import_node_zlib = require("zlib");
 function compressString(str) {
   const input = Buffer.from(str, "utf8");
-  const compressed = (0, import_brotli.compress)(input);
+  const compressed = (0, import_node_zlib.brotliCompressSync)(input);
   return Buffer.from(compressed).toString("base64");
 }
 function decompressString(compressed) {
   const buffer = Buffer.from(compressed, "base64");
-  const decompressed = (0, import_brotli.decompress)(buffer);
+  const decompressed = (0, import_node_zlib.brotliDecompressSync)(buffer);
   return Buffer.from(decompressed).toString("utf8");
 }
 
@@ -436,9 +438,9 @@ var commandCallSchema = import_typebox.Type.Union([import_typebox.Type.Null(), i
 // src/types/util.ts
 var import_typebox2 = require("@sinclair/typebox");
 var import_value2 = require("@sinclair/typebox/value");
-function jsonType(type, decompress2 = false) {
+function jsonType(type, decompress = false) {
   return import_typebox2.Type.Transform(import_typebox2.Type.String()).Decode((value) => {
-    const parsed = JSON.parse(decompress2 ? decompressString(value) : value);
+    const parsed = JSON.parse(decompress ? decompressString(value) : value);
     return import_value2.Value.Decode(type, import_value2.Value.Default(type, parsed));
   }).Encode((value) => JSON.stringify(value));
 }
@@ -527,7 +529,9 @@ async function createActionsPlugin(handler, options) {
   try {
     const result = await handler(context2);
     core.setOutput("result", result);
-    await returnDataToKernel(pluginGithubToken, inputs.stateId, result);
+    if (pluginOptions?.returnDataToKernel) {
+      await returnDataToKernel(pluginGithubToken, inputs.stateId, result);
+    }
   } catch (error) {
     await handleError(context2, pluginOptions, error);
   }
@@ -625,9 +629,63 @@ function createPlugin(handler, manifest, options) {
   });
   return app;
 }
+
+// src/markdown.ts
+var VOID_TAGS = /* @__PURE__ */ new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+function cleanMarkdown(md, options = {}) {
+  const codeBlockRegex = /(```[\s\S]*?```|~~~[\s\S]*?~~~)/g;
+  const { tags = [], shouldCollapseEmptyLines = false } = options;
+  const segments = [];
+  let lastIndex = 0;
+  const matches = [...md.matchAll(codeBlockRegex)];
+  for (const match of matches) {
+    if (match.index > lastIndex) {
+      segments.push(processSegment(md.slice(lastIndex, match.index), tags, shouldCollapseEmptyLines));
+    }
+    segments.push(match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < md.length) {
+    segments.push(processSegment(md.slice(lastIndex), tags, shouldCollapseEmptyLines));
+  }
+  return segments.join("");
+}
+function processSegment(segment, extraTags, shouldCollapseEmptyLines) {
+  const inlineCodeRegex = /`[^`]*`/g;
+  const inlineCodes = [];
+  let s = segment.replace(inlineCodeRegex, (m) => {
+    inlineCodes.push(m);
+    return `__INLINE_CODE_${inlineCodes.length - 1}__`;
+  });
+  s = s.replace(/<!--[\s\S]*?-->/g, "");
+  for (const raw of extraTags) {
+    if (!raw) continue;
+    const tag = raw.toLowerCase().trim().replace(/[^\w:-]/g, "");
+    if (!tag) continue;
+    if (VOID_TAGS.has(tag)) {
+      const voidRe = new RegExp(`<${tag}\\b[^>]*\\/?>`, "gi");
+      s = s.replace(voidRe, "");
+      continue;
+    }
+    const pairRe = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi");
+    let prev;
+    do {
+      prev = s;
+      s = s.replace(pairRe, "");
+    } while (s !== prev);
+    const openCloseRe = new RegExp(`<\\/?${tag}\\b[^>]*>`, "gi");
+    s = s.replace(openCloseRe, "");
+  }
+  s = s.replace(/__INLINE_CODE_(\d+)__/g, (str, idx) => inlineCodes[+idx]);
+  if (shouldCollapseEmptyLines) {
+    s = s.replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n");
+  }
+  return s;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CommentHandler,
+  cleanMarkdown,
   createActionsPlugin,
   createPlugin
 });

package/dist/index.mjs

@@ -123,7 +123,8 @@ function getPluginOptions(options) {
     envSchema: options?.envSchema,
     commandSchema: options?.commandSchema,
     // eslint-disable-next-line sonarjs/deprecation
-    bypassSignatureVerification: options?.bypassSignatureVerification || false
+    bypassSignatureVerification: options?.bypassSignatureVerification || false,
+    returnDataToKernel: options?.returnDataToKernel ?? true
   };
 }
 
@@ -316,15 +317,15 @@ function getCommand(inputs, pluginOptions) {
 }
 
 // src/helpers/compression.ts
-import { compress, decompress } from "brotli";
+import { brotliCompressSync, brotliDecompressSync } from "node:zlib";
 function compressString(str) {
   const input = Buffer.from(str, "utf8");
-  const compressed = compress(input);
+  const compressed = brotliCompressSync(input);
   return Buffer.from(compressed).toString("base64");
 }
 function decompressString(compressed) {
   const buffer = Buffer.from(compressed, "base64");
-  const decompressed = decompress(buffer);
+  const decompressed = brotliDecompressSync(buffer);
   return Buffer.from(decompressed).toString("utf8");
 }
 
@@ -398,9 +399,9 @@ var commandCallSchema = T.Union([T.Null(), T.Object({ name: T.String(), paramete
 // src/types/util.ts
 import { Type } from "@sinclair/typebox";
 import { Value as Value2 } from "@sinclair/typebox/value";
-function jsonType(type, decompress2 = false) {
+function jsonType(type, decompress = false) {
   return Type.Transform(Type.String()).Decode((value) => {
-    const parsed = JSON.parse(decompress2 ? decompressString(value) : value);
+    const parsed = JSON.parse(decompress ? decompressString(value) : value);
     return Value2.Decode(type, Value2.Default(type, parsed));
   }).Encode((value) => JSON.stringify(value));
 }
@@ -489,7 +490,9 @@ async function createActionsPlugin(handler, options) {
   try {
     const result = await handler(context2);
     core.setOutput("result", result);
-    await returnDataToKernel(pluginGithubToken, inputs.stateId, result);
+    if (pluginOptions?.returnDataToKernel) {
+      await returnDataToKernel(pluginGithubToken, inputs.stateId, result);
+    }
   } catch (error) {
     await handleError(context2, pluginOptions, error);
   }
@@ -587,8 +590,62 @@ function createPlugin(handler, manifest, options) {
   });
   return app;
 }
+
+// src/markdown.ts
+var VOID_TAGS = /* @__PURE__ */ new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+function cleanMarkdown(md, options = {}) {
+  const codeBlockRegex = /(```[\s\S]*?```|~~~[\s\S]*?~~~)/g;
+  const { tags = [], shouldCollapseEmptyLines = false } = options;
+  const segments = [];
+  let lastIndex = 0;
+  const matches = [...md.matchAll(codeBlockRegex)];
+  for (const match of matches) {
+    if (match.index > lastIndex) {
+      segments.push(processSegment(md.slice(lastIndex, match.index), tags, shouldCollapseEmptyLines));
+    }
+    segments.push(match[0]);
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < md.length) {
+    segments.push(processSegment(md.slice(lastIndex), tags, shouldCollapseEmptyLines));
+  }
+  return segments.join("");
+}
+function processSegment(segment, extraTags, shouldCollapseEmptyLines) {
+  const inlineCodeRegex = /`[^`]*`/g;
+  const inlineCodes = [];
+  let s = segment.replace(inlineCodeRegex, (m) => {
+    inlineCodes.push(m);
+    return `__INLINE_CODE_${inlineCodes.length - 1}__`;
+  });
+  s = s.replace(/<!--[\s\S]*?-->/g, "");
+  for (const raw of extraTags) {
+    if (!raw) continue;
+    const tag = raw.toLowerCase().trim().replace(/[^\w:-]/g, "");
+    if (!tag) continue;
+    if (VOID_TAGS.has(tag)) {
+      const voidRe = new RegExp(`<${tag}\\b[^>]*\\/?>`, "gi");
+      s = s.replace(voidRe, "");
+      continue;
+    }
+    const pairRe = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi");
+    let prev;
+    do {
+      prev = s;
+      s = s.replace(pairRe, "");
+    } while (s !== prev);
+    const openCloseRe = new RegExp(`<\\/?${tag}\\b[^>]*>`, "gi");
+    s = s.replace(openCloseRe, "");
+  }
+  s = s.replace(/__INLINE_CODE_(\d+)__/g, (str, idx) => inlineCodes[+idx]);
+  if (shouldCollapseEmptyLines) {
+    s = s.replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n");
+  }
+  return s;
+}
 export {
   CommentHandler,
+  cleanMarkdown,
   createActionsPlugin,
   createPlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubiquity-os/plugin-sdk",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "SDK for plugin support.",
   "author": "Ubiquity DAO",
   "license": "MIT",
@@ -103,7 +103,6 @@
     "@octokit/types": "^13.8.0",
     "@octokit/webhooks": "^13.7.4",
     "@ubiquity-os/ubiquity-os-logger": "^1.4.0",
-    "brotli": "^1.3.3",
     "dotenv": "^16.4.5",
     "hono": "^4.6.9"
   },
@@ -119,7 +118,6 @@
     "@eslint/js": "^9.14.0",
     "@jest/globals": "^29.7.0",
     "@mswjs/data": "0.16.1",
-    "@types/brotli": "^1.3.4",
     "@types/node": "^20.11.19",
     "@ubiquity-os/eslint-plugin-no-empty-strings": "^1.0.3",
     "cross-env": "^7.0.3",