spexcode 0.5.8 → 0.5.9

package/spec-forge/src/cache.ts

@@ -6,39 +6,61 @@ export type ForgeDelta =
   | { 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.issues.set(delta.issue.number, delta.issue)
-    else if (delta.kind === 'pr') this.prs.set(delta.pr.number, delta.pr)
-    else (delta.target === 'issue' ? this.issues : this.prs).delete(delta.number)
+    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()])
-    this.issues = new Map(issues.map((i) => [i.number, i]))
-    this.prs = new Map(prs.map((p) => [p.number, p]))
+    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
   }
 
-  // the INCREMENTAL halves reconcile() is made of: merge an updated-since issue window over the map
-  // (an issue never leaves — a closed one just updates in place), and replace the PR set (the open-PR
-  // list is small and self-truncating, so full replacement IS its delta).
   applyIssues(issues: ForgeIssue[]): void {
-    for (const i of issues) this.issues.set(i.number, i)
+    for (const i of issues) this.set(this.issues, i)
   }
   setPRs(prs: ForgePR[]): void {
-    this.prs = new Map(prs.map((p) => [p.number, p]))
+    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)
   }
 
-  // the raw cached set — for the one consumer (the unified Issue port, spec-cli issues.ts) that needs
-  // EVERY cached issue, linked or not. Resolution stays the only derived view (view() above).
   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

@@ -4,7 +4,6 @@ import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from './drivers.js'
 import { resolveLinks, type NodeLinks } from './links.js'
 import { resolveEvalPending, type NodeEvalPending } from './needs-eval.js'
 
-// tiny flag reader over this command's own arg slice (everything after `forge`), so cli.ts stays routing-only.
 function flag(args: string[], name: string): string | undefined {
   const i = args.indexOf(`--${name}`)
   return i >= 0 ? args[i + 1] : undefined
@@ -14,8 +13,6 @@ const has = (args: string[], name: string) => args.includes(`--${name}`)
 async function readForge(
   args: string[],
 ): Promise<{ driver: ForgeDriver; nodeIds: string[]; issues: ForgeIssue[]; prs: ForgePR[] } | null> {
-  // the forge is a VALUE, never a command ([[cli-surface]]): `--store <host>` names it, mirroring the
-  // store axis every other issue verb uses.
   const host = flag(args, 'store') ?? resolveForgeHost()
   const driver = forgeDriverFor(host)
   if (!driver) {
@@ -97,9 +94,6 @@ async function evalPending(args: string[]): Promise<number> {
   return 0
 }
 
-// `spex issue links [--pending]` ([[cli-surface]]): the read-only forge→spec trace, folded into the issue
-// drawer (the forge drawer is dissolved — a forge is a value, `--store`). Bare = every linked node's open
-// issues/PRs; --pending narrows to the threads still awaiting an eval reading (the old eval-pending view).
 export async function runIssueLinks(args: string[]): Promise<number> {
   return has(args, 'pending') ? evalPending(args) : links(args)
 }

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

@@ -17,7 +17,6 @@ export const githubDriver: ForgeDriver = {
   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 }[] }[]>(
-        // comments ride the same list read (no per-issue fetch) — heavier GraphQL points, covered by the resident cache's TTL
         ['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')])
@@ -26,7 +25,7 @@ export const githubDriver: ForgeDriver = {
       title: r.title,
       body: r.body ?? '',
       url: r.url,
-      state: (r.state || '').toLowerCase(),   // one canonical casing at the adapter (gh GraphQL says OPEN, REST says open)
+      state: (r.state || '').toLowerCase(),
       labels: (r.labels ?? []).map((l) => l.name),
       author: r.author?.login ?? '',
       createdAt: r.createdAt ?? '',
@@ -34,9 +33,6 @@ export const githubDriver: ForgeDriver = {
     }))
   },
 
-  // the INCREMENTAL window: only issues updated since `sinceISO` (GitHub REST honors `since` = updated-at),
-  // paged manually (100/page, stop on a short page — an incremental window is normally one page). PRs ride
-  // the same REST endpoint flagged with `pull_request` and are filtered out — the PR list keeps its own path.
   async listIssuesSince(sinceISO: string): Promise<ForgeIssue[]> {
     type ApiRow = {
       number: number; title: string; body: string | null; html_url: string; state: string
@@ -49,8 +45,6 @@ export const githubDriver: ForgeDriver = {
       out.push(...rows)
       if (rows.length < 100) break
     }
-    // REST's since-window carries only a comment COUNT — fetch each commented issue's thread alongside
-    // (the window is normally a handful of issues, so this stays a handful of calls, not a re-list).
     return Promise.all(out.filter((r) => !r.pull_request).map(async (r) => ({
       number: r.number,
       title: r.title,
@@ -89,8 +83,6 @@ export const githubDriver: ForgeDriver = {
     }))
   },
 
-  // the port's first write verb (promotion — see port.ts). `gh issue create` prints the new issue's URL on
-  // stdout; the number is its last path segment. Fails loud like every other driver call.
   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() ?? ''
@@ -99,8 +91,6 @@ export const githubDriver: ForgeDriver = {
     return { number, url }
   },
 
-  // the second write verb (a store-routed reply — see port.ts). `gh issue comment` prints the new
-  // comment's permalink on stdout. Fails loud like every other driver call.
   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() ?? ''
@@ -118,7 +108,6 @@ export const githubDriver: ForgeDriver = {
   },
 }
 
-// one commented issue's thread, REST (the incremental window's companion read).
 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`],

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

@@ -1,11 +1,6 @@
 import { execFileSync } from 'node:child_process'
 import type { ForgeComment, ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
 
-// @@@gitlab context — resolved once, lazily, from the repo the command runs in.
-// base + project come from `git remote get-url origin` (https://host/group/proj.git and
-// git@host:group/proj.git forms both collapse to { base: https://host, project: group/proj });
-// the token is never a config value: GITLAB_TOKEN env first, else git's own credential store
-// (`git credential fill` — the same place a push to that host already authenticates from).
 type Ctx = { base: string; host: string; project: string; token: string }
 let ctx: Ctx | null = null
 
@@ -26,17 +21,13 @@ function gitlabCtx(): Ctx {
 }
 
 export function parseRemote(remote: string): { base: string; host: string; project: string } | null {
-  // https://host[:port]/group/sub/project(.git)
   let m = remote.match(/^(https?:\/\/[^/]+)\/(.+?)(?:\.git)?\/?$/)
   if (m) return { base: m[1], host: m[1].replace(/^https?:\/\//, ''), project: m[2] }
-  // git@host:group/project(.git)  |  ssh://git@host[:port]/group/project(.git)
   m = remote.match(/^(?:ssh:\/\/)?[\w.-]+@([\w.-]+)(?::\d+)?[:/](.+?)(?:\.git)?\/?$/)
   if (m) return { base: `https://${m[1]}`, host: m[1], project: m[2] }
   return null
 }
 
-// ask git's credential store for the host's password (the PAT) — read-only: `fill`, never
-// `approve`/`reject`. Prompting is disabled so an unconfigured host fails fast instead of hanging.
 function credentialToken(host: string): string {
   try {
     const out = execFileSync('git', ['credential', 'fill'], {
@@ -63,7 +54,7 @@ async function api<T>(path: string, init?: RequestInit): Promise<T> {
   return (await res.json()) as T
 }
 
-// full pagination for list reads — stop on a short page (100/page, 20-page ceiling like github's window)
+// 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[] = []
@@ -80,16 +71,13 @@ type ApiIssue = {
   labels: string[]; author: { username: string } | null; created_at: string; user_notes_count: number
 }
 
-// GitLab's list read cannot embed the thread (no `comments` field), so each COMMENTED issue's
-// notes are fetched alongside — user_notes_count already excludes system notes, so uncommented
-// issues (the common case) cost nothing extra; the resident cache's TTL covers the rest.
 async function toIssue(r: ApiIssue): Promise<ForgeIssue> {
   return {
-    number: r.iid, // per-project iid, the number a human sees on the host — never the global id
+    number: r.iid,
     title: r.title,
     body: r.description ?? '',
     url: r.web_url,
-    state: normalizeState(r.state), // GitLab says `opened`; the port's canonical open-state is `open`
+    state: normalizeState(r.state),
     labels: r.labels ?? [],
     author: r.author?.username ?? '',
     createdAt: r.created_at ?? '',
@@ -106,7 +94,7 @@ 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) // system notes are lifecycle noise (label/assign/close events), not discussion
+    .filter((n) => !n.system)
     .map((n) => ({ author: n.author?.username ?? '', createdAt: n.created_at ?? '', body: n.body ?? '' }))
 }
 
@@ -118,8 +106,6 @@ export const gitlabDriver: ForgeDriver = {
     return Promise.all(rows.map(toIssue))
   },
 
-  // the INCREMENTAL window — GitLab's `updated_after` is the direct analog of GitHub's `since`
-  // (updated-at ≥ the moment), and its issues endpoint never mixes MRs in, so no filtering needed.
   async listIssuesSince(sinceISO: string): Promise<ForgeIssue[]> {
     const rows = await paged<ApiIssue>(`issues?state=all&updated_after=${encodeURIComponent(sinceISO)}`)
     return Promise.all(rows.map(toIssue))
@@ -128,7 +114,6 @@ export const gitlabDriver: ForgeDriver = {
   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')
-    // GitLab resolves "Closes #N" server-side — one small read per OPEN MR, no description parsing
     return Promise.all(
       rows.map(async (r) => ({
         number: r.iid,

package/spec-forge/src/drivers.ts

@@ -12,22 +12,11 @@ export function forgeDriverFor(host: string): ForgeDriver | undefined {
   return FORGE_DRIVERS.find((d) => d.host === host)
 }
 
-// the issue stores a THIS repo's forge offers — scoped to the RESOLVED host, not every registered
-// driver, so a gitlab repo never gets a 'github' store in its New-issue dropdown. A resolved host
-// whose driver isn't registered yet contributes no store (the local store always remains).
 export function forgeIssueStores(): { id: string; label: string; kind: 'forge' }[] {
   const driver = forgeDriverFor(resolveForgeHost())
   return driver ? [{ id: driver.host, label: driver.host, kind: 'forge' }] : []
 }
 
-// ── host resolution ([[forge-host]]) ─────────────────────────────────────────────────────────────
-// WHICH forge a repo talks to is a repo fact, not a constant: derived from the origin remote, with an
-// explicit `forge.host` in spexcode.json / spexcode.local.json winning over the derivation, and
-// DEFAULT_FORGE_HOST only when nothing resolves (no repo, no origin). The resolved host may name a
-// driver that isn't registered yet (e.g. 'gitlab' before its driver lands) — callers degrade to an
-// empty forge slice via forgeDriverFor returning undefined, never to a wrong-host network call.
-
-// strip git's hook-exported env so repo discovery works from the filesystem (mirrors spec-cli git.ts)
 function gitEnv(): NodeJS.ProcessEnv {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
@@ -40,9 +29,6 @@ function gitOut(args: string[]): string | null {
   } catch { return null }
 }
 
-// the `forge.host` config override — local over committed, same layering readConfig applies. Read here
-// (not via spec-cli) so the seam stays inside spec-forge; a malformed config file still fails LOUD,
-// exactly like spec-cli's readJsonConfig, rather than silently reverting the override.
 function configuredHost(): string | null {
   const root = gitOut(['rev-parse', '--show-toplevel'])
   if (!root) return null
@@ -58,7 +44,6 @@ function configuredHost(): string | null {
   return null
 }
 
-// hostname out of the two remote-URL shapes: a real scheme URL, or scp-like `git@host:owner/repo.git`
 function remoteHostname(url: string): string | null {
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
     try { return new URL(url).hostname || null } catch { return null }
@@ -67,9 +52,6 @@ function remoteHostname(url: string): string | null {
   return scp ? scp[1] : null
 }
 
-// hostname → host id. The SaaS vendors match by name; every OTHER resolvable remote is read as
-// self-hosted GitLab (the common self-hosted forge shape, e.g. dev.aminer.cn) — a wrong guess costs
-// only an empty slice (no driver ever runs against the wrong host) and `forge.host` corrects it.
 function hostFor(hostname: string): string {
   const h = hostname.toLowerCase()
   if (h.includes('github')) return 'github'

package/spec-forge/src/links.ts

@@ -40,7 +40,6 @@ export function resolveLinks(
     return s
   }
 
-  // PRs: branch → node (free structural link), and remember which node each PR belongs to.
   const prNode = new Map<number, string>()
   for (const pr of prs) {
     const node = branchToNode(pr.headRefName, nodeIds)
@@ -49,7 +48,6 @@ export function resolveLinks(
     slot(node).prs.set(pr.number, { ...pr, via: 'branch' })
   }
 
-  // Issues by marker — the explicit convention. Unknown ids are dropped (no inventing nodes).
   const issueByNumber = new Map(issues.map((i) => [i.number, i]))
   for (const issue of issues) {
     for (const id of parseSpecMarkers(issue.body)) {
@@ -57,8 +55,6 @@ export function resolveLinks(
     }
   }
 
-  // Transitive: a PR on a node branch that closes an issue links that issue to the node — unless a marker
-  // already linked it (marker wins, so we don't overwrite the explicit source with the inferred one).
   for (const pr of prs) {
     const node = prNode.get(pr.number)
     if (!node) continue

package/spec-forge/src/needs-eval.ts

@@ -3,7 +3,6 @@ import { resolveLinks, type LinkedIssue } from './links.js'
 
 export const NEEDS_EVAL = 'needs-eval'
 
-// a bare-marker body line: the name alone, case-insensitive, any indent, optional trailing colon — content after it (`needs-eval: foo`) is NOT a match
 const BODY_MARKER = new RegExp(`^\\s*${NEEDS_EVAL}\\s*:?\\s*$`, 'im')
 
 export function isNeedsEval(issue: ForgeIssue): boolean {

package/spec-forge/src/port.ts

@@ -1,5 +1,3 @@
-// a forge issue's comment — the shape that becomes a unified Issue's Reply verbatim (author→by,
-// createdAt→at, body→body), so both stores' threads are one thread type downstream.
 export type ForgeComment = {
   author: string
   createdAt: string
@@ -13,12 +11,8 @@ export type ForgeIssue = {
   url: string
   state: string
   labels: string[]
-  // who opened it and when — what lets a forge issue stand beside a local issue thread as the same
-  // object in the unified Issue port (spec-cli issues.ts) with a `by` and a `created`.
   author: string
   createdAt: string
-  // the discussion under it — rides the same reads (list/since), so the unified Issue port maps it
-  // into replies[] with no second fetch path.
   comments: ForgeComment[]
 }
 
@@ -35,14 +29,8 @@ export interface ForgeDriver {
   readonly host: string
   listIssues(): Promise<ForgeIssue[]>
   listPRs(): Promise<ForgePR[]>
-  // the port's issue write verbs — used solely by the unified Issue port (spec-cli issues.ts): promotion
-  // creates an issue, a store-routed reply comments on one, and close advances the forge issue's own
-  // lifecycle. The driver stays the only network toucher; the tracer never calls these; node state is never touched.
   createIssue(input: { title: string; body: string }): Promise<{ number: number; url: string }>
   createComment(input: { number: number; body: string }): Promise<{ url: string }>
   closeIssue(input: { number: number }): Promise<{ url: string }>
-  // optional INCREMENTAL window — only issues whose updated-at ≥ sinceISO. A driver that offers it lets
-  // the resident cache merge small deltas between periodic full reconciles instead of re-listing the
-  // world every TTL; a driver without it simply always full-lists.
   listIssuesSince?(sinceISO: string): Promise<ForgeIssue[]>
 }

package/spec-forge/src/resident.ts

@@ -4,26 +4,14 @@ import type { ForgeIssue, ForgePR } from './port.js'
 
 const cache = new ForgeCache()
 let inFlight: Promise<void> | null = null
-// track last ATTEMPT, not last success, so the TTL also backs off failures — else a forge-less repo respawns `gh` every poll
 let lastAttempt = 0
-// tuned to the dashboard's LIVE cadence: the issues page re-polls /api/issues every ~15s and each poll
-// opportunistically triggers this refresh, so a TTL near the poll cadence means an externally-posted forge
-// issue surfaces on the board within ~one poll+cycle (~15–30s) with no page reload — the "post a github
-// issue → it just appears" contract. Each cycle is a tiny incremental read (one page), well inside
-// GitHub's rate budget; the back-off still covers a forge-less repo (a failed probe updates lastAttempt).
 const TTL_MS = 20_000
-// incremental-first: after the seeding full reconcile, each TTL cycle fetches only the updated-since
-// window (tiny — normally one page) and merges it; a periodic full reconcile stays as the backstop for
-// what an update window can't see (deleted/transferred issues).
 let lastIssueSync: string | null = null
 let lastFull = 0
 const FULL_MS = 30 * 60_000
 
 function refreshIfStale(now: number): void {
   if (inFlight || (lastAttempt && now - lastAttempt < TTL_MS)) return
-  // the driver is picked per cycle from the RESOLVED host ([[forge-host]]: repo remote / forge.host
-  // override) — a host whose driver isn't registered yet (e.g. a gitlab remote before a gitlab driver
-  // lands) keeps the slice empty without spawning anything, never a wrong-host `gh` call or a throw
   const driver = forgeDriverFor(resolveForgeHost())
   if (!driver) return
   lastAttempt = now
@@ -40,19 +28,15 @@ function refreshIfStale(now: number): void {
     .finally(() => { inFlight = null })
 }
 
-// the raw cached forge set, same freshness contract as the view (instant, background reconcile) — the
-// server-side slice the unified Issue port (spec-cli issues.ts) merges with the local store.
 export function residentForgeState(): { issues: ForgeIssue[]; prs: ForgePR[] } {
   refreshIfStale(Date.now())
   return cache.state()
 }
 
-// a write must show up where it lands: after the server posts a forge comment, force one refresh past the
-// TTL and await it, so the next read carries the real read-back (never a local echo). Coalesces with an
-// in-flight cycle first — a refresh started BEFORE the write could read the pre-write world. The forced
-// cycle is a FULL re-list, never the incremental window: the REST since-read can lag a just-posted write,
-// and a lagged cycle advances the watermark PAST it — the write would then be invisible until the next
-// full reconcile. The full list reads the same backend the write went to, so the read-back is real.
+export function residentForgeRevision(): number {
+  return cache.stateRevision()
+}
+
 export async function refreshForgeNow(): Promise<void> {
   if (inFlight) await inFlight
   lastAttempt = 0