mira-harness 0.1.5 → 0.2.0

package/README.md

@@ -27,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
@@ -48,35 +49,35 @@ 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 — full settled reply as JSON (message via arg or stdin)
-npm run dev -- send "STON_USDT_10"
-echo "STON_USDT_10" | npm run dev -- send
+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
-npm run dev -- loop --category core
-npm run dev -- loop --category generation --confirm   # also taps a safe ✅ (spends Pro credits)
+bun run dev -- loop --category core
+bun run dev -- loop --category generation --confirm   # also taps a safe ✅ (spends Pro credits)
 
 # read the results back
-npm run dev -- report --out report.md                 # JSONL run log → Markdown
-npm run dev -- stats                                  # totals · latency records · 🏆 fastest · sparkline
+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
-npm run dev -- doctor
-npm run dev -- loop --list
-npm run dev -- watch                                  # watch @mira while you poke it by hand
+bun run dev -- doctor
+bun run dev -- loop --list
+bun run dev -- watch                                  # watch @mira while you poke it by hand
 ```
 
-Once built (`npm run build`) or installed (`npm i -g mira-harness`), the same commands run as
+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).
 
@@ -126,7 +127,7 @@ per-feature flags — `MIRA_NO_BANNER=1` (mascot + tip), `MIRA_NO_NOTIFY=1` (com
 
 ### 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):
@@ -144,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();
 ```
@@ -165,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
 {
@@ -210,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[];