@reneturcios/greenlight 0.9.3 → 0.10.1

package/dist/portfolio.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `greenlight portfolio`: one-screen campaign summary (v0.10.0).
+ *
+ * Multi-agent field lesson 2026-10-18: with several agents opening PRs
+ * in parallel, nobody holds the whole board in their head. `portfolio`
+ * combines the API census (open/merged/closed), claims by state, the
+ * pending posting queue, and the sync drift count into one screen, as
+ * human text or --json. READS ONLY: it never posts or claims.
+ */
+import { type ClaimsRegistryFile } from "./claims-registry.js";
+import { type PostingLedger } from "./posting-ledger.js";
+import { type CensusPr, type SyncDrift } from "./sync.js";
+export interface ClaimBuckets {
+    /** Claims with a linked PR URL. */
+    linked: number;
+    /** No PR, older than the stale window. */
+    unlinkedStale: number;
+    /** The rest: recent, unlinked, still in play. */
+    active: number;
+}
+export interface PendingQueue {
+    /** Ledger entries that never got a confirmed outcome. */
+    unconfirmedPosts: Array<{
+        ts: string;
+        kind: string;
+        targetUrl: string;
+        agent?: string;
+    }>;
+    /** Claims with no linked PR (built work that may not be posted). */
+    unlinkedClaims: Array<{
+        issueUrl: string;
+        postedAt: string;
+    }>;
+}
+export interface Portfolio {
+    author: string;
+    census: {
+        total: number;
+        open: number;
+        merged: number;
+        closedUnmerged: number;
+    };
+    claims: ClaimBuckets & {
+        total: number;
+    };
+    knownPrs: number;
+    pending: PendingQueue;
+    drift: {
+        total: number;
+        unknownPrs: number;
+        stateMismatches: number;
+        staleClaims: number;
+    };
+}
+export declare function bucketClaims(claims: ClaimsRegistryFile["claims"], staleDays: number, nowMs: number): ClaimBuckets;
+export declare function pendingQueue(registry: ClaimsRegistryFile, ledger: PostingLedger): PendingQueue;
+export declare function buildPortfolio(args: {
+    author: string;
+    census: CensusPr[];
+    registry: ClaimsRegistryFile;
+    ledger: PostingLedger;
+    drift: SyncDrift;
+    staleDays: number;
+    nowMs: number;
+}): Portfolio;
+/** Human one-screen summary: counts first, then the items that need action. */
+export declare function formatPortfolioHuman(p: Portfolio): string;
+export declare function portfolioJson(p: Portfolio): Record<string, unknown>;
+export interface PortfolioRunOptions {
+    author: string;
+    staleDays?: number;
+    registryPath?: string;
+    ledgerPath?: string;
+    nowMs?: number;
+}
+/** Full portfolio run: census, registry, ledger, drift, one Portfolio. */
+export declare function runPortfolio(opts: PortfolioRunOptions): Promise<Portfolio>;

package/dist/portfolio.js

@@ -0,0 +1,108 @@
+/**
+ * `greenlight portfolio`: one-screen campaign summary (v0.10.0).
+ *
+ * Multi-agent field lesson 2026-10-18: with several agents opening PRs
+ * in parallel, nobody holds the whole board in their head. `portfolio`
+ * combines the API census (open/merged/closed), claims by state, the
+ * pending posting queue, and the sync drift count into one screen, as
+ * human text or --json. READS ONLY: it never posts or claims.
+ */
+import { defaultRegistryPath, loadRegistry, } from "./claims-registry.js";
+import { defaultLedgerPath, readLedger, } from "./posting-ledger.js";
+import { computeDrift, fetchAuthorCensus, } from "./sync.js";
+export function bucketClaims(claims, staleDays, nowMs) {
+    const out = { linked: 0, unlinkedStale: 0, active: 0 };
+    const staleMs = staleDays * 24 * 60 * 60 * 1000;
+    for (const c of claims) {
+        if (c.prUrl) {
+            out.linked++;
+            continue;
+        }
+        const age = nowMs - Date.parse(c.postedAt);
+        if (Number.isFinite(age) && age >= staleMs)
+            out.unlinkedStale++;
+        else
+            out.active++;
+    }
+    return out;
+}
+export function pendingQueue(registry, ledger) {
+    return {
+        unconfirmedPosts: ledger.entries
+            .filter((e) => e.outcome === "unconfirmed")
+            .map((e) => ({ ts: e.ts, kind: e.kind, targetUrl: e.targetUrl, agent: e.agent })),
+        unlinkedClaims: registry.claims
+            .filter((c) => !c.prUrl)
+            .map((c) => ({ issueUrl: c.issueUrl, postedAt: c.postedAt })),
+    };
+}
+export function buildPortfolio(args) {
+    const { census, registry, drift, staleDays, nowMs, author } = args;
+    const claims = bucketClaims(registry.claims, staleDays, nowMs);
+    return {
+        author,
+        census: {
+            total: census.length,
+            open: census.filter((c) => c.state === "open").length,
+            merged: census.filter((c) => c.merged).length,
+            closedUnmerged: census.filter((c) => c.state === "closed" && !c.merged).length,
+        },
+        claims: { ...claims, total: registry.claims.length },
+        knownPrs: registry.prs?.length ?? 0,
+        pending: pendingQueue(registry, args.ledger),
+        drift: {
+            total: drift.unknownPrs.length + drift.stateMismatches.length + drift.staleClaims.length,
+            unknownPrs: drift.unknownPrs.length,
+            stateMismatches: drift.stateMismatches.length,
+            staleClaims: drift.staleClaims.length,
+        },
+    };
+}
+/** Human one-screen summary: counts first, then the items that need action. */
+export function formatPortfolioHuman(p) {
+    const lines = [];
+    lines.push(`**portfolio: ${p.author}**`);
+    lines.push(`PRs: ${p.census.total} total (${p.census.open} open, ${p.census.merged} merged, ${p.census.closedUnmerged} closed unmerged)`);
+    lines.push(`Claims: ${p.claims.total} total (${p.claims.linked} linked, ${p.claims.active} active, ${p.claims.unlinkedStale} unlinked-stale)`);
+    lines.push(`Known PRs in registry: ${p.knownPrs}`);
+    lines.push(`Drift: ${p.drift.total} item${p.drift.total === 1 ? "" : "s"} (${p.drift.unknownPrs} unknown PRs, ${p.drift.stateMismatches} state mismatches, ${p.drift.staleClaims} stale claims)`);
+    lines.push("");
+    const unconfirmed = p.pending.unconfirmedPosts;
+    lines.push(`## Pending posts (${unconfirmed.length})`);
+    if (unconfirmed.length === 0)
+        lines.push("_None._");
+    else
+        for (const u of unconfirmed.slice(0, 10)) {
+            lines.push(`- ${u.kind} ${u.targetUrl} (${u.ts}${u.agent ? `, agent ${u.agent}` : ""})`);
+        }
+    if (unconfirmed.length > 10)
+        lines.push(`_... and ${unconfirmed.length - 10} more._`);
+    lines.push("");
+    const unlinked = p.pending.unlinkedClaims;
+    lines.push(`## Unlinked claims (${unlinked.length})`);
+    if (unlinked.length === 0)
+        lines.push("_None._");
+    else
+        for (const u of unlinked.slice(0, 10)) {
+            lines.push(`- ${u.issueUrl} (claimed ${u.postedAt})`);
+        }
+    if (unlinked.length > 10)
+        lines.push(`_... and ${unlinked.length - 10} more._`);
+    return lines.join("\n");
+}
+export function portfolioJson(p) {
+    return { portfolio: p };
+}
+/** Full portfolio run: census, registry, ledger, drift, one Portfolio. */
+export async function runPortfolio(opts) {
+    const registryPath = opts.registryPath ?? defaultRegistryPath();
+    const ledgerPath = opts.ledgerPath ?? defaultLedgerPath();
+    const nowMs = opts.nowMs ?? Date.now();
+    const staleDays = opts.staleDays ?? 7;
+    const census = await fetchAuthorCensus(opts.author);
+    const registry = loadRegistry(registryPath);
+    const ledger = readLedger(ledgerPath);
+    const drift = computeDrift(census, registry, null, staleDays, nowMs);
+    return buildPortfolio({ author: opts.author, census, registry, ledger, drift, staleDays, nowMs });
+}
+//# sourceMappingURL=portfolio.js.map

package/dist/portfolio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portfolio.js","sourceRoot":"","sources":["../src/portfolio.ts"],"names":[],"mappings":"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"}

package/dist/posting-ledger.d.ts

@@ -4,13 +4,32 @@ export type PostingOutcome = "confirmed" | "blocked" | "unconfirmed" | "supersed
 export interface PostingLedgerEntry {
     /** ISO timestamp of the attempt. */
     ts: string;
+    /**
+     * Unique entry id (v0.10.0). Two posts in the same millisecond share a
+     * ts, so finishPost matches on this, never on ts alone. Older entries
+     * may lack it; matching falls back to ts + targetUrl for those.
+     */
+    id?: string;
     kind: PostingKind;
     /** Canonical target, e.g. https://github.com/owner/repo/issues/123. */
     targetUrl: string;
     outcome: PostingOutcome;
     /** Short human note, e.g. "comment #6238115199" or "403 Blocked". */
     note?: string;
+    /**
+     * Which agent recorded the entry (v0.10.0). GREENLIGHT_AGENT_ID when set,
+     * otherwise "<hostname>:<pid>" captured at write time. Older entries may
+     * lack it; pacing counts every entry regardless.
+     */
+    agent?: string;
 }
+/**
+ * The identity stamped on each ledger entry. Operators running several
+ * agents (or machines) in parallel set GREENLIGHT_AGENT_ID per agent
+ * (e.g. "worker-a", "cron-scan") so the ledger shows who posted what.
+ * Unset, the tool falls back to "<hostname>:<pid>".
+ */
+export declare function agentId(env?: NodeJS.ProcessEnv): string;
 export interface PostingLedger {
     v: 1;
     entries: PostingLedgerEntry[];
@@ -19,9 +38,40 @@ export declare function defaultLedgerPath(): string;
 export declare function emptyLedger(): PostingLedger;
 /** Read the ledger; a missing or corrupt file means an empty ledger. */
 export declare function readLedger(path?: string): PostingLedger;
-export declare function appendLedgerEntry(entry: Omit<PostingLedgerEntry, "ts"> & {
+/**
+ * Exclusive lock around read-modify-write, so concurrent agents cannot
+ * both read an empty-looking ledger and race past the daily cap or the
+ * claim cadence. Implemented with an exclusive-create lock file and a
+ * staleness rule (a lock older than 30s is a crashed holder and is
+ * stolen), so a dead process can never wedge the ledger forever.
+ */
+export declare function withLedgerLock<T>(path: string, fn: () => T): T;
+export declare function appendLedgerEntry(entry: Omit<PostingLedgerEntry, "ts" | "agent"> & {
     ts?: string;
+    agent?: string;
 }, path?: string): PostingLedgerEntry;
+/**
+ * Result of reserving a post under the lock: the pacing check and the
+ * ledger write happen in one critical section, so two agents cannot both
+ * observe an allowed window and both post. The reservation is recorded
+ * immediately with outcome "unconfirmed"; finishPost updates it once the
+ * post resolves.
+ */
+export interface ReserveResult {
+    allowed: boolean;
+    reason: string | null;
+    /** The reserved entry (matched by ts + targetUrl in finishPost), or null. */
+    entry: PostingLedgerEntry | null;
+    decision: PacingDecision;
+}
+export declare function reservePost(path: string, entry: Omit<PostingLedgerEntry, "ts" | "agent" | "outcome"> & {
+    outcome?: PostingOutcome;
+    agent?: string;
+}, config: PacingConfig, nowMs: number, opts?: {
+    force?: boolean;
+}): ReserveResult;
+/** Update a reserved entry's outcome under the lock (matched by ts + targetUrl). */
+export declare function finishPost(path: string, entry: PostingLedgerEntry, outcome: PostingOutcome, note?: string): void;
 /** Comment-class writes (the surface GitHub's anti-spam flag watches). */
 export declare const COMMENT_KINDS: PostingKind[];
 export interface PacingConfig {

package/dist/posting-ledger.js

@@ -17,9 +17,22 @@
  * All time-dependent decisions take an explicit `nowMs`, so the tests
  * drive them with an injected clock.
  */
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { join } from "node:path";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, openSync, closeSync, statSync, unlinkSync, } from "node:fs";
+/**
+ * The identity stamped on each ledger entry. Operators running several
+ * agents (or machines) in parallel set GREENLIGHT_AGENT_ID per agent
+ * (e.g. "worker-a", "cron-scan") so the ledger shows who posted what.
+ * Unset, the tool falls back to "<hostname>:<pid>".
+ */
+export function agentId(env = process.env) {
+    const fromEnv = (env.GREENLIGHT_AGENT_ID ?? "").trim();
+    if (fromEnv.length > 0)
+        return fromEnv;
+    return `${hostname()}:${process.pid}`;
+}
 export function defaultLedgerPath() {
     return join(homedir(), ".greenlight", "posting-ledger.json");
 }
@@ -42,19 +55,143 @@ export function readLedger(path = defaultLedgerPath()) {
     }
     return emptyLedger();
 }
+/** Lock-file path for the atomic ledger operations below. */
+function ledgerLockPath(path) {
+    return `${path}.lock`;
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_POLL_MS = 25;
+const LOCK_TIMEOUT_MS = 10_000;
+function sleepMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Exclusive lock around read-modify-write, so concurrent agents cannot
+ * both read an empty-looking ledger and race past the daily cap or the
+ * claim cadence. Implemented with an exclusive-create lock file and a
+ * staleness rule (a lock older than 30s is a crashed holder and is
+ * stolen), so a dead process can never wedge the ledger forever.
+ */
+export function withLedgerLock(path, fn) {
+    const lp = ledgerLockPath(path);
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const fd = openSync(lp, "wx");
+            try {
+                writeFileSync(fd, `${process.pid}`);
+            }
+            catch {
+                // Best effort: the lock's existence is the signal, not its content.
+            }
+            closeSync(fd);
+            break;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            try {
+                const st = statSync(lp);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    try {
+                        unlinkSync(lp);
+                    }
+                    catch {
+                        // Lost the race to steal it; loop back and re-check.
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // Lock vanished between checks; loop back and re-create it.
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`timed out acquiring posting-ledger lock for ${path}`);
+            }
+            sleepMs(LOCK_POLL_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            unlinkSync(lp);
+        }
+        catch {
+            // Another process already stole and released it; nothing to do.
+        }
+    }
+}
+function writeLedger(path, ledger) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, JSON.stringify(ledger, null, 2));
+}
 export function appendLedgerEntry(entry, path = defaultLedgerPath()) {
-    const full = { ts: new Date().toISOString(), ...entry };
-    const ledger = readLedger(path);
-    ledger.entries.push(full);
+    const full = {
+        ts: new Date().toISOString(),
+        agent: agentId(),
+        ...entry,
+    };
     try {
-        mkdirSync(join(path, ".."), { recursive: true });
-        writeFileSync(path, JSON.stringify(ledger, null, 2));
+        withLedgerLock(path, () => {
+            const ledger = readLedger(path);
+            ledger.entries.push(full);
+            writeLedger(path, ledger);
+        });
     }
     catch {
-        // The ledger is advisory: a write failure must never break posting.
+        // The ledger is advisory: a lock or write failure must never break posting.
+        // Fall through and still return the entry we meant to record.
     }
     return full;
 }
+export function reservePost(path, entry, config, nowMs, opts = {}) {
+    return withLedgerLock(path, () => {
+        const ledger = readLedger(path);
+        const decision = checkPacing(ledger, nowMs, config);
+        if (!decision.allowed && !opts.force) {
+            return { allowed: false, reason: decision.reason, entry: null, decision };
+        }
+        const full = {
+            ts: new Date(nowMs).toISOString(),
+            agent: agentId(),
+            outcome: "unconfirmed",
+            ...entry,
+            // Unique per reservation: two posts in the same millisecond must
+            // not share an identity (finishPost matches on this). The caller's
+            // partial never overrides it.
+            id: randomUUID(),
+        };
+        ledger.entries.push(full);
+        writeLedger(path, ledger);
+        return { allowed: true, reason: null, entry: full, decision };
+    });
+}
+/** Update a reserved entry's outcome under the lock (matched by ts + targetUrl). */
+export function finishPost(path, entry, outcome, note) {
+    try {
+        withLedgerLock(path, () => {
+            const ledger = readLedger(path);
+            // Match on the reservation id: ts + targetUrl is not unique when
+            // two posts land in the same millisecond. Entries written before
+            // ids existed fall back to ts + targetUrl.
+            const stored = entry.id
+                ? ledger.entries.find((e) => e.id === entry.id)
+                : ledger.entries.find((e) => e.ts === entry.ts && e.targetUrl === entry.targetUrl);
+            if (stored) {
+                stored.outcome = outcome;
+                if (note !== undefined)
+                    stored.note = note;
+                writeLedger(path, ledger);
+            }
+        });
+    }
+    catch {
+        // Advisory, like every ledger write.
+    }
+}
 /** Comment-class writes (the surface GitHub's anti-spam flag watches). */
 export const COMMENT_KINDS = ["claim", "release", "heartbeat", "comment"];
 export function pacingConfigFromEnv(env = process.env) {

package/dist/posting-ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"posting-ledger.js","sourceRoot":"","sources":["../src/posting-ledger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"posting-ledger.js","sourceRoot":"","sources":["../src/posting-ledger.ts"],"names":[],"mappings":"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"}

package/dist/preflight.d.ts

@@ -0,0 +1,39 @@
+export interface PreflightOptions {
+    owner: string;
+    repo: string;
+    /** Base SHA the fix was built against; with --files, enables drift detection. */
+    base?: string;
+    /** Repo-relative file paths to check for upstream drift. */
+    files?: string[];
+    capabilitiesPath?: string;
+}
+export interface ForkCheck {
+    ok: boolean;
+    detail: string;
+}
+export interface CapabilityCheck {
+    verdict: "KNOWN-BLOCKED" | "CLEAR" | "NO-RECORD";
+    detail: string;
+}
+export interface GateCheck {
+    collaboratorsOnly: boolean;
+    detected: string[];
+    detail: string;
+}
+export interface DriftFile {
+    path: string;
+    status: "CLEAN" | "DRIFTED" | "MISSING";
+    detail: string;
+}
+export interface PreflightResult {
+    owner: string;
+    repo: string;
+    fork: ForkCheck;
+    capability: CapabilityCheck;
+    gates: GateCheck;
+    drift?: DriftFile[];
+    verdict: "GO" | "NO-GO";
+    reasons: string[];
+}
+export declare function runPreflight(opts: PreflightOptions): Promise<PreflightResult>;
+export declare function formatPreflightHuman(r: PreflightResult): string;