@cuongtran001/kanna 0.39.2

package/src/server/share.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, test } from "bun:test"
+import { ensureCloudflaredInstalled, logShareDetails, renderTerminalQr, startShareTunnel } from "./share"
+
+describe("ensureCloudflaredInstalled", () => {
+  test("returns immediately when the binary already exists", async () => {
+    const installCalls: string[] = []
+
+    const result = await ensureCloudflaredInstalled({
+      cloudflaredBin: "/tmp/cloudflared",
+      existsSync: () => true,
+      installCloudflared: async (to) => {
+        installCalls.push(to)
+        return to
+      },
+    })
+
+    expect(result).toBe("/tmp/cloudflared")
+    expect(installCalls).toEqual([])
+  })
+
+  test("installs the binary on demand when it is missing", async () => {
+    const installCalls: string[] = []
+    const logLines: string[] = []
+
+    const result = await ensureCloudflaredInstalled({
+      cloudflaredBin: "/tmp/cloudflared",
+      existsSync: () => false,
+      installCloudflared: async (to) => {
+        installCalls.push(to)
+        return to
+      },
+      log: (message) => {
+        logLines.push(message)
+      },
+    })
+
+    expect(result).toBe("/tmp/cloudflared")
+    expect(installCalls).toEqual(["/tmp/cloudflared"])
+    expect(logLines).toEqual(["installing cloudflared binary"])
+  })
+})
+
+describe("startShareTunnel", () => {
+  test("starts a quick tunnel after ensuring the binary exists", async () => {
+    const installCalls: string[] = []
+    const quickTunnelUrls: string[] = []
+    let stopCalls = 0
+
+    const shareTunnel = await startShareTunnel("http://localhost:3333", "quick", {
+      cloudflaredBin: "/tmp/cloudflared",
+      existsSync: () => false,
+      installCloudflared: async (to) => {
+        installCalls.push(to)
+        return to
+      },
+      createQuickTunnel: (localUrl) => {
+        quickTunnelUrls.push(localUrl)
+        return {
+          once(event: "url" | "connected" | "error" | "exit", listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+            if (event === "url") {
+              queueMicrotask(() => (listener as (url: string) => void)("https://kanna.trycloudflare.com"))
+            }
+            return this
+          },
+          off(_event: "url" | "connected" | "error" | "exit", _listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+            return this
+          },
+          stop() {
+            stopCalls += 1
+            return true
+          },
+        }
+      },
+    })
+
+    expect(installCalls).toEqual(["/tmp/cloudflared"])
+    expect(quickTunnelUrls).toEqual(["http://localhost:3333"])
+    expect(shareTunnel.publicUrl).toBe("https://kanna.trycloudflare.com")
+    shareTunnel.stop()
+    expect(stopCalls).toBe(1)
+  })
+
+  test("starts a named tunnel with token and accepts missing hostname discovery", async () => {
+    const installCalls: string[] = []
+    const namedTunnelCalls: Array<{ token: string; localUrl: string }> = []
+    let stopCalls = 0
+
+    const shareTunnel = await startShareTunnel("http://localhost:3333", { kind: "token", token: "secret-token" }, {
+      cloudflaredBin: "/tmp/cloudflared",
+      existsSync: () => false,
+      installCloudflared: async (to: string) => {
+        installCalls.push(to)
+        return to
+      },
+      createNamedTunnel: (token: string, localUrl: string) => {
+        namedTunnelCalls.push({ token, localUrl })
+        return {
+          once(event: "url" | "connected" | "error" | "exit", listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+            if (event === "connected") {
+              queueMicrotask(() => (listener as () => void)())
+            }
+            return this
+          },
+          off(_event: "url" | "connected" | "error" | "exit", _listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+            return this
+          },
+          stop() {
+            stopCalls += 1
+            return true
+          },
+        }
+      },
+    })
+
+    expect(installCalls).toEqual(["/tmp/cloudflared"])
+    expect(namedTunnelCalls).toEqual([{ token: "secret-token", localUrl: "http://localhost:3333" }])
+    expect(shareTunnel.publicUrl).toBeNull()
+    shareTunnel.stop()
+    expect(stopCalls).toBe(1)
+  })
+
+  test("normalizes a discovered named tunnel hostname into https", async () => {
+    const shareTunnel = await startShareTunnel("http://localhost:3333", { kind: "token", token: "secret-token" }, {
+      cloudflaredBin: "/tmp/cloudflared",
+      existsSync: () => true,
+      createNamedTunnel: () => ({
+        once(event: "url" | "connected" | "error" | "exit", listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+          if (event === "url") {
+            queueMicrotask(() => (listener as (url: string) => void)("app.example.com"))
+          }
+          return this
+        },
+        off(_event: "url" | "connected" | "error" | "exit", _listener: ((url: string) => void) | (() => void) | ((error: Error) => void) | ((code: number | null, signal: NodeJS.Signals | null) => void)) {
+          return this
+        },
+        stop() {
+          return true
+        },
+      }),
+    })
+
+    expect(shareTunnel.publicUrl).toBe("https://app.example.com")
+  })
+})
+
+describe("logShareDetails", () => {
+  test("prints qr, public url, and local url in the expected order", async () => {
+    const logLines: string[] = []
+
+    await logShareDetails(
+      (message) => {
+        logLines.push(message)
+      },
+      "https://kanna.trycloudflare.com",
+      "http://localhost:3333",
+      async (url) => `[qr:${url}]\n`,
+    )
+
+    expect(logLines).toEqual([
+      "QR Code:",
+      "[qr:https://kanna.trycloudflare.com]",
+      "",
+      "Public URL:",
+      "https://kanna.trycloudflare.com",
+      "",
+      "Local URL:",
+      "http://localhost:3333",
+    ])
+  })
+})
+
+describe("renderTerminalQr", () => {
+  test("renders an ANSI qr string", async () => {
+    const result = await renderTerminalQr("https://kanna.trycloudflare.com")
+
+    expect(result).toContain("\x1b[47m")
+    expect(result).toContain("\n")
+    expect(result.length).toBeGreaterThan(0)
+  })
+})

package/src/server/share.ts

@@ -0,0 +1,150 @@
+import { existsSync } from "node:fs"
+import { renderANSI } from "uqr"
+import { ConfigHandler, Tunnel, bin as cloudflaredBin, install as installCloudflared } from "cloudflared"
+import type { ShareMode } from "../shared/share"
+import { isTokenShareMode } from "../shared/share"
+
+export interface StartedShareTunnel {
+  publicUrl: string | null
+  stop: () => void
+}
+
+export interface ShareTunnelProcess {
+  once(event: "url", listener: (url: string) => void): ShareTunnelProcess
+  once(event: "connected", listener: () => void): ShareTunnelProcess
+  once(event: "error", listener: (error: Error) => void): ShareTunnelProcess
+  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): ShareTunnelProcess
+  off(event: "url", listener: (url: string) => void): ShareTunnelProcess
+  off(event: "connected", listener: () => void): ShareTunnelProcess
+  off(event: "error", listener: (error: Error) => void): ShareTunnelProcess
+  off(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): ShareTunnelProcess
+  stop(): boolean
+}
+
+export interface ShareTunnelDeps {
+  cloudflaredBin?: string
+  existsSync?: (path: string) => boolean
+  installCloudflared?: (to: string) => Promise<string>
+  createQuickTunnel?: (localUrl: string) => ShareTunnelProcess
+  createNamedTunnel?: (token: string, localUrl: string) => ShareTunnelProcess
+  log?: (message: string) => void
+}
+
+export async function renderTerminalQr(url: string) {
+  return renderANSI(url, {
+    ecc: "L",
+    border: 2,
+  })
+}
+
+export async function ensureCloudflaredInstalled(
+  deps: ShareTunnelDeps = {},
+) {
+  const resolvedBin = deps.cloudflaredBin ?? cloudflaredBin
+  const fileExists = deps.existsSync ?? existsSync
+  const installBinary = deps.installCloudflared ?? installCloudflared
+
+  if (fileExists(resolvedBin)) {
+    return resolvedBin
+  }
+
+  deps.log?.("installing cloudflared binary")
+  await installBinary(resolvedBin)
+  return resolvedBin
+}
+
+function normalizePublicUrl(url: string) {
+  return /^https?:\/\//.test(url) ? url : `https://${url}`
+}
+
+function createNamedTunnel(token: string, localUrl: string) {
+  const tunnel = Tunnel.withToken(token, { "--url": localUrl })
+  new ConfigHandler(tunnel)
+  return tunnel
+}
+
+async function awaitTunnelReady(
+  tunnel: ShareTunnelProcess,
+  { expectUrl }: { expectUrl: boolean },
+) {
+  return await new Promise<string | null>((resolve, reject) => {
+    let settled = false
+
+    const cleanup = () => {
+      tunnel.off("url", handleUrl)
+      tunnel.off("connected", handleConnected)
+      tunnel.off("error", handleError)
+      tunnel.off("exit", handleExit)
+    }
+
+    const settle = (callback: () => void) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      callback()
+    }
+
+    const handleUrl = (url: string) => {
+      settle(() => resolve(normalizePublicUrl(url)))
+    }
+
+    const handleConnected = () => {
+      if (expectUrl) return
+      settle(() => resolve(null))
+    }
+
+    const handleError = (error: Error) => {
+      settle(() => reject(error))
+    }
+
+    const handleExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      const readyState = expectUrl ? "a public URL was ready" : "it was ready"
+      settle(() => reject(new Error(`Cloudflare tunnel exited before ${readyState} (code: ${String(code)}, signal: ${String(signal)})`)))
+    }
+
+    tunnel.once("url", handleUrl)
+    if (!expectUrl) {
+      tunnel.once("connected", handleConnected)
+    }
+    tunnel.once("error", handleError)
+    tunnel.once("exit", handleExit)
+  })
+}
+
+export async function startShareTunnel(
+  localUrl: string,
+  shareMode: Exclude<ShareMode, false> = "quick",
+  deps: ShareTunnelDeps = {},
+): Promise<StartedShareTunnel> {
+  await ensureCloudflaredInstalled(deps)
+  const namedTunnel = isTokenShareMode(shareMode)
+  const tunnel = namedTunnel
+    ? (deps.createNamedTunnel ?? createNamedTunnel)(shareMode.token, localUrl)
+    : (deps.createQuickTunnel ?? ((url) => Tunnel.quick(url)))(localUrl)
+  const publicUrl = await awaitTunnelReady(tunnel, { expectUrl: !namedTunnel })
+
+  return {
+    publicUrl,
+    stop: () => {
+      tunnel.stop()
+    },
+  }
+}
+
+export async function logShareDetails(
+  log: (message: string) => void,
+  publicUrl: string,
+  localUrl: string,
+  renderShareQrImpl: (url: string) => Promise<string> = renderTerminalQr,
+) {
+  const qrCode = await renderShareQrImpl(publicUrl)
+
+  log("QR Code:")
+  log(qrCode.trimEnd())
+  log("")
+  log("Public URL:")
+  log(publicUrl)
+  log("")
+  log("Local URL:")
+  log(localUrl)
+}

package/src/server/standalone-export.test.ts

@@ -0,0 +1,224 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import type { TranscriptEntry } from "../shared/types"
+import { writeStandaloneTranscriptExport } from "./standalone-export"
+
+const tempDirs: string[] = []
+
+async function createTempDir(prefix: string) {
+  const dir = await mkdtemp(path.join(tmpdir(), prefix))
+  tempDirs.push(dir)
+  return dir
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+async function createViewerDist() {
+  const viewerDistDir = await createTempDir("kanna-viewer-")
+  await mkdir(path.join(viewerDistDir, "assets"), { recursive: true })
+  await writeFile(path.join(viewerDistDir, "index.html"), "<!doctype html><html><body><div id=\"root\"></div></body></html>\n", "utf8")
+  await writeFile(path.join(viewerDistDir, "assets", "viewer.js"), "console.log('viewer')\n", "utf8")
+  return viewerDistDir
+}
+
+function createMessages(attachmentAbsolutePath: string): TranscriptEntry[] {
+  return [
+    {
+      _id: "user-1",
+      createdAt: Date.now(),
+      kind: "user_prompt",
+      messageId: "message-1",
+      content: "Please review this attachment.",
+      attachments: [{
+        id: "attachment-1",
+        kind: "image",
+        displayName: "mock.png",
+        absolutePath: attachmentAbsolutePath,
+        relativePath: "./.kanna/uploads/mock.png",
+        contentUrl: "/api/projects/project-1/uploads/mock.png/content",
+        mimeType: "image/png",
+        size: 4,
+      }],
+    },
+    {
+      _id: "assistant-1",
+      createdAt: Date.now(),
+      kind: "assistant_text",
+      messageId: "message-2",
+      text: `Looks good in ${attachmentAbsolutePath}.`,
+    },
+  ]
+}
+
+describe("writeStandaloneTranscriptExport", () => {
+  test("writes a metadata-only export with viewer assets and sanitized attachments", async () => {
+    const viewerDistDir = await createViewerDist()
+    const projectDir = await createTempDir("kanna-project-")
+    const uploadsDir = path.join(projectDir, ".kanna", "uploads")
+    await mkdir(uploadsDir, { recursive: true })
+    const attachmentPath = path.join(uploadsDir, "mock.png")
+    await writeFile(attachmentPath, "mock", "utf8")
+    const uploadedRequests = new Map<string, string>()
+
+    const result = await writeStandaloneTranscriptExport({
+      chatId: "chat-1",
+      title: "Release Review",
+      localPath: projectDir,
+      theme: "dark",
+      attachmentMode: "metadata",
+      messages: createMessages(attachmentPath),
+    }, {
+      fetch: async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url
+        const body = init?.body
+        const bodyText = typeof body === "string"
+          ? body
+          : body instanceof Uint8Array
+            ? new TextDecoder().decode(body)
+            : ""
+        uploadedRequests.set(url, bodyText)
+        expect(init?.method).toBe("PUT")
+        return new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: {
+            "content-type": "application/json",
+          },
+        })
+      },
+      sharePublicBaseUrl: "https://share.example.com",
+      shareSlugSuffix: "ax71234ka",
+      shareUploadBaseUrl: "https://upload.example.com/api/share",
+      viewerDistDir,
+      now: new Date("2026-04-23T12:34:56.000Z"),
+    })
+
+    expect(result.ok).toBe(true)
+    if (!result.ok) {
+      throw new Error(result.error)
+    }
+    expect(await Bun.file(result.indexHtmlPath).exists()).toBe(true)
+    expect(await Bun.file(path.join(result.outputDir, "assets", "viewer.js")).exists()).toBe(true)
+    expect(result.totalAttachmentCount).toBe(1)
+    expect(result.bundledAttachmentCount).toBe(0)
+    expect(result.shareSlug).toBe("release-review-ax71234ka")
+    expect(result.shareUrl).toBe("https://share.example.com/release-review-ax71234ka")
+    expect(result.uploadedFileCount).toBe(1)
+
+    const bundle = await Bun.file(result.transcriptJsonPath).json()
+    expect(bundle.title).toBe("Release Review")
+    expect(bundle.viewerVersion).toBeDefined()
+    expect(bundle.theme).toBe("dark")
+    expect(bundle.attachmentMode).toBe("metadata")
+    expect(bundle.localPath).toBe("/workspace")
+    expect(bundle.messages[0].attachments[0].contentUrl).toBe("")
+    expect(bundle.messages[0].attachments[0].absolutePath).toBe("")
+    expect(bundle.messages[0].attachments[0].relativePath).toBe("")
+    expect(JSON.stringify(bundle)).not.toContain(projectDir)
+    expect([...uploadedRequests.keys()]).toEqual([
+      "https://upload.example.com/api/share/release-review-ax71234ka/transcript.json",
+    ])
+  })
+
+  test("copies attachments into the export when bundle mode is selected", async () => {
+    const viewerDistDir = await createViewerDist()
+    const projectDir = await createTempDir("kanna-project-")
+    const uploadsDir = path.join(projectDir, ".kanna", "uploads")
+    await mkdir(uploadsDir, { recursive: true })
+    const attachmentPath = path.join(uploadsDir, "mock.png")
+    await writeFile(attachmentPath, "mock", "utf8")
+    const uploadedPaths: string[] = []
+
+    const result = await writeStandaloneTranscriptExport({
+      chatId: "chat-1",
+      title: "Release Review",
+      localPath: projectDir,
+      theme: "light",
+      attachmentMode: "bundle",
+      messages: createMessages(attachmentPath),
+    }, {
+      fetch: async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url
+        uploadedPaths.push(url)
+        return new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: {
+            "content-type": "application/json",
+          },
+        })
+      },
+      sharePublicBaseUrl: "https://share.example.com",
+      shareSlugSuffix: "bundle123",
+      shareUploadBaseUrl: "https://upload.example.com/api/share",
+      viewerDistDir,
+      now: new Date("2026-04-23T12:34:56.000Z"),
+    })
+
+    expect(result.ok).toBe(true)
+    if (!result.ok) {
+      throw new Error(result.error)
+    }
+    expect(result.totalAttachmentCount).toBe(1)
+    expect(result.bundledAttachmentCount).toBe(1)
+    expect(result.shareUrl).toBe("https://share.example.com/release-review-bundle123")
+    expect(result.uploadedFileCount).toBe(2)
+
+    const bundle = await Bun.file(result.transcriptJsonPath).json()
+    const exportedAttachment = bundle.messages[0].attachments[0]
+    expect(bundle.viewerVersion).toBeDefined()
+    expect(exportedAttachment.contentUrl).toStartWith("./attachments/")
+    expect(exportedAttachment.absolutePath).toStartWith("./attachments/")
+    expect(exportedAttachment.relativePath).toStartWith("./attachments/")
+    expect(await Bun.file(path.join(result.outputDir, exportedAttachment.contentUrl.replace(/^\.\//u, ""))).text()).toBe("mock")
+    expect(uploadedPaths).toEqual([
+      "https://upload.example.com/api/share/release-review-bundle123/transcript.json",
+      expect.stringContaining("https://upload.example.com/api/share/release-review-bundle123/attachments/"),
+    ])
+  })
+
+  test("returns transcript json for download when share upload fails", async () => {
+    const viewerDistDir = await createViewerDist()
+    const projectDir = await createTempDir("kanna-project-")
+    const uploadsDir = path.join(projectDir, ".kanna", "uploads")
+    await mkdir(uploadsDir, { recursive: true })
+    const attachmentPath = path.join(uploadsDir, "mock.png")
+    await writeFile(attachmentPath, "mock", "utf8")
+
+    const result = await writeStandaloneTranscriptExport({
+      chatId: "chat-1",
+      title: "Release Review",
+      localPath: projectDir,
+      theme: "light",
+      attachmentMode: "bundle",
+      messages: createMessages(attachmentPath),
+    }, {
+      fetch: async () => new Response(JSON.stringify({ error: "No release viewer assets were found for 0.34.5." }), {
+        status: 400,
+        headers: {
+          "content-type": "application/json",
+        },
+      }),
+      sharePublicBaseUrl: "https://share.example.com",
+      shareSlugSuffix: "failed123",
+      shareUploadBaseUrl: "https://upload.example.com/api/share",
+      viewerDistDir,
+      now: new Date("2026-04-23T12:34:56.000Z"),
+    })
+
+    expect(result.ok).toBe(false)
+    if (result.ok) {
+      throw new Error("Expected export upload to fail")
+    }
+
+    expect(result.error).toContain("Failed to upload shared transcript file transcript.json")
+    expect(result.error).toContain("No release viewer assets were found")
+    expect(result.shareUrl).toBe("https://share.example.com/release-review-failed123")
+    expect(result.transcriptFileName).toBe("Release-Review-2026-04-23T12-34-56Z-transcript.json")
+    expect(result.transcriptJsonPath).toEndWith("/transcript.json")
+    expect(JSON.parse(result.transcriptJson).title).toBe("Release Review")
+    expect(JSON.stringify(JSON.parse(result.transcriptJson))).not.toContain(projectDir)
+  })
+})