mira-harness 0.1.4 → 0.2.0

package/README.md

@@ -1,5 +1,13 @@
 # mira-harness — a CLI + MCP dev-tool for communicating with [@mira](https://t.me/mira)
 
+```text
+     *  .  *
+    .-------.
+    | o   o |     hi — I drive @mira so you don't have to copy-paste its replies.
+    |   ~   |     ( I blink ^_^ when doctor passes, and yawn -_- on a timeout. )
+    '-------'
+```
+
 Drive the **@mira Telegram bot** from a userbot, capture its **full** reply
 (buttons, links, media, edits), and run a self-driving experiment catalog — from the
 **CLI**, as a **library**, or via **MCP**.
@@ -19,13 +27,14 @@ is a **userbot** — driving a real Telegram *user account* via MTProto (GramJS)
 ## Install
 
 Published on [npm](https://www.npmjs.com/package/mira-harness) — run the CLI / MCP via
-`npx mira-harness <command>` (or `npm i -g mira-harness`). To develop or use
-`npm run login`, clone instead:
+`npx mira-harness <command>` (or `npm i -g mira-harness`) — runs under Node, no bun
+needed. To develop (or use `bun run login`), clone instead; development uses
+[bun](https://bun.sh):
 
 ```bash
 git clone https://github.com/Masashi-Ono0611/mira-harness.git
 cd mira-harness
-npm install
+bun install
 ```
 
 ## Configuration
@@ -40,55 +49,37 @@ cp .env.example .env
 Mint the session once (interactive — enter the code Telegram sends you):
 
 ```bash
-npm run login          # prints TG_SESSION=... -> paste it into .env
+bun run login          # prints TG_SESSION=... -> paste it into .env
 ```
 
 (Optional) Mira Pro credits: DM `/promo MIRAFAM26` to @mira.
 
 ## Usage
 
-Via `npm run dev -- <args>`, or build once (`npm run build`) and use the `mira-harness` bin / `npx`.
+Via `bun run dev -- <args>`, or build once (`bun run build`) and use the `mira-harness` bin / `npx`.
 
 ```bash
-# one probe — prints the full settled reply as JSON
-npm run dev -- send "STON_USDT_10"
-
-# self-driving catalog (paced 15s, STOP_MIRA kill switch, observe-only)
-npm run dev -- loop --category core
-npm run dev -- loop --category skills --max 4
-
-# also press a safe ✅ Confirm on generation probes (spends Pro credits)
-npm run dev -- loop --category generation --confirm
-
-# run in a group instead of the DM (needs TG_EXPERIMENT_CHAT)
-npm run dev -- loop --peer experiment
-
-# distill the run log into Markdown
-npm run dev -- report
-npm run dev -- report --out report.md
-
-# preflight checks (env / session / connectivity) and list the catalog
-npm run dev -- doctor
-npm run dev -- catalog
-npm run dev -- loop --list
-
-# message via stdin; tune timing; quiet (no spinner); skip the run log
-echo "STON_USDT_10" | npm run dev -- send
-npm run dev -- send "ping" --settle 3000 --timeout 30000 --quiet --no-log
-
-# live-tail @mira while you poke at it by hand; custom catalog; filtered report
-npm run dev -- watch
-npm run dev -- loop --catalog ./examples/catalog.sample.json
-npm run dev -- report --category core
+# one probe — full settled reply as JSON (message via arg or stdin)
+bun run dev -- send "What can you do?"
+echo "What can you do?" | bun run dev -- send
+
+# self-driving catalog — paced, STOP_MIRA kill switch, observe-only
+bun run dev -- loop --category core
+bun run dev -- loop --category generation --confirm   # also taps a safe ✅ (spends Pro credits)
+
+# read the results back
+bun run dev -- report --out report.md                 # JSONL run log → Markdown
+bun run dev -- stats                                  # totals · latency records · 🏆 fastest · sparkline
+
+# no-send commands: preflight, dry-run, live-tail
+bun run dev -- doctor
+bun run dev -- loop --list
+bun run dev -- watch                                  # watch @mira while you poke it by hand
 ```
 
-After `npm run build`, or straight from npm (no clone needed):
-
-```bash
-npx mira-harness doctor
-npx mira-harness send "STON_USDT_10"
-npx mira-harness loop --category core
-```
+Once built (`bun run build`) or installed (`npm i -g mira-harness`), the same commands run as
+`mira-harness <command>` — or straight from npm with no clone: `npx mira-harness doctor`.
+Every command and flag is in [Commands](#commands); custom catalogs in [Custom catalog](#custom-catalog).
 
 ## Capture fidelity (the point)
 
@@ -114,12 +105,29 @@ a "typing…" fallback for a slow bot — replies run 5–62s) and capture, per
 | `catalog` | List the catalog (no sends). `--category --catalog --json` |
 | `watch` | Live-tail @mira's messages (observe-only). `--peer` |
 | `report` | Distill the run log into Markdown. `--in --out --category` |
+| `stats` | At-a-glance dashboard: totals, latency records, sparkline. `--in --category --json` |
 
 Run `mira-harness --help` (or `<command> --help`) for full options.
 
+## Terminal flair
+
+Because waiting on a bot shouldn't be boring:
+
+- **Mascot** greets you on startup, **blinks `^_^`** when `doctor` passes and **`x_x`** when it fails.
+- **Rotating tips** under the banner surface a hidden flag each day.
+- **Playful spinner** — @mira can take 5–62s, so the wait cycles through verbs ("Summoning…",
+  "Consulting the chain…", and a reassuring "Still pondering…" past 30s) next to the elapsed time.
+- **Tab-title progress** during `loop` (`mira loop 3/6 · core`) so you can background it.
+- **Completion ping** — a terminal notification (OSC 9) when a `loop` finishes.
+
+It never gets in the way: **all decoration goes to stderr** (stdout stays machine-clean for
+JSON / Markdown) and only on an interactive TTY. Silence it with `--quiet`, `NO_COLOR`, or
+per-feature flags — `MIRA_NO_BANNER=1` (mascot + tip), `MIRA_NO_NOTIFY=1` (completion ping),
+`MIRA_NO_TITLE=1` (tab title).
+
 ### Custom catalog
 
-The built-in catalog (30 probes: `core` / `skills` / `generation` / `wallet`) is just a
+The built-in catalog (27 probes: `core` / `skills` / `generation` / `wallet`) is just a
 default. Point `--catalog <file.json>` (CLI) or `catalogFile` (MCP) at your own probe set
 to probe any bot — each entry needs `id` + `send` (`category` / `hypothesis` / `slow` /
 `confirm` / `note` optional). See [`examples/catalog.sample.json`](examples/catalog.sample.json):
@@ -137,7 +145,7 @@ The CLI is a thin frontend over an exported core:
 import { connect, sendAndCollect } from "mira-harness";
 
 const client = await connect(process.env.TG_SESSION!);
-const result = await sendAndCollect(client, "mira", "STON_USDT_10");
+const result = await sendAndCollect(client, "mira", "What can you do?");
 console.log(result.messages[0]?.buttons); // captured buttons (incl. web_app/startapp)
 await client.disconnect();
 ```
@@ -158,7 +166,7 @@ Claude/agent can probe @mira directly via tools.
 | `mira_report` | `inFile?`, `category?` | run log → Markdown |
 | `mira_doctor` | — | env / session / connectivity check |
 
-Register it (local build — run `npm run build` first):
+Register it (local build — run `bun run build` first):
 
 ```json
 {
@@ -203,10 +211,17 @@ directory. The bin ships in the published `mira-harness` package, so:
 
 ## Develop
 
+Development uses [bun](https://bun.sh) (≥ 1.3); the published package stays Node-compatible.
+
 ```bash
-npm run typecheck   # tsc --noEmit
-npm test            # unit tests for the pure extractors (no network)
-npm run build       # tsup -> dist/cli.js
+bun install
+bun run dev -- doctor   # run the CLI straight from source
+bun run lint            # biome check (lint + format) · `bun run format` to auto-fix
+bun run typecheck       # tsc --noEmit
+bun test                # bun:test unit tests (no network)
+bun run build           # bun build -> dist (+ tsc declarations)
+bun run check:publish   # publint + attw — validate the package & type resolution
+bun run slop            # advisory AI-slop scan (never fails)
 ```
 
 ## License

package/dist/capture.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure extraction: GramJS `Api.Message` -> a flat, JSON-serializable record of
+ * everything @mira put in a reply. NO network here, so this is unit-testable.
+ *
+ * Why this matters: the *interesting* Mira behaviors live OUTSIDE the plain text
+ * — Mini App "Launch" cards (web_app / startapp deep links), deep-research source
+ * links (text_url entities), generated media. The old harness grabbed only the
+ * first message's `.message` string and dropped all of that. These extractors
+ * pull it back so a probe captures Mira's full surface.
+ */
+import type { Api } from "telegram";
+/** An inline-keyboard button, flattened to the bits we care about. */
+export interface CapturedButton {
+    text: string;
+    /** KeyboardButtonUrl / KeyboardButtonUrlAuth */
+    url?: string;
+    /** KeyboardButtonWebView / KeyboardButtonSimpleWebView — the Mini App "Launch" target. */
+    webAppUrl?: string;
+    /** KeyboardButtonCallback payload, base64 (rarely human-readable). */
+    callbackData?: string;
+}
+/** A hyperlink found in the message text (entities). */
+export interface CapturedLink {
+    /** The visible text the link is attached to (text_url) — omitted for bare urls. */
+    text?: string;
+    url: string;
+}
+export interface CapturedMedia {
+    kind: "photo" | "video" | "audio" | "document" | "webpage" | "other";
+    /** webpage url, when the media is a link preview. */
+    url?: string;
+    mime?: string;
+    fileName?: string;
+}
+/** One message (or its final edited state) from @mira. */
+export interface CapturedMessage {
+    id: number;
+    text: string;
+    /** How many edits we observed (0 = sent once, never edited). */
+    editCount: number;
+    buttons: CapturedButton[];
+    links: CapturedLink[];
+    media?: CapturedMedia;
+}
+/** The full result of one probe = one send + everything @mira sent back. */
+export interface ProbeResult {
+    peer: string;
+    sent: string;
+    messages: CapturedMessage[];
+    /** ms from send to the first reply message (null if nothing arrived). */
+    firstReplyMs: number | null;
+    /** ms from send until the reply settled (or the cap was hit). */
+    totalMs: number;
+    /** true if we gave up waiting for a first reply. */
+    timedOut: boolean;
+    ts: string;
+}
+export declare function extractLinks(text: string, entities?: Api.TypeMessageEntity[]): CapturedLink[];
+export declare function extractButtons(markup?: Api.TypeReplyMarkup): CapturedButton[];
+export declare function extractMedia(media?: Api.TypeMessageMedia): CapturedMedia | undefined;
+/**
+ * Flatten one message into a CapturedMessage. `editCount` is supplied by the
+ * collector (it tracks how many edits it saw for this id), defaulting to 0.
+ */
+export declare function extractMessage(msg: Api.Message, editCount?: number): CapturedMessage;

package/dist/catalog.d.ts

@@ -0,0 +1,27 @@
+/** Built-in categories. Custom catalogs may use any category string. */
+export type ProbeCategory = "core" | "skills" | "generation" | "wallet";
+export interface Probe {
+    id: string;
+    /** Built-in probes use a ProbeCategory; custom catalogs may use any string. */
+    category: string;
+    hypothesis: string;
+    send: string;
+    /** Generation / deep research is slow — widen collector windows. */
+    slow?: boolean;
+    /**
+     * Safe to press a "✅ Confirm" callback button to complete this probe (e.g. to
+     * actually run a credit-gated generation). ONLY set on generation probes — never
+     * on wallet/OAuth. Still requires the runner's `--confirm` CLI opt-in to fire.
+     */
+    confirm?: boolean;
+    note?: string;
+}
+export declare const CATEGORIES: ProbeCategory[];
+/**
+ * Load a custom probe catalog from a JSON file (an array of probe objects).
+ * Throws a clear error on a missing file or an entry that fails validation.
+ */
+export declare function loadCatalog(file: string): Probe[];
+export declare const CATALOG: Probe[];
+/** Filter probes by category. `source` defaults to the built-in CATALOG. */
+export declare function probesFor(category?: string, source?: Probe[]): Probe[];