@qotaq/lalphgram 0.1.0

package/src/lib/SpecHtmlGenerator.ts

@@ -0,0 +1,199 @@
+/**
+ * Generates a self-contained HTML page from spec files, with Mermaid.js
+ * CDN for client-side diagram rendering.
+ * @since 1.0.0
+ */
+
+export interface SpecFile {
+  readonly name: string
+  readonly content: string
+  readonly mermaid: boolean
+}
+
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+
+const markdownToHtml = (text: string): string => {
+  const placeholders: Array<readonly [string, string]> = []
+  let counter = 0
+
+  const makePlaceholder = (htmlContent: string): string => {
+    const key = `\x00PH${counter}\x00`
+    counter++
+    placeholders.push([key, htmlContent])
+    return key
+  }
+
+  // Extract fenced code blocks
+  let result = text.replace(
+    /```(\w+)?\n([\s\S]*?)```/g,
+    (_, lang: string | undefined, code: string) => {
+      const escaped = escapeHtml(code)
+      if (lang) {
+        return makePlaceholder(
+          `<pre><code class="language-${escapeHtml(lang)}">${escaped}</code></pre>`
+        )
+      }
+      return makePlaceholder(`<pre><code>${escaped}</code></pre>`)
+    }
+  )
+
+  // Extract inline code
+  result = result.replace(
+    /`([^`\n]+)`/g,
+    (_, code: string) => makePlaceholder(`<code>${escapeHtml(code)}</code>`)
+  )
+
+  // HTML-escape remaining text
+  result = escapeHtml(result)
+
+  // Bold: **text** or __text__
+  result = result.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
+  result = result.replace(/__(.+?)__/g, "<strong>$1</strong>")
+
+  // Italic: *text*
+  result = result.replace(/\*(\S.*?\S|\S)\*/g, "<em>$1</em>")
+  result = result.replace(/(?<!\w)_(\S.*?\S|\S)_(?!\w)/g, "<em>$1</em>")
+
+  // Links: [text](url)
+  result = result.replace(
+    /\[([^\]]+)\]\(([^)]+)\)/g,
+    "<a href=\"$2\">$1</a>"
+  )
+
+  // Strikethrough: ~~text~~
+  result = result.replace(/~~(.+?)~~/g, "<s>$1</s>")
+
+  // Horizontal rules: --- or *** or ___ on their own line
+  result = result.replace(/^(?:---|\*\*\*|___)$/gm, "<hr>")
+
+  // Process block-level elements line by line
+  const lines = result.split("\n")
+  const output: Array<string> = []
+  let inList = false
+
+  for (const line of lines) {
+    // Headers: # Header
+    const headerMatch = /^(#{1,6})\s+(.+)$/.exec(line)
+    if (headerMatch?.[1] && headerMatch[2]) {
+      if (inList) {
+        output.push("</ul>")
+        inList = false
+      }
+      const level = headerMatch[1].length
+      output.push(`<h${level}>${headerMatch[2]}</h${level}>`)
+      continue
+    }
+
+    // Unordered list items: - item or * item
+    const listMatch = /^[-*]\s+(.+)$/.exec(line)
+    if (listMatch?.[1]) {
+      if (!inList) {
+        output.push("<ul>")
+        inList = true
+      }
+      output.push(`<li>${listMatch[1]}</li>`)
+      continue
+    }
+
+    // Close list if we hit a non-list line
+    if (inList) {
+      output.push("</ul>")
+      inList = false
+    }
+
+    // Skip <hr> — already converted
+    if (line === "<hr>") {
+      output.push(line)
+      continue
+    }
+
+    // Empty lines
+    if (line.trim() === "") {
+      output.push("")
+      continue
+    }
+
+    // Regular paragraph
+    output.push(`<p>${line}</p>`)
+  }
+
+  if (inList) {
+    output.push("</ul>")
+  }
+
+  result = output.join("\n")
+
+  // Restore placeholders
+  for (const [key, htmlContent] of placeholders) {
+    result = result.replace(key, htmlContent)
+  }
+
+  return result
+}
+
+const renderFileSection = (file: SpecFile): string => {
+  const heading = `<h2>${escapeHtml(file.name)}</h2>`
+  if (file.mermaid) {
+    return `${heading}\n<pre class="mermaid">${escapeHtml(file.content)}</pre>`
+  }
+  return `${heading}\n${markdownToHtml(file.content)}`
+}
+
+/**
+ * Generate a self-contained HTML page from spec files.
+ * Mermaid files are wrapped in `<pre class="mermaid">` for client-side rendering.
+ * Markdown files are converted to basic HTML.
+ * @since 1.0.0
+ */
+export const generateSpecHtml = (files: ReadonlyArray<SpecFile>): string => {
+  const sections = files.map(renderFileSection).join("\n\n")
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Spec Files</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 1rem;
+      line-height: 1.6;
+      color: #333;
+    }
+    pre {
+      background: #f5f5f5;
+      padding: 1rem;
+      overflow-x: auto;
+      border-radius: 4px;
+    }
+    code {
+      background: #f0f0f0;
+      padding: 0.15em 0.3em;
+      border-radius: 3px;
+      font-size: 0.9em;
+    }
+    pre code {
+      background: none;
+      padding: 0;
+    }
+    h2 {
+      border-bottom: 1px solid #eee;
+      padding-bottom: 0.3em;
+    }
+  </style>
+</head>
+<body>
+${sections}
+<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+<script>mermaid.initialize({ startOnLoad: true });</script>
+</body>
+</html>`
+}

package/src/lib/StreamJsonParser.ts

@@ -0,0 +1,99 @@
+/**
+ * NDJSON parser for Claude Code `--output-format stream-json` output
+ * @since 1.0.0
+ */
+import { Effect, flow, identity, Schema, Stream } from "effect"
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export const ContentBlock = Schema.Struct({
+  type: Schema.String,
+  id: Schema.optional(Schema.String),
+  text: Schema.optional(Schema.String),
+  name: Schema.optional(Schema.String),
+  input: Schema.optional(Schema.Unknown)
+})
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class StreamJsonMessage extends Schema.Class<StreamJsonMessage>("StreamJsonMessage")({
+  type: Schema.String,
+  subtype: Schema.optional(Schema.String),
+  session_id: Schema.optional(Schema.String),
+  message: Schema.optional(
+    Schema.Struct({
+      id: Schema.optional(Schema.String),
+      content: Schema.optional(Schema.Array(ContentBlock))
+    })
+  )
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export const QuestionOption = Schema.Struct({
+  label: Schema.String,
+  description: Schema.optional(Schema.String)
+})
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Question = Schema.Struct({
+  question: Schema.String,
+  header: Schema.optional(Schema.String),
+  options: Schema.optional(Schema.Array(QuestionOption)),
+  multiSelect: Schema.optional(Schema.Boolean)
+})
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export const AskUserQuestionInput = Schema.Struct({
+  questions: Schema.optional(Schema.Array(Question))
+})
+
+/**
+ * @since 1.0.0
+ * @category schemas
+ */
+export class StreamJsonInput extends Schema.Class<StreamJsonInput>("StreamJsonInput")({
+  type: Schema.Literal("user"),
+  message: Schema.Struct({
+    role: Schema.Literal("user"),
+    content: Schema.String
+  }),
+  session_id: Schema.String,
+  parent_tool_use_id: Schema.NullOr(Schema.String)
+}) {}
+
+const decodeJsonMessage = Schema.decodeUnknown(Schema.parseJson(StreamJsonMessage))
+
+/**
+ * Splits a string stream into lines and parses each as a StreamJsonMessage,
+ * silently filtering out lines that don't match.
+ * @since 1.0.0
+ * @category parsers
+ */
+export const parseNdjsonMessages = flow(
+  Stream.splitLines,
+  Stream.filter((line: string) => line.trim().length > 0),
+  Stream.mapEffect((line: string) =>
+    decodeJsonMessage(line).pipe(
+      Effect.tapError((err) =>
+        Effect.logWarning("Non-JSON stdout line, skipping").pipe(
+          Effect.annotateLogs({ line: line.slice(0, 300), error: err.message.slice(0, 100) })
+        )
+      ),
+      Effect.option
+    )
+  ),
+  Stream.filterMap(identity)
+)

package/src/lib/TelegramFormatter.ts

@@ -0,0 +1,151 @@
+/**
+ * Markdown-to-Telegram-HTML converter.
+ *
+ * Telegram supports a narrow HTML subset: `<b>`, `<i>`, `<code>`, `<pre>`,
+ * `<a href>`, `<s>`. This module converts common markdown patterns to that
+ * subset while preserving code blocks verbatim.
+ *
+ * Ported from `repos/claude-code-telegram/src/bot/utils/html_format.py`.
+ * @since 1.0.0
+ */
+
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+
+/**
+ * Convert markdown text to Telegram-compatible HTML.
+ *
+ * Order of operations:
+ * 1. Extract fenced code blocks → placeholders
+ * 2. Extract inline code → placeholders
+ * 3. HTML-escape remaining text
+ * 4. Bold (`**text**` / `__text__`)
+ * 5. Italic (`*text*`, `_text_` at word boundaries)
+ * 6. Links (`[text](url)`)
+ * 7. Headers (`# Header` → `<b>Header</b>`)
+ * 8. Strikethrough (`~~text~~`)
+ * 9. Restore placeholders
+ * @since 1.0.0
+ */
+export const markdownToTelegramHtml = (text: string): string => {
+  const placeholders: Array<readonly [string, string]> = []
+  let counter = 0
+
+  const makePlaceholder = (htmlContent: string): string => {
+    const key = `\x00PH${counter}\x00`
+    counter++
+    placeholders.push([key, htmlContent])
+    return key
+  }
+
+  // 1. Extract fenced code blocks
+  let result = text.replace(
+    /```(\w+)?\n([\s\S]*?)```/g,
+    (_, lang: string | undefined, code: string) => {
+      const escaped = escapeHtml(code)
+      if (lang) {
+        return makePlaceholder(
+          `<pre><code class="language-${escapeHtml(lang)}">${escaped}</code></pre>`
+        )
+      }
+      return makePlaceholder(`<pre><code>${escaped}</code></pre>`)
+    }
+  )
+
+  // 2. Extract inline code
+  result = result.replace(
+    /`([^`\n]+)`/g,
+    (_, code: string) => makePlaceholder(`<code>${escapeHtml(code)}</code>`)
+  )
+
+  // 3. HTML-escape remaining text
+  result = escapeHtml(result)
+
+  // 4. Bold: **text** or __text__
+  result = result.replace(/\*\*(.+?)\*\*/g, "<b>$1</b>")
+  result = result.replace(/__(.+?)__/g, "<b>$1</b>")
+
+  // 5. Italic: *text* (non-space bounded)
+  result = result.replace(/\*(\S.*?\S|\S)\*/g, "<i>$1</i>")
+  // _text_ only at word boundaries (avoid my_var_name)
+  result = result.replace(/(?<!\w)_(\S.*?\S|\S)_(?!\w)/g, "<i>$1</i>")
+
+  // 6. Links: [text](url)
+  result = result.replace(
+    /\[([^\]]+)\]\(([^)]+)\)/g,
+    "<a href=\"$2\">$1</a>"
+  )
+
+  // 7. Headers: # Header -> <b>Header</b>
+  result = result.replace(/^#{1,6}\s+(.+)$/gm, "<b>$1</b>")
+
+  // 8. Strikethrough: ~~text~~
+  result = result.replace(/~~(.+?)~~/g, "<s>$1</s>")
+
+  // 9. Restore placeholders
+  for (const [key, htmlContent] of placeholders) {
+    result = result.replace(key, htmlContent)
+  }
+
+  return result
+}
+
+/**
+ * Split a message into chunks that fit within Telegram's message size limit.
+ *
+ * Splits on `\n\n` boundaries first; if a single paragraph still exceeds the
+ * limit, splits on `\n`.
+ * @since 1.0.0
+ */
+export const splitMessage = (
+  text: string,
+  maxLen: number = 4096
+): ReadonlyArray<string> => {
+  if (text.length <= maxLen) {
+    return [text]
+  }
+
+  const chunks: Array<string> = []
+  const paragraphs = text.split("\n\n")
+  let current = ""
+
+  for (const para of paragraphs) {
+    const candidate = current.length === 0 ? para : `${current}\n\n${para}`
+
+    if (candidate.length <= maxLen) {
+      current = candidate
+    } else {
+      if (current.length > 0) {
+        chunks.push(current)
+        current = ""
+      }
+
+      // If the paragraph itself exceeds maxLen, split on \n
+      if (para.length > maxLen) {
+        const lines = para.split("\n")
+        for (const line of lines) {
+          const lineCandidate = current.length === 0 ? line : `${current}\n${line}`
+          if (lineCandidate.length <= maxLen) {
+            current = lineCandidate
+          } else {
+            if (current.length > 0) {
+              chunks.push(current)
+            }
+            current = line
+          }
+        }
+      } else {
+        current = para
+      }
+    }
+  }
+
+  if (current.length > 0) {
+    chunks.push(current)
+  }
+
+  return chunks
+}