@reneturcios/greenlight 0.11.0 → 0.13.0

package/README.md

@@ -18,7 +18,7 @@ One command sets it up:
 npx @reneturcios/greenlight init --agent claude-code
 ```
 
-(also `cursor`, `copilot`, `windsurf`, `cline`; repeat `--agent` for more than one). Init copies the MCP config into your project and installs the workflow instruction snippet that teaches your agent the one behavior rule: **check Greenlight before it opens a PR.** Prefer doing it by hand? The [`integrations/`](integrations/README.md) drop-in pack has ready-to-copy MCP configs plus the same snippets. Then verify with a "list your MCP tools" prompt; the greenlight server carries 17 tools (check_issue, scan_repo, repo_friction, claim_issue, prep_issue, open_pr, ci_triage, review_triage, guard_pr, repo_digest, claim_status, preflight, verify_comment, babysit_prs, evidence_pack, scout_campaign, my_claims).
+(also `cursor`, `copilot`, `windsurf`, `cline`; repeat `--agent` for more than one). Init copies the MCP config into your project and installs the workflow instruction snippet that teaches your agent the one behavior rule: **check Greenlight before it opens a PR.** Prefer doing it by hand? The [`integrations/`](integrations/README.md) drop-in pack has ready-to-copy MCP configs plus the same snippets. Then verify with a "list your MCP tools" prompt; the greenlight server carries 24 tools (check_issue, scan_repo, repo_friction, claim_issue, prep_issue, open_pr, ci_triage, review_triage, guard_pr, repo_digest, claim_status, preflight, verify_comment, babysit_prs, evidence_pack, scout_campaign, my_claims, sync_campaign, campaign_portfolio, autopilot_report, api_status, claim_via_api, heartbeat_via_api, xray_issues).
 
 ## The problem
 
@@ -134,6 +134,10 @@ npx @reneturcios/greenlight check https://github.com/batrapulkit/squidbrake/issu
 # unassigned issues when the repo does not use those labels; --no-fallback to opt out)
 npx @reneturcios/greenlight scan PrefectHQ/fastmcp
 
+# Deep-verify candidates against their timelines first (catches hidden in-flight PRs)
+npx @reneturcios/greenlight xray usebruno/bruno --issues 8149,9319
+npx @reneturcios/greenlight scan usebruno/bruno --deep
+
 # Friction score for a repo
 npx @reneturcios/greenlight friction triggerdotdev/trigger.dev
 
@@ -276,6 +280,14 @@ The Agent Policy Index field work kept finding agent bans Greenlight itself miss
 - **Scoped bans dual-class instead of collapsing.** A ban aimed at one kind of agent operation (TypeScript's "bulk, agent-driven contributions", ppt-master's "purely AI-generated PRs submitted without human review") now surfaces as both `agents_banned` for autonomous operation and `agents_disclosure` for the human-led path. An explicit prohibition (nuxt, ripgrep, zed) still stands on its own, and explicit welcome or waiver language (hyperframes welcomes AI help and waives disclosure) never reads as a ban.
 - **Friction JSON states its units.** `friction --json` now carries `outsider_merge_share` (0 to 1 fraction) and `outsider_merge_share_pct` (0 to 100), plus `signals.externalPRMergeRate_pct` next to the existing fraction field. The human-readable output is unchanged.
 
+### v0.13.0: Timeline X-Ray
+
+`greenlight xray` deep-verifies candidate issues against their GitHub timelines: the linked-PR walk (timeline + search) with linkStrength scoring, reporter-owned-PR detection, and a lazy comment-claim scan, at ~4 API calls per issue. `scan --deep` demotes anything the x-ray finds taken before presenting results. New MCP tool `xray_issues`; `scan_repo` gains `deep`. Born from a Bruno focus session where 6 of 7 hand-vetted issues turned out to be secretly taken by timeline-only PRs.
+
+### v0.12.0: the Claim Protocol GitHub App client
+
+One command claims now: `greenlight claim <issue-url> --via-api` posts through the hosted claim API instead of handing you a comment to paste. `greenlight auth login` runs the GitHub device flow once and stores the token in your OS keychain (or `~/.greenlight/api-token` at 0600 when no keychain is available); `--token` / `GREENLIGHT_API_TOKEN` covers scripts. Before any `--via-api` write, the client checks whether the Greenlight Claims app is installed on the repo: installed means the claim goes through the app backend (durable state recorded via webhooks); not installed means the current direct-API comment path with a printed one-line note saying so. The downgrade is never silent. The flow is honest end to end: a hosted status read runs the TAKEN pre-flight (refuses on another holder unless `--queue-ok`), the posted comment is verified by re-reading the status, and a 401 re-runs the device flow once before printing the manual steps. `greenlight release --via-api` and `greenlight heartbeat --via-api` cover the rest of the lifecycle. The MCP server grows to 23 tools with `api_status`, `claim_via_api`, and `heartbeat_via_api` (all report-mode-safe).
+
 ### v0.11.0: Autopilot
 
 Open PRs were dying between babysit sweeps: a bot review sitting unanswered, a CI failure on the PR's own code, a drifted branch, a missing DCO trailer. Autopilot closes that loop. `greenlight autopilot` (report-only by default, `--apply` to fix) collects reviews, comments, and check results per open PR, verifies bot findings against the code at head (REAL, FALSE_POSITIVE with quoted counter-evidence, or NEEDS_HUMAN), and triages CI failures as introduced vs pre-existing against the base branch. The mechanical items fix themselves: DCO gaps get message-only surgery with byte-identical trees, merge conflicts resolve only when provably mechanical (lockfiles regenerated, changelogs unioned, version or counter bumps), and formatting pushes only when the diff is whitespace-only. Everything else becomes a plan, never a speculative edit. Fixes land on your fork branch with Rene's sign-off, respect the capability ledger's blocked repos, and replies queue as drafts behind the comment block instead of posting. Also exposed as the read-only `autopilot_report` MCP tool.
@@ -321,7 +333,7 @@ The same engine is exposed over stdio for coding agents (Claude, Cursor, Cline).
 Tools:
 
 * `check_issue` - verdict for one issue URL
-* `scan_repo` - rank a repo's open issues, GO first (label-tagged starter issues, falling back to recent open unassigned issues)
+* `scan_repo` - rank a repo's open issues, GO first (label-tagged starter issues, falling back to recent open unassigned issues; `deep: true` timeline-x-rays the candidates first)
 * `repo_friction` - friction score for a repo
 * `claim_issue` - verdict-gated claim comment (dry run unless `execute: true`)
 * `prep_issue` - fork and branch check plus a local PREP.md checklist with the repo's learned conventions (dry run unless `execute: true`)
@@ -335,6 +347,7 @@ Tools:
 * `verify_comment` - draft the verified-finding comment for maintainer-only repos (draft only, never posts)
 * `babysit_prs` - watch open PRs and get the one prioritized action list (needs you now, waiting on them, quiet), diffed against stored watermarks; also watches the my-claims registry (linked, healthy-active, heartbeat-due, expiring, unlinked-stale, queue-lost)
 * `evidence_pack` - the Verified PR evidence pack for one PR: guard verdict, CI triage, review triage, protocol status of linked issues, every claim citing its source
+* `xray_issues` - Timeline X-Ray: deep-verify candidate issues against their timelines (hidden in-flight PRs, reporter-owned fix PRs, comment claims); GO / RISKY / TAKEN per issue with PR evidence
 
 Run it locally: `npm run dev` (MCP entry is `src/index.ts`; CLI is `src/cli.ts`).
 

package/dist/claim-api.d.ts

@@ -0,0 +1,311 @@
+export declare const DEFAULT_API_BASE = "https://claim-api-wine.vercel.app";
+/**
+ * The claim-api OAuth app client id. Read from the live instance's
+ * /auth/github/login redirect (2026-10-18); override with
+ * GREENLIGHT_OAUTH_CLIENT_ID or --client-id when the app rotates.
+ */
+export declare const DEFAULT_OAUTH_CLIENT_ID = "Ov23liv9yM4RTci0UysE";
+export declare const GITHUB_DEVICE_BASE = "https://github.com";
+export declare const GITHUB_API_BASE = "https://api.github.com";
+/** Claim Protocol marker; the fallback comment is byte-compatible with it. */
+export declare const CLAIM_MARKER_V1 = "<!-- greenlight-claim v1 -->";
+type FetchImpl = typeof fetch;
+export interface ApiConfig {
+    apiBase: string;
+}
+export declare function configFilePath(home?: string): string;
+export declare function readApiConfig(home?: string): ApiConfig | null;
+export declare function writeApiConfig(apiBase: string, home?: string): void;
+/**
+ * Resolution order: --api-base flag, GREENLIGHT_API_BASE env, the cached
+ * config file, then the hosted default. A successful --api-base or env
+ * value is cached so later calls need no flag.
+ */
+export declare function resolveApiBase(opts: {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string;
+export type StoredTokenKind = "github" | "session";
+export interface StoredToken {
+    token: string;
+    kind: StoredTokenKind;
+    login: string | null;
+    storedAt: string;
+}
+export interface TokenStore {
+    get(): Promise<StoredToken | null>;
+    set(token: StoredToken): Promise<void>;
+    clear(): Promise<void>;
+    /** Human line for `auth status`: names the backend in use. */
+    describe(): string;
+}
+/** File fallback: ~/.greenlight/api-token, always 0600. */
+export declare class FileTokenStore implements TokenStore {
+    private readonly home;
+    constructor(home?: string);
+    private path;
+    get(): Promise<StoredToken | null>;
+    set(t: StoredToken): Promise<void>;
+    clear(): Promise<void>;
+    describe(): string;
+}
+/**
+ * The default store: OS keychain when a keychain tool is available,
+ * otherwise the 0600 file fallback. Callers (and tests) may inject their
+ * own TokenStore instead.
+ */
+export declare function defaultTokenStore(home?: string): Promise<TokenStore>;
+export interface ResolvedToken {
+    token: string;
+    kind: StoredTokenKind;
+    login: string | null;
+    /** Where it came from: --token, env, or the store. */
+    source: "flag" | "env" | "store";
+}
+export declare function resolveApiToken(opts: {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+    store?: TokenStore;
+    home?: string;
+}): Promise<ResolvedToken | null>;
+export declare function noTokenMessage(): string;
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceLoginOpts {
+    clientId?: string;
+    fetchImpl?: FetchImpl;
+    store?: TokenStore;
+    deviceBase?: string;
+    apiBase?: string;
+    /** Override the server's poll interval (tests). */
+    pollIntervalMs?: number;
+    /** Overall budget; default 10 minutes. */
+    timeoutMs?: number;
+    onCode?: (userCode: string, verificationUri: string) => void;
+}
+/**
+ * Run the GitHub OAuth device flow, store the resulting user token, and
+ * return it. Polling honors the server's interval; mocked-fetch tests
+ * inject a tiny interval.
+ */
+export declare function deviceFlowLogin(opts?: DeviceLoginOpts): Promise<ResolvedToken>;
+export interface BrowserLoginOpts {
+    apiBase?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    store?: TokenStore;
+    fetchImpl?: FetchImpl;
+    /** Opens the URL in the user's browser; default tries the platform opener. */
+    openUrl?: (url: string) => Promise<void>;
+    /** Reads one line from stdin; injected in tests. */
+    promptToken?: () => Promise<string | null>;
+}
+/**
+ * Browser OAuth grant: open the claim-api login page, the user completes
+ * the grant in the browser, and pastes the session token from the
+ * ?format=json callback page. Stored as kind "session".
+ */
+export declare function browserLoginFlow(opts?: BrowserLoginOpts): Promise<ResolvedToken>;
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly payload?: unknown;
+    constructor(status: number, code: string | undefined, message: string, payload?: unknown);
+}
+export interface ClaimApiClientOpts {
+    base: string;
+    token?: string;
+    fetchImpl?: FetchImpl;
+}
+export declare class ClaimApiClient {
+    private readonly base;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(opts: ClaimApiClientOpts);
+    private request;
+    /** Public status payload (SPEC 5.1 shape plus competing PRs/gates). */
+    issueStatus(owner: string, repo: string, number: number): Promise<any>;
+    /**
+     * App-aware check: is the Greenlight Claims app installed on this repo?
+     * Returns null when the endpoint does not exist (backend older than
+     * v1.0.0 returns 404) or the route cannot be reached; the caller treats
+     * null as "not installed" and falls back to the direct comment path.
+     */
+    appInstallation(owner: string, repo: string): Promise<{
+        installed: boolean;
+        app_slug?: string;
+    } | null>;
+    postClaim(owner: string, repo: string, number: number, opts: {
+        plan?: string;
+        eta_days?: number;
+        queue_ok?: boolean;
+    }): Promise<any>;
+    postRelease(owner: string, repo: string, number: number): Promise<any>;
+    postHeartbeat(owner: string, repo: string, number: number, mode?: "comment" | "reaction"): Promise<any>;
+}
+export type ViaApiPath = "app" | "direct";
+export interface PathChoice {
+    path: ViaApiPath;
+    /** The one-line note, printed when falling back to the direct path. */
+    note: string | null;
+}
+/**
+ * Before any --via-api write: ask the backend whether the Greenlight
+ * Claims app is installed on the repo. Installed -> proceed through the
+ * app backend. Not installed, or the endpoint missing/unreachable ->
+ * fall back to the current direct-API comment path with the printed
+ * note. Never silently downgrade.
+ */
+export declare function chooseViaApiPath(client: ClaimApiClient, owner: string, repo: string): Promise<PathChoice>;
+/**
+ * After a via-api write, re-read the status payload and check the
+ * caller's login appears in the active claim or the queue. Returns false
+ * when it cannot be confirmed (the CLI then prints the comment URL and
+ * tells the user to check, rather than claiming success).
+ */
+export declare function statusConfirmsLogin(status: any, login: string | null): boolean;
+export interface ViaApiCommonDeps {
+    fetchImpl?: FetchImpl;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    store?: TokenStore;
+    print?: (line: string) => void;
+    /** Re-runs the device flow (interactive); injected in tests. */
+    relogin?: () => Promise<ResolvedToken>;
+    /**
+     * The direct-comment fallback executor: posts the protocol comment
+     * through the GitHub API exactly as `greenlight claim --yes` does.
+     * Injected in tests; defaults to the real claim machinery.
+     */
+    directClaim?: (args: {
+        owner: string;
+        repo: string;
+        number: number;
+        plan?: string;
+        etaDays?: number;
+        queueOk?: boolean;
+        githubToken: string;
+    }) => Promise<{
+        posted: boolean;
+        commentUrl?: string;
+        commentBody: string;
+    }>;
+    /**
+     * The direct-comment fallback for release/heartbeat markers. Injected
+     * in tests; defaults to posting the marker comment via the GitHub API.
+     */
+    directMarker?: (args: {
+        owner: string;
+        repo: string;
+        number: number;
+        body: string;
+        githubToken: string;
+    }) => Promise<{
+        posted: boolean;
+        commentUrl?: string;
+    }>;
+}
+export interface ViaApiClaimOptions {
+    plan?: string;
+    etaDays?: number;
+    queueOk?: boolean;
+    tokenFlag?: string;
+    apiBaseFlag?: string;
+    /** false = dry run: no write, return the plan. */
+    yes?: boolean;
+}
+export interface ViaApiClaimResult {
+    outcome: "claimed" | "queued" | "already-claimed" | "refused-taken" | "dry-run" | "no-token" | "api-unreachable" | "auth-failed" | "direct-fallback";
+    path: ViaApiPath | null;
+    note: string | null;
+    commentUrl?: string;
+    commentBody?: string;
+    queuePosition?: number;
+    holder?: {
+        claimant: string;
+        expiresAt: string | null;
+    };
+    login?: string | null;
+    message: string;
+}
+export declare function viaApiClaim(issue: {
+    owner: string;
+    repo: string;
+    number: number;
+    url: string;
+}, opts: ViaApiClaimOptions, deps?: ViaApiCommonDeps): Promise<ViaApiClaimResult>;
+export interface ViaApiWriteResult {
+    outcome: "done" | "refused" | "no-token" | "api-unreachable" | "auth-failed";
+    path: ViaApiPath | null;
+    note: string | null;
+    commentUrl?: string;
+    login?: string | null;
+    message: string;
+}
+export declare function viaApiRelease(issue: {
+    owner: string;
+    repo: string;
+    number: number;
+    url: string;
+}, opts: {
+    tokenFlag?: string;
+    apiBaseFlag?: string;
+    yes?: boolean;
+}, deps?: ViaApiCommonDeps): Promise<ViaApiWriteResult>;
+export declare function viaApiHeartbeat(issue: {
+    owner: string;
+    repo: string;
+    number: number;
+    url: string;
+}, opts: {
+    tokenFlag?: string;
+    apiBaseFlag?: string;
+    mode?: "comment" | "reaction";
+    yes?: boolean;
+}, deps?: ViaApiCommonDeps): Promise<ViaApiWriteResult>;
+export interface McpToolDeps extends ViaApiCommonDeps {
+    parseIssueUrl?: (url: string) => {
+        owner: string;
+        repo: string;
+        number: number;
+    };
+}
+/**
+ * api_status: the hosted status payload for one issue, for agents that
+ * want the 60-second-fresh answer instead of the 15-minute static one.
+ * Read only; no token needed.
+ */
+export declare function mcpApiStatus(args: {
+    issue_url: string;
+    api_base?: string;
+}, deps?: McpToolDeps): Promise<unknown>;
+/**
+ * claim_via_api: claim one issue through the hosted claim API.
+ * Report-mode-safe: execute defaults to false (dry run returns the plan);
+ * executes only with execute true and a stored token (else it refuses
+ * with the auth login instructions).
+ */
+export declare function mcpClaimViaApi(args: {
+    issue_url: string;
+    plan?: string;
+    eta_days?: number;
+    queue_ok?: boolean;
+    execute?: boolean;
+    api_base?: string;
+    token?: string;
+}, deps?: McpToolDeps): Promise<unknown>;
+/** heartbeat_via_api: renew one claim through the hosted claim API. Same report-mode safety. */
+export declare function mcpHeartbeatViaApi(args: {
+    issue_url: string;
+    mode?: "comment" | "reaction";
+    execute?: boolean;
+    api_base?: string;
+    token?: string;
+}, deps?: McpToolDeps): Promise<unknown>;
+export {};