@ozzylabs/feedradar 0.1.0

package/dist/core/config.js

@@ -0,0 +1,101 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { RadarConfigSchema } from "../schemas/index.js";
+/** File name of the workspace config, located at the workspace root. */
+export const CONFIG_FILENAME = "radar.config.yaml";
+/**
+ * Hard-coded fallback when neither `--agent` nor `radar.config.yaml` sets a
+ * default. Documented in user-guide.md and architecture.md (ADR-0001).
+ */
+export const HARDCODED_DEFAULT_AGENT = "claude-code";
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Error raised when `radar.config.yaml` exists but fails to parse or violates
+ * `RadarConfigSchema`. Throws (rather than fall-back to defaults) because the
+ * user explicitly authored a config and silently ignoring it would surprise
+ * them and mask typos like `defaultResarchAgent`.
+ */
+export class RadarConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RadarConfigError";
+    }
+}
+/**
+ * Load `radar.config.yaml` from a workspace root.
+ *
+ * Behavior:
+ *   - File missing -> returns an empty config (`{}`).
+ *   - File present and valid -> returns the parsed `RadarConfig`.
+ *   - File present but malformed (YAML parse error / schema violation)
+ *     -> throws `RadarConfigError` with a contextual message.
+ *
+ * Returning `{}` for the missing-file case lets callers treat absence as
+ * "use the hard-coded default" without an extra `await pathExists` round-trip.
+ */
+export async function loadRadarConfig(cwd) {
+    const file = join(cwd, CONFIG_FILENAME);
+    if (!(await pathExists(file))) {
+        return {};
+    }
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (e) {
+        throw new RadarConfigError(`failed to read ${CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (e) {
+        throw new RadarConfigError(`failed to parse ${CONFIG_FILENAME} as YAML: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // An empty file parses to `null` / `undefined`; normalize to `{}` so the
+    // schema validation treats it the same as an absent file.
+    const candidate = parsed ?? {};
+    const result = RadarConfigSchema.safeParse(candidate);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("\n");
+        throw new RadarConfigError(`${CONFIG_FILENAME} schema violation:\n${issues}`);
+    }
+    return result.data;
+}
+export async function getDefaultAgent(command, options = {}) {
+    if (options.explicit) {
+        return options.explicit;
+    }
+    const config = options.configOverride ?? (await loadRadarConfig(options.cwd ?? process.cwd()));
+    const fromConfig = pickConfigDefault(command, config);
+    if (fromConfig) {
+        return fromConfig;
+    }
+    return HARDCODED_DEFAULT_AGENT;
+}
+function pickConfigDefault(command, config) {
+    switch (command) {
+        case "research":
+            return config.defaultResearchAgent;
+        case "review":
+            return config.defaultReviewAgent;
+        default: {
+            // Exhaustiveness check — adding a new `ConfigurableCommand` without
+            // updating this switch becomes a compile error.
+            const _exhaustive = command;
+            return _exhaustive;
+        }
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

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

package/dist/core/feeds/derive-id.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Candidate inputs an adapter passes to `deriveStableKey()`. The adapter
+ * ranks its candidates in preferred order (most-stable first); the helper
+ * returns the first non-empty value, falling back to a `sha1:`-prefixed
+ * content hash so the result is **always** defined.
+ *
+ * - `publisherId`: a stable id the publisher itself declares (RSS `guid`,
+ *   GitHub release id, npm `<pkg>@<version>`, …). Preferred when present.
+ * - `url`: the canonical URL of the entity. Preferred fallback because URLs
+ *   are usually stable across re-fetches even when no explicit id is given.
+ * - `fallbackHashInputs`: free-form strings (title, pubDate, …) hashed only
+ *   when neither `publisherId` nor `url` exists. The `sha1:` prefix is
+ *   retained from the legacy implementation so existing ids stay byte-stable
+ *   across the refactor.
+ */
+export interface StableKeyCandidates {
+    publisherId?: string;
+    url?: string;
+    fallbackHashInputs?: Array<string | undefined>;
+}
+/**
+ * Pick the most stable identifier available for an entity from a
+ * publisher-id-first fallback ladder. See ADR-0002 "Item ID 派生のコントラクト"
+ * for the contract this helper enforces.
+ *
+ * The return value is opaque — callers pass it directly to `deriveItemId()`
+ * (or hash it themselves) without inspecting the contents.
+ */
+export declare function deriveStableKey(candidates: StableKeyCandidates): string;
+/**
+ * Build the canonical `Item.id` for a feed entry.
+ *
+ * Shape: `<title-slug>-<8 hex of sha256(stableKey)>` (or just the hash when
+ * the title contains no slug-friendly characters).
+ *
+ * The title slug keeps ids human-readable in shell args and log lines; the
+ * hash suffix makes the id stable across re-fetches and avoids collisions
+ * between entries with identical titles within the same source. We hash the
+ * adapter-selected `stableKey`, not the raw title, so two posts with the
+ * same title still get distinct ids when their publisher ids differ.
+ */
+export declare function deriveItemId(title: string | undefined, stableKey: string): string;
+//# sourceMappingURL=derive-id.d.ts.map

package/dist/core/feeds/derive-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-id.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/derive-id.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAOvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIjF"}

package/dist/core/feeds/derive-id.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+/**
+ * Maximum number of characters kept from the title slug before the hash
+ * suffix. 40 keeps `Item.id` short enough for shell args and file names while
+ * still leaving room for human-readable context.
+ */
+const SLUG_MAX_LENGTH = 40;
+/**
+ * Length of the hash suffix appended to the slug. 8 hex chars (32 bits) is
+ * enough to disambiguate same-title entries within a single source without
+ * bloating ids — feeds have at most a few thousand active items, far below
+ * the birthday-collision threshold.
+ */
+const HASH_SUFFIX_LENGTH = 8;
+/**
+ * Pick the most stable identifier available for an entity from a
+ * publisher-id-first fallback ladder. See ADR-0002 "Item ID 派生のコントラクト"
+ * for the contract this helper enforces.
+ *
+ * The return value is opaque — callers pass it directly to `deriveItemId()`
+ * (or hash it themselves) without inspecting the contents.
+ */
+export function deriveStableKey(candidates) {
+    const publisherId = trimToValue(candidates.publisherId);
+    if (publisherId)
+        return publisherId;
+    const url = trimToValue(candidates.url);
+    if (url)
+        return url;
+    const joined = (candidates.fallbackHashInputs ?? []).map((v) => v ?? "").join("|");
+    return `sha1:${createHash("sha1").update(joined).digest("hex")}`;
+}
+/**
+ * Build the canonical `Item.id` for a feed entry.
+ *
+ * Shape: `<title-slug>-<8 hex of sha256(stableKey)>` (or just the hash when
+ * the title contains no slug-friendly characters).
+ *
+ * The title slug keeps ids human-readable in shell args and log lines; the
+ * hash suffix makes the id stable across re-fetches and avoids collisions
+ * between entries with identical titles within the same source. We hash the
+ * adapter-selected `stableKey`, not the raw title, so two posts with the
+ * same title still get distinct ids when their publisher ids differ.
+ */
+export function deriveItemId(title, stableKey) {
+    const hash = createHash("sha256").update(stableKey).digest("hex").slice(0, HASH_SUFFIX_LENGTH);
+    const slug = slugifyTitle(title);
+    return slug ? `${slug}-${hash}` : hash;
+}
+/** Title → kebab-case, lowercase, ASCII-only, capped at SLUG_MAX_LENGTH. */
+function slugifyTitle(title) {
+    return (title ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/-+$/g, "");
+}
+/** Trim a candidate and return `undefined` for empty strings. */
+function trimToValue(value) {
+    if (value == null)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+//# sourceMappingURL=derive-id.js.map

package/dist/core/feeds/derive-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-id.js","sourceRoot":"","sources":["../../../src/core/feeds/derive-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAuB7B;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,UAA+B;IAC7D,MAAM,WAAW,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACxD,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,GAAG,GAAG,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,MAAM,MAAM,GAAG,CAAC,UAAU,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnF,OAAO,QAAQ,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB,EAAE,SAAiB;IACvE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACzC,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CAAC,KAAyB;IAC7C,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;SACjB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;SACzB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,iEAAiE;AACjE,SAAS,WAAW,CAAC,KAAyB;IAC5C,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACpD,CAAC"}

package/dist/core/feeds/github-api.d.ts

@@ -0,0 +1,69 @@
+import type { FetchLike } from "./types.js";
+/** A single GitHub Release as returned by the REST API. Only fields we touch are typed. */
+export interface GitHubRelease {
+    id: number;
+    tag_name: string;
+    name: string | null;
+    body: string | null;
+    draft: boolean;
+    prerelease: boolean;
+    html_url: string;
+    published_at: string | null;
+    created_at: string;
+}
+/** Parsed `owner/repo` extracted from various URL/shorthand inputs. */
+export interface OwnerRepo {
+    owner: string;
+    repo: string;
+}
+/**
+ * Accept both `https://github.com/<owner>/<repo>` and shorthand `<owner>/<repo>`.
+ *
+ * We intentionally allow trailing path segments (`.../tree/main`, `.git`) so
+ * users can paste any GitHub URL without trimming first.
+ */
+export declare function parseOwnerRepo(input: string): OwnerRepo;
+/** Build the canonical Releases API URL for an `owner/repo`. */
+export declare function buildReleasesUrl(owner: string, repo: string): string;
+/** Inputs to `fetchReleases()`. `fetch` and `token` are injectable for tests. */
+export interface FetchReleasesOptions {
+    fetch?: FetchLike;
+    /** GitHub PAT (or any token accepted by GitHub). Defaults to `process.env.GITHUB_TOKEN`. */
+    token?: string;
+    /** `If-None-Match` value from a previous response. */
+    etag?: string;
+    /** Logger for rate-limit warnings; defaults to `console.warn`. */
+    warn?: (message: string) => void;
+    signal?: AbortSignal;
+}
+/** Result shape returned by `fetchReleases()`. */
+export interface FetchReleasesResult {
+    status: number;
+    releases: GitHubRelease[];
+    etag: string | null;
+    /** `true` when the server responded 304 Not Modified. */
+    notModified: boolean;
+    rateLimit: RateLimitInfo;
+}
+/** Subset of GitHub rate-limit headers we care about. */
+export interface RateLimitInfo {
+    /** Requests remaining in the current window (`X-RateLimit-Remaining`). */
+    remaining: number | null;
+    /** Total quota for the current window (`X-RateLimit-Limit`). */
+    limit: number | null;
+    /** Unix epoch seconds when the window resets (`X-RateLimit-Reset`). */
+    resetAt: number | null;
+}
+/**
+ * Fetch GitHub Releases for an `owner/repo`.
+ *
+ * Why we hit the REST API directly instead of bringing in `@octokit/rest`:
+ * the adapter only needs one endpoint, and dropping the dep keeps the
+ * published bundle small (see ADR-0002 / issue #37 commit 1 rationale).
+ *
+ * Authentication is opportunistic — without a token we still work, just at
+ * the much lower 60 req/h anonymous rate. The caller (CLI) is expected to
+ * surface `GITHUB_TOKEN` in user-facing docs.
+ */
+export declare function fetchReleases(owner: string, repo: string, options?: FetchReleasesOptions): Promise<FetchReleasesResult>;
+//# sourceMappingURL=github-api.d.ts.map

package/dist/core/feeds/github-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-api.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/github-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5C,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CA+BvD;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA+E9B"}

package/dist/core/feeds/github-api.js

@@ -0,0 +1,161 @@
+const USER_AGENT = "feedradar/0.0.0 (+https://github.com/ozzy-labs/feedradar)";
+const GITHUB_API_BASE = "https://api.github.com";
+/**
+ * Threshold under which we surface a rate-limit warning. GitHub resets the
+ * counter every hour, so 10 leftover requests is the smallest cushion that
+ * still lets a typical run (1–2 sources) complete before reset.
+ */
+const RATE_LIMIT_WARNING_THRESHOLD = 10;
+/**
+ * Accept both `https://github.com/<owner>/<repo>` and shorthand `<owner>/<repo>`.
+ *
+ * We intentionally allow trailing path segments (`.../tree/main`, `.git`) so
+ * users can paste any GitHub URL without trimming first.
+ */
+export function parseOwnerRepo(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new Error("github-releases adapter: empty source URL");
+    let candidate = trimmed;
+    // URL form — strip protocol/host and any trailing path.
+    if (/^https?:\/\//i.test(candidate)) {
+        let url;
+        try {
+            url = new URL(candidate);
+        }
+        catch {
+            throw new Error(`github-releases adapter: invalid URL: ${input}`);
+        }
+        // Accept api.github.com/repos/<owner>/<repo> too, in case someone pastes an API URL.
+        const path = url.pathname.replace(/^\/repos\//, "/").replace(/^\/+|\/+$/g, "");
+        candidate = path;
+    }
+    else {
+        candidate = candidate.replace(/^\/+|\/+$/g, "");
+    }
+    // Strip a `.git` suffix and anything past the second segment (`tree/main`, etc.).
+    const segments = candidate.split("/").filter(Boolean);
+    const [ownerSegment, repoSegment] = segments;
+    if (!ownerSegment || !repoSegment) {
+        throw new Error(`github-releases adapter: expected <owner>/<repo>, got: ${input}`);
+    }
+    const repo = repoSegment.replace(/\.git$/i, "");
+    if (!repo) {
+        throw new Error(`github-releases adapter: expected <owner>/<repo>, got: ${input}`);
+    }
+    return { owner: ownerSegment, repo };
+}
+/** Build the canonical Releases API URL for an `owner/repo`. */
+export function buildReleasesUrl(owner, repo) {
+    return `${GITHUB_API_BASE}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/releases`;
+}
+/**
+ * Fetch GitHub Releases for an `owner/repo`.
+ *
+ * Why we hit the REST API directly instead of bringing in `@octokit/rest`:
+ * the adapter only needs one endpoint, and dropping the dep keeps the
+ * published bundle small (see ADR-0002 / issue #37 commit 1 rationale).
+ *
+ * Authentication is opportunistic — without a token we still work, just at
+ * the much lower 60 req/h anonymous rate. The caller (CLI) is expected to
+ * surface `GITHUB_TOKEN` in user-facing docs.
+ */
+export async function fetchReleases(owner, repo, options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new Error("github-releases adapter: no fetch implementation available (Node 22+ required)");
+    }
+    const token = options.token ?? process.env.GITHUB_TOKEN;
+    const warn = options.warn ?? ((m) => console.warn(m));
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": USER_AGENT,
+        // Pinning the API version protects us from breaking schema changes on
+        // the GitHub side without an explicit migration step.
+        "x-github-api-version": "2022-11-28",
+    };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    if (options.etag)
+        headers["if-none-match"] = options.etag;
+    const url = buildReleasesUrl(owner, repo);
+    const response = await fetchImpl(url, { headers, signal: options.signal });
+    const rateLimit = {
+        remaining: parseIntHeader(response.headers.get("x-ratelimit-remaining")),
+        limit: parseIntHeader(response.headers.get("x-ratelimit-limit")),
+        resetAt: parseIntHeader(response.headers.get("x-ratelimit-reset")),
+    };
+    emitRateLimitWarning(rateLimit, owner, repo, token != null, warn);
+    const etag = response.headers.get("etag");
+    if (response.status === 304) {
+        return { status: 304, releases: [], etag, notModified: true, rateLimit };
+    }
+    if (response.status === 403 && rateLimit.remaining === 0) {
+        // Distinct error message so the CLI / docs can guide users to set
+        // `GITHUB_TOKEN`. The bare HTTP 403 message is ambiguous (could be auth).
+        const resetHint = formatResetHint(rateLimit.resetAt);
+        throw new Error(`github-releases adapter: rate limit exhausted for ${owner}/${repo}${resetHint}. ` +
+            (token
+                ? "Authenticated quota is 5000 req/h."
+                : "Set GITHUB_TOKEN to raise the quota from 60 to 5000 req/h."));
+    }
+    if (response.status === 404) {
+        throw new Error(`github-releases adapter: repository not found: ${owner}/${repo}`);
+    }
+    if (response.status === 401) {
+        throw new Error(`github-releases adapter: authentication failed for ${owner}/${repo} (check GITHUB_TOKEN)`);
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`github-releases adapter: HTTP ${response.status} from ${url}`);
+    }
+    const body = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (e) {
+        throw new Error(`github-releases adapter: failed to parse JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`github-releases adapter: expected JSON array from ${url}, got ${typeof parsed}`);
+    }
+    const releases = parsed.filter(isGitHubRelease);
+    return { status: response.status, releases, etag, notModified: false, rateLimit };
+}
+/** Narrow `unknown` to `GitHubRelease`. Defensive — drops malformed entries silently. */
+function isGitHubRelease(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.id === "number" &&
+        typeof v.tag_name === "string" &&
+        typeof v.html_url === "string" &&
+        typeof v.draft === "boolean" &&
+        typeof v.prerelease === "boolean");
+}
+function parseIntHeader(value) {
+    if (value == null)
+        return null;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : null;
+}
+function emitRateLimitWarning(rateLimit, owner, repo, authenticated, warn) {
+    const { remaining, limit } = rateLimit;
+    if (remaining == null || remaining > RATE_LIMIT_WARNING_THRESHOLD)
+        return;
+    const limitHint = limit != null ? `/${limit}` : "";
+    const authHint = authenticated
+        ? ""
+        : " Set GITHUB_TOKEN to raise the quota from 60 to 5000 req/h.";
+    const resetHint = formatResetHint(rateLimit.resetAt);
+    warn(`github-releases: rate limit low (${remaining}${limitHint} remaining) for ${owner}/${repo}${resetHint}.${authHint}`);
+}
+function formatResetHint(resetAt) {
+    if (resetAt == null)
+        return "";
+    const date = new Date(resetAt * 1000);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return ` (resets at ${date.toISOString()})`;
+}
+//# sourceMappingURL=github-api.js.map

package/dist/core/feeds/github-api.js.map

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

package/dist/core/feeds/github-releases.d.ts

@@ -0,0 +1,3 @@
+import type { FeedAdapter } from "./types.js";
+export declare const githubReleasesAdapter: FeedAdapter;
+//# sourceMappingURL=github-releases.d.ts.map

package/dist/core/feeds/github-releases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-releases.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/github-releases.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,YAAY,CAAC;AAqDlE,eAAO,MAAM,qBAAqB,EAAE,WAmCnC,CAAC"}

package/dist/core/feeds/github-releases.js

@@ -0,0 +1,85 @@
+import { ItemSchema } from "../../schemas/index.js";
+import { deriveItemId, deriveStableKey } from "./derive-id.js";
+import { fetchReleases, parseOwnerRepo } from "./github-api.js";
+/**
+ * Normalize one GitHub Release into our canonical `Item` shape.
+ *
+ * Stable id derivation follows ADR-0002 §"Item ID 派生のコントラクト":
+ * - `publisherId`: `<tag_name>#<id>` — both fields can change independently
+ *   (re-tags rewrite `tag_name` but keep `id`; deleted-and-recreated releases
+ *   keep `tag_name` but get a new `id`). Combining them gives the strongest
+ *   "same entity" signal available, matching the issue spec
+ *   ("stableKey: release tag_name + id").
+ * - `url`: the release HTML URL — kept as a secondary fallback even though
+ *   GitHub guarantees `id`, so the contract behaves uniformly across adapters.
+ * - Title slug: prefer the release `name`; fall back to `tag_name` when the
+ *   maintainer left `name` blank (common on auto-cut releases).
+ */
+function releaseToItem(release, source, fetchedAt) {
+    const title = release.name?.trim() || release.tag_name;
+    const url = release.html_url;
+    const publishedAt = toIsoDate(release.published_at ?? release.created_at);
+    const summary = release.body?.trim() || undefined;
+    const stableKey = deriveStableKey({
+        publisherId: `${release.tag_name}#${release.id}`,
+        url,
+        fallbackHashInputs: [title, publishedAt],
+    });
+    const id = deriveItemId(title, stableKey);
+    const candidate = {
+        id,
+        sourceId: source.id,
+        title,
+        url,
+        summary,
+        publishedAt,
+        fetchedAt,
+        raw: release,
+    };
+    const result = ItemSchema.safeParse(candidate);
+    // Drop malformed entries silently — one broken release should not poison the
+    // whole feed (mirrors the RSS adapter's policy).
+    return result.success ? result.data : null;
+}
+/** Convert a GitHub timestamp to ISO 8601, returning `undefined` for invalid input. */
+function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+export const githubReleasesAdapter = {
+    kind: "github-releases",
+    fetch: async (source, options = {}) => {
+        const { owner, repo } = parseOwnerRepo(source.url);
+        const previous = options.state;
+        const fetchedAt = new Date().toISOString();
+        const response = await fetchReleases(owner, repo, {
+            fetch: options.fetch,
+            etag: previous?.lastEtag,
+        });
+        if (response.notModified) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    lastEtag: response.etag ?? previous?.lastEtag,
+                },
+            };
+        }
+        const items = response.releases
+            .map((release) => releaseToItem(release, source, fetchedAt))
+            .filter((i) => i !== null);
+        return {
+            items,
+            state: {
+                lastFetchedAt: fetchedAt,
+                lastEtag: response.etag ?? previous?.lastEtag,
+            },
+        };
+    },
+};
+//# sourceMappingURL=github-releases.js.map

package/dist/core/feeds/github-releases.js.map

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

package/dist/core/feeds/html.d.ts

@@ -0,0 +1,10 @@
+import type { Item, Source } from "../../schemas/index.js";
+import type { FeedAdapter } from "./types.js";
+/**
+ * Parse an HTML document into validated `Item[]` using the source's
+ * `selectors`. Exported so tests can drive the parser directly without
+ * needing a fake HTTP layer.
+ */
+export declare function parseHtmlDocument(html: string, source: Source, fetchedAt: string): Item[];
+export declare const htmlAdapter: FeedAdapter;
+//# sourceMappingURL=html.d.ts.map

package/dist/core/feeds/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/html.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAmB,MAAM,wBAAwB,CAAC;AAG5E,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC;AA6J7E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAiBzF;AA+CD,eAAO,MAAM,WAAW,EAAE,WAuDzB,CAAC"}