npm - spexcode - Versions diffs - 0.1.6 → 0.2.1 - Mend

spexcode 0.1.6 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (73) hide show

package/README.md +99 -35
package/README.zh-CN.md +135 -0
package/package.json +5 -6
package/spec-cli/README.md +86 -0
package/spec-cli/bin/spex.mjs +15 -3
package/spec-cli/hooks/dispatch.sh +20 -8
package/spec-cli/hooks/harness.sh +18 -11
package/spec-cli/src/board.ts +47 -18
package/spec-cli/src/boardCache.ts +70 -0
package/spec-cli/src/boardDelta.ts +90 -0
package/spec-cli/src/boardStream.ts +178 -0
package/spec-cli/src/cli.ts +184 -122
package/spec-cli/src/client.ts +6 -4
package/spec-cli/src/gateway.ts +64 -24
package/spec-cli/src/git.ts +105 -92
package/spec-cli/src/guide.ts +186 -19
package/spec-cli/src/harness-select.ts +63 -0
package/spec-cli/src/harness.ts +506 -100
package/spec-cli/src/help.ts +362 -0
package/spec-cli/src/hooks.ts +0 -14
package/spec-cli/src/index.ts +279 -32
package/spec-cli/src/init.ts +41 -1
package/spec-cli/src/issues.ts +301 -0
package/spec-cli/src/layout.ts +70 -28
package/spec-cli/src/lint.ts +12 -10
package/spec-cli/src/listen.ts +28 -0
package/spec-cli/src/localIssues.ts +700 -0
package/spec-cli/src/materialize.ts +182 -27
package/spec-cli/src/mentions.ts +192 -0
package/spec-cli/src/plugin-harness.ts +145 -0
package/spec-cli/src/pty-bridge.ts +378 -81
package/spec-cli/src/self.ts +123 -20
package/spec-cli/src/sessions.ts +461 -298
package/spec-cli/src/specs.ts +55 -14
package/spec-cli/src/supervise.ts +23 -3
package/spec-cli/src/tsx-bin.ts +14 -5
package/spec-cli/src/uninstall.ts +146 -0
package/spec-cli/templates/hooks/post-merge +27 -0
package/spec-cli/templates/hooks/pre-commit +51 -31
package/spec-cli/templates/hooks/prepare-commit-msg +31 -8
package/spec-cli/templates/presets/careful/.config/clarify-before-code/spec.md +11 -0
package/spec-cli/templates/spec/project/.config/core/spec-of-file/spec-of-file.sh +26 -3
package/spec-cli/templates/spec/project/.config/core/spec.md +4 -0
package/spec-cli/templates/spec/project/.config/core/stop-gate/stop-gate.sh +16 -4
package/spec-cli/templates/spec/project/.config/extract/spec.md +1 -1
package/spec-cli/templates/spec/project/.config/regroup/spec.md +1 -1
package/spec-cli/templates/spec/project/.config/reproduce-before-fix/spec.md +18 -0
package/spec-cli/templates/spec/project/.config/spec.md +3 -3
package/spec-cli/templates/spec/project/.config/supervisor/spec.md +2 -2
package/spec-cli/templates/spec/project/.config/tidy/spec.md +1 -1
package/spec-cli/templates/spec/project/spec.md +2 -2
package/spec-dashboard/dist/assets/index-Ct_ubwrd.css +32 -0
package/spec-dashboard/dist/assets/index-DehTZ-h9.js +145 -0
package/spec-dashboard/dist/index.html +17 -5
package/spec-forge/src/cache.ts +16 -0
package/spec-forge/src/cli.ts +4 -10
package/spec-forge/src/drivers/github.ts +74 -4
package/spec-forge/src/drivers.ts +13 -0
package/spec-forge/src/port.ts +25 -0
package/spec-forge/src/resident.ts +40 -6
package/spec-yatsu/src/cli.ts +227 -38
package/spec-yatsu/src/evaltab.ts +169 -19
package/spec-yatsu/src/filing.ts +48 -0
package/spec-yatsu/src/freshness.ts +55 -20
package/spec-yatsu/src/proof.ts +89 -3
package/spec-yatsu/src/scenariofresh.ts +92 -0
package/spec-yatsu/src/sidecar.ts +75 -11
package/spec-yatsu/src/timeline.ts +47 -0
package/spec-yatsu/src/yatsu.ts +47 -3
package/spec-cli/src/relay.ts +0 -28
package/spec-cli/templates/spec/project/.config/scenario/spec.md +0 -32
package/spec-dashboard/dist/assets/index-Bk4E1EQy.js +0 -139
package/spec-dashboard/dist/assets/index-Cq7hwngj.css +0 -32

package/spec-dashboard/dist/index.html CHANGED Viewed

@@ -4,11 +4,23 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>SpexCode</title>
-    <!-- tab-icon: pre-load default favicon (🔭, on brand with the watch glyph); a configured dashboard.icon
-         replaces it at runtime once the board loads. Inline emoji SVG — no asset to ship. -->
-    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E%F0%9F%94%AD%3C/text%3E%3C/svg%3E" />
-    <script type="module" crossorigin src="/assets/index-Bk4E1EQy.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Cq7hwngj.css">
+    <!-- tab-icon: pre-load default favicon (the SpexCode mark — a spec-tree glyph on a compass arc);
+         a configured dashboard.icon replaces it at runtime once the board loads. Inline SVG — no asset to ship. -->
+    <link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2064%2064'%3E%3Crect%20x='2'%20y='2'%20width='60'%20height='60'%20rx='14'%20fill='%236b46c1'/%3E%3Cpath%20d='M15%2035%20Q32%2044%2049%2035'%20stroke='%23fff'%20stroke-width='2.8'%20fill='none'%20stroke-linecap='round'/%3E%3Cg%20stroke='%23fff'%20stroke-width='3.2'%20stroke-linecap='round'%20fill='none'%3E%3Cpath%20d='M32%2017%20L20%2042'/%3E%3Cpath%20d='M32%2017%20L44%2042'/%3E%3C/g%3E%3Cg%20fill='%23fff'%3E%3Ccircle%20cx='32'%20cy='16.5'%20r='5'/%3E%3Ccircle%20cx='20'%20cy='42.6'%20r='5'/%3E%3Ccircle%20cx='44'%20cy='42.6'%20r='5'/%3E%3C/g%3E%3C/svg%3E" />
+    <!-- theme: apply the saved light/dark choice (else the OS preference) to <html data-theme> BEFORE
+         first paint, so there's no light-flash before the module boots. Mirrors theme.js's getTheme(). -->
+    <script>
+      (function () {
+        try {
+          var t = localStorage.getItem('spexcode.theme')
+          if (t !== 'light' && t !== 'dark')
+            t = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+          document.documentElement.setAttribute('data-theme', t)
+        } catch (e) { /* localStorage/matchMedia unavailable — default (light) stands */ }
+      })()
+    </script>
+    <script type="module" crossorigin src="/assets/index-DehTZ-h9.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Ct_ubwrd.css">
   </head>
   <body>
     <div id="root"></div>

package/spec-forge/src/cache.ts CHANGED Viewed

@@ -22,7 +22,23 @@ export class ForgeCache {
     this.prs = new Map(prs.map((p) => [p.number, p]))
   }
+  // 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)
+  }
+  setPRs(prs: ForgePR[]): void {
+    this.prs = new Map(prs.map((p) => [p.number, p]))
+  }
   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()] }
+  }
 }

package/spec-forge/src/cli.ts CHANGED Viewed

@@ -1,15 +1,9 @@
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
-import { githubDriver } from './drivers/github.js'
+import { DEFAULT_FORGE_HOST, FORGE_DRIVERS, forgeDriverFor } from './drivers.js'
 import { resolveLinks, type NodeLinks } from './links.js'
 import { resolveEvalPending, type NodeEvalPending } from './needs-yatsu-eval.js'
-const DRIVERS: ForgeDriver[] = [githubDriver]
-const DEFAULT_HOST = 'github'
-function driverFor(host: string): ForgeDriver | undefined {
-  return DRIVERS.find((d) => d.host === host)
-}
 // 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}`)
@@ -20,10 +14,10 @@ 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, 'host') ?? DEFAULT_HOST
-  const driver = driverFor(host)
+  const host = flag(args, 'host') ?? DEFAULT_FORGE_HOST
+  const driver = forgeDriverFor(host)
   if (!driver) {
-    console.error(`forge: unknown host '${host}' (known: ${DRIVERS.map((d) => d.host).join(', ')})`)
+    console.error(`forge: unknown host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
     return null
   }
   const nodeIds = (await loadSpecs()).map((s) => s.id)

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

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
-import type { ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
+import type { ForgeComment, ForgeDriver, ForgeIssue, ForgePR } from '../port.js'
 const run = promisify(execFile)
@@ -16,8 +16,9 @@ export const githubDriver: ForgeDriver = {
   // 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 }[] }[]>(
-        ['issue', 'list', '--state', state, '--limit', '200', '--json', 'number,title,body,url,state,labels'],
+      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')])
     return [...open, ...closed].map((r) => ({
@@ -25,11 +26,44 @@ export const githubDriver: ForgeDriver = {
       title: r.title,
       body: r.body ?? '',
       url: r.url,
-      state: r.state,
+      state: (r.state || '').toLowerCase(),   // one canonical casing at the adapter (gh GraphQL says OPEN, REST says open)
       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 ?? '' })),
     }))
   },
+  // 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
+      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
+    }
+    // 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,
+      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
@@ -54,6 +88,42 @@ export const githubDriver: ForgeDriver = {
       closesIssues: (r.closingIssuesReferences ?? []).map((c) => c.number),
     }))
   },
+  // 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() ?? ''
+    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 }
+  },
+  // 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() ?? ''
+    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 }
+  },
+}
+// 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`],
+  )
+  return rows.map((c) => ({ author: c.user?.login ?? '', createdAt: c.created_at ?? '', body: c.body ?? '' }))
 }
 function isUnknownFieldError(err: unknown): boolean {

package/spec-forge/src/drivers.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import type { ForgeDriver } from './port.js'
+import { githubDriver } from './drivers/github.js'
+export const FORGE_DRIVERS: ForgeDriver[] = [githubDriver]
+export const DEFAULT_FORGE_HOST = 'github'
+export function forgeDriverFor(host: string): ForgeDriver | undefined {
+  return FORGE_DRIVERS.find((d) => d.host === host)
+}
+export function forgeIssueStores(): { id: string; label: string; kind: 'forge' }[] {
+  return FORGE_DRIVERS.map((d) => ({ id: d.host, label: d.host, kind: 'forge' }))
+}

package/spec-forge/src/port.ts CHANGED Viewed

@@ -1,3 +1,11 @@
+// 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
+  body: string
+}
 export type ForgeIssue = {
   number: number
   title: string
@@ -5,6 +13,13 @@ 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[]
 }
 export type ForgePR = {
@@ -20,4 +35,14 @@ 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 CHANGED Viewed

@@ -1,23 +1,57 @@
 import { ForgeCache } from './cache.js'
 import { githubDriver } from './drivers/github.js'
-import type { NodeLinks } from './links.js'
+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
-const TTL_MS = 60_000
+// 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
   lastAttempt = now
-  inFlight = cache
-    .reconcile(githubDriver)
+  const startISO = new Date(now).toISOString()   // stamped at fetch START so an update during the fetch lands in the next window
+  const incremental = lastIssueSync && githubDriver.listIssuesSince && now - lastFull < FULL_MS
+  inFlight = (incremental
+    ? Promise.all([
+        githubDriver.listIssuesSince!(lastIssueSync!).then((delta) => cache.applyIssues(delta)),
+        githubDriver.listPRs().then((prs) => cache.setPRs(prs)),
+      ]).then(() => { lastIssueSync = startISO })
+    : cache.reconcile(githubDriver).then(() => { lastFull = now; lastIssueSync = startISO })
+  )
     .catch(() => {})
     .finally(() => { inFlight = null })
 }
-export function residentForgeView(nodeIds: string[]): NodeLinks[] {
+// 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.view(nodeIds)
+  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 async function refreshForgeNow(): Promise<void> {
+  if (inFlight) await inFlight
+  lastAttempt = 0
+  lastFull = 0
+  refreshIfStale(Date.now())
+  if (inFlight) await inFlight
 }