@minjun0219/mdwire 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minjun Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# mdwire
+
+English | [한국어](README.ko.md)
+
+Send LLM-generated Markdown to chat channels without it breaking.
+
+Agents emit Markdown. Chat channels don't accept it — each has its own subset, its own
+escaping rules, and its own length limit. Existing converters assume the input is
+well-formed CommonMark and target one channel at a time. Neither assumption holds for
+agent output.
+
+**Status: v0.1.4.** Normalizing, rendering, splitting and streaming work for three
+channels — Telegram HTML, Slack `markdown_text`, and plain text — from a Rust core, a CLI,
+an npm package (WASM), and a Go port. See `SPEC.md` for what is in v0.1 and what was
+deliberately deferred. `SPEC.md` and `DESIGN.md` are written in Korean.
+
+## What it does
+
+```
+LLM markdown  →  normalize  →  render for channel  →  split safely  →  send
+```
+
+1. **Normalize.** Agent output is not well-formed. Unpaired `**`, emphasis that spans a
+   line break in wrapped prose, unclosed code fences. Repair before rendering.
+2. **Render.** Emit the syntax the channel actually accepts. Telegram HTML allows nine
+   tags; Slack `markdown_text` takes standard Markdown directly.
+3. **Split.** Respect the channel's limit — and never cut through markup. This also
+   covers streaming: a chunk boundary must not land inside `**bold**`.
+
+Two options around that pipeline. **Input dialect:** an agent that learned Slack from its
+docs writes legacy `mrkdwn` (`*bold*`, `~strike~`, `<url|text>`); `--from slack-mrkdwn`
+reads it as such instead of as standard Markdown. **Repair report:** how many times the
+normalizer stepped in — unclosed emphasis, unclosed fence, unpaired backticks, dropped
+markers — so you can log how often the model breaks its own formatting.
+
+## Use it
+
+```sh
+cat agent-output.md | mdwire --channel telegram-html          # parts separated by NUL
+cat agent-output.md | mdwire --channel slack-markdown --stream # emit as it arrives
+
+# The agent wrote Slack's legacy mrkdwn (*bold*, ~strike~)? Say so. --report prints what
+# the normalizer fixed (unclosed emphasis, unclosed fence, …) as one JSON line on stderr.
+cat agent-output.md | mdwire --channel slack-markdown --from slack-mrkdwn --report
+```
+
+```rust
+let parts = mdwire::render(input, Channel::TelegramHtml);
+
+let mut s = Streamer::new(Channel::SlackMarkdown);
+s.push_into(chunk, &mut out);  // no allocation per chunk
+s.finish_into(&mut out);       // flush, closing anything left open
+```
+
+```js
+import { render, renderWithReport, Streamer } from "@minjun0219/mdwire";   // npm — bundlers, Node, Bun
+
+const parts = render(markdown, "telegram-html");
+const { repairs } = renderWithReport(markdown, "slack-markdown", { from: "slack-mrkdwn" });
+
+// A channel that rewrites the whole message (Telegram edit): send acc plus the tail
+// that closes open blocks. Keep acc itself untouched.
+const s = new Streamer("telegram-html");
+let acc = "";
+for await (const chunk of tokens) {
+  acc += s.push(chunk);
+  await edit(acc + s.closeOpen());
+}
+acc += s.finish();
+
+// An append-only channel (Slack appendStream): send each piece as is — never closeOpen.
+const t = new Streamer("slack-markdown");
+for await (const chunk of tokens) {
+  const piece = t.push(chunk);
+  if (piece) await append(piece);
+}
+await append(t.finish());
+```
+
+**Append-only contract.** What `push` returns is final — a later chunk never rewrites it —
+and `finish` only appends the tail. So the pieces concatenated equal a one-shot `render`,
+whatever the chunk size (unless the document is long enough to be split into parts).
+This is tested on the corpus, by fuzzing, and by `mdwire-check --scan <dir>`, which streams
+every file one character and 64 characters at a time and reports any divergence. Runs in
+Node, Bun, and bundlers. See `SPEC.md` §8.2.
+
+The streamer holds back only what it must: a prefix it cannot classify yet, a marker run
+at the end of a chunk, and the inside of an emphasis that has not closed. Paragraphs are
+never held — a renderer that waits for a newline is not streaming.
+
+## Why another one
+
+Three gaps in what exists today, each measured rather than assumed:
+
+- **Broken input is the normal case.** In a sample of 60 agent-generated documents,
+  44 contained emphasis spanning a line break. A regex-based converter mispaired those
+  into *inverted* emphasis ranges — and the channel returned HTTP 200, so nothing caught it.
+- **CJK is guessed at.** One converter pads emphasis with U+200B next to Korean text;
+  another does not. Neither measured the channel. We did: Slack `markdown_text` follows
+  CommonMark, so `_italic_` dies next to a Korean particle and `*italic*` lives. mdwire
+  emits `*` and pads nothing.
+- **Streaming has no answer.** Every converter is batch: parse the whole document, build an
+  AST, render. When tokens arrive incrementally, markup splits across chunk boundaries.
+
+## Design
+
+- **No dependencies in the core.** Not a purity stance — batch parsers are structurally
+  wrong for streaming. See `DESIGN.md`.
+- **Rust core, many front ends.** WASM for npm, a single static binary for the CLI.
+  The CLI matters most: any agent in any language can pipe through it with no bindings.
+  A Go port lives in `go/` (stdlib only) and is held to the same corpus — and to the Rust
+  core itself: random inputs and real documents must render identically.
+- **The test corpus is a first-class artifact.** `corpus/` holds input → expected output
+  per channel. A port in another language is correct when it passes the corpus. This is
+  how consistency survives more than one implementation.
+
+## Installing
+
+Every release carries its own artifacts — no registry needed:
+
+```sh
+# npm package (works under a bundler and in plain Node)
+npm install https://github.com/minjun0219/mdwire/releases/download/v0.1.4/mdwire-0.1.4.tgz
+
+# CLI binary — macOS (Apple silicon) or Linux (x86_64)
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.4/mdwire-v0.1.4-aarch64-apple-darwin.tar.gz | tar xz
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.4/mdwire-v0.1.4-x86_64-unknown-linux-gnu.tar.gz | tar xz
+```
+
+The release notes list a SHA-256 for every artifact — pin to it when installing by URL.
+
+Or from source: `cargo install --path crates/mdwire-cli`.
+
+Go, as a library or a CLI with the same flags:
+
+```sh
+go get github.com/minjun0219/mdwire/go@latest
+go install github.com/minjun0219/mdwire/go/cmd/mdwire@latest
+```
+
+```go
+parts := mdwire.Render(input, mdwire.TelegramHTML)
+
+s := mdwire.NewStreamer(mdwire.SlackMarkdown)
+s.PushTo(chunk, &out)   // no allocation per chunk
+s.FinishTo(&out)
+
+out := mdwire.RenderWith(input, mdwire.SlackMarkdown, mdwire.Options{From: mdwire.SlackMrkdwn})
+log.Printf("%+v", out.Repairs)
+```
+
+## Building
+
+```sh
+./scripts/build-npm.sh     # the npm package into pkg/ (needs `cargo install wasm-pack`)
+./scripts/smoke.sh         # install it into a scratch project; call it from Node, Bun, and TypeScript
+```
+
+The wasm binary is 111 KB, release with `wasm-opt`. The package carries two builds and
+picks by `exports` condition: `node` gets a CommonJS build that loads the wasm from disk,
+everything else gets the ESM bundler build. The script writes the root `package.json`
+itself: the crate has to stay `mdwire-wasm` because the core's library is already named
+`mdwire`, and wasm-pack takes the npm name from the crate.
+
+```sh
+cargo test --workspace     # unit tests, the corpus, and the allocation gate
+cargo clippy --workspace
+cargo run --release -p mdwire-bench       # allocation counts and throughput
+cargo run -p mdwire-harness --bin mdwire-check   # corpus + invariant scoring
+```
+
+`mdwire-check` scores any implementation that reads stdin and writes stdout, so a port in
+another language can be measured with the same yardstick:
+
+```sh
+mdwire-check --cmd "node convert.js --to {channel}"
+mdwire-check --scan ./some-directory-of-markdown   # invariants only, no expected output
+```
+
+## Releasing
+
+Nobody edits the version by hand. After every merge to `main` a bot keeps a
+`release: X.Y.Z` pull request open; merging it tags `vX.Y.Z` and `go/vX.Y.Z` and publishes
+the release with its artifacts. See `AGENTS.md`.
+
+## License
+
+MIT

package/bundler/mdwire.d.ts

@@ -0,0 +1,101 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** 변환 옵션. 생략하면 표준 마크다운 입력이다. */
+export interface RenderOptions {
+    /** 입력 표기. 슬랙 레거시 mrkdwn(`*굵게*` `~취소~`)으로 쓴 에이전트 출력이면 "slack-mrkdwn". */
+    from?: "markdown" | "slack-mrkdwn";
+}
+
+
+
+/**
+ * `renderWithReport` 의 결과.
+ */
+export class Rendered {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * 조각들. 한도를 넘지 않았으면 하나다.
+     */
+    readonly parts: string[];
+    /**
+     * 정규화가 고친 것.
+     */
+    readonly repairs: Repairs;
+}
+
+/**
+ * 정규화가 고친 것의 개수.
+ */
+export class Repairs {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * 블록이 끝나도록 안 닫혀서 닫아 준 강조.
+     */
+    closedEmphasis: number;
+    /**
+     * 문서 끝까지 안 닫혀서 닫아 준 코드펜스.
+     */
+    closedFence: number;
+    /**
+     * 짝 잃은 채 버린 `**`.
+     */
+    droppedMarker: number;
+    /**
+     * 짝이 없어 글자로 되돌린 백틱 런.
+     */
+    revertedCodeSpan: number;
+}
+
+/**
+ * 스트리밍 변환기.
+ *
+ * 조각을 넣으면 지금 안전하게 내보낼 수 있는 만큼만 돌려준다. 경계에 걸린 마크업은
+ * 안에 남는다 — 토큰이 흘러들어오는 대로 화면에 붙이는 쪽이 이것 때문에 쓴다.
+ */
+export class Streamer {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * **지금까지 받은 것을 그대로 보내려면 이걸 뒤에 붙인다.**
+     *
+     * 상태는 건드리지 않으므로 붙인 뒤에도 스트리밍은 이어진다. 누적본 자체에는
+     * 넣지 말고, 보내기 직전에만 붙인다. 토큰이 오는 대로 메시지를 편집하는 쪽이 쓴다.
+     *
+     * ```js
+     * acc += s.push(chunk);
+     * await edit(acc + s.closeOpen());   // 누적본은 그대로 둔다
+     * ```
+     */
+    closeOpen(): string;
+    /**
+     * 입력이 끝났다. 남은 것을 내보내고 열린 마크업을 닫는다.
+     */
+    finish(): string;
+    constructor(channel: string, options?: RenderOptions | null);
+    push(chunk: string): string;
+    /**
+     * 지금까지 정규화가 고친 것. `finish` 뒤에 보면 문서 전체의 값이다.
+     */
+    repairs(): Repairs;
+}
+
+/**
+ * 채널의 길이 한도(문자 수). 조각을 직접 다루려는 호출자를 위해 열어 둔다.
+ */
+export function limit(channel: string): number;
+
+/**
+ * 완성된 문서를 변환한다. 한도를 넘으면 조각 배열로 돌아온다.
+ */
+export function render(input: string, channel: string, options?: RenderOptions | null): string[];
+
+/**
+ * [`render`] 에 **정규화가 고친 것**을 같이 돌려준다. 모델이 얼마나 자주 서식을 깨는지
+ * 로그로 남기려는 쪽이 쓴다.
+ */
+export function renderWithReport(input: string, channel: string, options?: RenderOptions | null): Rendered;

package/bundler/mdwire.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./mdwire.d.ts" */
+import * as wasm from "./mdwire_bg.wasm";
+import { __wbg_set_wasm } from "./mdwire_bg.js";
+
+__wbg_set_wasm(wasm);
+
+export {
+    Rendered, Repairs, Streamer, limit, render, renderWithReport
+} from "./mdwire_bg.js";