kanna-code 0.35.1 → 0.36.0

package/src/server/app-settings.test.ts

@@ -3,6 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import path from "node:path"
 import { AppSettingsManager, readAppSettingsSnapshot } from "./app-settings"
+import type { AppSettingsSnapshot } from "../shared/types"
 
 let tempDirs: string[] = []
 
@@ -17,16 +18,52 @@ async function createTempFilePath() {
   return path.join(dir, "settings.json")
 }
 
+function expectedSettingsSnapshot(filePath: string, overrides: Partial<AppSettingsSnapshot> = {}): AppSettingsSnapshot {
+  return {
+    analyticsEnabled: true,
+    browserSettingsMigrated: false,
+    theme: "system",
+    chatSoundPreference: "always",
+    chatSoundId: "funk",
+    terminal: {
+      scrollbackLines: 1_000,
+      minColumnWidth: 450,
+    },
+    editor: {
+      preset: "cursor",
+      commandTemplate: "cursor {path}",
+    },
+    defaultProvider: "last_used",
+    providerDefaults: {
+      claude: {
+        model: "claude-opus-4-7",
+        modelOptions: {
+          reasoningEffort: "high",
+          contextWindow: "200k",
+        },
+        planMode: false,
+      },
+      codex: {
+        model: "gpt-5.5",
+        modelOptions: {
+          reasoningEffort: "high",
+          fastMode: false,
+        },
+        planMode: false,
+      },
+    },
+    warning: null,
+    filePathDisplay: filePath,
+    ...overrides,
+  }
+}
+
 describe("readAppSettingsSnapshot", () => {
   test("returns defaults when the file does not exist", async () => {
     const filePath = await createTempFilePath()
     const snapshot = await readAppSettingsSnapshot(filePath)
 
-    expect(snapshot).toEqual({
-      analyticsEnabled: true,
-      warning: null,
-      filePathDisplay: filePath,
-    })
+    expect(snapshot).toEqual(expectedSettingsSnapshot(filePath))
   })
 
   test("returns a warning when the file contains invalid json", async () => {
@@ -52,11 +89,7 @@ describe("AppSettingsManager", () => {
     }
     expect(payload.analyticsEnabled).toBe(true)
     expect(payload.analyticsUserId).toMatch(/^anon_/)
-    expect(manager.getSnapshot()).toEqual({
-      analyticsEnabled: true,
-      warning: null,
-      filePathDisplay: filePath,
-    })
+    expect(manager.getSnapshot()).toEqual(expectedSettingsSnapshot(filePath))
 
     manager.dispose()
   })
@@ -77,14 +110,53 @@ describe("AppSettingsManager", () => {
       analyticsUserId: string
     }
 
-    expect(snapshot).toEqual({
-      analyticsEnabled: false,
-      warning: null,
-      filePathDisplay: filePath,
-    })
+    expect(snapshot).toEqual(expectedSettingsSnapshot(filePath, { analyticsEnabled: false }))
     expect(nextPayload.analyticsEnabled).toBe(false)
     expect(nextPayload.analyticsUserId).toBe(initialPayload.analyticsUserId)
 
     manager.dispose()
   })
+
+  test("patches expanded settings without replacing the stored user id", async () => {
+    const filePath = await createTempFilePath()
+    const manager = new AppSettingsManager(filePath)
+
+    await manager.initialize()
+    const initialPayload = JSON.parse(await readFile(filePath, "utf8")) as {
+      analyticsUserId: string
+    }
+
+    const snapshot = await manager.writePatch({
+      theme: "dark",
+      chatSoundId: "glass",
+      terminal: { scrollbackLines: 2_500 },
+      editor: { preset: "vscode" },
+      providerDefaults: {
+        codex: {
+          modelOptions: { reasoningEffort: "high", fastMode: true },
+        },
+      },
+    })
+    const nextPayload = JSON.parse(await readFile(filePath, "utf8")) as {
+      analyticsUserId: string
+      theme: string
+      chatSoundId: string
+      terminal: { scrollbackLines: number; minColumnWidth: number }
+      editor: { preset: string; commandTemplate: string }
+      providerDefaults: { codex: { modelOptions: { fastMode: boolean } } }
+    }
+
+    expect(snapshot.theme).toBe("dark")
+    expect(snapshot.chatSoundId).toBe("glass")
+    expect(snapshot.terminal.scrollbackLines).toBe(2_500)
+    expect(snapshot.terminal.minColumnWidth).toBe(450)
+    expect(snapshot.editor.preset).toBe("vscode")
+    expect(snapshot.editor.commandTemplate).toBe("cursor {path}")
+    expect(snapshot.providerDefaults.codex.modelOptions.fastMode).toBe(true)
+    expect(nextPayload.analyticsUserId).toBe(initialPayload.analyticsUserId)
+    expect(nextPayload.theme).toBe("dark")
+    expect(nextPayload.chatSoundId).toBe("glass")
+
+    manager.dispose()
+  })
 })

package/src/server/app-settings.ts

@@ -4,11 +4,48 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
 import path from "node:path"
 import { getSettingsFilePath, LOG_PREFIX } from "../shared/branding"
-import type { AppSettingsSnapshot } from "../shared/types"
+import {
+  DEFAULT_CLAUDE_MODEL_OPTIONS,
+  DEFAULT_CODEX_MODEL_OPTIONS,
+  isClaudeReasoningEffort,
+  isCodexReasoningEffort,
+  normalizeClaudeContextWindow,
+  normalizeClaudeModelId,
+  normalizeCodexModelId,
+  supportsClaudeMaxReasoningEffort,
+  type AppSettingsPatch,
+  type AppSettingsSnapshot,
+  type AppThemePreference,
+  type ChatProviderPreferences,
+  type ChatSoundId,
+  type ChatSoundPreference,
+  type ClaudeModelOptions,
+  type CodexModelOptions,
+  type DefaultProviderPreference,
+  type EditorPreset,
+  type ProviderPreference,
+} from "../shared/types"
 
 interface AppSettingsFile {
   analyticsEnabled?: unknown
   analyticsUserId?: unknown
+  browserSettingsMigrated?: unknown
+  theme?: unknown
+  chatSoundPreference?: unknown
+  chatSoundId?: unknown
+  terminal?: {
+    scrollbackLines?: unknown
+    minColumnWidth?: unknown
+  }
+  editor?: {
+    preset?: unknown
+    commandTemplate?: unknown
+  }
+  defaultProvider?: unknown
+  providerDefaults?: {
+    claude?: Partial<ProviderPreference<Partial<ClaudeModelOptions>>> & { effort?: unknown }
+    codex?: Partial<ProviderPreference<Partial<CodexModelOptions>>> & { effort?: unknown }
+  }
 }
 
 interface AppSettingsState extends AppSettingsSnapshot {
@@ -16,14 +53,21 @@ interface AppSettingsState extends AppSettingsSnapshot {
 }
 
 interface NormalizedAppSettings {
-  payload: {
-    analyticsEnabled: boolean
-    analyticsUserId: string
-  }
+  payload: AppSettingsState
   warning: string | null
   shouldWrite: boolean
 }
 
+const DEFAULT_TERMINAL_SCROLLBACK = 1_000
+const MIN_TERMINAL_SCROLLBACK = 500
+const MAX_TERMINAL_SCROLLBACK = 5_000
+const DEFAULT_TERMINAL_MIN_COLUMN_WIDTH = 450
+const MIN_TERMINAL_MIN_COLUMN_WIDTH = 250
+const MAX_TERMINAL_MIN_COLUMN_WIDTH = 900
+const DEFAULT_EDITOR_PRESET: EditorPreset = "cursor"
+const DEFAULT_CHAT_SOUND_PREFERENCE: ChatSoundPreference = "always"
+const DEFAULT_CHAT_SOUND_ID: ChatSoundId = "funk"
+
 function formatDisplayPath(filePath: string) {
   const homePath = homedir()
   if (filePath === homePath) return "~"
@@ -37,6 +81,168 @@ function createAnalyticsUserId() {
   return `anon_${randomUUID()}`
 }
 
+function getDefaultEditorCommandTemplate(preset: EditorPreset) {
+  switch (preset) {
+    case "vscode":
+      return "code {path}"
+    case "xcode":
+      return "xed {path}"
+    case "windsurf":
+      return "windsurf {path}"
+    case "custom":
+    case "cursor":
+    default:
+      return "cursor {path}"
+  }
+}
+
+function createDefaultProviderDefaults(): ChatProviderPreferences {
+  return {
+    claude: {
+      model: "claude-opus-4-7",
+      modelOptions: { ...DEFAULT_CLAUDE_MODEL_OPTIONS },
+      planMode: false,
+    },
+    codex: {
+      model: "gpt-5.5",
+      modelOptions: { ...DEFAULT_CODEX_MODEL_OPTIONS },
+      planMode: false,
+    },
+  }
+}
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number) {
+  const numberValue = typeof value === "number" ? value : Number(value)
+  if (!Number.isFinite(numberValue)) return fallback
+  return Math.min(max, Math.max(min, Math.round(numberValue)))
+}
+
+function normalizeTheme(value: unknown): AppThemePreference {
+  return value === "light" || value === "dark" || value === "system" ? value : "system"
+}
+
+function normalizeChatSoundPreference(value: unknown): ChatSoundPreference {
+  return value === "never" || value === "unfocused" || value === "always" ? value : DEFAULT_CHAT_SOUND_PREFERENCE
+}
+
+function normalizeChatSoundId(value: unknown): ChatSoundId {
+  switch (value) {
+    case "blow":
+    case "bottle":
+    case "frog":
+    case "funk":
+    case "glass":
+    case "ping":
+    case "pop":
+    case "purr":
+    case "tink":
+      return value
+    default:
+      return DEFAULT_CHAT_SOUND_ID
+  }
+}
+
+function normalizeDefaultProvider(value: unknown): DefaultProviderPreference {
+  return value === "claude" || value === "codex" || value === "last_used" ? value : "last_used"
+}
+
+function normalizeEditorPreset(value: unknown): EditorPreset {
+  return value === "vscode" || value === "xcode" || value === "windsurf" || value === "custom" || value === "cursor"
+    ? value
+    : DEFAULT_EDITOR_PRESET
+}
+
+function normalizeEditorCommandTemplate(value: unknown, preset: EditorPreset) {
+  const trimmed = typeof value === "string" ? value.trim() : ""
+  return trimmed || getDefaultEditorCommandTemplate(preset)
+}
+
+function normalizeClaudePreference(value?: {
+  model?: unknown
+  effort?: unknown
+  modelOptions?: Partial<Record<keyof ClaudeModelOptions, unknown>>
+  planMode?: unknown
+}): ProviderPreference<ClaudeModelOptions> {
+  const model = normalizeClaudeModelId(typeof value?.model === "string" ? value.model : undefined)
+  const reasoningEffort = value?.modelOptions?.reasoningEffort
+  const normalizedEffort = isClaudeReasoningEffort(reasoningEffort)
+    ? reasoningEffort
+    : isClaudeReasoningEffort(value?.effort)
+      ? value.effort
+      : DEFAULT_CLAUDE_MODEL_OPTIONS.reasoningEffort
+
+  return {
+    model,
+    modelOptions: {
+      reasoningEffort: !supportsClaudeMaxReasoningEffort(model) && normalizedEffort === "max" ? "high" : normalizedEffort,
+      contextWindow: normalizeClaudeContextWindow(model, value?.modelOptions?.contextWindow),
+    },
+    planMode: value?.planMode === true,
+  }
+}
+
+function normalizeCodexPreference(value?: {
+  model?: unknown
+  effort?: unknown
+  modelOptions?: Partial<Record<keyof CodexModelOptions, unknown>>
+  planMode?: unknown
+}): ProviderPreference<CodexModelOptions> {
+  const reasoningEffort = value?.modelOptions?.reasoningEffort
+  return {
+    model: normalizeCodexModelId(typeof value?.model === "string" ? value.model : undefined),
+    modelOptions: {
+      reasoningEffort: isCodexReasoningEffort(reasoningEffort)
+        ? reasoningEffort
+        : isCodexReasoningEffort(value?.effort)
+          ? value.effort
+          : DEFAULT_CODEX_MODEL_OPTIONS.reasoningEffort,
+      fastMode: typeof value?.modelOptions?.fastMode === "boolean"
+        ? value.modelOptions.fastMode
+        : DEFAULT_CODEX_MODEL_OPTIONS.fastMode,
+    },
+    planMode: value?.planMode === true,
+  }
+}
+
+function normalizeProviderDefaults(value: AppSettingsFile["providerDefaults"] | undefined): ChatProviderPreferences {
+  const defaults = createDefaultProviderDefaults()
+  return {
+    claude: normalizeClaudePreference(value?.claude ?? defaults.claude),
+    codex: normalizeCodexPreference(value?.codex ?? defaults.codex),
+  }
+}
+
+function toFilePayload(state: AppSettingsState) {
+  return {
+    analyticsEnabled: state.analyticsEnabled,
+    analyticsUserId: state.analyticsUserId,
+    browserSettingsMigrated: state.browserSettingsMigrated,
+    theme: state.theme,
+    chatSoundPreference: state.chatSoundPreference,
+    chatSoundId: state.chatSoundId,
+    terminal: state.terminal,
+    editor: state.editor,
+    defaultProvider: state.defaultProvider,
+    providerDefaults: state.providerDefaults,
+  }
+}
+
+function toSnapshot(state: AppSettingsState): AppSettingsSnapshot {
+  return {
+    analyticsEnabled: state.analyticsEnabled,
+    browserSettingsMigrated: state.browserSettingsMigrated,
+    theme: state.theme,
+    chatSoundPreference: state.chatSoundPreference,
+    chatSoundId: state.chatSoundId,
+    terminal: state.terminal,
+    editor: state.editor,
+    defaultProvider: state.defaultProvider,
+    providerDefaults: state.providerDefaults,
+    warning: state.warning,
+    filePathDisplay: state.filePathDisplay,
+  }
+}
+
 function normalizeAppSettings(
   value: unknown,
   filePath = getSettingsFilePath(homedir())
@@ -50,80 +256,122 @@ function normalizeAppSettings(
     warnings.push("Settings file must contain a JSON object")
   }
 
-  const analyticsEnabled = typeof source?.analyticsEnabled === "boolean"
-    ? source.analyticsEnabled
-    : true
+  const analyticsEnabled = typeof source?.analyticsEnabled === "boolean" ? source.analyticsEnabled : true
   if (source?.analyticsEnabled !== undefined && typeof source.analyticsEnabled !== "boolean") {
     warnings.push("analyticsEnabled must be a boolean")
   }
 
-  const rawAnalyticsUserId = typeof source?.analyticsUserId === "string"
-    ? source.analyticsUserId.trim()
-    : ""
+  const rawAnalyticsUserId = typeof source?.analyticsUserId === "string" ? source.analyticsUserId.trim() : ""
   if (source?.analyticsUserId !== undefined && typeof source.analyticsUserId !== "string") {
     warnings.push("analyticsUserId must be a string")
   }
-
   const analyticsUserId = rawAnalyticsUserId || createAnalyticsUserId()
   if (!rawAnalyticsUserId && source?.analyticsUserId !== undefined) {
     warnings.push("analyticsUserId must be a non-empty string")
   }
 
-  const shouldWrite = !source
-    || source.analyticsEnabled !== analyticsEnabled
-    || rawAnalyticsUserId !== analyticsUserId
+  const editorPreset = normalizeEditorPreset(source?.editor?.preset)
+  const state: AppSettingsState = {
+    analyticsEnabled,
+    analyticsUserId,
+    browserSettingsMigrated: source?.browserSettingsMigrated === true,
+    theme: normalizeTheme(source?.theme),
+    chatSoundPreference: normalizeChatSoundPreference(source?.chatSoundPreference),
+    chatSoundId: normalizeChatSoundId(source?.chatSoundId),
+    terminal: {
+      scrollbackLines: clampNumber(source?.terminal?.scrollbackLines, DEFAULT_TERMINAL_SCROLLBACK, MIN_TERMINAL_SCROLLBACK, MAX_TERMINAL_SCROLLBACK),
+      minColumnWidth: clampNumber(source?.terminal?.minColumnWidth, DEFAULT_TERMINAL_MIN_COLUMN_WIDTH, MIN_TERMINAL_MIN_COLUMN_WIDTH, MAX_TERMINAL_MIN_COLUMN_WIDTH),
+    },
+    editor: {
+      preset: editorPreset,
+      commandTemplate: normalizeEditorCommandTemplate(source?.editor?.commandTemplate, editorPreset),
+    },
+    defaultProvider: normalizeDefaultProvider(source?.defaultProvider),
+    providerDefaults: normalizeProviderDefaults(source?.providerDefaults),
+    warning: null,
+    filePathDisplay: formatDisplayPath(filePath),
+  }
+
+  const shouldWrite = JSON.stringify(source ? toComparablePayload(source) : null) !== JSON.stringify(toFilePayload(state))
+  state.warning = warnings.length > 0
+    ? `Some settings were reset to defaults: ${warnings.join("; ")}`
+    : null
 
   return {
-    payload: {
-      analyticsEnabled,
-      analyticsUserId,
-    },
-    warning: warnings.length > 0
-      ? `Some settings were reset to defaults: ${warnings.join("; ")}`
-      : null,
+    payload: state,
+    warning: state.warning,
     shouldWrite,
   }
 }
 
-function toSnapshot(state: AppSettingsState): AppSettingsSnapshot {
+function toComparablePayload(source: AppSettingsFile) {
   return {
-    analyticsEnabled: state.analyticsEnabled,
-    warning: state.warning,
-    filePathDisplay: state.filePathDisplay,
+    analyticsEnabled: source.analyticsEnabled,
+    analyticsUserId: typeof source.analyticsUserId === "string" ? source.analyticsUserId.trim() : source.analyticsUserId,
+    browserSettingsMigrated: source.browserSettingsMigrated,
+    theme: source.theme,
+    chatSoundPreference: source.chatSoundPreference,
+    chatSoundId: source.chatSoundId,
+    terminal: source.terminal,
+    editor: source.editor,
+    defaultProvider: source.defaultProvider,
+    providerDefaults: source.providerDefaults,
   }
 }
 
+function applyPatch(state: AppSettingsState, patch: AppSettingsPatch): AppSettingsState {
+  return normalizeAppSettings({
+    ...toFilePayload(state),
+    ...patch,
+    terminal: {
+      ...state.terminal,
+      ...patch.terminal,
+    },
+    editor: {
+      ...state.editor,
+      ...patch.editor,
+    },
+    providerDefaults: {
+      claude: {
+        ...state.providerDefaults.claude,
+        ...patch.providerDefaults?.claude,
+        modelOptions: {
+          ...state.providerDefaults.claude.modelOptions,
+          ...patch.providerDefaults?.claude?.modelOptions,
+        },
+      },
+      codex: {
+        ...state.providerDefaults.codex,
+        ...patch.providerDefaults?.codex,
+        modelOptions: {
+          ...state.providerDefaults.codex.modelOptions,
+          ...patch.providerDefaults?.codex?.modelOptions,
+        },
+      },
+    },
+  }, state.filePathDisplay).payload
+}
+
 export async function readAppSettingsSnapshot(filePath = getSettingsFilePath(homedir())) {
   try {
     const text = await readFile(filePath, "utf8")
     if (!text.trim()) {
       const normalized = normalizeAppSettings(undefined, filePath)
       return {
-        analyticsEnabled: normalized.payload.analyticsEnabled,
+        ...toSnapshot(normalized.payload),
         warning: "Settings file was empty. Using defaults.",
-        filePathDisplay: formatDisplayPath(filePath),
       } satisfies AppSettingsSnapshot
     }
 
-    const normalized = normalizeAppSettings(JSON.parse(text), filePath)
-    return {
-      analyticsEnabled: normalized.payload.analyticsEnabled,
-      warning: normalized.warning,
-      filePathDisplay: formatDisplayPath(filePath),
-    } satisfies AppSettingsSnapshot
+    return toSnapshot(normalizeAppSettings(JSON.parse(text), filePath).payload)
   } catch (error) {
     if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
-      return {
-        analyticsEnabled: true,
-        warning: null,
-        filePathDisplay: formatDisplayPath(filePath),
-      } satisfies AppSettingsSnapshot
+      return toSnapshot(normalizeAppSettings(undefined, filePath).payload)
     }
     if (error instanceof SyntaxError) {
       return {
-        analyticsEnabled: true,
+        ...toSnapshot(normalizeAppSettings(undefined, filePath).payload),
         warning: "Settings file is invalid JSON. Using defaults.",
-        filePathDisplay: formatDisplayPath(filePath),
       } satisfies AppSettingsSnapshot
     }
     throw error
@@ -138,13 +386,7 @@ export class AppSettingsManager {
 
   constructor(filePath = getSettingsFilePath(homedir())) {
     this.filePath = filePath
-    const displayPath = formatDisplayPath(this.filePath)
-    this.state = {
-      analyticsEnabled: true,
-      analyticsUserId: createAnalyticsUserId(),
-      warning: null,
-      filePathDisplay: displayPath,
-    }
+    this.state = normalizeAppSettings(undefined, filePath).payload
   }
 
   async initialize() {
@@ -180,58 +422,47 @@ export class AppSettingsManager {
   }
 
   async write(value: { analyticsEnabled: boolean }) {
-    const payload = {
-      analyticsEnabled: value.analyticsEnabled,
-      analyticsUserId: this.state.analyticsUserId || createAnalyticsUserId(),
-    }
-    await mkdir(path.dirname(this.filePath), { recursive: true })
-    await writeFile(this.filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8")
-    const nextState: AppSettingsState = {
-      analyticsEnabled: payload.analyticsEnabled,
-      analyticsUserId: payload.analyticsUserId,
+    return this.writePatch({ analyticsEnabled: value.analyticsEnabled })
+  }
+
+  async writePatch(patch: AppSettingsPatch) {
+    const nextState = {
+      ...applyPatch(this.state, patch),
       warning: null,
       filePathDisplay: formatDisplayPath(this.filePath),
     }
+    await mkdir(path.dirname(this.filePath), { recursive: true })
+    await writeFile(this.filePath, `${JSON.stringify(toFilePayload(nextState), null, 2)}\n`, "utf8")
     this.setState(nextState)
     return toSnapshot(nextState)
   }
 
   private async readState(options?: { persistNormalized?: boolean }) {
     const file = Bun.file(this.filePath)
-    const displayPath = formatDisplayPath(this.filePath)
 
     try {
       const text = await file.text()
       const hasText = text.trim().length > 0
       const normalized = normalizeAppSettings(hasText ? JSON.parse(text) : undefined, this.filePath)
       if (options?.persistNormalized && (!hasText || normalized.shouldWrite)) {
-        await writeFile(this.filePath, `${JSON.stringify(normalized.payload, null, 2)}\n`, "utf8")
+        await writeFile(this.filePath, `${JSON.stringify(toFilePayload(normalized.payload), null, 2)}\n`, "utf8")
       }
       return {
-        analyticsEnabled: normalized.payload.analyticsEnabled,
-        analyticsUserId: normalized.payload.analyticsUserId,
-        warning: !hasText
-          ? "Settings file was empty. Using defaults."
-          : normalized.warning,
-        filePathDisplay: displayPath,
+        ...normalized.payload,
+        warning: !hasText ? "Settings file was empty. Using defaults." : normalized.warning,
       } satisfies AppSettingsState
     } catch (error) {
       if ((error as NodeJS.ErrnoException)?.code !== "ENOENT" && !(error instanceof SyntaxError)) {
         throw error
       }
 
-      const warning = error instanceof SyntaxError
-        ? "Settings file is invalid JSON. Using defaults."
-        : null
       const normalized = normalizeAppSettings(undefined, this.filePath)
       if (options?.persistNormalized) {
-        await writeFile(this.filePath, `${JSON.stringify(normalized.payload, null, 2)}\n`, "utf8")
+        await writeFile(this.filePath, `${JSON.stringify(toFilePayload(normalized.payload), null, 2)}\n`, "utf8")
       }
       return {
-        analyticsEnabled: normalized.payload.analyticsEnabled,
-        analyticsUserId: normalized.payload.analyticsUserId,
-        warning,
-        filePathDisplay: displayPath,
+        ...normalized.payload,
+        warning: error instanceof SyntaxError ? "Settings file is invalid JSON. Using defaults." : null,
       } satisfies AppSettingsState
     }
   }

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

@@ -96,6 +96,10 @@ describe("writeStandaloneTranscriptExport", () => {
       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)
@@ -153,6 +157,10 @@ describe("writeStandaloneTranscriptExport", () => {
       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")
@@ -170,4 +178,47 @@ describe("writeStandaloneTranscriptExport", () => {
       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)
+  })
 })