viber-channel 0.4.0 → 0.5.1

package/lib/connect.ts

@@ -0,0 +1,190 @@
+/**
+ * connect.ts — one-shot claim flow that turns a Viber connection URL into
+ * `.viber/auth.json` so the channel can be started.
+ *
+ * Invoked from the CLI as:
+ *   bunx viber-channel connect https://viber.dgypx.dev/connect/<claim_id>
+ *
+ * Pure logic: takes a URL + a target folder, talks to the Worker, writes the
+ * three files (`.viber/auth.json`, `.viber/readme.md`, `.gitignore` entry).
+ * No MCP, no SSE.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { clientFingerprint } from "./fingerprint.js";
+import { cfAccessHeaders } from "./cfAccess.js";
+
+interface InitResponse {
+  confirm_url: string;
+  wait_token: string;
+}
+
+interface ConsumedResponse {
+  status: "consumed";
+  project_id: number;
+  project_name: string;
+  user_email: string;
+  project_token: string;
+  issued_at: string;
+  rotates_after?: string;
+  target_conversation_id?: string | null;
+  readme_md: string;
+}
+
+interface PendingResponse {
+  status: "pending";
+}
+
+interface TerminalResponse {
+  status: "rejected" | "expired";
+  reason?: string;
+}
+
+type PollResponse = ConsumedResponse | PendingResponse | TerminalResponse;
+
+const POLL_INTERVAL_MS = 2000;
+const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
+
+function parseClaimUrl(input: string): { baseUrl: string; claimId: string } {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`Invalid URL: ${input}`);
+  }
+  const match = url.pathname.match(/^\/connect\/([a-f0-9-]+)\/?$/i);
+  if (!match) {
+    throw new Error(
+      `Not a Viber claim URL. Expected format: https://<host>/connect/<claim_id>`,
+    );
+  }
+  return { baseUrl: `${url.protocol}//${url.host}`, claimId: match[1] };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function writeAuthJson(
+  cwd: string,
+  data: ConsumedResponse,
+  fingerprint: string,
+): void {
+  const viberDir = join(cwd, ".viber");
+  mkdirSync(viberDir, { recursive: true });
+
+  const auth: Record<string, unknown> = {
+    schema_version: 1,
+    project_id: data.project_id,
+    project_name: data.project_name,
+    user_email: data.user_email,
+    project_token: data.project_token,
+    client_fingerprint: fingerprint,
+    issued_at: data.issued_at,
+    rotates_after: data.rotates_after,
+  };
+  // Only emit target_conversation_id when the server explicitly returned a
+  // non-null value (attach-to-project flow). Absent / null → omit to keep
+  // the file minimal for the common "fresh standalone conversation" case.
+  if (
+    data.target_conversation_id !== undefined &&
+    data.target_conversation_id !== null
+  ) {
+    auth.target_conversation_id = data.target_conversation_id;
+  }
+
+  writeFileSync(
+    join(viberDir, "auth.json"),
+    JSON.stringify(auth, null, 2),
+    "utf-8",
+  );
+  writeFileSync(join(viberDir, "readme.md"), data.readme_md, "utf-8");
+
+  // Append `.viber/` to .gitignore if not already present.
+  const gitignorePath = join(cwd, ".gitignore");
+  let current = "";
+  if (existsSync(gitignorePath)) {
+    current = readFileSync(gitignorePath, "utf-8");
+  }
+  const alreadyIgnored = current
+    .split(/\r?\n/)
+    .some((line) => {
+      const trimmed = line.trim();
+      return trimmed === ".viber/" || trimmed === ".viber";
+    });
+  if (!alreadyIgnored) {
+    const prefix = current === "" || current.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${prefix}.viber/\n`);
+  }
+}
+
+/**
+ * Run the claim flow. Writes .viber/auth.json + .viber/readme.md + .gitignore
+ * entry on success. Exits the process on any terminal outcome.
+ */
+export async function runConnect(
+  claimUrl: string,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  const { baseUrl, claimId } = parseClaimUrl(claimUrl);
+
+  const fingerprint = clientFingerprint(cwd);
+  process.stderr.write(
+    `[viber-channel] fingerprint=${fingerprint.slice(0, 8)}…\n`,
+  );
+
+  const initResp = await fetch(`${baseUrl}/api/connect/${claimId}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...cfAccessHeaders() },
+    body: JSON.stringify({ client_fingerprint: fingerprint }),
+  });
+  if (!initResp.ok) {
+    const body = await initResp.text().catch(() => "");
+    throw new Error(`Claim init failed (HTTP ${initResp.status}): ${body}`);
+  }
+  const init = (await initResp.json()) as InitResponse;
+  process.stdout.write(
+    `\nConfirm this connection in your browser:\n  ${init.confirm_url}\n\n`,
+  );
+  process.stdout.write(`Polling for confirmation (up to 10 minutes)…\n`);
+
+  const pollUrl = `${baseUrl}/api/connect/${claimId}?wait_token=${encodeURIComponent(init.wait_token)}`;
+  const deadline = Date.now() + MAX_POLL_DURATION_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    const pollResp = await fetch(pollUrl, { headers: cfAccessHeaders() });
+    if (!pollResp.ok) {
+      const body = await pollResp.text().catch(() => "");
+      throw new Error(`Poll failed (HTTP ${pollResp.status}): ${body}`);
+    }
+    const data = (await pollResp.json()) as PollResponse;
+    if (data.status === "consumed") {
+      writeAuthJson(cwd, data, fingerprint);
+      process.stdout.write(
+        `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\n` +
+          `  Wrote ${join(cwd, ".viber", "auth.json")}\n\n` +
+          `Next steps:\n` +
+          `  1. Register the channel MCP server (one-time per machine):\n` +
+          `       claude mcp add viber-channel --scope user -- bunx viber-channel@latest\n` +
+          `  2. Restart Claude Code in this directory.\n\n`,
+      );
+      return;
+    }
+    if (data.status === "rejected" || data.status === "expired") {
+      throw new Error(
+        `Connection ${data.status}${data.reason ? `: ${data.reason}` : ""}. Get a fresh URL from ${baseUrl}/projects.`,
+      );
+    }
+    // "pending" — keep polling
+  }
+  throw new Error(
+    `Confirmation timed out after ${MAX_POLL_DURATION_MS / 60_000} minutes. Get a fresh URL from ${baseUrl}/projects.`,
+  );
+}

package/lib/lockfile.ts

@@ -0,0 +1,25 @@
+/**
+ * lockfile.ts — derive the channel's lock file path from VIBER_BASE_URL.
+ *
+ * The lock prevents two instances of the channel from racing on stdin when
+ * Claude Code accidentally spawns duplicates. But two channels targeting
+ * *different* backends (e.g. staging + dev) are legitimately different
+ * processes — they shouldn't share a lock.
+ *
+ * Namespacing the lock by base URL lets them coexist.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+/**
+ * Return the lock file path for a given base URL, under `lockDir`.
+ *
+ * The filename is `channel-{8-hex}.lock` where the hex is a stable SHA-256
+ * prefix of the base URL. Two callers with the same base URL get the same
+ * path (same process collision still detected); different base URLs get
+ * different paths (no false collision).
+ */
+export function lockFilePath(baseUrl: string, lockDir: string): string {
+  const suffix = createHash("sha256").update(baseUrl).digest("hex").slice(0, 8);
+  return join(lockDir, `channel-${suffix}.lock`);
+}

package/lib/messages.ts

@@ -15,6 +15,62 @@ export class ConversationTokenExpiredError extends Error {
   }
 }
 
+export type ArtifactFormat = "markdown" | "code" | "json" | "html";
+
+export interface Artifact {
+  content: string;
+  format?: ArtifactFormat;
+}
+
+const ALLOWED_ARTIFACT_FORMATS: readonly ArtifactFormat[] = [
+  "markdown",
+  "code",
+  "json",
+  "html",
+];
+
+export type ParseArtifactResult =
+  | { ok: true; artifact: Artifact | undefined }
+  | { ok: false; error: string };
+
+/**
+ * Validate and normalize a raw `artifact` value coming from MCP tool input.
+ *
+ * - `undefined` / `null` → `{ ok: true, artifact: undefined }` (no artifact attached).
+ * - Anything else must be a plain object with a non-empty trimmed `content` string and,
+ *   optionally, a `format` from the whitelist (`markdown` | `code` | `json` | `html`).
+ *   An omitted `format` is normalized to `"markdown"`.
+ *
+ * Kept as a pure function so the CallTool handler in viber-channel.ts stays small
+ * and the validation rules are unit-testable on their own.
+ */
+export function parseArtifact(raw: unknown): ParseArtifactResult {
+  if (raw === undefined || raw === null) {
+    return { ok: true, artifact: undefined };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "artifact must be an object" };
+  }
+  const rawArtifact = raw as Record<string, unknown>;
+  const content = rawArtifact.content;
+  if (typeof content !== "string" || content.trim().length === 0) {
+    return { ok: false, error: "artifact.content must be a non-empty string" };
+  }
+  if (rawArtifact.format === undefined) {
+    return { ok: true, artifact: { content, format: "markdown" } };
+  }
+  if (
+    typeof rawArtifact.format !== "string" ||
+    !ALLOWED_ARTIFACT_FORMATS.includes(rawArtifact.format as ArtifactFormat)
+  ) {
+    return {
+      ok: false,
+      error: `artifact.format must be one of ${ALLOWED_ARTIFACT_FORMATS.join(", ")}`,
+    };
+  }
+  return { ok: true, artifact: { content, format: rawArtifact.format as ArtifactFormat } };
+}
+
 export interface MessagePostSuccess {
   ok: true;
   message_id: string;
@@ -40,6 +96,7 @@ export async function postMessage(
   conversationId: string,
   conversationToken: string,
   text: string,
+  artifact?: Artifact,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -60,7 +117,7 @@ export async function postMessage(
         "Content-Type": "application/json",
         ...cfAccessHeaders(),
       },
-      body: JSON.stringify({ content: text }),
+      body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
     });
   } catch (err) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-channel.ts

@@ -1,27 +1,84 @@
 #!/usr/bin/env bun
 /**
- * viber-channel MCP channel server (#217)
+ * viber-channel MCP channel server (#217, #232)
  *
  * Reads .viber/auth.json for authentication, then connects to
  * /api/conversations/<id>/events SSE stream and pushes transcripts and
  * messages as channel events.
  *
- * Start Claude with:
- *   claude --dangerously-load-development-channels server:viber-channel
+ * Launch via Claude Code — two MCP server names are in use:
+ *   - server:viber-channel       — npm-published build (bunx viber-channel@latest),
+ *                                  staging backend (viber.dgypx.dev), wired by
+ *                                  external consumers via `claude mcp add`.
+ *   - server:viber-dev-channel   — local-source build, dev backend
+ *                                  (viber-dev.dgypx.dev). Defined in this repo's
+ *                                  committed .mcp.json (or override locally).
+ *
+ *   claude --dangerously-load-development-channels server:<name>
+ *
+ * Two PowerShell launchers wrap the right flag:
+ *   - viber.ps1       → server:viber-channel (staging)
+ *   - viber-dev.ps1   → server:viber-dev-channel (this repo, dev)
+ *
+ * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
+ * claim flow that writes .viber/auth.json without requiring any Claude Code
+ * recipe in CLAUDE.md.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { runConnect } from "./lib/connect.ts";
+import { lockFilePath } from "./lib/lockfile.ts";
+
+// ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
+//
+// `bunx viber-channel connect <claim_url>` runs the one-shot claim flow and
+// exits — it does not start the MCP server. Any other invocation (no args, or
+// the unknown subcommand) falls through to the MCP server below.
+{
+  const sub = process.argv[2];
+  if (sub === "--help" || sub === "-h") {
+    process.stdout.write(
+      `viber-channel — voice + text MCP channel for Claude Code\n\n` +
+      `USAGE\n` +
+      `  bunx viber-channel connect <claim_url>   one-shot auth flow; writes .viber/auth.json\n` +
+      `  bunx viber-channel                       start the MCP server (used by Claude Code)\n\n` +
+      `Get <claim_url> from https://viber.dgypx.dev/projects → Create connection.\n`,
+    );
+    process.exit(0);
+  }
+  if (sub === "connect") {
+    const claimUrl = process.argv[3];
+    if (!claimUrl) {
+      process.stderr.write(
+        `[viber-channel] Missing claim URL.\n` +
+        `Usage: bunx viber-channel connect <claim_url>\n` +
+        `Get the URL from https://viber.dgypx.dev/projects → Create connection.\n`,
+      );
+      process.exit(1);
+    }
+    try {
+      await runConnect(claimUrl);
+      process.exit(0);
+    } catch (err) {
+      process.stderr.write(`[viber-channel] ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+  }
+}
 
-// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac)
+// Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
+// Namespaced by VIBER_BASE_URL so channels targeting different backends
+// (staging + dev) coexist on the same machine — only same-backend duplicates
+// still collide, which is the intended guard.
 const LOCK_DIR =
   process.env.APPDATA
     ? join(process.env.APPDATA, "viber")
     : join(process.env.HOME ?? "/tmp", ".config", "viber");
-// TODO: rename to channel.lock once all installations have transitioned off the old name
-const LOCK_FILE = join(LOCK_DIR, "watchdog.lock");
+const LOCK_BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
+const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_DIR);
 
 function isProcessAlive(pid: number): boolean {
   try {
@@ -92,16 +149,18 @@ process.on("SIGTERM", () => { releaseLock(); process.exit(0); });
 // the bun subprocess outlives Claude Code and leaks (the orphan that
 // taunts us on every restart). The MCP transport uses stdin too, but
 // it doesn't propagate close as a process exit, so we wire it ourselves.
+//
+// NOTE: we deliberately listen to `end` only, not `close`. On Windows/Bun,
+// registering an MCP `StdioServerTransport` reader appears to trigger a
+// spurious `close` event ~2 ms after the transport's read loop starts,
+// which would kill the channel mid-mint before MCP traffic even begins.
+// `end` fires on real EOF (parent closes write end) and is sufficient for
+// orphan detection. See plan #236 step-09 for the diagnosis.
 process.stdin.on("end", () => {
   process.stderr.write("[viber-channel] stdin closed (parent exited), shutting down\n");
   releaseLock();
   process.exit(0);
 });
-process.stdin.on("close", () => {
-  process.stderr.write("[viber-channel] stdin close event, shutting down\n");
-  releaseLock();
-  process.exit(0);
-});
 
 // ---- Auth from .viber/auth.json ----
 
@@ -127,7 +186,7 @@ if (computedFp !== auth.client_fingerprint) {
 // ---- Imports for mint ----
 
 import { defaultLabel, mintConversation, ReverifyRequiredError } from "./lib/conversation.ts";
-import { postMessage, ConversationTokenExpiredError } from "./lib/messages.ts";
+import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
 const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
@@ -136,17 +195,20 @@ const label = process.env.VIBER_CONVERSATION_LABEL ?? defaultLabel(process.cwd()
 // ---- MCP server ----
 
 const mcp = new Server(
-  { name: "viber-channel", version: "0.3.0" },
+  { name: "viber-channel", version: "0.5.0" },
   {
     capabilities: {
       experimental: { "claude/channel": {} },
       tools: {},
     },
     instructions: [
-      'Voice transcripts arrive as <channel source="viber-channel">.',
-      "Each event contains transcriptions from the user's microphone.",
-      "Process the transcript and respond with speak(). Do NOT launch any watchdog or call check_voice().",
-      "On exit intent (bye, au revoir, stop) → call stop_conversation(), speak farewell, stop.",
+      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
+      "Reply with send_message. The `text` field is read aloud to the user, so keep it a short, natural spoken sentence — no markdown symbols, no bullet lists, no tables, no code blocks.",
+      "Put technical content (code, lists, JSON, tables, command output, long file paths) in the optional `artifact` field with the matching `format`; it renders in a side viewer the user can read.",
+      "Available formats: `markdown` (default), `code`, `json`, `html`.",
+      "Use `html` only when the rendering needs structural HTML markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't try to send executable JS.",
+      "Rule of thumb: if it would sound bad read aloud, it belongs in the artifact, not the text.",
+      "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
     ].join(" "),
   }
 );
@@ -158,14 +220,37 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "send_message",
       description:
-        "Send a message into the Viber conversation this channel is bound to. The user sees it in the web UI in real-time. Use this to deliver Claude's responses to the user without typing.",
+        "Send a message into the Viber conversation this channel is bound to. " +
+        "`text` is the spoken/conversational reply (read aloud — keep it short and natural, no markdown). " +
+        "`artifact` is optional and carries technical content (markdown, code, JSON, or sanitized HTML) rendered in a side viewer. " +
+        "Use `html` only when structural HTML markdown can't express is required; scripts and event handlers are stripped before display.",
       inputSchema: {
         type: "object" as const,
         properties: {
           text: {
             type: "string",
             minLength: 1,
-            description: "Message text to send to the user's conversation",
+            description: "Spoken/conversational reply. Plain sentences, no markdown symbols or lists.",
+          },
+          artifact: {
+            type: "object",
+            description: "Optional technical content rendered in the artifact viewer alongside the spoken text.",
+            properties: {
+              content: {
+                type: "string",
+                minLength: 1,
+                description: "Artifact body — markdown, code, JSON, or HTML.",
+              },
+              format: {
+                type: "string",
+                enum: ["markdown", "code", "json", "html"],
+                description:
+                  "Render format for the artifact body. Defaults to markdown if omitted. " +
+                  "Use `html` only when structural HTML is required (styled cards, badges, mixed layouts); " +
+                  "scripts, event handlers, iframes, and inline styles are stripped server-side before rendering.",
+              },
+            },
+            required: ["content"],
           },
         },
         required: ["text"],
@@ -194,9 +279,18 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
   }
 
+  const parsed = parseArtifact(args.artifact);
+  if (!parsed.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text" as const, text: `Invalid input: ${parsed.error}` }],
+    };
+  }
+  const artifact = parsed.artifact;
+
   let result;
   try {
-    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text);
+    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text, artifact);
   } catch (err) {
     if (err instanceof ConversationTokenExpiredError) {
       // Notify Claude (and the user) that the channel token has expired
@@ -341,19 +435,36 @@ async function pushTranscript(text: string, lang: string): Promise<void> {
   });
 }
 
-/** Forward a saved conversation message from the event bus to Claude. */
-async function pushMessage(msg: { text: string; id?: string | null; source?: string }): Promise<void> {
-  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.text.slice(0, 60)}"\n`);
+/**
+ * Forward a saved conversation message from the event bus to Claude.
+ *
+ * Wire field name is `content` — the SSE payload mirrors the Worker's
+ * `MessageResponse` shape (viber-api/src/db/types.ts), republished verbatim by
+ * Python (`ws_server.internal_notify_message` → `publish_to_conversation`).
+ * The optional `artifact` field is accepted here and threaded through the meta
+ * so downstream consumers (step-03 React viewer) can opt-in without a second
+ * round-trip; the channel itself does no special rendering of it yet.
+ */
+async function pushMessage(msg: {
+  content: string;
+  id?: string | null;
+  source?: string;
+  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+}): Promise<void> {
+  process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.slice(0, 60)}"\n`);
   // MCP notification handler (Claude Code v2.1.143) validates meta with Zod;
   // null fields are rejected as invalid type. Omit message_id when missing.
-  const meta: Record<string, string> = { source: msg.source ?? "conversation" };
+  const meta: Record<string, unknown> = { source: msg.source ?? "conversation" };
   if (typeof msg.id === "string" && msg.id.length > 0) {
     meta.message_id = msg.id;
   }
+  if (msg.artifact && typeof msg.artifact === "object" && typeof msg.artifact.content === "string") {
+    meta.artifact = msg.artifact;
+  }
   try {
     await mcp.notification({
       method: "notifications/claude/channel",
-      params: { content: msg.text, meta },
+      params: { content: msg.content, meta },
     });
     process.stderr.write(`[viber-channel] pushMessage OK\n`);
   } catch (err) {
@@ -439,11 +550,21 @@ async function sseLoop(): Promise<void> {
           process.stderr.write(`[viber-channel] SSE event 'message' received, data_len=${data.length}\n`);
           if (data) {
             try {
-              const msg = JSON.parse(data) as { text: string; id?: string; source?: string; role?: string; timestamp?: string };
-              if (msg.text) {
+              // Wire shape mirrors viber-api `MessageResponse` (db/types.ts):
+              // primary text is `content`, not `text`. `artifact` is threaded
+              // through opaquely so step-03 (React viewer) can consume it.
+              const msg = JSON.parse(data) as {
+                content: string;
+                id?: string;
+                source?: string;
+                role?: string;
+                timestamp?: string;
+                artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+              };
+              if (msg.content) {
                 await pushMessage(msg);
               } else {
-                process.stderr.write(`[viber-channel] 'message' event has empty text\n`);
+                process.stderr.write(`[viber-channel] 'message' event has empty content\n`);
               }
             } catch (err) {
               process.stderr.write(`[viber-channel] Failed to parse message data: ${String(err)}\n`);