@balpal4495/quorum 3.3.2 → 3.4.0

package/bin/commands/ingest-git.js

@@ -0,0 +1,192 @@
+/**
+ * quorum ingest-git [--since P90D] [--propose]
+ *
+ * Reads git commit history and ingests each commit as a low-trust evidence
+ * record in .chronicle/sources/ and .chronicle/evidence/.
+ *
+ * With --propose, each commit is also written to .chronicle/proposals/
+ * for review with: quorum commit --list
+ *
+ * --since accepts ISO 8601 durations: P90D (90 days), P6M (6 months), P1Y (1 year).
+ * Defaults to P90D.
+ */
+
+import { execSync } from "child_process"
+import { promises as fs } from "fs"
+import path from "path"
+import { randomUUID } from "crypto"
+import { c } from "../shared/colors.js"
+import { findChronicleDir } from "../shared/chronicle.js"
+
+function parseArgs(argv) {
+  const args = { since: "P90D", propose: false }
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--since" && argv[i + 1]) { args.since = argv[++i]; continue }
+    if (argv[i].startsWith("--since="))       { args.since = argv[i].slice(8); continue }
+    if (argv[i] === "--propose")               { args.propose = true }
+  }
+  return args
+}
+
+/**
+ * Parse a restricted subset of ISO 8601 duration (PnD, PnM, PnY) to a
+ * human-readable git --since value. Returns a safe numeric string like
+ * "90 days ago" — never passes raw user input to the shell.
+ */
+export function parseDurationToGitSince(duration) {
+  const match = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?$/.exec(duration)
+  if (!match) return "90 days ago"
+  const years  = parseInt(match[1] ?? "0", 10)
+  const months = parseInt(match[2] ?? "0", 10)
+  const days   = parseInt(match[3] ?? "0", 10)
+  const total  = years * 365 + months * 30 + days
+  return `${total > 0 ? total : 90} days ago`
+}
+
+function deriveScope(files) {
+  const scope = []
+  if (files.some(f => f.startsWith("modules/")))  scope.push("modules")
+  if (files.some(f => f.startsWith("bin/")))       scope.push("cli")
+  if (files.some(f => f.startsWith(".github/")))   scope.push("ci")
+  if (files.some(f => f === "README.md"))          scope.push("docs")
+  if (files.some(f => f === "package.json"))       scope.push("npm")
+  if (scope.length === 0) scope.push("general")
+  return scope
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+
+  const chronicleDir = await findChronicleDir()
+  if (!chronicleDir) {
+    console.error(c.red("No .chronicle/ directory found. Run quorum init first."))
+    process.exit(1)
+  }
+
+  const sourcesDir   = path.join(chronicleDir, "sources")
+  const evidenceDir  = path.join(chronicleDir, "evidence")
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  await fs.mkdir(sourcesDir,  { recursive: true })
+  await fs.mkdir(evidenceDir, { recursive: true })
+  if (args.propose) await fs.mkdir(proposalsDir, { recursive: true })
+
+  // Load already-ingested commit hashes to avoid duplicates
+  const existingRefs = new Set()
+  try {
+    for (const f of await fs.readdir(sourcesDir)) {
+      if (!f.endsWith(".json")) continue
+      try {
+        const src = JSON.parse(await fs.readFile(path.join(sourcesDir, f), "utf8"))
+        if (src.type === "git-commit" && src.ref) existingRefs.add(src.ref)
+      } catch { /* skip malformed */ }
+    }
+  } catch { /* no sources yet */ }
+
+  const gitSince = parseDurationToGitSince(args.since)
+  console.log(c.bold(`\nReading git history since "${gitSince}"...\n`))
+
+  let logRaw
+  try {
+    logRaw = execSync(
+      // Safe: gitSince is always "N days ago" from parseDurationToGitSince
+      `git log --since="${gitSince}" --pretty=format:"%H|||%ci|||%s" --no-merges`,
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] },
+    ).trim()
+  } catch {
+    console.error(c.red("Could not run git log. Ensure this is a git repository."))
+    process.exit(1)
+  }
+
+  if (!logRaw) {
+    console.log(c.dim(`No commits found since "${gitSince}"`))
+    return
+  }
+
+  const commits = logRaw
+    .split("\n")
+    .filter(Boolean)
+    .map(line => {
+      const [hash, date, ...parts] = line.split("|||")
+      return { hash: hash.trim(), date: date.trim(), subject: parts.join("|||").trim() }
+    })
+
+  let ingested = 0, skipped = 0, proposed = 0
+  const now = new Date().toISOString()
+
+  for (const { hash, date, subject } of commits) {
+    if (existingRefs.has(hash)) { skipped++; continue }
+
+    // Get changed files — hash is hex from git log, safe to interpolate
+    let changedFiles = []
+    try {
+      changedFiles = execSync(
+        `git diff-tree --no-commit-id -r --name-only ${hash}`,
+        { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] },
+      ).trim().split("\n").filter(Boolean)
+    } catch { /* skip file list on error */ }
+
+    const scope      = deriveScope(changedFiles)
+    const sourceId   = randomUUID()
+    const evidenceId = randomUUID()
+
+    const sourceRecord = {
+      id: sourceId,
+      type: "git-commit",
+      ref: hash,
+      ingested_at: now,
+      metadata: { date, subject, files_changed: changedFiles.length },
+    }
+    await fs.writeFile(
+      path.join(sourcesDir, `${sourceId}.json`),
+      JSON.stringify(sourceRecord, null, 2),
+    )
+    existingRefs.add(hash)
+
+    const evidenceRecord = {
+      id: evidenceId,
+      source_id: sourceId,
+      schema_version: 2,
+      topic: `git: ${subject.slice(0, 80)}`,
+      key_insight: subject.slice(0, 150),
+      decision: subject.slice(0, 150),
+      affected_areas: changedFiles.slice(0, 10),
+      scope,
+      alternatives_considered: [],
+      rejected_reason: [],
+      status: "open",
+      confidence: 0.4,
+      source_quality: "metadata-derived",
+      needs_human_summary: true,
+      source_module: "ingest-git",
+      work_ref: { type: "git-commit", ref: hash, date },
+      ingested_at: now,
+    }
+    await fs.writeFile(
+      path.join(evidenceDir, `${evidenceId}.json`),
+      JSON.stringify(evidenceRecord, null, 2),
+    )
+
+    if (args.propose) {
+      const proposalId = randomUUID()
+      const { id: _id, ingested_at: _ts, ...proposalBody } = evidenceRecord
+      await fs.writeFile(
+        path.join(proposalsDir, `${proposalId}.json`),
+        JSON.stringify(proposalBody, null, 2),
+      )
+      proposed++
+      console.log(c.green(`  ✓ propose  ${hash.slice(0, 7)}  ${subject.slice(0, 60)}`))
+    } else {
+      console.log(c.green(`  ✓ ingest   ${hash.slice(0, 7)}  ${subject.slice(0, 60)}`))
+    }
+    ingested++
+  }
+
+  const suffix = args.propose ? `  ${proposed} proposed` : ""
+  console.log(`\n${c.bold("Done.")}  ${ingested} commits ingested  ${skipped} already ingested${suffix}`)
+  if (ingested > 0 && !args.propose) {
+    console.log(c.dim(`\n  Evidence in .chronicle/evidence/`))
+    console.log(c.dim(`  Re-run with --propose to stage as Chronicle proposals.`))
+  } else if (proposed > 0) {
+    console.log(c.dim(`\n  Review proposals:  quorum commit --list`))
+  }
+}

package/bin/commands/ingest-url.js

@@ -0,0 +1,224 @@
+/**
+ * quorum ingest-url <url...> [--propose]
+ *
+ * Fetches one or more URLs and stores each as a low-trust evidence record in
+ * .chronicle/sources/ and .chronicle/evidence/.
+ *
+ * With --propose, each URL is also written to .chronicle/proposals/
+ * for review with: quorum commit --list
+ *
+ * Only http:// and https:// URLs are accepted.
+ */
+
+import { createHash, randomUUID } from "crypto"
+import { promises as fs } from "fs"
+import https from "https"
+import http from "http"
+import path from "path"
+import { c } from "../shared/colors.js"
+import { findChronicleDir } from "../shared/chronicle.js"
+
+function parseArgs(argv) {
+  const args = { urls: [], propose: false }
+  for (const arg of argv) {
+    if (arg === "--propose")                                      args.propose = true
+    else if (arg.startsWith("http://") || arg.startsWith("https://")) args.urls.push(arg)
+    else if (!arg.startsWith("-")) {
+      console.warn(c.dim(`  skip: ${arg} (not an http/https URL)`))
+    }
+  }
+  return args
+}
+
+/**
+ * Validate that a URL uses only http or https — no file://, ftp://, etc.
+ */
+function validateUrl(raw) {
+  let u
+  try { u = new URL(raw) } catch { return null }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return null
+  return u
+}
+
+/**
+ * Fetch a URL, following one redirect, returning raw body as a string.
+ * Resolves with the text body or rejects with an Error.
+ */
+function fetchUrl(url, redirectDepth = 0) {
+  if (redirectDepth > 3) return Promise.reject(new Error("Too many redirects"))
+  const parsed = validateUrl(url)
+  if (!parsed) return Promise.reject(new Error(`Rejected URL scheme: ${url}`))
+
+  return new Promise((resolve, reject) => {
+    const protocol = parsed.protocol === "https:" ? https : http
+    const req = protocol.get(url, { headers: { "User-Agent": "quorum-ingest/1.0" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect — re-validate the Location header
+        const location = res.headers.location
+        res.resume()
+        fetchUrl(location, redirectDepth + 1).then(resolve).catch(reject)
+        return
+      }
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        res.resume()
+        reject(new Error(`HTTP ${res.statusCode}`))
+        return
+      }
+      const chunks = []
+      res.on("data", chunk => chunks.push(chunk))
+      res.on("end",  () => resolve(Buffer.concat(chunks).toString("utf8")))
+      res.on("error", reject)
+    })
+    req.on("error", reject)
+    req.setTimeout(15_000, () => { req.destroy(); reject(new Error("Request timeout")) })
+  })
+}
+
+function stripHtml(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&[a-z]+;/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 3000)
+}
+
+function extractTitle(html) {
+  const m = /<title[^>]*>([^<]+)<\/title>/i.exec(html)
+  return m ? m[1].trim().slice(0, 150) : ""
+}
+
+function deriveScope(url) {
+  try {
+    const u = new URL(url)
+    const first = u.pathname.split("/").filter(Boolean)[0]
+    return ["external", ...(first ? [first.slice(0, 20)] : [])]
+  } catch {
+    return ["external"]
+  }
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+  if (args.urls.length === 0) {
+    console.error(c.red("Usage: quorum ingest-url <url...> [--propose]"))
+    console.error(c.dim("  Only http:// and https:// URLs are supported."))
+    process.exit(1)
+  }
+
+  const chronicleDir = await findChronicleDir()
+  if (!chronicleDir) {
+    console.error(c.red("No .chronicle/ directory found. Run quorum init first."))
+    process.exit(1)
+  }
+
+  const sourcesDir   = path.join(chronicleDir, "sources")
+  const evidenceDir  = path.join(chronicleDir, "evidence")
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  await fs.mkdir(sourcesDir,  { recursive: true })
+  await fs.mkdir(evidenceDir, { recursive: true })
+  if (args.propose) await fs.mkdir(proposalsDir, { recursive: true })
+
+  // Load already-ingested URLs to skip duplicates
+  const existingRefs = new Set()
+  try {
+    for (const f of await fs.readdir(sourcesDir)) {
+      if (!f.endsWith(".json")) continue
+      try {
+        const src = JSON.parse(await fs.readFile(path.join(sourcesDir, f), "utf8"))
+        if (src.type === "url" && src.ref) existingRefs.add(src.ref)
+      } catch { /* skip malformed */ }
+    }
+  } catch { /* no sources yet */ }
+
+  let ingested = 0, skipped = 0, proposed = 0
+  const now = new Date().toISOString()
+  console.log(c.bold(`\nIngesting ${args.urls.length} URL(s)...\n`))
+
+  for (const url of args.urls) {
+    if (existingRefs.has(url)) {
+      skipped++
+      console.log(c.dim(`  ≡ skip  ${url} (already ingested)`))
+      continue
+    }
+
+    let rawHtml
+    try {
+      rawHtml = await fetchUrl(url)
+    } catch (err) {
+      console.warn(c.red(`  ✗ error  ${url} — ${err.message}`))
+      continue
+    }
+
+    const title    = extractTitle(rawHtml) || url
+    const text     = stripHtml(rawHtml)
+    const hashKey  = `sha256:${createHash("sha256").update(text).digest("hex")}`
+    const scope    = deriveScope(url)
+    const summary  = `${title} — ${text.slice(0, 120)}`
+    const sourceId   = randomUUID()
+    const evidenceId = randomUUID()
+
+    const sourceRecord = {
+      id: sourceId,
+      type: "url",
+      ref: url,
+      ingested_at: now,
+      content_hash: hashKey,
+      metadata: { title, content_length: text.length },
+    }
+    await fs.writeFile(
+      path.join(sourcesDir, `${sourceId}.json`),
+      JSON.stringify(sourceRecord, null, 2),
+    )
+    existingRefs.add(url)
+
+    const evidenceRecord = {
+      id: evidenceId,
+      source_id: sourceId,
+      schema_version: 2,
+      topic: `url: ${title.slice(0, 80)}`,
+      key_insight: summary.slice(0, 150),
+      decision: summary.slice(0, 150),
+      affected_areas: [url],
+      scope,
+      alternatives_considered: [],
+      rejected_reason: [],
+      status: "open",
+      confidence: 0.4,
+      source_quality: "metadata-derived",
+      needs_human_summary: true,
+      source_module: "ingest-url",
+      work_ref: { type: "url", ref: url },
+      ingested_at: now,
+    }
+    await fs.writeFile(
+      path.join(evidenceDir, `${evidenceId}.json`),
+      JSON.stringify(evidenceRecord, null, 2),
+    )
+
+    if (args.propose) {
+      const proposalId = randomUUID()
+      const { id: _id, ingested_at: _ts, ...proposalBody } = evidenceRecord
+      await fs.writeFile(
+        path.join(proposalsDir, `${proposalId}.json`),
+        JSON.stringify(proposalBody, null, 2),
+      )
+      proposed++
+      console.log(c.green(`  ✓ propose  ${url}`))
+    } else {
+      console.log(c.green(`  ✓ ingest   ${url}`))
+    }
+    ingested++
+  }
+
+  const suffix = args.propose ? `  ${proposed} proposed` : ""
+  console.log(`\n${c.bold("Done.")}  ${ingested} ingested  ${skipped} already ingested${suffix}`)
+  if (ingested > 0 && !args.propose) {
+    console.log(c.dim(`\n  Evidence in .chronicle/evidence/`))
+    console.log(c.dim(`  Re-run with --propose to stage as Chronicle proposals.`))
+  } else if (proposed > 0) {
+    console.log(c.dim(`\n  Review proposals:  quorum commit --list`))
+  }
+}

package/bin/commands/ingest.js

@@ -0,0 +1,212 @@
+/**
+ * quorum ingest <paths...> [--recurse] [--propose]
+ *
+ * Ingests files and directories into .chronicle/sources/ and .chronicle/evidence/
+ * as low-trust, metadata-derived records (confidence 0.4, needs_human_summary: true).
+ *
+ * With --propose, each evidence item is also written to .chronicle/proposals/
+ * for review with: quorum commit --list
+ */
+
+import { createHash, randomUUID } from "crypto"
+import { promises as fs } from "fs"
+import path from "path"
+import { c } from "../shared/colors.js"
+import { findChronicleDir } from "../shared/chronicle.js"
+
+function parseArgs(argv) {
+  const args = { paths: [], recurse: false, propose: false }
+  for (const arg of argv) {
+    if (arg === "--recurse" || arg === "-r") args.recurse = true
+    else if (arg === "--propose") args.propose = true
+    else if (!arg.startsWith("-")) args.paths.push(arg)
+  }
+  return args
+}
+
+async function* walkDir(dir) {
+  let entries
+  try { entries = await fs.readdir(dir, { withFileTypes: true }) } catch { return }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue
+      yield* walkDir(full)
+    } else {
+      yield full
+    }
+  }
+}
+
+async function collectFiles(targetPaths, recurse) {
+  const files = []
+  for (const p of targetPaths) {
+    const stat = await fs.stat(p).catch(() => null)
+    if (!stat) { console.warn(c.dim(`  skip: ${p} (not found)`)); continue }
+    if (stat.isDirectory()) {
+      if (recurse) {
+        for await (const f of walkDir(p)) files.push(f)
+      } else {
+        console.warn(c.dim(`  skip: ${p} is a directory — use --recurse`))
+      }
+    } else {
+      files.push(p)
+    }
+  }
+  return files
+}
+
+const TEXT_EXTS = new Set([
+  ".md", ".txt", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
+  ".json", ".yaml", ".yml", ".toml", ".sh", ".bash",
+  ".html", ".htm", ".css", ".scss", ".svg", ".xml", ".csv",
+  ".rst", ".adoc", ".env",
+])
+
+async function extractContent(filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  if (!TEXT_EXTS.has(ext)) return null
+  try {
+    const raw = await fs.readFile(filePath, "utf8")
+    return raw.slice(0, 3000)
+  } catch {
+    return null
+  }
+}
+
+function deriveScope(filePath) {
+  const scope = []
+  const rel = filePath.replace(/\\/g, "/")
+  if (rel.match(/\/docs?\//i) || rel.endsWith(".md") || rel.endsWith(".rst")) scope.push("docs")
+  if (rel.match(/\/(src|lib|modules)\//))  scope.push("source")
+  if (rel.match(/\/(tests?|__tests__)\//i) || rel.match(/\.(test|spec)\./)) scope.push("tests")
+  if (rel.includes("/.github/") || rel.includes("/ci/")) scope.push("ci")
+  if (rel.includes("/bin/") || rel.endsWith(".sh")) scope.push("cli")
+  if (scope.length === 0) scope.push("general")
+  return scope
+}
+
+function summariseContent(filePath, content) {
+  if (!content) return `Ingested ${path.basename(filePath)}`
+  const lines = content.split("\n").map(l => l.trim()).filter(Boolean)
+  const heading = lines.find(l => l.startsWith("#")) ?? lines[0] ?? ""
+  return heading.replace(/^#+\s*/, "").slice(0, 150) || `Content from ${path.basename(filePath)}`
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv)
+  if (args.paths.length === 0) {
+    console.error(c.red("Usage: quorum ingest <paths...> [--recurse] [--propose]"))
+    process.exit(1)
+  }
+
+  const chronicleDir = await findChronicleDir()
+  if (!chronicleDir) {
+    console.error(c.red("No .chronicle/ directory found. Run quorum init first."))
+    process.exit(1)
+  }
+
+  const sourcesDir   = path.join(chronicleDir, "sources")
+  const evidenceDir  = path.join(chronicleDir, "evidence")
+  const proposalsDir = path.join(chronicleDir, "proposals")
+  await fs.mkdir(sourcesDir,  { recursive: true })
+  await fs.mkdir(evidenceDir, { recursive: true })
+  if (args.propose) await fs.mkdir(proposalsDir, { recursive: true })
+
+  // Load existing content hashes to skip unchanged files
+  const existingHashes = new Set()
+  try {
+    for (const f of await fs.readdir(sourcesDir)) {
+      if (!f.endsWith(".json")) continue
+      try {
+        const src = JSON.parse(await fs.readFile(path.join(sourcesDir, f), "utf8"))
+        if (src.type === "file" && src.content_hash) existingHashes.add(src.content_hash)
+      } catch { /* skip malformed */ }
+    }
+  } catch { /* no sources yet */ }
+
+  const files = await collectFiles(args.paths, args.recurse)
+  let ingested = 0, skipped = 0, proposed = 0
+  const now = new Date().toISOString()
+
+  console.log(c.bold(`\nIngesting ${files.length} file(s)...\n`))
+
+  for (const filePath of files) {
+    const content  = await extractContent(filePath)
+    const text     = content ?? ""
+    const hashKey  = `sha256:${createHash("sha256").update(text).digest("hex")}`
+
+    if (existingHashes.has(hashKey)) {
+      skipped++
+      console.log(c.dim(`  ≡ skip    ${path.relative(process.cwd(), filePath)} (unchanged)`))
+      continue
+    }
+
+    const relPath    = path.relative(process.cwd(), filePath)
+    const scope      = deriveScope(filePath)
+    const summary    = summariseContent(filePath, content)
+    const sourceId   = randomUUID()
+    const evidenceId = randomUUID()
+
+    const sourceRecord = {
+      id: sourceId,
+      type: "file",
+      ref: relPath,
+      ingested_at: now,
+      content_hash: hashKey,
+      metadata: { size_bytes: text.length, ext: path.extname(filePath) },
+    }
+    await fs.writeFile(
+      path.join(sourcesDir, `${sourceId}.json`),
+      JSON.stringify(sourceRecord, null, 2),
+    )
+    existingHashes.add(hashKey)
+
+    const evidenceRecord = {
+      id: evidenceId,
+      source_id: sourceId,
+      schema_version: 2,
+      topic: relPath,
+      key_insight: summary,
+      decision: summary,
+      affected_areas: [relPath],
+      scope,
+      alternatives_considered: [],
+      rejected_reason: [],
+      status: "open",
+      confidence: 0.4,
+      source_quality: "metadata-derived",
+      needs_human_summary: true,
+      source_module: "ingest",
+      work_ref: { type: "file", ref: relPath },
+      ingested_at: now,
+    }
+    await fs.writeFile(
+      path.join(evidenceDir, `${evidenceId}.json`),
+      JSON.stringify(evidenceRecord, null, 2),
+    )
+
+    if (args.propose) {
+      const proposalId = randomUUID()
+      const { id: _id, ingested_at: _ts, ...proposalBody } = evidenceRecord
+      await fs.writeFile(
+        path.join(proposalsDir, `${proposalId}.json`),
+        JSON.stringify(proposalBody, null, 2),
+      )
+      proposed++
+      console.log(c.green(`  ✓ propose  ${relPath}`))
+    } else {
+      console.log(c.green(`  ✓ ingest   ${relPath}`))
+    }
+    ingested++
+  }
+
+  const suffix = args.propose ? `  ${proposed} proposed` : ""
+  console.log(`\n${c.bold("Done.")}  ${ingested} ingested  ${skipped} unchanged${suffix}`)
+  if (ingested > 0 && !args.propose) {
+    console.log(c.dim(`\n  Evidence in .chronicle/evidence/`))
+    console.log(c.dim(`  Re-run with --propose to stage as Chronicle proposals.`))
+  } else if (proposed > 0) {
+    console.log(c.dim(`\n  Review proposals:  quorum commit --list`))
+  }
+}

package/bin/commands/serve.js

@@ -0,0 +1,52 @@
+import { c } from "../shared/colors.js"
+import { findChronicleDir } from "../shared/chronicle.js"
+import { createServer } from "../mcp/server.js"
+
+function parseArgs(argv) {
+  const portIdx = argv.indexOf("--port")
+  const port = portIdx !== -1
+    ? Number(argv[portIdx + 1])
+    : Number(argv.find(a => /^\d{2,5}$/.test(a)) ?? 3000)
+  const hostIdx = argv.indexOf("--host")
+  const host = hostIdx !== -1 ? argv[hostIdx + 1] : "localhost"
+  return { port: isNaN(port) ? 3000 : port, host }
+}
+
+export async function run(argv) {
+  const { port, host } = parseArgs(argv)
+
+  const projectRoot  = process.cwd()
+  const chronicleDir = await findChronicleDir(projectRoot)
+
+  if (!chronicleDir) {
+    console.error(`\n${c.red("No .chronicle/ directory found.")} Run ${c.bold("quorum init")} first.\n`)
+    process.exit(1)
+  }
+
+  const server = await createServer({ projectRoot, chronicleDir })
+
+  server.listen(port, host, () => {
+    const base = `http://${host}:${port}`
+    console.log(`\n${c.bold("Quorum")}  ${c.dim(`serving ${projectRoot}`)}\n`)
+    console.log(`  ${c.cyan("UI")}         ${c.dim(base + "/")}`)
+    console.log(`  ${c.cyan("MCP")}        ${c.dim(base + "/mcp")}`)
+    console.log(`  ${c.cyan("Chronicle")}  ${c.dim(chronicleDir)}\n`)
+    console.log(c.bold("Claude Desktop") + c.dim(" — add to claude_desktop_config.json:"))
+    console.log(c.dim(JSON.stringify({
+      mcpServers: { quorum: { type: "streamable-http", url: `${base}/mcp` } }
+    }, null, 2)))
+    console.log(`\n${c.dim("Press Ctrl+C to stop.")}\n`)
+  })
+
+  server.on("error", err => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`\n${c.red(`Port ${port} is already in use.`)} Try ${c.bold(`quorum serve --port ${port + 1}`)}\n`)
+    } else {
+      console.error(`\n${c.red("Server error:")} ${err.message}\n`)
+    }
+    process.exit(1)
+  })
+
+  process.on("SIGINT",  () => { server.close(); process.exit(0) })
+  process.on("SIGTERM", () => { server.close(); process.exit(0) })
+}