spexcode 0.6.2 → 0.6.6

package/spec-eval/src/sidecar.ts

@@ -1,93 +0,0 @@
-import { readFileSync, appendFileSync, existsSync } from 'node:fs'
-
-export type Verdict = { status: 'pass' | 'fail'; note?: string }
-
-export type EvidenceKind = 'image' | 'transcript' | 'video' | 'data'
-export type Evidence = { hash: string; kind: EvidenceKind }
-
-export type Reading = {
-  scenario: string
-  codeSha: string
-  scenarioHash?: string
-  evidence?: Evidence[]
-  blob?: string | null
-  blobKind?: EvidenceKind
-  timelineBlob?: string
-  evaluator?: string
-  by?: string
-  verdict?: Verdict
-  ts: string
-}
-
-export function evidenceOf(r: { evidence?: Evidence[]; blob?: string | null; blobKind?: EvidenceKind }): Evidence[] {
-  if (r.evidence?.length) return r.evidence
-  if (r.blob) return [{ hash: r.blob, kind: r.blobKind ?? 'image' }]
-  return []
-}
-
-export function isJsonBlob(b: Buffer): boolean {
-  if (!b.length || b.includes(0)) return false           // empty or binary → not JSON text
-  if (b.length > 4_000_000) return false                 // don't parse an unbounded blob just to sniff a type
-  const s = b.toString('utf8').trim()
-  const open = s[0], close = s[s.length - 1]
-  if (!((open === '{' && close === '}') || (open === '[' && close === ']'))) return false
-  try { const v = JSON.parse(s); return v !== null && typeof v === 'object' } catch { return false }
-}
-
-export type Retraction = { retracts: string; scenario: string; note?: string; by?: string; ts: string }
-
-export type HumanOk = { kind: 'human-ok'; scenario: string; okTs: string; okSha: string; by: string; ts: string }
-
-export function readSidecar(sidecarPath: string): { readings: Reading[]; retractions: Retraction[]; oks: HumanOk[] } {
-  const readings: Reading[] = []
-  const retractions: Retraction[] = []
-  const oks: HumanOk[] = []
-  if (!existsSync(sidecarPath)) return { readings, retractions, oks }
-  for (const line of readFileSync(sidecarPath, 'utf8').split('\n')) {
-    const t = line.trim()
-    if (!t) continue
-    try {
-      const r = JSON.parse(t)
-      if (!r || typeof r.scenario !== 'string') continue
-      if (typeof r.retracts === 'string') retractions.push(r as Retraction)
-      else if (r.kind === 'human-ok' && typeof r.okTs === 'string') oks.push(r as HumanOk)
-      else if (typeof r.codeSha === 'string') readings.push(r as Reading)
-    } catch { /* Keep earlier events readable after an incomplete append. */ }
-  }
-  return { readings, retractions, oks }
-}
-
-export function applyRetractions(readings: Reading[], retractions: Retraction[]): Reading[] {
-  if (!retractions.length) return readings
-  const gone = new Set(retractions.map((x) => `${x.scenario}\0${x.retracts}`))
-  return readings.filter((r) => !gone.has(`${r.scenario}\0${r.ts}`))
-}
-
-export function readReadings(sidecarPath: string): Reading[] {
-  const { readings, retractions } = readSidecar(sidecarPath)
-  return applyRetractions(readings, retractions)
-}
-
-export function appendReading(sidecarPath: string, r: Reading): void {
-  appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
-}
-
-export function appendRetraction(sidecarPath: string, r: Retraction): void {
-  appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
-}
-
-export function appendHumanOk(sidecarPath: string, r: HumanOk): void {
-  appendFileSync(sidecarPath, JSON.stringify(r) + '\n')
-}
-
-export function humanOkFor(oks: HumanOk[], scenario: string, readingTs: string): HumanOk | null {
-  let hit: HumanOk | null = null
-  for (const o of oks) if (o.scenario === scenario && o.okTs === readingTs) hit = o
-  return hit
-}
-
-export function latestPerScenario(readings: Reading[]): Map<string, Reading> {
-  const m = new Map<string, Reading>()
-  for (const r of readings) m.set(r.scenario, r)   // later lines overwrite earlier → last wins
-  return m
-}

package/spec-eval/src/timeline.ts

@@ -1,54 +0,0 @@
-export type TimelineEvent = { at: number; step: string; node?: string }
-export type StepTimeline = { v: 2; axis: string; events: TimelineEvent[] }
-
-export type LegacyTimelineEvent = { tMs: number; step: string; node?: string }
-export type LegacyStepTimeline = { v: 1; events: LegacyTimelineEvent[] }
-
-const V2_EVENT_KEYS = new Set(['at', 'step', 'node'])
-const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node'])
-
-export function validateTimeline(raw: unknown): string[] {
-  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return ['timeline must be a JSON object { v, axis, events }']
-  const o = raw as Record<string, unknown>
-  if (o.v !== 1 && o.v !== 2) return ['`v` must be 1 (legacy time axis) or 2 (axis-tagged)']
-  const errs: string[] = []
-  const v2 = o.v === 2
-  const posKey = v2 ? 'at' : 'tMs'
-  const rootKeys = v2 ? new Set(['v', 'axis', 'events']) : new Set(['v', 'events'])
-  const evKeys = v2 ? V2_EVENT_KEYS : V1_EVENT_KEYS
-  for (const k of Object.keys(o)) if (!rootKeys.has(k)) errs.push(`unknown field \`${k}\` (allowed: ${[...rootKeys].join(', ')})`)
-  if (v2 && (typeof o.axis !== 'string' || !o.axis.trim())) errs.push('`axis` must be a non-empty string (e.g. time, frame, line, index)')
-  if (!Array.isArray(o.events)) { errs.push('`events` must be an array'); return errs }
-  let prev = -Infinity
-  o.events.forEach((e, i) => {
-    if (typeof e !== 'object' || e === null || Array.isArray(e)) { errs.push(`events[${i}] must be an object`); return }
-    const ev = e as Record<string, unknown>
-    for (const k of Object.keys(ev)) if (!evKeys.has(k)) errs.push(`events[${i}]: unknown field \`${k}\` (allowed: ${[...evKeys].join(', ')})`)
-    const pos = ev[posKey]
-    if (typeof pos !== 'number' || !Number.isFinite(pos) || pos < 0) {
-      errs.push(`events[${i}].${posKey} must be a finite number ≥ 0`)
-    } else {
-      if (pos < prev) errs.push(`events[${i}].${posKey} is out of order (the list is ordered by position)`)
-      prev = pos
-    }
-    if (typeof ev.step !== 'string' || !ev.step.trim()) errs.push(`events[${i}].step must be a non-empty string`)
-    if (ev.node !== undefined && (typeof ev.node !== 'string' || !ev.node.trim())) errs.push(`events[${i}].node must be a non-empty string when present`)
-  })
-  return errs
-}
-
-export function normalizeTimeline(raw: unknown): { axis: string; events: TimelineEvent[] } {
-  const o = (raw ?? {}) as Record<string, any>
-  const events: any[] = Array.isArray(o.events) ? o.events : []
-  if (o.v === 1) return { axis: 'time', events: events.map((e) => ({ at: e.tMs, step: e.step, ...(e.node ? { node: e.node } : {}) })) }
-  return { axis: typeof o.axis === 'string' ? o.axis : 'time', events: events.map((e) => ({ at: e.at, step: e.step, ...(e.node ? { node: e.node } : {}) })) }
-}
-
-export function stepAt(events: TimelineEvent[], pos: number): TimelineEvent | null {
-  let hit: TimelineEvent | null = null
-  for (const e of events) {
-    if (e.at <= pos) hit = e
-    else break
-  }
-  return hit
-}

package/spec-forge/src/__fixtures__/github-forge.json

@@ -1,63 +0,0 @@
-{
-  "_note": "Fixture mirroring githubDriver output (the vendor-neutral ForgeIssue[]/ForgePR[] a `gh issue/pr list` collapses to) for a sample repo. Drives the needs-eval resolver test with no network.",
-  "issues": [
-    {
-      "number": 1,
-      "title": "login redirect is broken on /logout",
-      "body": "Steps to repro: click logout, land on a 404.\n\nSpec: sessions\nneeds-eval\n",
-      "url": "https://github.com/acme/repo/issues/1",
-      "state": "open",
-      "labels": []
-    },
-    {
-      "number": 2,
-      "title": "board badge count is off by one",
-      "body": "The open-issue badge over-counts.\n\nSpec: dashboard-issues",
-      "url": "https://github.com/acme/repo/issues/2",
-      "state": "open",
-      "labels": ["bug", "needs-eval"]
-    },
-    {
-      "number": 3,
-      "title": "tracer mislinks a node/<id> branch with a dash",
-      "body": "branchToNode picks the short id.\n\nSpec: links",
-      "url": "https://github.com/acme/repo/issues/3",
-      "state": "open",
-      "labels": ["bug"]
-    },
-    {
-      "number": 4,
-      "title": "old forge-cache drift already verified",
-      "body": "Spec: forge-cache\nNeeds-Eval\n",
-      "url": "https://github.com/acme/repo/issues/4",
-      "state": "closed",
-      "labels": []
-    },
-    {
-      "number": 5,
-      "title": "flagged but names no node",
-      "body": "This one is flagged but carries no Spec: marker and no closing PR.\n\nneeds-eval\n",
-      "url": "https://github.com/acme/repo/issues/5",
-      "state": "open",
-      "labels": ["needs-eval"]
-    },
-    {
-      "number": 6,
-      "title": "fixed via an open PR, no marker on the issue",
-      "body": "A worked bug; the node comes transitively from the closing PR.\n\nneeds-eval: ignore-the-trailing-text",
-      "url": "https://github.com/acme/repo/issues/6",
-      "state": "open",
-      "labels": ["needs-eval"]
-    }
-  ],
-  "prs": [
-    {
-      "number": 20,
-      "title": "fix logout redirect",
-      "url": "https://github.com/acme/repo/pull/20",
-      "state": "open",
-      "headRefName": "node/port-7f3a1c2",
-      "closesIssues": [6]
-    }
-  ]
-}

package/spec-forge/src/cache.ts

@@ -1,66 +0,0 @@
-import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
-import { resolveLinks, type NodeLinks } from './links.js'
-
-export type ForgeDelta =
-  | { kind: 'issue'; issue: ForgeIssue }
-  | { kind: 'pr'; pr: ForgePR }
-  | { kind: 'remove'; target: 'issue' | 'pr'; number: number }
-
-function sameMap<T>(a: Map<number, T>, b: Map<number, T>): boolean {
-  if (a.size !== b.size) return false
-  for (const [number, value] of a)
-    if (!b.has(number) || JSON.stringify(value) !== JSON.stringify(b.get(number))) return false
-  return true
-}
-
-export class ForgeCache {
-  private issues = new Map<number, ForgeIssue>()
-  private prs = new Map<number, ForgePR>()
-  private revision = 0
-
-  apply(delta: ForgeDelta): void {
-    if (delta.kind === 'issue') this.set(this.issues, delta.issue)
-    else if (delta.kind === 'pr') this.set(this.prs, delta.pr)
-    else {
-      const target = delta.target === 'issue' ? this.issues : this.prs
-      if (target.delete(delta.number)) this.revision++
-    }
-  }
-
-  async reconcile(driver: ForgeDriver): Promise<void> {
-    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
-    const nextIssues = new Map(issues.map((i) => [i.number, i]))
-    const nextPRs = new Map(prs.map((p) => [p.number, p]))
-    if (!sameMap(this.issues, nextIssues) || !sameMap(this.prs, nextPRs)) this.revision++
-    this.issues = nextIssues
-    this.prs = nextPRs
-  }
-
-  applyIssues(issues: ForgeIssue[]): void {
-    for (const i of issues) this.set(this.issues, i)
-  }
-  setPRs(prs: ForgePR[]): void {
-    const next = new Map(prs.map((p) => [p.number, p]))
-    if (!sameMap(this.prs, next)) this.revision++
-    this.prs = next
-  }
-
-  view(nodeIds: string[]): NodeLinks[] {
-    return resolveLinks([...this.issues.values()], [...this.prs.values()], nodeIds)
-  }
-
-  state(): { issues: ForgeIssue[]; prs: ForgePR[] } {
-    return { issues: [...this.issues.values()], prs: [...this.prs.values()] }
-  }
-
-  stateRevision(): number {
-    return this.revision
-  }
-
-  private set<T extends ForgeIssue | ForgePR>(target: Map<number, T>, value: T): void {
-    if (JSON.stringify(target.get(value.number)) !== JSON.stringify(value)) {
-      target.set(value.number, value)
-      this.revision++
-    }
-  }
-}

package/spec-forge/src/cli.ts

@@ -1,99 +0,0 @@
-import { loadSpecs } from '../../spec-cli/src/specs.js'
-import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
-import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from './drivers.js'
-import { resolveLinks, type NodeLinks } from './links.js'
-import { resolveEvalPending, type NodeEvalPending } from './needs-eval.js'
-
-function flag(args: string[], name: string): string | undefined {
-  const i = args.indexOf(`--${name}`)
-  return i >= 0 ? args[i + 1] : undefined
-}
-const has = (args: string[], name: string) => args.includes(`--${name}`)
-
-async function readForge(
-  args: string[],
-): Promise<{ driver: ForgeDriver; nodeIds: string[]; issues: ForgeIssue[]; prs: ForgePR[] } | null> {
-  const host = flag(args, 'store') ?? resolveForgeHost()
-  const driver = forgeDriverFor(host)
-  if (!driver) {
-    console.error(`spex issue links: unknown --store '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
-    return null
-  }
-  const nodeIds = (await loadSpecs()).map((s) => s.id)
-  const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
-  return { driver, nodeIds, issues, prs }
-}
-
-function render(links: NodeLinks[]): string {
-  const out: string[] = []
-  for (const n of links) {
-    out.push(`\n${n.node}`)
-    if (n.issues.length) {
-      out.push('  issues:')
-      for (const i of n.issues) out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`)
-    }
-    if (n.prs.length) {
-      out.push('  prs:')
-      for (const p of n.prs) out.push(`    #${p.number} ${p.state}  ${p.title}  ${p.headRefName}  ${p.url}`)
-    }
-  }
-  return out.join('\n')
-}
-
-async function links(args: string[]): Promise<number> {
-  const forge = await readForge(args)
-  if (!forge) return 2
-  const { driver, nodeIds, issues, prs } = forge
-  let resolved = resolveLinks(issues, prs, nodeIds)
-
-  const only = flag(args, 'node')
-  if (only) {
-    if (!nodeIds.includes(only)) { console.error(`spex issue links: no such node '${only}'`); return 1 }
-    resolved = resolved.filter((n) => n.node === only)
-  }
-
-  if (has(args, 'json')) { console.log(JSON.stringify(resolved, null, 2)); return 0 }
-  const nIssues = resolved.reduce((a, n) => a + n.issues.length, 0)
-  const nPRs = resolved.reduce((a, n) => a + n.prs.length, 0)
-  console.log(
-    `spec-forge · ${driver.host} · ${resolved.length} linked node(s) · ${nIssues} issue(s), ${nPRs} pr(s)` +
-      ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`,
-  )
-  if (resolved.length) console.log(render(resolved))
-  return 0
-}
-
-function renderPending(pending: NodeEvalPending[]): string {
-  const out: string[] = []
-  for (const n of pending) {
-    out.push(`\n${n.node}`)
-    for (const i of n.pending) out.push(`    #${i.number} ${i.state}  ${i.title}  (via ${i.via})  ${i.url}`)
-  }
-  return out.join('\n')
-}
-
-async function evalPending(args: string[]): Promise<number> {
-  const forge = await readForge(args)
-  if (!forge) return 2
-  const { driver, nodeIds, issues, prs } = forge
-  let resolved = resolveEvalPending(issues, prs, nodeIds)
-
-  const only = flag(args, 'node')
-  if (only) {
-    if (!nodeIds.includes(only)) { console.error(`spex issue links: no such node '${only}'`); return 1 }
-    resolved = resolved.filter((n) => n.node === only)
-  }
-
-  if (has(args, 'json')) { console.log(JSON.stringify(resolved, null, 2)); return 0 }
-  const nPending = resolved.reduce((a, n) => a + n.pending.length, 0)
-  console.log(
-    `spec-forge · ${driver.host} · ${resolved.length} node(s) with eval pending · ${nPending} issue(s)` +
-      ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`,
-  )
-  if (resolved.length) console.log(renderPending(resolved))
-  return 0
-}
-
-export async function runIssueLinks(args: string[]): Promise<number> {
-  return has(args, 'pending') ? evalPending(args) : links(args)
-}

package/spec-forge/src/drivers/github.ts

@@ -1,132 +0,0 @@
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
-import type { ForgeComment, ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
-
-const run = promisify(execFile)
-
-// maxBuffer is raised above the 1MB default: a busy repo's issue/PR JSON can exceed it
-async function gh<T>(args: string[]): Promise<T> {
-  const { stdout } = await run('gh', args, { maxBuffer: 16 * 1024 * 1024 })
-  return JSON.parse(stdout) as T
-}
-
-export const githubDriver: ForgeDriver = {
-  host: 'github',
-
-  // fetch open and closed in separate `--limit 200` windows and merge, so a flood of closed issues can't crowd the open set out of one shared `--state all` limit
-  async listIssues(): Promise<ForgeIssue[]> {
-    const list = (state: string) =>
-      gh<{ number: number; title: string; body: string; url: string; state: string; labels: { name: string }[]; author: { login: string } | null; createdAt: string; comments: { author: { login: string } | null; body: string; createdAt: string }[] }[]>(
-        ['issue', 'list', '--state', state, '--limit', '200', '--json', 'number,title,body,url,state,labels,author,createdAt,comments'],
-      )
-    const [open, closed] = await Promise.all([list('open'), list('closed')])
-    return [...open, ...closed].map((r) => ({
-      number: r.number,
-      title: r.title,
-      body: r.body ?? '',
-      url: r.url,
-      state: (r.state || '').toLowerCase(),
-      labels: (r.labels ?? []).map((l) => l.name),
-      author: r.author?.login ?? '',
-      createdAt: r.createdAt ?? '',
-      comments: (r.comments ?? []).map((c) => ({ author: c.author?.login ?? '', createdAt: c.createdAt ?? '', body: c.body ?? '' })),
-    }))
-  },
-
-  async listIssuesSince(sinceISO: string): Promise<ForgeIssue[]> {
-    type ApiRow = {
-      number: number; title: string; body: string | null; html_url: string; state: string
-      labels: ({ name?: string } | string)[]; user: { login: string } | null; created_at: string
-      comments: number; pull_request?: unknown
-    }
-    const out: ApiRow[] = []
-    for (let page = 1; page <= 20; page++) {
-      const rows = await gh<ApiRow[]>(['api', `repos/{owner}/{repo}/issues?state=all&since=${encodeURIComponent(sinceISO)}&per_page=100&page=${page}`])
-      out.push(...rows)
-      if (rows.length < 100) break
-    }
-    return Promise.all(out.filter((r) => !r.pull_request).map(async (r) => ({
-      number: r.number,
-      title: r.title,
-      body: r.body ?? '',
-      url: r.html_url,
-      state: (r.state || '').toLowerCase(),
-      labels: (r.labels ?? []).map((l) => (typeof l === 'string' ? l : l.name ?? '')).filter(Boolean),
-      author: r.user?.login ?? '',
-      createdAt: r.created_at ?? '',
-      comments: r.comments > 0 ? await listComments(r.number) : [],
-    })))
-  },
-
-  async listPRs(): Promise<ForgePR[]> {
-    type Row = {
-      number: number; title: string; url: string; state: string; headRefName: string
-      closingIssuesReferences?: { number: number }[]
-    }
-    const base = ['pr', 'list', '--state', 'open', '--limit', '200', '--json']
-    const fields = 'number,title,url,state,headRefName'
-    let rows: Row[]
-    try {
-      rows = await gh<Row[]>([...base, `${fields},closingIssuesReferences`])
-    } catch (err) {
-      if (!isUnknownFieldError(err)) throw err
-      warnNoTransitiveOnce()
-      rows = await gh<Row[]>([...base, fields])
-    }
-    return rows.map((r) => ({
-      number: r.number,
-      title: r.title,
-      url: r.url,
-      state: r.state,
-      headRefName: r.headRefName,
-      closesIssues: (r.closingIssuesReferences ?? []).map((c) => c.number),
-    }))
-  },
-
-  async createIssue({ title, body }: { title: string; body: string }): Promise<{ number: number; url: string }> {
-    const { stdout } = await run('gh', ['issue', 'create', '--title', title, '--body', body], { maxBuffer: 1024 * 1024 })
-    const url = stdout.trim().split('\n').pop() ?? ''
-    const number = parseInt(url.split('/').pop() ?? '', 10)
-    if (!url.startsWith('http') || !Number.isFinite(number)) throw new Error(`gh issue create returned an unexpected result: ${stdout.trim()}`)
-    return { number, url }
-  },
-
-  async createComment({ number, body }: { number: number; body: string }): Promise<{ url: string }> {
-    const { stdout } = await run('gh', ['issue', 'comment', String(number), '--body', body], { maxBuffer: 1024 * 1024 })
-    const url = stdout.trim().split('\n').pop() ?? ''
-    if (!url.startsWith('http')) throw new Error(`gh issue comment returned an unexpected result: ${stdout.trim()}`)
-    return { url }
-  },
-
-  // the lifecycle write verb (see port.ts). `gh issue close` does not reliably print a permalink, so read
-  // the issue URL back through gh's JSON surface after the close succeeds.
-  async closeIssue({ number }: { number: number }): Promise<{ url: string }> {
-    await run('gh', ['issue', 'close', String(number)], { maxBuffer: 1024 * 1024 })
-    const r = await gh<{ url: string }>(['issue', 'view', String(number), '--json', 'url'])
-    if (!r.url?.startsWith('http')) throw new Error(`gh issue view returned an unexpected url after close: ${JSON.stringify(r)}`)
-    return { url: r.url }
-  },
-}
-
-async function listComments(number: number): Promise<ForgeComment[]> {
-  const rows = await gh<{ user: { login: string } | null; body: string | null; created_at: string }[]>(
-    ['api', `repos/{owner}/{repo}/issues/${number}/comments?per_page=100`],
-  )
-  return rows.map((c) => ({ author: c.user?.login ?? '', createdAt: c.created_at ?? '', body: c.body ?? '' }))
-}
-
-function isUnknownFieldError(err: unknown): boolean {
-  const e = err as { stderr?: string; message?: string }
-  const text = `${e?.stderr ?? ''}\n${e?.message ?? ''}`
-  return /unknown json field/i.test(text)
-}
-
-let warnedNoTransitive = false
-function warnNoTransitiveOnce(): void {
-  if (warnedNoTransitive) return
-  warnedNoTransitive = true
-  console.warn(
-    'spec-forge: this `gh` is too old for `closingIssuesReferences` — transitive issue↔PR links are ' +
-      'disabled (branch + `Spec:` marker links still work). Upgrade `gh` to restore them.',
-  )
-}

package/spec-forge/src/drivers/gitlab.ts

@@ -1,153 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import type { ForgeComment, ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
-
-type Ctx = { base: string; host: string; project: string; token: string }
-let ctx: Ctx | null = null
-
-function gitlabCtx(): Ctx {
-  if (ctx) return ctx
-  const remote = execFileSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf8' }).trim()
-  const parsed = parseRemote(remote)
-  if (!parsed) throw new Error(`gitlab: cannot parse origin remote '${remote}' as a GitLab URL`)
-  const token = process.env.GITLAB_TOKEN || credentialToken(parsed.host)
-  if (!token) {
-    throw new Error(
-      `gitlab: no token for ${parsed.host} — set GITLAB_TOKEN, or store a PAT in git's credential store:\n` +
-        `  printf "protocol=https\\nhost=${parsed.host}\\nusername=<user>\\npassword=<token>\\n\\n" | git credential approve`,
-    )
-  }
-  ctx = { ...parsed, token }
-  return ctx
-}
-
-export function parseRemote(remote: string): { base: string; host: string; project: string } | null {
-  let m = remote.match(/^(https?:\/\/[^/]+)\/(.+?)(?:\.git)?\/?$/)
-  if (m) return { base: m[1], host: m[1].replace(/^https?:\/\//, ''), project: m[2] }
-  m = remote.match(/^(?:ssh:\/\/)?[\w.-]+@([\w.-]+)(?::\d+)?[:/](.+?)(?:\.git)?\/?$/)
-  if (m) return { base: `https://${m[1]}`, host: m[1], project: m[2] }
-  return null
-}
-
-function credentialToken(host: string): string {
-  try {
-    const out = execFileSync('git', ['credential', 'fill'], {
-      input: `protocol=https\nhost=${host}\n\n`,
-      encoding: 'utf8',
-      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'true' },
-      stdio: ['pipe', 'pipe', 'ignore'],
-    })
-    return out.match(/^password=(.+)$/m)?.[1] ?? ''
-  } catch {
-    return ''
-  }
-}
-
-async function api<T>(path: string, init?: RequestInit): Promise<T> {
-  const { base, project, token } = gitlabCtx()
-  const sep = path.includes('?') ? '&' : '?'
-  const url = `${base}/api/v4/projects/${encodeURIComponent(project)}/${path}${init?.method ? '' : `${sep}per_page=100`}`
-  const res = await fetch(url, {
-    ...init,
-    headers: { 'PRIVATE-TOKEN': token, 'content-type': 'application/json', ...init?.headers },
-  })
-  if (!res.ok) throw new Error(`gitlab: ${init?.method ?? 'GET'} ${path} → ${res.status} ${(await res.text()).slice(0, 300)}`)
-  return (await res.json()) as T
-}
-
-// GitLab's API has no bounded list query; stop at a short page and cap the walk.
-async function paged<T>(path: string): Promise<T[]> {
-  const sep = path.includes('?') ? '&' : '?'
-  const out: T[] = []
-  for (let page = 1; page <= 20; page++) {
-    const rows = await api<T[]>(`${path}${sep}page=${page}`)
-    out.push(...rows)
-    if (rows.length < 100) break
-  }
-  return out
-}
-
-type ApiIssue = {
-  iid: number; title: string; description: string | null; web_url: string; state: string
-  labels: string[]; author: { username: string } | null; created_at: string; user_notes_count: number
-}
-
-async function toIssue(r: ApiIssue): Promise<ForgeIssue> {
-  return {
-    number: r.iid,
-    title: r.title,
-    body: r.description ?? '',
-    url: r.web_url,
-    state: normalizeState(r.state),
-    labels: r.labels ?? [],
-    author: r.author?.username ?? '',
-    createdAt: r.created_at ?? '',
-    comments: r.user_notes_count > 0 ? await listNotes(r.iid) : [],
-  }
-}
-
-function normalizeState(state: string): string {
-  const s = (state || '').toLowerCase()
-  return s === 'opened' ? 'open' : s
-}
-
-async function listNotes(iid: number): Promise<ForgeComment[]> {
-  type Note = { system: boolean; author: { username: string } | null; created_at: string; body: string | null }
-  const rows = await paged<Note>(`issues/${iid}/notes`)
-  return rows
-    .filter((n) => !n.system)
-    .map((n) => ({ author: n.author?.username ?? '', createdAt: n.created_at ?? '', body: n.body ?? '' }))
-}
-
-export const gitlabDriver: ForgeDriver = {
-  host: 'gitlab',
-
-  async listIssues(): Promise<ForgeIssue[]> {
-    const rows = await paged<ApiIssue>('issues?state=all')
-    return Promise.all(rows.map(toIssue))
-  },
-
-  async listIssuesSince(sinceISO: string): Promise<ForgeIssue[]> {
-    const rows = await paged<ApiIssue>(`issues?state=all&updated_after=${encodeURIComponent(sinceISO)}`)
-    return Promise.all(rows.map(toIssue))
-  },
-
-  async listPRs(): Promise<ForgePR[]> {
-    type ApiMR = { iid: number; title: string; web_url: string; state: string; source_branch: string }
-    const rows = await paged<ApiMR>('merge_requests?state=opened')
-    return Promise.all(
-      rows.map(async (r) => ({
-        number: r.iid,
-        title: r.title,
-        url: r.web_url,
-        state: normalizeState(r.state),
-        headRefName: r.source_branch,
-        closesIssues: (await paged<{ iid: number }>(`merge_requests/${r.iid}/closes_issues`)).map((i) => i.iid),
-      })),
-    )
-  },
-
-  async createIssue({ title, body }: { title: string; body: string }): Promise<{ number: number; url: string }> {
-    const r = await api<{ iid: number; web_url: string }>('issues', {
-      method: 'POST',
-      body: JSON.stringify({ title, description: body }),
-    })
-    if (!r.web_url?.startsWith('http') || !Number.isFinite(r.iid)) throw new Error(`gitlab: issue create returned an unexpected result: ${JSON.stringify(r)}`)
-    return { number: r.iid, url: r.web_url }
-  },
-
-  async createComment({ number, body }: { number: number; body: string }): Promise<{ url: string }> {
-    const { base, project } = gitlabCtx()
-    const r = await api<{ id: number }>(`issues/${number}/notes`, { method: 'POST', body: JSON.stringify({ body }) })
-    if (!Number.isFinite(r.id)) throw new Error(`gitlab: note create returned an unexpected result: ${JSON.stringify(r)}`)
-    return { url: `${base}/${project}/-/issues/${number}#note_${r.id}` }
-  },
-
-  async closeIssue({ number }: { number: number }): Promise<{ url: string }> {
-    const r = await api<{ web_url: string; state: string }>(`issues/${number}`, {
-      method: 'PUT',
-      body: JSON.stringify({ state_event: 'close' }),
-    })
-    if (!r.web_url?.startsWith('http')) throw new Error(`gitlab: issue close returned an unexpected result: ${JSON.stringify(r)}`)
-    return { url: r.web_url }
-  },
-}