@doriandev/devcc 0.1.2 → 0.3.0

package/src/devcc/init/prompt.ts

@@ -0,0 +1,179 @@
+import { basename } from "node:path"
+import { readSnippet, renderStarterConfig, type ProjectFacts } from "./detect.js"
+
+/**
+ * The prompt that lets a coding agent set up devcc for a project.
+ *
+ * It carries what devcc already detected (so the agent verifies rather than
+ * rediscovers), a draft to start from, the config reference, and firm rules:
+ * never invent commands, never guess hosts, keep verify non-interactive.
+ *
+ * Two delivery modes:
+ * - `write`: an interactive agent edits `.devcc.ts` itself and checks its work
+ *   with `devcc config check` (used by `devcc init --agent`).
+ * - `print`: a headless agent prints the file between markers; devcc validates
+ *   it and asks before writing (used from the dashboard, where the agent has no
+ *   permission to edit files).
+ */
+
+export type SetupPromptMode = "write" | "print"
+
+export const CONFIG_BEGIN_MARKER = "----- BEGIN .devcc.ts -----"
+export const CONFIG_END_MARKER = "----- END .devcc.ts -----"
+
+const REFERENCE = `
+## .devcc.ts reference (all fields optional)
+
+export default {
+  name?: string,                       // header label
+  processes?: [{                       // long-running things devcc starts/stops
+    id, name?, command, args?: string[], cwd?, env?: Record<string, string>,
+    kind?: "service" | "task", autoStart?: boolean, url?: string, port?: number,
+    dependsOn?: string[],              // ids that must be ready first
+    readiness?: { port?: number, host?: string, logPattern?: string, timeoutMs?: number },
+    restartOnCrash?: boolean,
+  }],
+  commands?: [{                        // palette actions
+    id, title, category?, command, args?, cwd?, keywords?: string[],
+    confirm?: true | { title, message }, // REQUIRED for anything destructive
+  }],
+  verify?: (string | { id, name?, command, args?, cwd? })[],
+                                       // strings = command ids, then package.json script names
+  services?: [                         // extra things to watch
+    { id, name?, port, host?, healthPath? } |
+    { id, name?, type: "ollama", baseUrl: "http://host:11434" },
+  ],
+  agents?: { claude?: { command?, args? }, codex?: { command?, args? } },
+  editor?: { command: "code" | "zed" | "cursor" | "webstorm" } | { application: "WebStorm" },
+  terminal?: { application: "iTerm" } | { command, args?, execArgs? },
+  worktrees?: { directory?: string },  // relative to the main worktree, default ".."
+  remoteMachines?: [{ id, name?, host, transport: "ssh", port?, user?, services?: string[] }],
+  refresh?: { system?, services?, git?, clock? },
+}
+
+Everything is spawned as command + args with no shell: never put pipes, &&, env assignments or
+quotes inside a single string. \`command: "pnpm", args: ["run", "dev"]\` is right;
+\`command: "pnpm run dev"\` is wrong.`
+
+function factsSection(facts: ProjectFacts): string {
+  const lines = [
+    `- root: ${facts.rootDir}`,
+    `- name: ${facts.name}`,
+    `- git repository: ${facts.hasGit ? "yes" : "no"}`,
+    `- languages: ${facts.languages.join(", ") || "none detected"}`,
+    `- package manager: ${facts.packageManager ? `${facts.packageManager.manager} (from ${facts.packageManager.source})` : "none (no package.json)"}`,
+    `- monorepo: ${facts.monorepo ?? "no"}`,
+    `- frameworks (by dependency): ${facts.frameworks.map((framework) => `${framework.name} (default port ${framework.port})`).join(", ") || "none recognised"}`,
+    `- notable files: ${facts.files.join(", ") || "none"}`,
+    `- existing devcc config: ${facts.configPath ? basename(facts.configPath) : "none"}`,
+  ]
+  if (facts.scripts.length > 0) {
+    lines.push(`- package.json scripts:`)
+    for (const script of facts.scripts) lines.push(`  - ${script.name}: ${script.command}`)
+  }
+  if (facts.skippedScripts.length > 0) {
+    lines.push(
+      `- left out of verify: ${facts.skippedScripts.map((script) => `${script.name} (${script.reason})`).join(", ")}`,
+    )
+  }
+  return lines.join("\n")
+}
+
+export function buildSetupPrompt(facts: ProjectFacts, mode: SetupPromptMode): string {
+  const existing = facts.configPath ? readSnippet(facts.configPath, 6_000) : null
+  const draft = renderStarterConfig(facts)
+
+  const output =
+    mode === "write"
+      ? `## Deliver
+
+1. ${facts.configPath ? `Update \`${basename(facts.configPath)}\` in place, keeping anything the user wrote that is still correct.` : "Create `.devcc.ts` in the project root."}
+2. Run \`devcc config check\` and fix every issue it reports. Do not stop until it exits 0.
+3. If you added \`verify\`, run \`devcc verify\`. A step that fails because the project itself is broken
+   stays in the list - report it; do not delete checks to make the gate pass.
+4. Finish with a short summary: what you configured, what you deliberately left out, and why.`
+      : `## Deliver
+
+You cannot edit files in this session. Print the complete file, and nothing else between the markers,
+exactly like this:
+
+${CONFIG_BEGIN_MARKER}
+export default {
+  ...
+}
+${CONFIG_END_MARKER}
+
+devcc validates it and asks the user before writing it${facts.configPath ? ` over \`${basename(facts.configPath)}\`` : ""}. After the markers, add
+a short summary: what you configured, what you left out, and why.`
+
+  return `Set up devcc for this project: produce a solid .devcc.ts.
+
+devcc (@doriandev/devcc) is a keyboard-driven terminal dashboard for local development. Its config
+tells it which dev processes it may start, which checks \`devcc verify\` runs as the quality gate, and
+which commands appear in its palette. You are configuring it for the repository in your working
+directory.
+
+## What devcc already detected
+
+${factsSection(facts)}
+
+## Draft from \`devcc init\`
+
+Start from this, but verify every line against the repository - it only knows script names.
+
+\`\`\`ts
+${draft.trimEnd()}
+\`\`\`
+${existing ? `\n## Current config (${basename(facts.configPath ?? "")})\n\n\`\`\`ts\n${existing.trimEnd()}\n\`\`\`\n` : ""}
+## Investigate before writing
+
+- Read package.json (every workspace package in a monorepo), the README, CONTRIBUTING, AGENTS.md or
+  CLAUDE.md, CI workflows (.github/workflows), Makefile/justfile, docker compose files, framework
+  configs (next.config.*, vite.config.*, etc.) and .env.example.
+- Find the real dev servers and their ports. Ports come from scripts, framework config or
+  .env.example - not from defaults when the project overrides them.
+- CI shows what the team treats as the quality gate; mirror it in \`verify\` where it can run locally.
+
+## Rules
+
+- Only use commands that exist in this repository or are the standard CLI of a toolchain it uses. Never
+  invent scripts, binaries or ports.
+- \`processes\`: long-running dev servers, watchers and local infra the developer starts by hand. Use
+  \`readiness\` with the real port (or a \`logPattern\` from the server's actual output) and \`dependsOn\`
+  when one service needs another. In a monorepo, one process per app with \`cwd\`. Do not set
+  \`autoStart\` unless the README says the project is always run that way.
+- \`verify\`: fast to slow (format check, lint, typecheck, tests, build). Every step must be
+  non-interactive, exit on its own, and not modify files (no --watch, --fix or --write). Prefer
+  package.json script names over inline steps.
+- \`commands\`: useful project tasks that are not already scripts devcc shows (migrations, seeding,
+  codegen, docker compose profiles). Anything that deletes, resets, migrates or deploys needs
+  \`confirm: true\`.
+- Never add secrets, tokens, credentials or values from .env files. Never add \`remoteMachines\`,
+  hostnames or IP addresses unless the repository documents them for local development.
+- Leave out \`editor\`, \`terminal\` and \`agents\` unless the repository states a preference; they are
+  personal. Leave out anything you are unsure of rather than guessing - a small correct config beats a
+  large wrong one.
+- Use a plain \`export default { ... }\` object. Import \`defineConfig\` from "@doriandev/devcc" only if that
+  package is already a dependency of this project.
+${REFERENCE}
+
+${output}
+`
+}
+
+/**
+ * Pull the config out of a headless agent's output: the last block between the
+ * markers, with a surrounding code fence removed. Null when there is none.
+ */
+export function extractConfigFromOutput(output: string): string | null {
+  const end = output.lastIndexOf(CONFIG_END_MARKER)
+  if (end === -1) return null
+  const begin = output.lastIndexOf(CONFIG_BEGIN_MARKER, end)
+  if (begin === -1) return null
+  const body = output
+    .slice(begin + CONFIG_BEGIN_MARKER.length, end)
+    .replace(/^\s*```[a-z]*\s*\n/u, "")
+    .replace(/\n\s*```\s*$/u, "")
+    .trim()
+  return body === "" ? null : `${body}\n`
+}

package/src/devcc/platform/launch.ts

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process"
+import type { EditorConfig, RemoteMachineConfig, TerminalConfig } from "../core/config.js"
+import { sshDestination } from "../services/remote.js"
+import { DevccError } from "../utils/errors.js"
+
+/**
+ * Opening things outside devcc: editors, terminals, SSH sessions.
+ *
+ * Every launch is an executable plus an argv array, detached from devcc so
+ * closing the dashboard never closes your editor. macOS conventions (`open`,
+ * `open -a`) are used only when running on macOS; elsewhere a configured
+ * command is required.
+ */
+
+export interface LaunchCommand {
+  command: string
+  args: string[]
+}
+
+export type Platform = NodeJS.Platform
+
+/** Replace `{path}` inside individual arguments. Never joins arguments into a string. */
+export function substitutePath(args: readonly string[], path: string): string[] {
+  return args.map((arg) => arg.split("{path}").join(path))
+}
+
+export function editorCommand(
+  path: string,
+  editor: EditorConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (editor?.command) return { command: editor.command, args: [...(editor.args ?? []), path] }
+  if (editor?.application) {
+    if (platform !== "darwin") {
+      throw new DevccError({
+        scope: "command",
+        message: `editor.application only works on macOS; set editor.command`,
+      })
+    }
+    return { command: "open", args: ["-a", editor.application, path] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No editor configured",
+    detail: 'Set editor: { command: "code" } (or zed, cursor, webstorm) in .devcc.ts',
+  })
+}
+
+export function terminalCommand(
+  path: string,
+  terminal: TerminalConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (terminal?.command) {
+    const args = terminal.args ?? ["{path}"]
+    return { command: terminal.command, args: substitutePath(args, path) }
+  }
+  if (platform === "darwin") {
+    return { command: "open", args: ["-a", terminal?.application ?? "Terminal", path] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No terminal configured",
+    detail: 'Set terminal: { command: "wezterm", args: ["start", "--cwd", "{path}"] } in .devcc.ts',
+  })
+}
+
+/**
+ * An interactive SSH session needs a terminal. On macOS `open ssh://host`
+ * hands the URL to the default terminal, which runs `ssh` with the user's own
+ * config for that alias. Elsewhere the configured terminal runs `ssh`.
+ */
+export function sshCommand(
+  machine: Pick<RemoteMachineConfig, "host" | "user" | "port">,
+  terminal: TerminalConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (terminal?.command && terminal.execArgs) {
+    const port = machine.port ? ["-p", String(machine.port)] : []
+    return {
+      command: terminal.command,
+      args: [...terminal.execArgs, "ssh", ...port, sshDestination(machine)],
+    }
+  }
+  if (platform === "darwin") {
+    const user = machine.user ? `${encodeURIComponent(machine.user)}@` : ""
+    const port = machine.port ? `:${machine.port}` : ""
+    return { command: "open", args: [`ssh://${user}${machine.host}${port}`] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No terminal configured for SSH",
+    detail: 'Set terminal: { command: "wezterm", execArgs: ["start", "--"] } in .devcc.ts',
+  })
+}
+
+/**
+ * Start a GUI or launcher process detached from devcc. Resolves once it has
+ * spawned (not when it exits); rejects with a readable error if it cannot start.
+ */
+export function launchDetached(launch: LaunchCommand, cwd?: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let child
+    try {
+      child = spawn(launch.command, launch.args, { cwd, detached: true, stdio: "ignore", windowsHide: true })
+    } catch (error) {
+      reject(toLaunchError(launch, error))
+      return
+    }
+    child.once("error", (error) => reject(toLaunchError(launch, error)))
+    child.once("spawn", () => {
+      child.unref()
+      resolve()
+    })
+  })
+}
+
+function toLaunchError(launch: LaunchCommand, error: unknown): DevccError {
+  const code = (error as NodeJS.ErrnoException).code
+  return new DevccError({
+    scope: "command",
+    message: code === "ENOENT" ? `\`${launch.command}\` was not found` : `Could not run ${launch.command}`,
+    cause: error,
+  })
+}

package/src/devcc/services/ServiceManager.ts

@@ -35,6 +35,8 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
   private readonly adapters = new Map<string, ServiceAdapter>()
   private readonly detected = new Set<string>()
   private readonly snapshots = new Map<string, ServiceSnapshot>()
+  /** When each adapter was last asked for its status. */
+  private readonly checkedAt = new Map<string, number>()
   private timer: NodeJS.Timeout | null = null
   private refreshing = false
   private readonly intervalMs: number
@@ -92,7 +94,7 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
 
   start(): void {
     if (this.timer) return
-    this.timer = setInterval(() => void this.refresh(), this.intervalMs)
+    this.timer = setInterval(() => void this.refresh({ polled: true }), this.intervalMs)
     this.timer.unref?.()
   }
 
@@ -102,14 +104,24 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
     this.timer = null
   }
 
-  /** Refresh all detected adapters concurrently. Overlapping calls are skipped. */
-  async refresh(): Promise<ServiceSnapshot[]> {
+  /**
+   * Refresh all detected adapters concurrently. Overlapping calls are skipped.
+   * A `polled` refresh (the timer) skips adapters whose `refreshIntervalMs`
+   * has not elapsed; an explicit refresh checks everything.
+   */
+  async refresh(options: { polled?: boolean } = {}): Promise<ServiceSnapshot[]> {
     if (this.refreshing) return this.list()
     this.refreshing = true
     try {
+      const now = Date.now()
       const targets = [...this.detected]
         .map((id) => this.adapters.get(id))
         .filter((a): a is ServiceAdapter => !!a)
+        .filter((adapter) => {
+          if (!options.polled || !adapter.refreshIntervalMs) return true
+          return now - (this.checkedAt.get(adapter.id) ?? 0) >= adapter.refreshIntervalMs
+        })
+      for (const adapter of targets) this.checkedAt.set(adapter.id, now)
 
       await Promise.all(
         targets.map(async (adapter) => {

package/src/devcc/services/node.ts

@@ -73,7 +73,7 @@ export class PortService implements ServiceAdapter {
   }
 }
 
-interface FrameworkHint {
+export interface FrameworkHint {
   /** Dependency name to look for in package.json. */
   dependency: string
   id: string
@@ -108,20 +108,26 @@ function dependencyNames(packageJson: Record<string, unknown> | null): Set<strin
   return names
 }
 
+/** Frameworks this project depends on, in hint order, one per port. */
+export function detectFrameworks(packageJson: Record<string, unknown> | null): FrameworkHint[] {
+  const dependencies = dependencyNames(packageJson)
+  const seenPorts = new Set<number>()
+  const found: FrameworkHint[] = []
+  for (const hint of FRAMEWORK_HINTS) {
+    if (!dependencies.has(hint.dependency) || seenPorts.has(hint.port)) continue
+    seenPorts.add(hint.port)
+    found.push(hint)
+  }
+  return found
+}
+
 /**
  * Build port adapters for frameworks this project actually depends on.
  * Nothing is assumed: a project with none of these gets no adapters.
  */
 export function detectNodeServices(packageJson: Record<string, unknown> | null): PortService[] {
-  const dependencies = dependencyNames(packageJson)
-  const seenPorts = new Set<number>()
-  const adapters: PortService[] = []
-
-  for (const hint of FRAMEWORK_HINTS) {
-    if (!dependencies.has(hint.dependency)) continue
-    if (seenPorts.has(hint.port)) continue
-    seenPorts.add(hint.port)
-    adapters.push(
+  return detectFrameworks(packageJson).map(
+    (hint) =>
       new PortService({
         id: hint.id,
         name: hint.name,
@@ -130,8 +136,5 @@ export function detectNodeServices(packageJson: Record<string, unknown> | null):
         healthPath: hint.healthPath,
         onlyWhenListening: true,
       }),
-    )
-  }
-
-  return adapters
+  )
 }

package/src/devcc/services/ollama.ts

@@ -1,73 +1,216 @@
+import { formatBytes } from "../utils/format.js"
 import { probeTcpPort } from "../utils/exec.js"
-import type { ServiceAdapter, ServiceStatus } from "./types.js"
+import type { ServiceAdapter, ServiceStatus, ServiceStatusItem } from "./types.js"
 
 const DEFAULT_HOST = "127.0.0.1"
 const DEFAULT_PORT = 11434
+/** Remote endpoints are checked at most this often while polling. */
+const REMOTE_REFRESH_MS = 60_000
+const MAX_ITEMS = 12
+
+interface OllamaModelDetails {
+  parameter_size?: string
+  quantization_level?: string
+  family?: string
+}
 
 interface OllamaTagsResponse {
-  models?: { name?: string }[]
+  models?: { name?: string; size?: number; details?: OllamaModelDetails }[]
+}
+
+interface OllamaPsResponse {
+  models?: {
+    name?: string
+    size?: number
+    size_vram?: number
+    expires_at?: string
+    details?: OllamaModelDetails
+  }[]
+}
+
+export interface OllamaModel {
+  name: string
+  /** Bytes on disk. */
+  size?: number
+  parameterSize?: string
+  quantization?: string
+  family?: string
+  /** Loaded into memory right now. */
+  loaded: boolean
+  /** Bytes of VRAM in use, when loaded. */
+  vram?: number
+  /** When Ollama will unload it. */
+  expiresAt?: Date
 }
 
 export interface OllamaServiceOptions {
+  /** Defaults to `ollama`; set for extra endpoints. */
+  id?: string
+  name?: string
+  /** `http://gpu-server:11434`. Takes precedence over host/port and `OLLAMA_HOST`. */
+  baseUrl?: string
   host?: string
   port?: number
   timeoutMs?: number
+  /** Minimum time between polled checks (default: none locally, 60s for a baseUrl). */
+  refreshIntervalMs?: number
 }
 
 /**
- * Ollama adapter. Uses the HTTP API for a model count when the port is open;
- * falls back to a plain port probe if the API call fails.
+ * Ollama adapter, local or remote.
+ *
+ * Reachability is a TCP probe; when the port answers, `/api/tags` lists the
+ * models and `/api/ps` says which are loaded. Model names are never assumed.
  */
 export class OllamaService implements ServiceAdapter {
-  readonly id = "ollama"
-  readonly name = "Ollama"
+  readonly id: string
+  readonly name: string
   readonly category = "ai" as const
+  readonly refreshIntervalMs: number | undefined
 
+  private readonly baseUrl: string
   private readonly host: string
   private readonly port: number
   private readonly timeoutMs: number
+  private readonly remote: boolean
 
   constructor(options: OllamaServiceOptions = {}) {
+    const fromUrl = options.baseUrl ? parseBaseUrl(options.baseUrl) : null
     const fromEnv = parseHostPort(process.env.OLLAMA_HOST)
-    this.host = options.host ?? fromEnv?.host ?? DEFAULT_HOST
-    this.port = options.port ?? fromEnv?.port ?? DEFAULT_PORT
+    this.remote = options.baseUrl !== undefined
+    this.id = options.id ?? "ollama"
+    this.host = fromUrl?.host ?? options.host ?? fromEnv?.host ?? DEFAULT_HOST
+    this.port = fromUrl?.port ?? options.port ?? fromEnv?.port ?? DEFAULT_PORT
+    this.baseUrl = options.baseUrl?.replace(/\/+$/u, "") ?? `http://${this.host}:${this.port}`
+    this.name = options.name ?? (this.remote ? `Ollama (${this.host})` : "Ollama")
     this.timeoutMs = options.timeoutMs ?? 1_500
+    this.refreshIntervalMs = options.refreshIntervalMs ?? (this.remote ? REMOTE_REFRESH_MS : undefined)
   }
 
+  /** A configured endpoint is always shown, so "unreachable" is visible; the local one only when running. */
   async detect(): Promise<boolean> {
+    if (this.remote) return true
     return probeTcpPort(this.port, this.host)
   }
 
   async getStatus(): Promise<ServiceStatus> {
     const checkedAt = new Date()
     const endpoint = `${this.host}:${this.port}`
-    const listening = await probeTcpPort(this.port, this.host)
-    if (!listening) return { state: "stopped", endpoint, detail: "not listening", checkedAt }
+    const listening = await probeTcpPort(this.port, this.host, this.remote ? 2_000 : 700)
+    if (!listening) {
+      return { state: "stopped", endpoint, detail: this.remote ? "unreachable" : "not listening", checkedAt }
+    }
+
+    const [tags, ps] = await Promise.all([
+      this.getJson<OllamaTagsResponse>("/api/tags"),
+      this.getJson<OllamaPsResponse>("/api/ps"),
+    ])
+    if (!tags) return { state: "degraded", endpoint, detail: "listening, API not responding", checkedAt }
+
+    const models = mergeOllamaModels(tags, ps)
+    const loaded = models.filter((model) => model.loaded).length
+    const detail = [
+      `${models.length} model${models.length === 1 ? "" : "s"}`,
+      ps ? `${loaded} loaded` : undefined,
+    ]
+      .filter(Boolean)
+      .join(" · ")
 
-    const models = await this.listModels()
     return {
       state: "running",
       endpoint,
-      detail: models === null ? "listening" : `${models.length} model${models.length === 1 ? "" : "s"}`,
-      items: models?.slice(0, 6).map((name) => ({ name, state: "running" as const })),
+      detail,
+      items: models.slice(0, MAX_ITEMS).map(modelItem),
       checkedAt,
     }
   }
 
-  private async listModels(): Promise<string[] | null> {
+  /** Models with metadata, for the CLI and tests. Null when unreachable. */
+  async listModels(): Promise<OllamaModel[] | null> {
+    const [tags, ps] = await Promise.all([
+      this.getJson<OllamaTagsResponse>("/api/tags"),
+      this.getJson<OllamaPsResponse>("/api/ps"),
+    ])
+    return tags ? mergeOllamaModels(tags, ps) : null
+  }
+
+  private async getJson<T>(path: string): Promise<T | null> {
     try {
-      const response = await fetch(`http://${this.host}:${this.port}/api/tags`, {
-        signal: AbortSignal.timeout(this.timeoutMs),
-      })
+      const response = await fetch(`${this.baseUrl}${path}`, { signal: AbortSignal.timeout(this.timeoutMs) })
       if (!response.ok) return null
-      const body = (await response.json()) as OllamaTagsResponse
-      return (body.models ?? []).map((model) => model.name ?? "unnamed")
+      return (await response.json()) as T
     } catch {
       return null
     }
   }
 }
 
+/** Combine `/api/tags` with `/api/ps`: loaded models first, then by name. */
+export function mergeOllamaModels(tags: OllamaTagsResponse, ps: OllamaPsResponse | null): OllamaModel[] {
+  const running = new Map(
+    (ps?.models ?? []).filter((model) => model.name).map((model) => [model.name as string, model]),
+  )
+  const models: OllamaModel[] = (tags.models ?? [])
+    .filter((model) => typeof model.name === "string")
+    .map((model) => {
+      const name = model.name as string
+      const live = running.get(name)
+      running.delete(name)
+      return {
+        name,
+        size: model.size,
+        parameterSize: model.details?.parameter_size,
+        quantization: model.details?.quantization_level,
+        family: model.details?.family,
+        loaded: live !== undefined,
+        vram: live?.size_vram,
+        expiresAt: parseDate(live?.expires_at),
+      }
+    })
+  // A model can be loaded but missing from tags (e.g. pulled mid-refresh).
+  for (const [name, live] of running) {
+    models.push({
+      name,
+      size: live.size,
+      parameterSize: live.details?.parameter_size,
+      quantization: live.details?.quantization_level,
+      family: live.details?.family,
+      loaded: true,
+      vram: live.size_vram,
+      expiresAt: parseDate(live.expires_at),
+    })
+  }
+  return models.sort((a, b) => Number(b.loaded) - Number(a.loaded) || a.name.localeCompare(b.name))
+}
+
+function modelItem(model: OllamaModel): ServiceStatusItem {
+  const meta = [model.parameterSize, model.quantization, model.size ? formatBytes(model.size) : undefined]
+  if (model.loaded && model.vram) meta.push(`${formatBytes(model.vram)} VRAM`)
+  return {
+    name: model.name,
+    state: model.loaded ? "running" : "stopped",
+    detail: [model.loaded ? "loaded" : undefined, ...meta].filter(Boolean).join(" · "),
+  }
+}
+
+function parseDate(value: string | undefined): Date | undefined {
+  if (!value) return undefined
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? undefined : date
+}
+
+/** A full base URL: a missing port means the scheme's default, exactly as `fetch` will treat it. */
+export function parseBaseUrl(value: string): { host: string; port: number } | null {
+  try {
+    const parsed = new URL(value)
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null
+    return { host: parsed.hostname, port: Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80)) }
+  } catch {
+    return null
+  }
+}
+
+/** `OLLAMA_HOST`-style `host[:port]`, where a missing port means Ollama's 11434. */
 export function parseHostPort(value: string | undefined): { host: string; port: number } | null {
   if (!value) return null
   const withScheme = value.includes("://") ? value : `http://${value}`