@spexcode/spec-forge 0.6.5

package/dist/cache.d.ts

@@ -0,0 +1,29 @@
+import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js';
+import { type NodeLinks } from './links.js';
+export type ForgeDelta = {
+    kind: 'issue';
+    issue: ForgeIssue;
+} | {
+    kind: 'pr';
+    pr: ForgePR;
+} | {
+    kind: 'remove';
+    target: 'issue' | 'pr';
+    number: number;
+};
+export declare class ForgeCache {
+    private issues;
+    private prs;
+    private revision;
+    apply(delta: ForgeDelta): void;
+    reconcile(driver: ForgeDriver): Promise<void>;
+    applyIssues(issues: ForgeIssue[]): void;
+    setPRs(prs: ForgePR[]): void;
+    view(nodeIds: string[]): NodeLinks[];
+    state(): {
+        issues: ForgeIssue[];
+        prs: ForgePR[];
+    };
+    stateRevision(): number;
+    private set;
+}

package/dist/cache.js

@@ -0,0 +1,59 @@
+import { resolveLinks } from './links.js';
+function sameMap(a, b) {
+    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 {
+    issues = new Map();
+    prs = new Map();
+    revision = 0;
+    apply(delta) {
+        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) {
+        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) {
+        for (const i of issues)
+            this.set(this.issues, i);
+    }
+    setPRs(prs) {
+        const next = new Map(prs.map((p) => [p.number, p]));
+        if (!sameMap(this.prs, next))
+            this.revision++;
+        this.prs = next;
+    }
+    view(nodeIds) {
+        return resolveLinks([...this.issues.values()], [...this.prs.values()], nodeIds);
+    }
+    state() {
+        return { issues: [...this.issues.values()], prs: [...this.prs.values()] };
+    }
+    stateRevision() {
+        return this.revision;
+    }
+    set(target, value) {
+        if (JSON.stringify(target.get(value.number)) !== JSON.stringify(value)) {
+            target.set(value.number, value);
+            this.revision++;
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runIssueLinks(args: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,100 @@
+import { loadSpecs } from '@spexcode/spec-core';
+import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from './drivers.js';
+import { resolveLinks } from './links.js';
+import { resolveEvalPending } from './needs-eval.js';
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+const has = (args, name) => args.includes(`--${name}`);
+async function readForge(args) {
+    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) {
+    const out = [];
+    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) {
+    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) {
+    const out = [];
+    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) {
+    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) {
+    return has(args, 'pending') ? evalPending(args) : links(args);
+}

package/dist/drivers/github.d.ts

@@ -0,0 +1,2 @@
+import type { ForgeDriver } from '../port.js';
+export declare const githubDriver: ForgeDriver;

package/dist/drivers/github.js

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+// maxBuffer is raised above the 1MB default: a busy repo's issue/PR JSON can exceed it
+async function gh(args) {
+    const { stdout } = await run('gh', args, { maxBuffer: 16 * 1024 * 1024 });
+    return JSON.parse(stdout);
+}
+export const githubDriver = {
+    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() {
+        const list = (state) => gh(['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: forgeLabels(r.labels),
+            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) {
+        const out = [];
+        for (let page = 1; page <= 20; page++) {
+            const rows = await gh(['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: forgeLabels(r.labels),
+            author: r.user?.login ?? '',
+            createdAt: r.created_at ?? '',
+            comments: r.comments > 0 ? await listComments(r.number) : [],
+        })));
+    },
+    async listPRs() {
+        const base = ['pr', 'list', '--state', 'open', '--limit', '200', '--json'];
+        const fields = 'number,title,url,state,headRefName';
+        let rows;
+        try {
+            rows = await gh([...base, `${fields},closingIssuesReferences`]);
+        }
+        catch (err) {
+            if (!isUnknownFieldError(err))
+                throw err;
+            warnNoTransitiveOnce();
+            rows = await gh([...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 }) {
+        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 }) {
+        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 }) {
+        await run('gh', ['issue', 'close', String(number)], { maxBuffer: 1024 * 1024 });
+        const r = await gh(['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 };
+    },
+};
+function forgeLabels(labels) {
+    return (labels ?? []).flatMap((label) => {
+        const name = typeof label === 'string' ? label : label.name ?? '';
+        return name ? [{ name, ...(typeof label === 'string' || !label.color ? {} : { color: label.color }) }] : [];
+    });
+}
+async function listComments(number) {
+    const rows = await gh(['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) {
+    const e = err;
+    const text = `${e?.stderr ?? ''}\n${e?.message ?? ''}`;
+    return /unknown json field/i.test(text);
+}
+let warnedNoTransitive = false;
+function warnNoTransitiveOnce() {
+    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/dist/drivers/gitlab.d.ts

@@ -0,0 +1,7 @@
+import type { ForgeDriver } from '../port.js';
+export declare function parseRemote(remote: string): {
+    base: string;
+    host: string;
+    project: string;
+} | null;
+export declare const gitlabDriver: ForgeDriver;

package/dist/drivers/gitlab.js

@@ -0,0 +1,144 @@
+import { execFileSync } from 'node:child_process';
+let ctx = null;
+function gitlabCtx() {
+    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) {
+    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) {
+    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(path, init) {
+    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());
+}
+// GitLab's API has no bounded list query; stop at a short page and cap the walk.
+async function paged(path) {
+    const sep = path.includes('?') ? '&' : '?';
+    const out = [];
+    for (let page = 1; page <= 20; page++) {
+        const rows = await api(`${path}${sep}page=${page}`);
+        out.push(...rows);
+        if (rows.length < 100)
+            break;
+    }
+    return out;
+}
+async function toIssue(r) {
+    return {
+        number: r.iid,
+        title: r.title,
+        body: r.description ?? '',
+        url: r.web_url,
+        state: normalizeState(r.state),
+        labels: forgeLabels(r.labels),
+        author: r.author?.username ?? '',
+        createdAt: r.created_at ?? '',
+        comments: r.user_notes_count > 0 ? await listNotes(r.iid) : [],
+    };
+}
+function forgeLabels(labels) {
+    return (labels ?? []).flatMap((label) => {
+        const name = typeof label === 'string' ? label : label.name ?? '';
+        if (!name)
+            return [];
+        if (typeof label === 'string')
+            return [{ name }];
+        return [{ name, ...(label.color ? { color: label.color } : {}), ...(label.text_color ? { textColor: label.text_color } : {}) }];
+    });
+}
+function normalizeState(state) {
+    const s = (state || '').toLowerCase();
+    return s === 'opened' ? 'open' : s;
+}
+async function listNotes(iid) {
+    const rows = await paged(`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 = {
+    host: 'gitlab',
+    async listIssues() {
+        const rows = await paged('issues?state=all&with_labels_details=true');
+        return Promise.all(rows.map(toIssue));
+    },
+    async listIssuesSince(sinceISO) {
+        const rows = await paged(`issues?state=all&with_labels_details=true&updated_after=${encodeURIComponent(sinceISO)}`);
+        return Promise.all(rows.map(toIssue));
+    },
+    async listPRs() {
+        const rows = await paged('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(`merge_requests/${r.iid}/closes_issues`)).map((i) => i.iid),
+        })));
+    },
+    async createIssue({ title, body }) {
+        const r = await api('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 }) {
+        const { base, project } = gitlabCtx();
+        const r = await api(`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 }) {
+        const r = await api(`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 };
+    },
+};

package/dist/drivers.d.ts

@@ -0,0 +1,10 @@
+import type { ForgeDriver } from './port.js';
+export declare const FORGE_DRIVERS: ForgeDriver[];
+export declare const DEFAULT_FORGE_HOST = "github";
+export declare function forgeDriverFor(host: string): ForgeDriver | undefined;
+export declare function forgeIssueStores(): {
+    id: string;
+    label: string;
+    kind: 'forge';
+}[];
+export declare function resolveForgeHost(): string;

package/dist/drivers.js

@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { githubDriver } from './drivers/github.js';
+import { gitlabDriver } from './drivers/gitlab.js';
+export const FORGE_DRIVERS = [githubDriver, gitlabDriver];
+export const DEFAULT_FORGE_HOST = 'github';
+export function forgeDriverFor(host) {
+    return FORGE_DRIVERS.find((d) => d.host === host);
+}
+export function forgeIssueStores() {
+    const driver = forgeDriverFor(resolveForgeHost());
+    return driver ? [{ id: driver.host, label: driver.host, kind: 'forge' }] : [];
+}
+function gitEnv() {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    return env;
+}
+function gitOut(args) {
+    try {
+        return execFileSync('git', args, { env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function configuredHost() {
+    const root = gitOut(['rev-parse', '--show-toplevel']);
+    if (!root)
+        return null;
+    for (const name of ['spexcode.local.json', 'spexcode.json']) {
+        const p = join(root, name);
+        if (!existsSync(p))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch (e) {
+            throw new Error(`${p} is not valid JSON: ${e.message}`);
+        }
+        const host = parsed?.forge?.host;
+        if (typeof host === 'string' && host.trim())
+            return host.trim();
+    }
+    return null;
+}
+function remoteHostname(url) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+        try {
+            return new URL(url).hostname || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const scp = /^(?:[^@\s/]+@)?([^:/\s]+):./.exec(url);
+    return scp ? scp[1] : null;
+}
+function hostFor(hostname) {
+    const h = hostname.toLowerCase();
+    if (h.includes('github'))
+        return 'github';
+    if (h.includes('bitbucket'))
+        return 'bitbucket';
+    return 'gitlab';
+}
+let cached = null;
+const RESOLVE_TTL_MS = 30_000;
+export function resolveForgeHost() {
+    const now = Date.now();
+    if (cached && now - cached.at < RESOLVE_TTL_MS)
+        return cached.host;
+    const url = gitOut(['remote', 'get-url', 'origin']);
+    const hostname = url ? remoteHostname(url) : null;
+    const host = configuredHost() ?? (hostname ? hostFor(hostname) : DEFAULT_FORGE_HOST);
+    cached = { host, at: now };
+    return host;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './port.js';
+export * from './links.js';
+export * from './drivers.js';
+export * from './resident.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './port.js';
+export * from './links.js';
+export * from './drivers.js';
+export * from './resident.js';

package/dist/links.d.ts

@@ -0,0 +1,15 @@
+import type { ForgeIssue, ForgePR } from './port.js';
+export type LinkedIssue = ForgeIssue & {
+    via: 'marker' | 'pr';
+};
+export type LinkedPR = ForgePR & {
+    via: 'branch';
+};
+export type NodeLinks = {
+    node: string;
+    issues: LinkedIssue[];
+    prs: LinkedPR[];
+};
+export declare function parseSpecMarkers(body: string): string[];
+export declare function branchToNode(branch: string, nodeIds: string[]): string | null;
+export declare function resolveLinks(issues: ForgeIssue[], prs: ForgePR[], nodeIds: string[]): NodeLinks[];

package/dist/links.js

@@ -0,0 +1,65 @@
+export function parseSpecMarkers(body) {
+    const ids = [];
+    for (const m of (body || '').matchAll(/^\s*spec:\s*(.+)$/gim)) {
+        for (const part of m[1].split(',')) {
+            const id = part.trim();
+            if (id)
+                ids.push(id);
+        }
+    }
+    return ids;
+}
+export function branchToNode(branch, nodeIds) {
+    if (!branch?.startsWith('node/'))
+        return null;
+    const rest = branch.slice('node/'.length);
+    let best = null;
+    for (const id of nodeIds) {
+        if (rest === id || rest.startsWith(id + '-')) {
+            if (!best || id.length > best.length)
+                best = id;
+        }
+    }
+    return best;
+}
+export function resolveLinks(issues, prs, nodeIds) {
+    const known = new Set(nodeIds);
+    const byNode = new Map();
+    const slot = (node) => {
+        let s = byNode.get(node);
+        if (!s) {
+            s = { issues: new Map(), prs: new Map() };
+            byNode.set(node, s);
+        }
+        return s;
+    };
+    const prNode = new Map();
+    for (const pr of prs) {
+        const node = branchToNode(pr.headRefName, nodeIds);
+        if (!node)
+            continue;
+        prNode.set(pr.number, node);
+        slot(node).prs.set(pr.number, { ...pr, via: 'branch' });
+    }
+    const issueByNumber = new Map(issues.map((i) => [i.number, i]));
+    for (const issue of issues) {
+        for (const id of parseSpecMarkers(issue.body)) {
+            if (known.has(id))
+                slot(id).issues.set(issue.number, { ...issue, via: 'marker' });
+        }
+    }
+    for (const pr of prs) {
+        const node = prNode.get(pr.number);
+        if (!node)
+            continue;
+        for (const num of pr.closesIssues) {
+            const issue = issueByNumber.get(num);
+            if (issue && !slot(node).issues.has(num)) {
+                slot(node).issues.set(num, { ...issue, via: 'pr' });
+            }
+        }
+    }
+    return [...byNode.entries()]
+        .map(([node, s]) => ({ node, issues: [...s.issues.values()], prs: [...s.prs.values()] }))
+        .sort((a, b) => a.node.localeCompare(b.node));
+}

package/dist/needs-eval.d.ts

@@ -0,0 +1,10 @@
+import type { ForgeIssue, ForgePR } from './port.js';
+import { type LinkedIssue } from './links.js';
+export declare const NEEDS_EVAL = "needs-eval";
+export declare function isNeedsEval(issue: ForgeIssue): boolean;
+export type EvalPending = LinkedIssue;
+export type NodeEvalPending = {
+    node: string;
+    pending: EvalPending[];
+};
+export declare function resolveEvalPending(issues: ForgeIssue[], prs: ForgePR[], nodeIds: string[]): NodeEvalPending[];

package/dist/needs-eval.js

@@ -0,0 +1,20 @@
+import { resolveLinks } from './links.js';
+export const NEEDS_EVAL = 'needs-eval';
+const BODY_MARKER = new RegExp(`^\\s*${NEEDS_EVAL}\\s*:?\\s*$`, 'im');
+export function isNeedsEval(issue) {
+    if (issue.labels.some((l) => l.name.trim().toLowerCase() === NEEDS_EVAL))
+        return true;
+    return BODY_MARKER.test(issue.body || '');
+}
+export function resolveEvalPending(issues, prs, nodeIds) {
+    const flagged = new Set(issues.filter(isNeedsEval).map((i) => i.number));
+    if (!flagged.size)
+        return [];
+    const out = [];
+    for (const { node, issues: linked } of resolveLinks(issues, prs, nodeIds)) {
+        const pending = linked.filter((i) => i.state === 'open' && flagged.has(i.number));
+        if (pending.length)
+            out.push({ node, pending });
+    }
+    return out;
+}

package/dist/port.d.ts

@@ -0,0 +1,53 @@
+export type ForgeComment = {
+    author: string;
+    createdAt: string;
+    body: string;
+};
+export type ForgeLabel = {
+    name: string;
+    color?: string;
+    textColor?: string;
+};
+export type ForgeIssue = {
+    number: number;
+    title: string;
+    body: string;
+    url: string;
+    state: string;
+    labels: ForgeLabel[];
+    author: string;
+    createdAt: string;
+    comments: ForgeComment[];
+};
+export type ForgePR = {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+    headRefName: string;
+    closesIssues: number[];
+};
+export interface ForgeDriver {
+    readonly host: string;
+    listIssues(): Promise<ForgeIssue[]>;
+    listPRs(): Promise<ForgePR[]>;
+    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;
+    }>;
+    listIssuesSince?(sinceISO: string): Promise<ForgeIssue[]>;
+}

package/dist/port.js

@@ -0,0 +1 @@
+export {};

package/dist/resident.d.ts

@@ -0,0 +1,7 @@
+import type { ForgeIssue, ForgePR } from './port.js';
+export declare function residentForgeState(): {
+    issues: ForgeIssue[];
+    prs: ForgePR[];
+};
+export declare function residentForgeRevision(): number;
+export declare function refreshForgeNow(): Promise<void>;

package/dist/resident.js

@@ -0,0 +1,43 @@
+import { ForgeCache } from './cache.js';
+import { forgeDriverFor, resolveForgeHost } from './drivers.js';
+const cache = new ForgeCache();
+let inFlight = null;
+let lastAttempt = 0;
+const TTL_MS = 20_000;
+let lastIssueSync = null;
+let lastFull = 0;
+const FULL_MS = 30 * 60_000;
+function refreshIfStale(now) {
+    if (inFlight || (lastAttempt && now - lastAttempt < TTL_MS))
+        return;
+    const driver = forgeDriverFor(resolveForgeHost());
+    if (!driver)
+        return;
+    lastAttempt = now;
+    const startISO = new Date(now).toISOString(); // stamped at fetch START so an update during the fetch lands in the next window
+    const incremental = lastIssueSync && driver.listIssuesSince && now - lastFull < FULL_MS;
+    inFlight = (incremental
+        ? Promise.all([
+            driver.listIssuesSince(lastIssueSync).then((delta) => cache.applyIssues(delta)),
+            driver.listPRs().then((prs) => cache.setPRs(prs)),
+        ]).then(() => { lastIssueSync = startISO; })
+        : cache.reconcile(driver).then(() => { lastFull = now; lastIssueSync = startISO; }))
+        .catch(() => { })
+        .finally(() => { inFlight = null; });
+}
+export function residentForgeState() {
+    refreshIfStale(Date.now());
+    return cache.state();
+}
+export function residentForgeRevision() {
+    return cache.stateRevision();
+}
+export async function refreshForgeNow() {
+    if (inFlight)
+        await inFlight;
+    lastAttempt = 0;
+    lastFull = 0;
+    refreshIfStale(Date.now());
+    if (inFlight)
+        await inFlight;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@spexcode/spec-forge",
+  "version": "0.6.5",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./port": "./dist/port.js",
+    "./links": "./dist/links.js",
+    "./drivers": "./dist/drivers.js",
+    "./resident": "./dist/resident.js",
+    "./cli": "./dist/cli.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "description": "Host-agnostic forge link tracer — reads a forge's open issues/PRs and resolves each to the spec node it serves (issue-body `Spec: <id>` marker + `node/<id>` PR branch). Read-only; a node's status stays git-derived.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../scripts/release-publish.mjs --from-package-publish",
+    "test": "tsx --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/spec-core": "0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}