kanna-code 0.14.0 → 0.16.0

package/src/server/event-store.ts

@@ -1,4 +1,5 @@
-import { appendFile, mkdir } from "node:fs/promises"
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises"
+import { existsSync, readFileSync as readFileSyncImmediate } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { getDataDir, LOG_PREFIX } from "../shared/branding"
@@ -19,6 +20,13 @@ import { resolveLocalPath } from "./paths"
 
 const COMPACTION_THRESHOLD_BYTES = 2 * 1024 * 1024
 
+interface LegacyTranscriptStats {
+  hasLegacyData: boolean
+  sources: Array<"snapshot" | "messages_log">
+  chatCount: number
+  entryCount: number
+}
+
 export class EventStore {
   readonly dataDir: string
   readonly state: StoreState = createEmptyState()
@@ -29,6 +37,10 @@ export class EventStore {
   private readonly chatsLogPath: string
   private readonly messagesLogPath: string
   private readonly turnsLogPath: string
+  private readonly transcriptsDir: string
+  private legacyMessagesByChatId = new Map<string, TranscriptEntry[]>()
+  private snapshotHasLegacyMessages = false
+  private cachedTranscript: { chatId: string; entries: TranscriptEntry[] } | null = null
 
   constructor(dataDir = getDataDir(homedir())) {
     this.dataDir = dataDir
@@ -37,17 +49,19 @@ export class EventStore {
     this.chatsLogPath = path.join(this.dataDir, "chats.jsonl")
     this.messagesLogPath = path.join(this.dataDir, "messages.jsonl")
     this.turnsLogPath = path.join(this.dataDir, "turns.jsonl")
+    this.transcriptsDir = path.join(this.dataDir, "transcripts")
   }
 
   async initialize() {
     await mkdir(this.dataDir, { recursive: true })
+    await mkdir(this.transcriptsDir, { recursive: true })
     await this.ensureFile(this.projectsLogPath)
     await this.ensureFile(this.chatsLogPath)
     await this.ensureFile(this.messagesLogPath)
     await this.ensureFile(this.turnsLogPath)
     await this.loadSnapshot()
     await this.replayLogs()
-    if (await this.shouldCompact()) {
+    if (!(await this.hasLegacyTranscriptData()) && await this.shouldCompact()) {
       await this.compact()
     }
   }
@@ -63,6 +77,7 @@ export class EventStore {
     if (this.storageReset) return
     this.storageReset = true
     this.resetState()
+    this.clearLegacyTranscriptState()
     await Promise.all([
       Bun.write(this.snapshotPath, ""),
       Bun.write(this.projectsLogPath, ""),
@@ -92,8 +107,11 @@ export class EventStore {
       for (const chat of parsed.chats) {
         this.state.chatsById.set(chat.id, { ...chat })
       }
-      for (const messageSet of parsed.messages) {
-        this.state.messagesByChatId.set(messageSet.chatId, cloneTranscriptEntries(messageSet.entries))
+      if (parsed.messages?.length) {
+        this.snapshotHasLegacyMessages = true
+        for (const messageSet of parsed.messages) {
+          this.legacyMessagesByChatId.set(messageSet.chatId, cloneTranscriptEntries(messageSet.entries))
+        }
       }
     } catch (error) {
       console.warn(`${LOG_PREFIX} Failed to load snapshot, resetting local history:`, error)
@@ -105,7 +123,12 @@ export class EventStore {
     this.state.projectsById.clear()
     this.state.projectIdsByPath.clear()
     this.state.chatsById.clear()
-    this.state.messagesByChatId.clear()
+    this.cachedTranscript = null
+  }
+
+  private clearLegacyTranscriptState() {
+    this.legacyMessagesByChatId.clear()
+    this.snapshotHasLegacyMessages = false
   }
 
   private async replayLogs() {
@@ -224,16 +247,10 @@ export class EventStore {
         break
       }
       case "message_appended": {
-        const chat = this.state.chatsById.get(event.chatId)
-        if (chat) {
-          if (event.entry.kind === "user_prompt") {
-            chat.lastMessageAt = event.entry.createdAt
-          }
-          chat.updatedAt = Math.max(chat.updatedAt, event.entry.createdAt)
-        }
-        const existing = this.state.messagesByChatId.get(event.chatId) ?? []
+        this.applyMessageMetadata(event.chatId, event.entry)
+        const existing = this.legacyMessagesByChatId.get(event.chatId) ?? []
         existing.push({ ...event.entry })
-        this.state.messagesByChatId.set(event.chatId, existing)
+        this.legacyMessagesByChatId.set(event.chatId, existing)
         break
       }
       case "turn_started": {
@@ -273,6 +290,15 @@ export class EventStore {
     }
   }
 
+  private applyMessageMetadata(chatId: string, entry: TranscriptEntry) {
+    const chat = this.state.chatsById.get(chatId)
+    if (!chat) return
+    if (entry.kind === "user_prompt") {
+      chat.lastMessageAt = entry.createdAt
+    }
+    chat.updatedAt = Math.max(chat.updatedAt, entry.createdAt)
+  }
+
   private append<TEvent extends StoreEvent>(filePath: string, event: TEvent) {
     const payload = `${JSON.stringify(event)}\n`
     this.writeChain = this.writeChain.then(async () => {
@@ -282,6 +308,28 @@ export class EventStore {
     return this.writeChain
   }
 
+  private transcriptPath(chatId: string) {
+    return path.join(this.transcriptsDir, `${chatId}.jsonl`)
+  }
+
+  private loadTranscriptFromDisk(chatId: string) {
+    const transcriptPath = this.transcriptPath(chatId)
+    if (!existsSync(transcriptPath)) {
+      return []
+    }
+
+    const text = readFileSyncImmediate(transcriptPath, "utf8")
+    if (!text.trim()) return []
+
+    const entries: TranscriptEntry[] = []
+    for (const rawLine of text.split("\n")) {
+      const line = rawLine.trim()
+      if (!line) continue
+      entries.push(JSON.parse(line) as TranscriptEntry)
+    }
+    return entries
+  }
+
   async openProject(localPath: string, title?: string) {
     const normalized = resolveLocalPath(localPath)
     const existingId = this.state.projectIdsByPath.get(normalized)
@@ -392,14 +440,17 @@ export class EventStore {
 
   async appendMessage(chatId: string, entry: TranscriptEntry) {
     this.requireChat(chatId)
-    const event: MessageEvent = {
-      v: STORE_VERSION,
-      type: "message_appended",
-      timestamp: Date.now(),
-      chatId,
-      entry,
-    }
-    await this.append(this.messagesLogPath, event)
+    const payload = `${JSON.stringify(entry)}\n`
+    const transcriptPath = this.transcriptPath(chatId)
+    this.writeChain = this.writeChain.then(async () => {
+      await mkdir(this.transcriptsDir, { recursive: true })
+      await appendFile(transcriptPath, payload, "utf8")
+      this.applyMessageMetadata(chatId, entry)
+      if (this.cachedTranscript?.chatId === chatId) {
+        this.cachedTranscript.entries.push({ ...entry })
+      }
+    })
+    return this.writeChain
   }
 
   async recordTurnStarted(chatId: string) {
@@ -481,7 +532,19 @@ export class EventStore {
   }
 
   getMessages(chatId: string) {
-    return cloneTranscriptEntries(this.state.messagesByChatId.get(chatId) ?? [])
+    if (this.cachedTranscript?.chatId === chatId) {
+      return cloneTranscriptEntries(this.cachedTranscript.entries)
+    }
+
+    const legacyEntries = this.legacyMessagesByChatId.get(chatId)
+    if (legacyEntries) {
+      this.cachedTranscript = { chatId, entries: cloneTranscriptEntries(legacyEntries) }
+      return cloneTranscriptEntries(this.cachedTranscript.entries)
+    }
+
+    const entries = this.loadTranscriptFromDisk(chatId)
+    this.cachedTranscript = { chatId, entries }
+    return cloneTranscriptEntries(entries)
   }
 
   listProjects() {
@@ -498,7 +561,34 @@ export class EventStore {
     return this.listChatsByProject(projectId).length
   }
 
-  async compact() {
+  async getLegacyTranscriptStats(): Promise<LegacyTranscriptStats> {
+    const messagesLogSize = await Bun.file(this.messagesLogPath).size
+    const sources: LegacyTranscriptStats["sources"] = []
+    if (this.snapshotHasLegacyMessages) {
+      sources.push("snapshot")
+    }
+    if (messagesLogSize > 0) {
+      sources.push("messages_log")
+    }
+
+    let entryCount = 0
+    for (const entries of this.legacyMessagesByChatId.values()) {
+      entryCount += entries.length
+    }
+
+    return {
+      hasLegacyData: sources.length > 0 || this.legacyMessagesByChatId.size > 0,
+      sources,
+      chatCount: this.legacyMessagesByChatId.size,
+      entryCount,
+    }
+  }
+
+  async hasLegacyTranscriptData() {
+    return (await this.getLegacyTranscriptStats()).hasLegacyData
+  }
+
+  private createSnapshot(includeLegacyMessages: boolean): SnapshotFile {
     const snapshot: SnapshotFile = {
       v: STORE_VERSION,
       generatedAt: Date.now(),
@@ -506,12 +596,20 @@ export class EventStore {
       chats: [...this.state.chatsById.values()]
         .filter((chat) => !chat.deletedAt)
         .map((chat) => ({ ...chat })),
-      messages: [...this.state.messagesByChatId.entries()].map(([chatId, entries]) => ({
+    }
+
+    if (includeLegacyMessages) {
+      snapshot.messages = [...this.legacyMessagesByChatId.entries()].map(([chatId, entries]) => ({
         chatId,
         entries: cloneTranscriptEntries(entries),
-      })),
+      }))
     }
 
+    return snapshot
+  }
+
+  async compact() {
+    const snapshot = this.createSnapshot(false)
     await Bun.write(this.snapshotPath, JSON.stringify(snapshot, null, 2))
     await Promise.all([
       Bun.write(this.projectsLogPath, ""),
@@ -521,6 +619,52 @@ export class EventStore {
     ])
   }
 
+  private async compactLegacyMessagesIntoSnapshot() {
+    const snapshot = this.createSnapshot(true)
+    await Bun.write(this.snapshotPath, JSON.stringify(snapshot, null, 2))
+    await Promise.all([
+      Bun.write(this.projectsLogPath, ""),
+      Bun.write(this.chatsLogPath, ""),
+      Bun.write(this.messagesLogPath, ""),
+      Bun.write(this.turnsLogPath, ""),
+    ])
+  }
+
+  async migrateLegacyTranscripts(onProgress?: (message: string) => void) {
+    const stats = await this.getLegacyTranscriptStats()
+    if (!stats.hasLegacyData) return false
+
+    const sourceSummary = stats.sources.map((source) => source === "messages_log" ? "messages.jsonl" : "snapshot.json").join(", ")
+    onProgress?.(`${LOG_PREFIX} transcript migration detected: ${stats.chatCount} chats, ${stats.entryCount} entries from ${sourceSummary}`)
+    onProgress?.(`${LOG_PREFIX} transcript migration: compacting legacy transcript state into snapshot`)
+    await this.compactLegacyMessagesIntoSnapshot()
+
+    const snapshot = JSON.parse(await readFile(this.snapshotPath, "utf8")) as SnapshotFile
+    const messageSets = snapshot.messages ?? []
+    onProgress?.(`${LOG_PREFIX} transcript migration: writing ${messageSets.length} per-chat transcript files`)
+
+    await mkdir(this.transcriptsDir, { recursive: true })
+    const logEveryChat = messageSets.length <= 10
+    for (let index = 0; index < messageSets.length; index += 1) {
+      const { chatId, entries } = messageSets[index]
+      const transcriptPath = this.transcriptPath(chatId)
+      const tempPath = `${transcriptPath}.tmp`
+      const payload = entries.map((entry) => JSON.stringify(entry)).join("\n")
+      await writeFile(tempPath, payload ? `${payload}\n` : "", "utf8")
+      await rename(tempPath, transcriptPath)
+      if (logEveryChat || (index + 1) % 25 === 0 || index === messageSets.length - 1) {
+        onProgress?.(`${LOG_PREFIX} transcript migration: ${index + 1}/${messageSets.length} chats`)
+      }
+    }
+
+    delete snapshot.messages
+    await Bun.write(this.snapshotPath, JSON.stringify(snapshot, null, 2))
+    this.clearLegacyTranscriptState()
+    this.cachedTranscript = null
+    onProgress?.(`${LOG_PREFIX} transcript migration complete`)
+    return true
+  }
+
   private async shouldCompact() {
     const sizes = await Promise.all([
       Bun.file(this.projectsLogPath).size,

package/src/server/events.ts

@@ -22,7 +22,6 @@ export interface StoreState {
   projectsById: Map<string, ProjectRecord>
   projectIdsByPath: Map<string, string>
   chatsById: Map<string, ChatRecord>
-  messagesByChatId: Map<string, TranscriptEntry[]>
 }
 
 export interface SnapshotFile {
@@ -30,7 +29,7 @@ export interface SnapshotFile {
   generatedAt: number
   projects: ProjectRecord[]
   chats: ChatRecord[]
-  messages: Array<{ chatId: string; entries: TranscriptEntry[] }>
+  messages?: Array<{ chatId: string; entries: TranscriptEntry[] }>
 }
 
 export type ProjectEvent = {
@@ -133,7 +132,6 @@ export function createEmptyState(): StoreState {
     projectsById: new Map(),
     projectIdsByPath: new Map(),
     chatsById: new Map(),
-    messagesByChatId: new Map(),
   }
 }
 

package/src/server/generate-title.ts

@@ -1,7 +1,5 @@
 import { QuickResponseAdapter } from "./quick-response"
 
-const LOG_PREFIX = "[kanna:title]"
-
 const TITLE_SCHEMA = {
   type: "object",
   properties: {
@@ -23,11 +21,6 @@ export async function generateTitleForChat(
   cwd: string,
   adapter = new QuickResponseAdapter()
 ): Promise<string | null> {
-  console.log(`${LOG_PREFIX} generating title`, {
-    cwd,
-    messagePreview: messageContent.replace(/\s+/g, " ").trim().slice(0, 120),
-  })
-
   const result = await adapter.generateStructured<string>({
     cwd,
     task: "conversation title generation",
@@ -39,11 +32,5 @@ export async function generateTitleForChat(
     },
   })
 
-  if (result) {
-    console.log(`${LOG_PREFIX} generated title`, { title: result })
-  } else {
-    console.warn(`${LOG_PREFIX} no title generated`)
-  }
-
   return result
 }

package/src/server/provider-catalog.test.ts

@@ -4,11 +4,34 @@ import {
   normalizeClaudeModelOptions,
   normalizeCodexModelOptions,
 } from "./provider-catalog"
+import { resolveClaudeApiModelId } from "../shared/types"
 
 describe("provider catalog normalization", () => {
   test("maps legacy Claude effort into shared model options", () => {
-    expect(normalizeClaudeModelOptions(undefined, "max")).toEqual({
+    expect(normalizeClaudeModelOptions("opus", undefined, "max")).toEqual({
       reasoningEffort: "max",
+      contextWindow: "200k",
+    })
+  })
+
+  test("normalizes Claude context window only for supported models", () => {
+    expect(normalizeClaudeModelOptions("sonnet", {
+      claude: {
+        reasoningEffort: "medium",
+        contextWindow: "1m",
+      },
+    })).toEqual({
+      reasoningEffort: "medium",
+      contextWindow: "1m",
+    })
+
+    expect(normalizeClaudeModelOptions("haiku", {
+      claude: {
+        reasoningEffort: "medium",
+        contextWindow: "1m",
+      },
+    })).toEqual({
+      reasoningEffort: "medium",
     })
   })
 
@@ -31,4 +54,9 @@ describe("provider catalog normalization", () => {
     })
     expect(codexServiceTierFromModelOptions(normalized)).toBe("fast")
   })
+
+  test("resolves Claude API model ids for 1m context window", () => {
+    expect(resolveClaudeApiModelId("opus", "1m")).toBe("opus[1m]")
+    expect(resolveClaudeApiModelId("sonnet", "200k")).toBe("sonnet")
+  })
 })

package/src/server/provider-catalog.ts

@@ -2,6 +2,7 @@ import type {
   AgentProvider,
   ClaudeModelOptions,
   CodexModelOptions,
+  ClaudeContextWindow,
   ModelOptions,
   ProviderCatalogEntry,
   ProviderModelOption,
@@ -11,6 +12,7 @@ import {
   DEFAULT_CLAUDE_MODEL_OPTIONS,
   DEFAULT_CODEX_MODEL_OPTIONS,
   PROVIDERS,
+  normalizeClaudeContextWindow,
   isClaudeReasoningEffort,
   isCodexReasoningEffort,
 } from "../shared/types"
@@ -47,7 +49,11 @@ export function normalizeServerModel(provider: AgentProvider, model?: string): s
   return catalog.defaultModel
 }
 
-export function normalizeClaudeModelOptions(modelOptions?: ModelOptions, legacyEffort?: string): ClaudeModelOptions {
+export function normalizeClaudeModelOptions(
+  model: string,
+  modelOptions?: ModelOptions,
+  legacyEffort?: string
+): ClaudeModelOptions {
   const reasoningEffort = modelOptions?.claude?.reasoningEffort
   return {
     reasoningEffort: isClaudeReasoningEffort(reasoningEffort)
@@ -55,6 +61,7 @@ export function normalizeClaudeModelOptions(modelOptions?: ModelOptions, legacyE
       : isClaudeReasoningEffort(legacyEffort)
         ? legacyEffort
         : DEFAULT_CLAUDE_MODEL_OPTIONS.reasoningEffort,
+    contextWindow: normalizeClaudeContextWindow(model, modelOptions?.claude?.contextWindow as ClaudeContextWindow | undefined),
   }
 }
 

package/src/server/quick-response.ts

@@ -1,7 +1,6 @@
 import { query } from "@anthropic-ai/claude-agent-sdk"
 import { CodexAppServerManager } from "./codex-app-server"
 
-const LOG_PREFIX = "[kanna:title]"
 const CLAUDE_STRUCTURED_TIMEOUT_MS = 5_000
 
 type JsonSchema = {
@@ -82,7 +81,6 @@ async function runClaudeStructured(args: Omit<StructuredQuickResponseArgs<unknow
 
     return result
   } catch (error) {
-    console.warn(`${LOG_PREFIX} claude structured query failed before fallback:`, error)
     return null
   } finally {
     try {
@@ -116,7 +114,6 @@ export class QuickResponseAdapter {
     this.runCodexStructured = args.runCodexStructured ?? ((structuredArgs) =>
       runCodexStructured(this.codexManager, structuredArgs))
   }
-
   async generateStructured<T>(args: StructuredQuickResponseArgs<T>): Promise<T | null> {
     const request = {
       cwd: args.cwd,
@@ -125,11 +122,9 @@ export class QuickResponseAdapter {
       schema: args.schema,
     }
 
-    console.log(`${LOG_PREFIX} starting ${args.task} via claude`, { cwd: args.cwd })
     const claudeResult = await this.tryProvider("claude", args.task, args.parse, () => this.runClaudeStructured(request))
     if (claudeResult !== null) return claudeResult
 
-    console.warn(`${LOG_PREFIX} claude returned no usable result for ${args.task}, falling back to codex`)
     return await this.tryProvider("codex", args.task, args.parse, () => this.runCodexStructured(request))
   }
 
@@ -142,20 +137,16 @@ export class QuickResponseAdapter {
     try {
       const result = await run()
       if (result === null) {
-        console.warn(`${LOG_PREFIX} ${provider} returned no structured output for ${task}`)
         return null
       }
   
       const parsed = parse(result)
       if (parsed === null) {
-        console.warn(`${LOG_PREFIX} ${provider} returned unparseable structured output for ${task}`, { result })
         return null
       }
   
-      console.log(`${LOG_PREFIX} ${provider} produced structured output for ${task}`)
       return parsed
     } catch (error) {
-      console.warn(`${LOG_PREFIX} ${provider} failed during ${task}:`, error)
       return null
     }
   }

package/src/server/read-models.test.ts

@@ -51,7 +51,7 @@ describe("read models", () => {
       lastTurnOutcome: null,
     })
 
-    const chat = deriveChatSnapshot(state, new Map(), "chat-1")
+    const chat = deriveChatSnapshot(state, new Map(), "chat-1", () => [])
     expect(chat?.runtime.provider).toBe("claude")
     expect(chat?.availableProviders.length).toBeGreaterThan(1)
     expect(chat?.availableProviders.find((provider) => provider.id === "codex")?.models.map((model) => model.id)).toEqual([

package/src/server/read-models.ts

@@ -8,7 +8,6 @@ import type {
   SidebarProjectGroup,
 } from "../shared/types"
 import type { ChatRecord, StoreState } from "./events"
-import { cloneTranscriptEntries } from "./events"
 import { resolveLocalPath } from "./paths"
 import { SERVER_PROVIDERS } from "./provider-catalog"
 
@@ -98,7 +97,8 @@ export function deriveLocalProjectsSnapshot(
 export function deriveChatSnapshot(
   state: StoreState,
   activeStatuses: Map<string, KannaStatus>,
-  chatId: string
+  chatId: string,
+  getMessages: (chatId: string) => ChatSnapshot["messages"]
 ): ChatSnapshot | null {
   const chat = state.chatsById.get(chatId)
   if (!chat || chat.deletedAt) return null
@@ -118,7 +118,7 @@ export function deriveChatSnapshot(
 
   return {
     runtime,
-    messages: cloneTranscriptEntries(state.messagesByChatId.get(chat.id) ?? []),
+    messages: getMessages(chat.id),
     availableProviders: [...SERVER_PROVIDERS],
   }
 }

package/src/server/server.ts

@@ -12,7 +12,9 @@ import { createWsRouter, type ClientState } from "./ws-router"
 
 export interface StartKannaServerOptions {
   port?: number
+  host?: string
   strictPort?: boolean
+  onMigrationProgress?: (message: string) => void
   update?: {
     version: string
     fetchLatestVersion: (packageName: string) => Promise<string>
@@ -22,10 +24,12 @@ export interface StartKannaServerOptions {
 
 export async function startKannaServer(options: StartKannaServerOptions = {}) {
   const port = options.port ?? 3210
+  const hostname = options.host ?? "127.0.0.1"
   const strictPort = options.strictPort ?? false
   const store = new EventStore()
   const machineDisplayName = getMachineDisplayName()
   await store.initialize()
+  await store.migrateLegacyTranscripts(options.onMigrationProgress)
   let discoveredProjects: DiscoveredProject[] = []
 
   async function refreshDiscovery() {
@@ -74,6 +78,7 @@ export async function startKannaServer(options: StartKannaServerOptions = {}) {
     try {
       server = Bun.serve<ClientState>({
         port: actualPort,
+        hostname,
         fetch(req, serverInstance) {
           const url = new URL(req.url)
 

package/src/server/ws-router.ts

@@ -121,7 +121,7 @@ export function createWsRouter({
       id,
       snapshot: {
         type: "chat",
-        data: deriveChatSnapshot(store.state, agent.getActiveStatuses(), topic.chatId),
+        data: deriveChatSnapshot(store.state, agent.getActiveStatuses(), topic.chatId, (chatId) => store.getMessages(chatId)),
       },
     }
   }

package/src/shared/dev-ports.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test"
+import {
+  DEFAULT_DEV_CLIENT_PORT,
+  getDefaultDevServerPort,
+  resolveDevPorts,
+  stripPortArg,
+} from "./dev-ports"
+
+describe("getDefaultDevServerPort", () => {
+  test("derives the default backend port from the client port", () => {
+    expect(getDefaultDevServerPort()).toBe(DEFAULT_DEV_CLIENT_PORT + 1)
+    expect(getDefaultDevServerPort(4000)).toBe(4001)
+  })
+})
+
+describe("resolveDevPorts", () => {
+  test("uses default dev ports when no port override is provided", () => {
+    expect(resolveDevPorts([])).toEqual({
+      clientPort: DEFAULT_DEV_CLIENT_PORT,
+      serverPort: DEFAULT_DEV_CLIENT_PORT + 1,
+    })
+  })
+
+  test("treats --port as the client port and derives the backend port", () => {
+    expect(resolveDevPorts(["--remote", "--port", "4000"])).toEqual({
+      clientPort: 4000,
+      serverPort: 4001,
+    })
+  })
+
+  test("uses the last provided --port value", () => {
+    expect(resolveDevPorts(["--port", "4000", "--port", "4100"])).toEqual({
+      clientPort: 4100,
+      serverPort: 4101,
+    })
+  })
+
+  test("throws when --port is missing a value", () => {
+    expect(() => resolveDevPorts(["--port"])).toThrow("Missing value for --port")
+    expect(() => resolveDevPorts(["--port", "--remote"])).toThrow("Missing value for --port")
+  })
+})
+
+describe("stripPortArg", () => {
+  test("removes --port and its value while preserving other args", () => {
+    expect(stripPortArg(["--remote", "--port", "4000", "--host", "dev-box"])).toEqual([
+      "--remote",
+      "--host",
+      "dev-box",
+    ])
+  })
+})

package/src/shared/dev-ports.ts

@@ -0,0 +1,43 @@
+export const DEFAULT_DEV_CLIENT_PORT = 5174
+
+export function getDefaultDevServerPort(clientPort = DEFAULT_DEV_CLIENT_PORT) {
+  return clientPort + 1
+}
+
+export function resolveDevPorts(args: string[]) {
+  let clientPort = DEFAULT_DEV_CLIENT_PORT
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg !== "--port") continue
+
+    const next = args[index + 1]
+    if (!next || next.startsWith("-")) {
+      throw new Error("Missing value for --port")
+    }
+
+    clientPort = Number(next)
+    index += 1
+  }
+
+  return {
+    clientPort,
+    serverPort: getDefaultDevServerPort(clientPort),
+  }
+}
+
+export function stripPortArg(args: string[]) {
+  const stripped: string[] = []
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === "--port") {
+      index += 1
+      continue
+    }
+
+    stripped.push(arg)
+  }
+
+  return stripped
+}

package/src/shared/ports.ts

@@ -1,3 +1,2 @@
 export const PROD_SERVER_PORT = 3210
-export const DEV_SERVER_PORT = 3211
 export const DEV_CLIENT_PORT = 5174