issuary 0.1.0

package/dist/cli.js

@@ -0,0 +1,3528 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import Database from 'better-sqlite3';
+import { parse } from 'yaml';
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+
+/**
+ * Names of the typed errors issuary raises for expected, user-facing failures.
+ *
+ * These carry a message written for a human, so the CLI prints just that line
+ * (no stack trace) and exits non-zero. Anything else is treated as unexpected
+ * and shown with more detail to aid debugging.
+ */
+const FRIENDLY_ERROR_NAMES = new Set([
+    "ConfigError",
+    "GitHubError",
+    "NetworkError",
+    "RepoCommandError",
+    "SyncCommandError",
+    "DigestError",
+    "RepoDigestError",
+    "CompactCommandError",
+    "CompactValidationError",
+    "ShowCommandError",
+    "SkillCommandError",
+    "AuthError",
+]);
+/**
+ * Top-level error handler for the CLI entry point.
+ *
+ * Known typed errors ({@link FRIENDLY_ERROR_NAMES}) print their message alone,
+ * with no stack trace. Unknown errors print a generic line plus their stack (or
+ * string form) so genuine bugs stay debuggable. Always sets a non-zero exit
+ * code; never swallows an error silently.
+ *
+ * @param error - The thrown value to report.
+ * @param sink - Output sink; defaults to `console`.
+ * @returns The process exit code to use (always 1).
+ */
+function handleCliError(error, sink = console) {
+    if (error instanceof Error && FRIENDLY_ERROR_NAMES.has(error.name)) {
+        sink.error(error.message);
+        return 1;
+    }
+    if (error instanceof Error) {
+        sink.error(`Unexpected error: ${error.stack ?? error.message}`);
+        return 1;
+    }
+    sink.error(`Unexpected error: ${String(error)}`);
+    return 1;
+}
+
+/** Name of the credentials file inside the issuary home directory. */
+const CREDENTIALS_FILE = "credentials.json";
+/** Absolute path to the credentials file inside the given issuary home. */
+function credentialsPath(home) {
+    return join(home, CREDENTIALS_FILE);
+}
+/**
+ * Reads the stored GitHub token from `{home}/credentials.json`.
+ *
+ * @param home - The issuary home directory.
+ * @returns The trimmed token, or `null` when absent or unreadable.
+ */
+function readStoredToken(home) {
+    const path = credentialsPath(home);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const token = (parsed.github_token ?? "").trim();
+        return token === "" ? null : token;
+    }
+    catch {
+        // A corrupt or unreadable file should not crash callers; treat as no token.
+        return null;
+    }
+}
+/**
+ * Writes the GitHub token to `{home}/credentials.json` with mode `0600`.
+ *
+ * Creates the home directory if needed. The token is never logged.
+ *
+ * @param home - The issuary home directory.
+ * @param token - The GitHub access token to store.
+ */
+function writeStoredToken(home, token) {
+    // 0700 so a stored credential is not even listable by other local users; the
+    // file itself is 0600. mode only applies on creation, which is fine here.
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const path = credentialsPath(home);
+    const data = { github_token: token };
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * Removes the stored credentials file.
+ *
+ * @param home - The issuary home directory.
+ * @returns `true` when a file was removed, `false` when none existed.
+ */
+function clearStoredToken(home) {
+    const path = credentialsPath(home);
+    if (!existsSync(path)) {
+        return false;
+    }
+    rmSync(path);
+    return true;
+}
+
+/** Default GitHub REST API base URL used when `GITHUB_API_URL` is unset. */
+const DEFAULT_API_URL = "https://api.github.com";
+/**
+ * Error thrown when configuration is invalid or incomplete.
+ *
+ * Callers should catch this to print a friendly, actionable message instead of
+ * a stack trace. Messages never contain secret values such as the token.
+ */
+class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Loads and validates configuration from the environment.
+ *
+ * Reads `GITHUB_TOKEN`, `GITHUB_API_URL` and `ISSUARY_HOME`, applying defaults and
+ * normalization. The token is resolved in precedence order: the `GITHUB_TOKEN`
+ * environment variable wins, then the token stored by `issuary login` in the
+ * credentials file. Throws {@link ConfigError} when a required value is missing.
+ *
+ * @param options - Resolution options; see {@link LoadConfigOptions}.
+ * @returns The resolved {@link Config}.
+ * @throws {ConfigError} When `requireToken` is `true` and no token is resolvable.
+ */
+function loadConfig(options = {}) {
+    const { requireToken = true } = options;
+    const apiUrl = normalizeApiUrl(process.env.GITHUB_API_URL);
+    const home = (process.env.ISSUARY_HOME ?? "").trim() || join(homedir(), ".issuary");
+    const dbPath = join(home, "db.sqlite");
+    // Precedence: GITHUB_TOKEN env wins, then a token stored by `issuary login`.
+    const envToken = (process.env.GITHUB_TOKEN ?? "").trim();
+    const token = envToken || readStoredToken(home) || "";
+    if (requireToken && token === "") {
+        throw new ConfigError("No GitHub token found. issuary needs a GitHub personal access token to reach the API. " +
+            "Either run `issuary login` to authenticate via the browser, or create a token at " +
+            "https://github.com/settings/tokens with the `repo` (or `public_repo`) read scope and " +
+            "export it, e.g. `export GITHUB_TOKEN=ghp_...`.");
+    }
+    return { token, apiUrl, home, dbPath };
+}
+/**
+ * Normalizes the API base URL: falls back to the default when unset/empty and
+ * trims any trailing slashes.
+ */
+function normalizeApiUrl(raw) {
+    const value = (raw ?? "").trim() || DEFAULT_API_URL;
+    return value.replace(/\/+$/, "");
+}
+
+/**
+ * Error thrown for a non-2xx, non-304 GitHub response (401, 403, 404, 422, ...).
+ *
+ * Carries the HTTP `status` and the parsed {@link RateLimit} so callers can
+ * distinguish auth failures from a rate-limit 403 and back off accordingly.
+ */
+class GitHubError extends Error {
+    /** HTTP status code of the failing response. */
+    status;
+    /** Rate-limit state at the time of the failure, when available. */
+    rateLimit;
+    constructor(message, status, rateLimit = null) {
+        super(message);
+        this.name = "GitHubError";
+        this.status = status;
+        this.rateLimit = rateLimit;
+    }
+}
+/**
+ * Error thrown when a `fetch` to GitHub keeps failing at the transport level
+ * (DNS, connection reset, `fetch failed`) after the client's bounded retries are
+ * exhausted. Distinct from {@link GitHubError}, which carries an HTTP status.
+ *
+ * Callers should catch this to print a friendly message instead of a raw stack.
+ */
+class NetworkError extends Error {
+    /** The last underlying transport error that triggered the failure, if any. */
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "NetworkError";
+        this.cause = cause;
+    }
+}
+
+/** Returns true when the payload item is a pull request, not a real issue. */
+function isPullRequest(item) {
+    return item.pull_request != null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+function asStringOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
+function asNumber(value) {
+    return typeof value === "number" ? value : 0;
+}
+function authorOf(user) {
+    return asStringOrNull(user?.login);
+}
+function stateOf(value) {
+    return value === "closed" ? "closed" : "open";
+}
+function stateReasonOf(value) {
+    return value === "completed" || value === "not_planned" ? value : null;
+}
+function labelsOf(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const names = [];
+    for (const label of value) {
+        const name = asStringOrNull(label?.name);
+        if (name !== null) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Maps a raw GitHub issue payload to the lean {@link NormalizedIssue} shape.
+ *
+ * `state_reason` and `labels` are copied verbatim, never interpreted.
+ */
+function normalizeIssue(raw) {
+    return {
+        number: asNumber(raw.number),
+        title: asString(raw.title),
+        state: stateOf(raw.state),
+        state_reason: stateReasonOf(raw.state_reason),
+        author: authorOf(raw.user),
+        labels: labelsOf(raw.labels),
+        created_at: asString(raw.created_at),
+        updated_at: asString(raw.updated_at),
+        closed_at: asStringOrNull(raw.closed_at),
+        comment_count: asNumber(raw.comments),
+        body: asStringOrNull(raw.body),
+    };
+}
+/**
+ * Maps a raw GitHub comment payload to the lean {@link NormalizedComment} shape.
+ */
+function normalizeComment(raw) {
+    return {
+        id: asNumber(raw.id),
+        author: authorOf(raw.user),
+        created_at: asString(raw.created_at),
+        updated_at: asString(raw.updated_at),
+        body: asStringOrNull(raw.body),
+    };
+}
+
+const API_VERSION = "2022-11-28";
+const ACCEPT = "application/vnd.github+json";
+const USER_AGENT = "merencia-issuary";
+const PER_PAGE = 100;
+/** Default number of automatic retries for rate-limit and network failures. */
+const DEFAULT_MAX_RETRIES = 3;
+/** Default cap on how long the client waits for a rate-limit window to reset. */
+const DEFAULT_MAX_RATE_LIMIT_WAIT_MS = 3 * 60 * 1000;
+/** Base delay (ms) for the exponential backoff between network-error retries. */
+const DEFAULT_NETWORK_BACKOFF_MS = 500;
+/** Default sleep backed by a real timer. */
+function defaultSleep$1(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Heuristic for a transient transport failure worth retrying: a thrown error
+ * (not an HTTP response) whose code or message points at a reset connection,
+ * a DNS hiccup, a timeout, or undici's generic `fetch failed`.
+ */
+function isTransientNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const code = error.code;
+    if (typeof code === "string") {
+        if (["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET"].includes(code)) {
+            return true;
+        }
+    }
+    const message = error.message.toLowerCase();
+    return (message.includes("fetch failed") ||
+        message.includes("econnreset") ||
+        message.includes("socket hang up") ||
+        message.includes("terminated"));
+}
+/** True when a response is a rate-limit rejection (403/429 with the tell-tale signals). */
+function isRateLimitedResponse(response, rateLimit) {
+    if (response.status !== 403 && response.status !== 429) {
+        return false;
+    }
+    if (response.headers.has("retry-after")) {
+        return true;
+    }
+    return rateLimit?.remaining === 0;
+}
+/**
+ * Computes how long to wait (ms) before retrying a rate-limited response.
+ * Prefers `Retry-After` (delta seconds), falling back to `x-ratelimit-reset`
+ * (epoch seconds). Returns 0 when no hint is present.
+ */
+function rateLimitWaitMs(response, rateLimit, nowMs) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter !== null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return Math.ceil(seconds * 1000);
+        }
+    }
+    if (rateLimit?.reset != null && Number.isFinite(rateLimit.reset)) {
+        return Math.max(0, rateLimit.reset * 1000 - nowMs);
+    }
+    return 0;
+}
+/**
+ * Parses a {@link RepoInput} into a {@link RepoRef}.
+ *
+ * @throws {GitHubError} (status 0) when the `"owner/name"` string is malformed.
+ */
+function parseRepo(repo) {
+    if (typeof repo !== "string") {
+        return repo;
+    }
+    const [owner, name, ...rest] = repo.split("/");
+    if (!owner || !name || rest.length > 0) {
+        throw new GitHubError(`Invalid repo "${repo}", expected "owner/name".`, 0);
+    }
+    return { owner, name };
+}
+/** Parses the `rel="next"` URL out of a `Link` header, or null when absent. */
+function nextLink(linkHeader) {
+    if (!linkHeader) {
+        return null;
+    }
+    for (const part of linkHeader.split(",")) {
+        const match = part.match(/<([^>]+)>\s*;\s*rel="next"/);
+        if (match) {
+            return match[1];
+        }
+    }
+    return null;
+}
+/** Reads `x-ratelimit-*` headers into a {@link RateLimit}. */
+function parseRateLimit(headers) {
+    const remaining = headers.get("x-ratelimit-remaining");
+    const reset = headers.get("x-ratelimit-reset");
+    return {
+        remaining: remaining === null ? null : Number(remaining),
+        reset: reset === null ? null : Number(reset),
+    };
+}
+/**
+ * Creates a GitHub REST client backed by the global `fetch`.
+ *
+ * The client is stateless except for {@link GitHubClient.rateLimit}, which holds
+ * the rate-limit headers seen on the most recent response.
+ *
+ * @param options - Token, API base URL, and optional `fetch` override.
+ * @returns A {@link GitHubClient}.
+ */
+function createGitHubClient(options) {
+    const { token, apiUrl } = options;
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? defaultSleep$1;
+    const now = options.now ?? Date.now;
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const maxRateLimitWaitMs = options.maxRateLimitWaitMs ?? DEFAULT_MAX_RATE_LIMIT_WAIT_MS;
+    const networkBackoffMs = options.networkBackoffMs ?? DEFAULT_NETWORK_BACKOFF_MS;
+    let rateLimit = null;
+    function baseHeaders() {
+        return {
+            Authorization: `Bearer ${token}`,
+            Accept: ACCEPT,
+            "X-GitHub-Api-Version": API_VERSION,
+            "User-Agent": USER_AGENT,
+        };
+    }
+    /** Wraps a `Retry-After`/reset wait into a dated, fail-fast GitHubError. */
+    function rateLimitFailFast(waitMs) {
+        const retryAt = new Date(now() + waitMs).toISOString();
+        throw new GitHubError(`GitHub rate limit exceeded and the reset is ${Math.ceil(waitMs / 1000)}s away, ` +
+            `beyond the ${Math.ceil(maxRateLimitWaitMs / 1000)}s wait cap. Retry after ${retryAt}.`, 403, rateLimit);
+    }
+    /** Throws a dated GitHubError when rate-limit retries are exhausted. */
+    function rateLimitExhausted(waitMs) {
+        const retryAt = new Date(now() + waitMs).toISOString();
+        throw new GitHubError(`GitHub rate limit exceeded after ${maxRetries} retries. Retry after ${retryAt}.`, 403, rateLimit);
+    }
+    /**
+     * Performs a single request, retrying on rate-limit (403/429) and transient
+     * network failures up to {@link maxRetries} times. Rate-limit retries honor
+     * `Retry-After`/`x-ratelimit-reset` (capped); network retries use exponential
+     * backoff. Both waits go through the injectable {@link sleep}.
+     */
+    async function request(url, headers) {
+        let attempt = 0;
+        for (;;) {
+            let response;
+            try {
+                response = await doFetch(url, { headers });
+            }
+            catch (error) {
+                if (isTransientNetworkError(error) && attempt < maxRetries) {
+                    await sleep(networkBackoffMs * 2 ** attempt);
+                    attempt += 1;
+                    continue;
+                }
+                if (isTransientNetworkError(error)) {
+                    throw new NetworkError(`Network request to GitHub failed after ${attempt + 1} attempts: ${error.message}.`, error);
+                }
+                throw error;
+            }
+            rateLimit = parseRateLimit(response.headers);
+            if (isRateLimitedResponse(response, rateLimit)) {
+                const waitMs = rateLimitWaitMs(response, rateLimit, now());
+                if (waitMs > maxRateLimitWaitMs) {
+                    rateLimitFailFast(waitMs);
+                }
+                if (attempt < maxRetries) {
+                    await sleep(waitMs);
+                    attempt += 1;
+                    continue;
+                }
+                // Retries exhausted while still rate-limited: throw an explicit dated
+                // error rather than falling through to the generic failure message.
+                rateLimitExhausted(waitMs);
+            }
+            return response;
+        }
+    }
+    /** Turns a non-ok, non-304 response into a thrown {@link GitHubError}. */
+    async function fail(response) {
+        const { status } = response;
+        const isRateLimited = (status === 403 || status === 429) && rateLimit?.remaining === 0;
+        let message;
+        if (isRateLimited) {
+            message = "GitHub rate limit exceeded (x-ratelimit-remaining is 0).";
+        }
+        else if (status === 404) {
+            // 404 is ambiguous: the repo may not exist, or the token may simply lack
+            // access to a private repo (GitHub hides those behind a 404 on purpose).
+            message = "GitHub returned 404: the repo was not found or your token has no access to it.";
+        }
+        else {
+            const detail = await readErrorMessage(response);
+            message = `GitHub request failed with ${status}${detail ? `: ${detail}` : ""}.`;
+        }
+        throw new GitHubError(message, status, rateLimit);
+    }
+    async function getRepo(repo) {
+        const { owner, name } = parseRepo(repo);
+        const response = await request(`${apiUrl}/repos/${owner}/${name}`, baseHeaders());
+        if (!response.ok) {
+            await fail(response);
+        }
+        const body = (await response.json());
+        return {
+            owner: typeof body.owner?.login === "string" ? body.owner.login : owner,
+            name: typeof body.name === "string" ? body.name : name,
+            fullName: typeof body.full_name === "string" ? body.full_name : `${owner}/${name}`,
+            private: body.private === true,
+        };
+    }
+    async function listIssues(repo, listOptions = {}) {
+        const { owner, name } = parseRepo(repo);
+        const params = new URLSearchParams({
+            state: "all",
+            per_page: String(PER_PAGE),
+            sort: "updated",
+            direction: "asc",
+        });
+        if (listOptions.since) {
+            params.set("since", listOptions.since);
+        }
+        let url = `${apiUrl}/repos/${owner}/${name}/issues?${params.toString()}`;
+        const issues = [];
+        let etag = null;
+        let first = true;
+        while (url) {
+            const headers = baseHeaders();
+            // The conditional request only makes sense for the first page.
+            if (first && listOptions.etag) {
+                headers["If-None-Match"] = listOptions.etag;
+            }
+            const response = await request(url, headers);
+            if (first && response.status === 304) {
+                return { status: "notModified" };
+            }
+            if (!response.ok) {
+                await fail(response);
+            }
+            if (first) {
+                etag = response.headers.get("etag");
+                first = false;
+            }
+            const page = (await response.json());
+            for (const item of page) {
+                if (!isPullRequest(item)) {
+                    issues.push(normalizeIssue(item));
+                }
+            }
+            url = nextLink(response.headers.get("link"));
+        }
+        return { status: "ok", issues, etag };
+    }
+    async function getComments(repo, number) {
+        const { owner, name } = parseRepo(repo);
+        const params = new URLSearchParams({ per_page: String(PER_PAGE) });
+        let url = `${apiUrl}/repos/${owner}/${name}/issues/${number}/comments?${params.toString()}`;
+        const comments = [];
+        while (url) {
+            const response = await request(url, baseHeaders());
+            if (!response.ok) {
+                await fail(response);
+            }
+            const page = (await response.json());
+            for (const item of page) {
+                comments.push(normalizeComment(item));
+            }
+            url = nextLink(response.headers.get("link"));
+        }
+        return comments;
+    }
+    return {
+        getRepo,
+        listIssues,
+        getComments,
+        get rateLimit() {
+            return rateLimit;
+        },
+    };
+}
+/** Best-effort extraction of GitHub's JSON `message` field for error detail. */
+async function readErrorMessage(response) {
+    try {
+        const body = (await response.json());
+        return typeof body.message === "string" ? body.message : null;
+    }
+    catch {
+        return null;
+    }
+}
+
+const migrations = [
+    {
+        version: 1,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE repos (
+          id INTEGER PRIMARY KEY,
+          owner TEXT NOT NULL,
+          name TEXT NOT NULL,
+          full_name TEXT NOT NULL UNIQUE,
+          added_at TEXT NOT NULL,
+          active INTEGER NOT NULL DEFAULT 1,
+          last_synced_at TEXT,
+          etag TEXT
+        );
+
+        CREATE TABLE issues (
+          id INTEGER PRIMARY KEY,
+          repo_id INTEGER NOT NULL REFERENCES repos(id),
+          number INTEGER NOT NULL,
+          title TEXT NOT NULL,
+          state TEXT NOT NULL,
+          state_reason TEXT,
+          author TEXT,
+          labels TEXT,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          closed_at TEXT,
+          comment_count INTEGER NOT NULL DEFAULT 0,
+          raw_body TEXT,
+          raw_comments TEXT,
+          raw_fetched_at TEXT,
+          compact TEXT,
+          compact_tldr TEXT,
+          compact_stale INTEGER NOT NULL DEFAULT 0,
+          compacted_at TEXT,
+          UNIQUE(repo_id, number)
+        );
+
+        CREATE TABLE events (
+          id INTEGER PRIMARY KEY,
+          issue_id INTEGER NOT NULL REFERENCES issues(id),
+          type TEXT NOT NULL,
+          detected_at TEXT NOT NULL,
+          seen INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE TABLE refs (
+          id INTEGER PRIMARY KEY,
+          issue_id INTEGER NOT NULL REFERENCES issues(id),
+          target TEXT NOT NULL,
+          UNIQUE(issue_id, target)
+        );
+
+        CREATE INDEX idx_issues_repo ON issues(repo_id);
+        CREATE INDEX idx_events_issue ON events(issue_id);
+        CREATE INDEX idx_refs_issue ON refs(issue_id);
+      `);
+        },
+    },
+];
+/**
+ * The schema version the code expects. Equals the highest defined migration.
+ */
+migrations[migrations.length - 1].version;
+/**
+ * Runs any pending migrations against the database, in order. Idempotent: the
+ * current schema version is read from the `user_version` pragma, and only
+ * migrations newer than it are applied. Each migration runs in its own
+ * transaction.
+ */
+function migrate(db) {
+    const current = db.pragma("user_version", { simple: true });
+    for (const migration of migrations) {
+        if (migration.version <= current) {
+            continue;
+        }
+        const run = db.transaction(() => {
+            migration.up(db);
+            db.pragma(`user_version = ${migration.version}`);
+        });
+        run();
+    }
+}
+
+function rowToEventWithContext(row) {
+    return {
+        id: row.id,
+        issueId: row.issue_id,
+        type: row.type,
+        detectedAt: row.detected_at,
+        seen: row.seen !== 0,
+        repoId: row.repo_id,
+        repoFullName: row.repo_full_name,
+        issueNumber: row.issue_number,
+        issueTitle: row.issue_title,
+        issueState: row.issue_state,
+    };
+}
+function rowToRef(row) {
+    return {
+        id: row.id,
+        issueId: row.issue_id,
+        target: row.target,
+    };
+}
+function rowToEvent(row) {
+    return {
+        id: row.id,
+        issueId: row.issue_id,
+        type: row.type,
+        detectedAt: row.detected_at,
+        seen: row.seen !== 0,
+    };
+}
+function rowToRepo(row) {
+    return {
+        id: row.id,
+        owner: row.owner,
+        name: row.name,
+        fullName: row.full_name,
+        addedAt: row.added_at,
+        active: row.active !== 0,
+        lastSyncedAt: row.last_synced_at,
+        etag: row.etag,
+    };
+}
+function rowToIssue(row) {
+    return {
+        id: row.id,
+        repoId: row.repo_id,
+        number: row.number,
+        title: row.title,
+        state: row.state,
+        stateReason: row.state_reason,
+        author: row.author,
+        labels: row.labels,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        closedAt: row.closed_at,
+        commentCount: row.comment_count,
+        rawBody: row.raw_body,
+        rawComments: row.raw_comments,
+        rawFetchedAt: row.raw_fetched_at,
+        compact: row.compact,
+        compactTldr: row.compact_tldr,
+        compactStale: row.compact_stale !== 0,
+        compactedAt: row.compacted_at,
+    };
+}
+function rowToIssueWithRepo(row) {
+    return { ...rowToIssue(row), repoFullName: row.repo_full_name };
+}
+/**
+ * Opens (creating its parent directory if needed) a SQLite database at
+ * `dbPath`, enables foreign keys and WAL journaling, runs pending migrations,
+ * and returns a typed {@link Store}. Pass `:memory:` for an ephemeral database.
+ *
+ * The path is an explicit argument (dependency injection) so callers and tests
+ * control where state lives; use {@link defaultDbPath} for the production path.
+ */
+function openStore(dbPath) {
+    if (dbPath !== ":memory:") {
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    const db = new Database(dbPath);
+    db.pragma("foreign_keys = ON");
+    db.pragma("journal_mode = WAL");
+    migrate(db);
+    const insertRepoStmt = db.prepare(`INSERT INTO repos (owner, name, full_name, added_at)
+     VALUES (?, ?, ?, ?)
+     RETURNING *`);
+    const getRepoStmt = db.prepare(`SELECT * FROM repos WHERE id = ?`);
+    const getRepoByFullNameStmt = db.prepare(`SELECT * FROM repos WHERE full_name = ?`);
+    const listReposStmt = db.prepare(`SELECT * FROM repos ORDER BY full_name`);
+    const listActiveReposStmt = db.prepare(`SELECT * FROM repos WHERE active = 1 ORDER BY full_name`);
+    const setRepoActiveStmt = db.prepare(`UPDATE repos SET active = ? WHERE full_name = ? RETURNING *`);
+    const upsertIssueStmt = db.prepare(`INSERT INTO issues (
+       repo_id, number, title, state, state_reason, author, labels,
+       created_at, updated_at, closed_at, comment_count,
+       raw_body, raw_comments, raw_fetched_at,
+       compact, compact_tldr, compact_stale, compacted_at
+     ) VALUES (
+       @repoId, @number, @title, @state, @stateReason, @author, @labels,
+       @createdAt, @updatedAt, @closedAt, @commentCount,
+       @rawBody, @rawComments, @rawFetchedAt,
+       @compact, @compactTldr, @compactStale, @compactedAt
+     )
+     ON CONFLICT(repo_id, number) DO UPDATE SET
+       title = excluded.title,
+       state = excluded.state,
+       state_reason = excluded.state_reason,
+       author = excluded.author,
+       labels = excluded.labels,
+       created_at = excluded.created_at,
+       updated_at = excluded.updated_at,
+       closed_at = excluded.closed_at,
+       comment_count = excluded.comment_count,
+       raw_body = excluded.raw_body,
+       raw_comments = excluded.raw_comments,
+       raw_fetched_at = excluded.raw_fetched_at,
+       compact = excluded.compact,
+       compact_tldr = excluded.compact_tldr,
+       compact_stale = excluded.compact_stale,
+       compacted_at = excluded.compacted_at
+     RETURNING *`);
+    const getIssueStmt = db.prepare(`SELECT * FROM issues WHERE repo_id = ? AND number = ?`);
+    const listIssuesStmt = db.prepare(`SELECT * FROM issues WHERE repo_id = ? ORDER BY number`);
+    const setCompactStmt = db.prepare(`UPDATE issues
+        SET compact = ?, compact_tldr = ?, compact_stale = 0, compacted_at = ?
+      WHERE repo_id = ? AND number = ?
+     RETURNING *`);
+    const setIssueRawCommentsStmt = db.prepare(`UPDATE issues
+        SET raw_comments = ?, raw_fetched_at = ?
+      WHERE repo_id = ? AND number = ?
+     RETURNING *`);
+    const insertEventStmt = db.prepare(`INSERT INTO events (issue_id, type, detected_at) VALUES (?, ?, ?) RETURNING *`);
+    const setCompactStaleStmt = db.prepare(`UPDATE issues SET compact_stale = ? WHERE id = ?`);
+    const updateRepoSyncStmt = db.prepare(`UPDATE repos SET last_synced_at = ?, etag = ? WHERE id = ?`);
+    const deleteIssueRefsStmt = db.prepare(`DELETE FROM refs WHERE issue_id = ?`);
+    const insertIssueRefStmt = db.prepare(`INSERT OR IGNORE INTO refs (issue_id, target) VALUES (?, ?)`);
+    const listIssueRefsStmt = db.prepare(`SELECT * FROM refs WHERE issue_id = ? ORDER BY id`);
+    return {
+        db,
+        insertRepo(repo) {
+            const addedAt = new Date().toISOString();
+            const row = insertRepoStmt.get(repo.owner, repo.name, repo.fullName, addedAt);
+            return rowToRepo(row);
+        },
+        getRepo(id) {
+            const row = getRepoStmt.get(id);
+            return row ? rowToRepo(row) : undefined;
+        },
+        getRepoByFullName(fullName) {
+            const row = getRepoByFullNameStmt.get(fullName);
+            return row ? rowToRepo(row) : undefined;
+        },
+        listRepos(options) {
+            const stmt = options?.activeOnly ? listActiveReposStmt : listReposStmt;
+            const rows = stmt.all();
+            return rows.map(rowToRepo);
+        },
+        setRepoActive(fullName, active) {
+            const row = setRepoActiveStmt.get(active ? 1 : 0, fullName);
+            return row ? rowToRepo(row) : undefined;
+        },
+        upsertIssue(issue) {
+            const row = upsertIssueStmt.get({
+                repoId: issue.repoId,
+                number: issue.number,
+                title: issue.title,
+                state: issue.state,
+                stateReason: issue.stateReason ?? null,
+                author: issue.author ?? null,
+                labels: issue.labels ?? null,
+                createdAt: issue.createdAt,
+                updatedAt: issue.updatedAt,
+                closedAt: issue.closedAt ?? null,
+                commentCount: issue.commentCount ?? 0,
+                rawBody: issue.rawBody ?? null,
+                rawComments: issue.rawComments ?? null,
+                rawFetchedAt: issue.rawFetchedAt ?? null,
+                compact: issue.compact ?? null,
+                compactTldr: issue.compactTldr ?? null,
+                compactStale: (issue.compactStale ?? false) ? 1 : 0,
+                compactedAt: issue.compactedAt ?? null,
+            });
+            return rowToIssue(row);
+        },
+        getIssue(repoId, number) {
+            const row = getIssueStmt.get(repoId, number);
+            return row ? rowToIssue(row) : undefined;
+        },
+        listIssues(repoId) {
+            const rows = listIssuesStmt.all(repoId);
+            return rows.map(rowToIssue);
+        },
+        queryIssues(filter = {}) {
+            // Only issues from active repos: a repo removed via `remove` keeps its
+            // history but must not surface in listings, consistent with every other
+            // command.
+            const conditions = ["r.active = 1"];
+            const params = [];
+            if (filter.state && filter.state !== "all") {
+                conditions.push("i.state = ?");
+                params.push(filter.state);
+            }
+            if (filter.repoIds && filter.repoIds.length > 0) {
+                const placeholders = filter.repoIds.map(() => "?").join(", ");
+                conditions.push(`i.repo_id IN (${placeholders})`);
+                params.push(...filter.repoIds);
+            }
+            if (filter.author) {
+                conditions.push("i.author = ?");
+                params.push(filter.author);
+            }
+            if (filter.stateReason) {
+                conditions.push("i.state_reason = ?");
+                params.push(filter.stateReason);
+            }
+            if (filter.since) {
+                conditions.push("i.updated_at >= ?");
+                params.push(filter.since);
+            }
+            if (filter.search) {
+                // Case-insensitive substring match. LIKE is case-insensitive for ASCII
+                // in SQLite by default; lower() on both sides covers the rest.
+                conditions.push("lower(i.title) LIKE '%' || lower(?) || '%'");
+                params.push(filter.search);
+            }
+            if (filter.compaction === "uncompacted") {
+                conditions.push("i.compact IS NULL");
+            }
+            else if (filter.compaction === "stale") {
+                conditions.push("i.compact IS NOT NULL AND i.compact_stale = 1");
+            }
+            else if (filter.compaction === "compacted") {
+                conditions.push("i.compact IS NOT NULL AND i.compact_stale = 0");
+            }
+            if (filter.labels && filter.labels.length > 0) {
+                const placeholders = filter.labels.map(() => "?").join(", ");
+                conditions.push(`EXISTS (SELECT 1 FROM json_each(i.labels) WHERE json_each.value IN (${placeholders}))`);
+                params.push(...filter.labels);
+            }
+            const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+            const sortColumn = { updated: "i.updated_at", created: "i.created_at", number: "i.number" }[filter.sort ?? "updated"];
+            const direction = filter.order === "asc" ? "ASC" : "DESC";
+            // Stable tiebreaker so equal sort keys have a deterministic order.
+            const orderBy = `ORDER BY ${sortColumn} ${direction}, i.number ${direction}`;
+            const limit = filter.limit !== undefined && filter.limit > 0 ? "LIMIT ?" : "";
+            if (limit) {
+                params.push(filter.limit);
+            }
+            const sql = `
+        SELECT i.*, r.full_name AS repo_full_name
+        FROM issues i
+        JOIN repos r ON r.id = i.repo_id
+        ${where}
+        ${orderBy}
+        ${limit}`;
+            const rows = db.prepare(sql).all(...params);
+            return rows.map(rowToIssueWithRepo);
+        },
+        setCompact(repoId, number, compact) {
+            const compactedAt = new Date().toISOString();
+            const row = setCompactStmt.get(compact.compact, compact.tldr, compactedAt, repoId, number);
+            return row ? rowToIssue(row) : undefined;
+        },
+        close() {
+            db.close();
+        },
+        setIssueRawComments(repoId, number, commentsJson, fetchedAt) {
+            const row = setIssueRawCommentsStmt.get(commentsJson, fetchedAt, repoId, number);
+            return row ? rowToIssue(row) : undefined;
+        },
+        insertEvent(issueId, type, detectedAt) {
+            const row = insertEventStmt.get(issueId, type, detectedAt);
+            return rowToEvent(row);
+        },
+        setCompactStale(issueId, stale) {
+            setCompactStaleStmt.run(stale ? 1 : 0, issueId);
+        },
+        updateRepoSync(repoId, sync) {
+            updateRepoSyncStmt.run(sync.lastSyncedAt, sync.etag, repoId);
+        },
+        listEvents(filter) {
+            const conditions = [];
+            const params = [];
+            if (filter?.seen !== undefined) {
+                conditions.push("e.seen = ?");
+                params.push(filter.seen ? 1 : 0);
+            }
+            if (filter?.since !== undefined) {
+                conditions.push("e.detected_at >= ?");
+                params.push(filter.since);
+            }
+            if (filter?.repoId !== undefined) {
+                conditions.push("r.id = ?");
+                params.push(filter.repoId);
+            }
+            const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+            const sql = `
+        SELECT
+          e.id AS id,
+          e.issue_id AS issue_id,
+          e.type AS type,
+          e.detected_at AS detected_at,
+          e.seen AS seen,
+          r.id AS repo_id,
+          r.full_name AS repo_full_name,
+          i.number AS issue_number,
+          i.title AS issue_title,
+          i.state AS issue_state
+        FROM events e
+        JOIN issues i ON i.id = e.issue_id
+        JOIN repos r ON r.id = i.repo_id
+        ${where}
+        ORDER BY e.detected_at DESC, e.id DESC`;
+            const rows = db.prepare(sql).all(...params);
+            return rows.map(rowToEventWithContext);
+        },
+        markEventsSeen(eventIds) {
+            if (eventIds.length === 0) {
+                return;
+            }
+            const placeholders = eventIds.map(() => "?").join(", ");
+            db.prepare(`UPDATE events SET seen = 1 WHERE id IN (${placeholders})`).run(...eventIds);
+        },
+        replaceIssueRefs(issueId, targets) {
+            const apply = db.transaction(() => {
+                deleteIssueRefsStmt.run(issueId);
+                for (const target of targets) {
+                    insertIssueRefStmt.run(issueId, target);
+                }
+            });
+            apply();
+        },
+        listIssueRefs(issueId) {
+            const rows = listIssueRefsStmt.all(issueId);
+            return rows.map(rowToRef);
+        },
+    };
+}
+
+/**
+ * Error thrown by the repo commands for expected, user-facing failures (malformed
+ * argument, repo not found, repo not watched). The CLI prints the message and
+ * exits non-zero.
+ */
+class RepoCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RepoCommandError";
+    }
+}
+/**
+ * Parses an `owner/repo` string argument.
+ *
+ * @throws {RepoCommandError} When the argument is not in the expected shape.
+ */
+function parseRepoArg(arg) {
+    const match = /^([^/\s]+)\/([^/\s]+)$/.exec(arg.trim());
+    if (!match) {
+        throw new RepoCommandError(`Invalid repo "${arg}". Expected the form owner/repo, e.g. octocat/hello.`);
+    }
+    return { owner: match[1], name: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+/**
+ * Core action for `issuary add`: validates the repo exists/accessible on GitHub,
+ * then inserts it (or reactivates it if it was previously removed).
+ *
+ * Separated from the Commander wiring so it can be tested with an injected
+ * client and store. The caller owns the {@link Store} lifecycle.
+ *
+ * @throws {RepoCommandError} For expected, user-facing failures.
+ * @throws {GitHubError} For unexpected GitHub failures (auth, rate limit, ...).
+ */
+async function runAdd(store, client, arg) {
+    const { owner, name, fullName } = parseRepoArg(arg);
+    try {
+        await client.getRepo({ owner, name });
+    }
+    catch (error) {
+        if (error instanceof GitHubError && error.status === 404) {
+            throw new RepoCommandError(`Repo "${fullName}" not found or no access. Check the name and your token's scopes.`);
+        }
+        throw error;
+    }
+    const existing = store.getRepoByFullName(fullName);
+    if (existing) {
+        if (existing.active) {
+            return { ok: true, repo: fullName, status: "already-watched" };
+        }
+        store.setRepoActive(fullName, true);
+        return { ok: true, repo: fullName, status: "reactivated" };
+    }
+    store.insertRepo({ owner, name, fullName });
+    return { ok: true, repo: fullName, status: "added" };
+}
+/** Human-readable line for a successful {@link runAdd}. */
+function addMessage(result) {
+    switch (result.status) {
+        case "added":
+            return `Now watching ${result.repo}.`;
+        case "reactivated":
+            return `Reactivated ${result.repo} (it was previously removed).`;
+        case "already-watched":
+            return `${result.repo} is already watched.`;
+    }
+}
+/** Builds the `add` command. */
+function addCommand() {
+    return new Command("add")
+        .description("Watch a GitHub repo's issues (validates it exists via the API)")
+        .argument("<owner/repo>", "repository to watch, as owner/repo")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (arg, options) => {
+        const config = loadConfig();
+        const client = createGitHubClient({ token: config.token, apiUrl: config.apiUrl });
+        const store = openStore(config.dbPath);
+        try {
+            const result = await runAdd(store, client, arg);
+            if (options.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(addMessage(result));
+            }
+        }
+        catch (error) {
+            if (error instanceof RepoCommandError || error instanceof GitHubError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Error thrown when a compact file does not conform to the canonical format.
+ *
+ * Carries a clear, human-readable message pointing at what is wrong. Callers
+ * (the `compact set` command) catch this to print a friendly error instead of a
+ * stack trace.
+ *
+ * @see file://../../docs/compact-format.md
+ */
+class CompactValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompactValidationError";
+    }
+}
+/** The allowed values for the frontmatter `status` field. */
+const VALID_STATUS = ["open", "closed"];
+/** The allowed values for the frontmatter `state_reason` field (besides null). */
+const VALID_STATE_REASON = ["completed", "not_planned"];
+/**
+ * Parses and validates a compact file in the canonical format.
+ *
+ * The canonical format is frontmatter between `---` fences (copied from the
+ * GitHub API) followed by an AI-written body. This function validates that the
+ * required structure and fields are present and well-formed, extracts the
+ * `tldr` for separate storage, and returns the full original text unchanged so
+ * it round-trips.
+ *
+ * @param text - The raw compact file contents.
+ * @returns The validated {@link ParsedCompact}.
+ * @throws {CompactValidationError} When the structure or any required field is invalid.
+ * @see file://../../docs/compact-format.md
+ */
+function parseCompact(text) {
+    const { frontmatterText, bodyText } = splitFrontmatter(text);
+    const frontmatter = parseFrontmatter(frontmatterText);
+    const tldr = extractTldr(bodyText);
+    return { compact: text, tldr, frontmatter };
+}
+/**
+ * Splits a compact into its frontmatter and body around the `---` fences.
+ *
+ * The document must open with a `---` line and contain a closing `---` line.
+ */
+function splitFrontmatter(text) {
+    const lines = text.split(/\r?\n/);
+    let start = 0;
+    while (start < lines.length && lines[start].trim() === "") {
+        start += 1;
+    }
+    if (start >= lines.length || lines[start].trim() !== "---") {
+        throw new CompactValidationError("Compact must start with a `---` frontmatter fence.");
+    }
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1) {
+        throw new CompactValidationError("Compact frontmatter is missing its closing `---` fence.");
+    }
+    const frontmatterText = lines.slice(start + 1, end).join("\n");
+    const bodyText = lines.slice(end + 1).join("\n");
+    return { frontmatterText, bodyText };
+}
+/**
+ * Parses and validates the frontmatter block: `status`, `state_reason`, and the
+ * optional `refs`, `versions`, and `labels` fields.
+ */
+function parseFrontmatter(frontmatterText) {
+    let raw;
+    try {
+        raw = parse(frontmatterText);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CompactValidationError(`Compact frontmatter is not valid YAML: ${detail}`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CompactValidationError("Compact frontmatter must be a set of key/value fields.");
+    }
+    const fm = raw;
+    if (!("status" in fm)) {
+        throw new CompactValidationError("Compact frontmatter is missing the required `status` field.");
+    }
+    const status = fm.status;
+    if (status !== "open" && status !== "closed") {
+        throw new CompactValidationError(`Compact \`status\` must be one of ${VALID_STATUS.join(", ")}, got ${formatValue(status)}.`);
+    }
+    if (!("state_reason" in fm)) {
+        throw new CompactValidationError("Compact frontmatter is missing the required `state_reason` field.");
+    }
+    const stateReason = normalizeStateReason(fm.state_reason);
+    if (status === "open" && stateReason !== null) {
+        throw new CompactValidationError("An open issue must have `state_reason: null`.");
+    }
+    const frontmatter = { status, stateReason };
+    if ("refs" in fm && fm.refs !== null && fm.refs !== undefined) {
+        frontmatter.refs = validateStringArray(fm.refs, "refs");
+    }
+    if ("labels" in fm && fm.labels !== null && fm.labels !== undefined) {
+        frontmatter.labels = validateStringArray(fm.labels, "labels");
+    }
+    if ("versions" in fm && fm.versions !== null && fm.versions !== undefined) {
+        frontmatter.versions = validateVersions(fm.versions);
+    }
+    return frontmatter;
+}
+/** Coerces a YAML `state_reason` value into the allowed set or null. */
+function normalizeStateReason(value) {
+    // `null` (bare or quoted as the string "null") is the no-reason case.
+    if (value === null || value === undefined || value === "null") {
+        return null;
+    }
+    if (value === "completed" || value === "not_planned") {
+        return value;
+    }
+    throw new CompactValidationError(`Compact \`state_reason\` must be one of ${VALID_STATE_REASON.join(", ")}, or null, got ${formatValue(value)}.`);
+}
+/** Validates that a frontmatter value is an array of strings. */
+function validateStringArray(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new CompactValidationError(`Compact \`${field}\` must be a list of strings.`);
+    }
+    return value;
+}
+/** Validates that a frontmatter `versions` value is an `{ affected?, fixed? }` object. */
+function validateVersions(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new CompactValidationError("Compact `versions` must be an object like { affected, fixed }.");
+    }
+    const obj = value;
+    const result = {};
+    for (const key of ["affected", "fixed"]) {
+        if (key in obj && obj[key] !== null && obj[key] !== undefined) {
+            if (typeof obj[key] !== "string") {
+                throw new CompactValidationError(`Compact \`versions.${key}\` must be a string.`);
+            }
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Extracts and validates the `tldr` body field: a non-empty, single-line value
+ * on a line of the form `tldr: <text>`.
+ */
+function extractTldr(bodyText) {
+    const lines = bodyText.split("\n");
+    const tldrLine = lines.find((line) => /^\s*tldr\s*:/.test(line));
+    if (tldrLine === undefined) {
+        throw new CompactValidationError("Compact body is missing the required `tldr` field.");
+    }
+    const tldr = tldrLine.replace(/^\s*tldr\s*:/, "").trim();
+    if (tldr === "") {
+        throw new CompactValidationError("Compact `tldr` must be a non-empty single line.");
+    }
+    if (tldr === "null") {
+        throw new CompactValidationError("Compact `tldr` must not be null; it is the headline and must stand alone.");
+    }
+    return tldr;
+}
+/** Renders an unexpected value compactly for error messages. */
+function formatValue(value) {
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (value === null) {
+        return "null";
+    }
+    return String(value);
+}
+
+/**
+ * Parses an `owner/repo#number` target string.
+ *
+ * @throws {Error} When the target is not in the expected shape.
+ */
+function parseTarget(target) {
+    const match = /^([^/\s]+\/[^/\s#]+)#(\d+)$/.exec(target.trim());
+    if (!match) {
+        throw new Error(`Invalid target "${target}". Expected the form owner/repo#number, e.g. octocat/hello#42.`);
+    }
+    return { fullName: match[1], number: Number.parseInt(match[2], 10) };
+}
+/**
+ * Parses the `--limit <n>` option value into a positive integer.
+ *
+ * @throws {CompactCommandError} When the value is not a positive integer.
+ */
+function parseLimit(value) {
+    const n = Number.parseInt(value, 10);
+    if (!Number.isInteger(n) || n < 1 || String(n) !== value.trim()) {
+        throw new CompactCommandError(`Invalid --limit "${value}". Expected a positive integer.`);
+    }
+    return n;
+}
+/**
+ * Error thrown by the `compact set` action for expected, user-facing failures
+ * (malformed target, unwatched repo, missing issue, invalid file). The CLI
+ * prints the message and exits non-zero.
+ */
+class CompactCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompactCommandError";
+    }
+}
+/**
+ * Core action for `issuary compact set`: validates the target, looks up the repo
+ * and issue, parses the compact file, and persists it via the store.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller is responsible for opening/closing the {@link Store}.
+ *
+ * @throws {CompactCommandError} For expected, user-facing failures.
+ */
+function runCompactSet(store, target, options) {
+    const { fullName, number } = parseTarget(target);
+    const repo = store.getRepoByFullName(fullName);
+    if (!repo) {
+        throw new CompactCommandError(`Repo "${fullName}" is not watched. Add it with \`issuary add ${fullName}\` first.`);
+    }
+    const issue = store.getIssue(repo.id, number);
+    if (!issue) {
+        throw new CompactCommandError(`Issue ${fullName}#${number} is not in the local store. Run \`issuary sync\` first.`);
+    }
+    let text;
+    try {
+        text = readFileSync(options.fromFile, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CompactCommandError(`Could not read compact file "${options.fromFile}": ${detail}`);
+    }
+    let parsed;
+    try {
+        parsed = parseCompact(text);
+    }
+    catch (error) {
+        if (error instanceof CompactValidationError) {
+            throw new CompactCommandError(`Invalid compact: ${error.message}`);
+        }
+        throw error;
+    }
+    store.setCompact(repo.id, number, { compact: parsed.compact, tldr: parsed.tldr });
+    return { ok: true, repo: fullName, number, tldr: parsed.tldr };
+}
+/** Derives the {@link CompactStatus} of an issue from its compact fields. */
+function compactStatus(issue) {
+    if (issue.compact === null) {
+        return "uncompacted";
+    }
+    return issue.compactStale ? "stale" : "compacted";
+}
+/**
+ * Core action for `issuary compact list`: walks the watched repos (or a single
+ * repo via `options.repo`) and returns their issues with compaction status.
+ * With `options.pending`, narrows to the actionable set (uncompacted or stale)
+ * and stamps each with a `reason`. With `options.limit`, caps the number of
+ * returned items (applied last, after the pending/repo filter).
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller is responsible for opening/closing the {@link Store}.
+ *
+ * @throws {CompactCommandError} When `options.repo` names an unwatched repo.
+ */
+function runCompactList(store, options = {}) {
+    let repos;
+    if (options.repo) {
+        const repo = store.getRepoByFullName(options.repo);
+        if (!repo) {
+            throw new CompactCommandError(`Repo "${options.repo}" is not watched. Add it with \`issuary add ${options.repo}\` first.`);
+        }
+        repos = [repo];
+    }
+    else {
+        repos = store.listRepos();
+    }
+    const items = [];
+    for (const repo of repos) {
+        for (const issue of store.listIssues(repo.id)) {
+            const status = compactStatus(issue);
+            const pending = status !== "compacted";
+            if (options.pending && !pending) {
+                continue;
+            }
+            items.push({
+                repo: repo.fullName,
+                number: issue.number,
+                title: issue.title,
+                state: issue.state,
+                status,
+                reason: pending ? status : null,
+                rawBody: issue.rawBody,
+                commentsNeedFetch: issue.rawComments === null && issue.commentCount > 0,
+            });
+        }
+    }
+    if (options.limit !== undefined && options.limit > 0) {
+        return items.slice(0, options.limit);
+    }
+    return items;
+}
+/**
+ * Renders the human-readable listing of {@link CompactListItem}s, grouped by
+ * repo. Each row shows the issue number, status, and title.
+ */
+function formatCompactList(items, options = {}) {
+    if (items.length === 0) {
+        return options.pending
+            ? "Nothing to compact. Every watched issue has a fresh compact."
+            : "No issues found. Run `issuary sync` to mirror issues first.";
+    }
+    const byRepo = new Map();
+    for (const item of items) {
+        const bucket = byRepo.get(item.repo);
+        if (bucket) {
+            bucket.push(item);
+        }
+        else {
+            byRepo.set(item.repo, [item]);
+        }
+    }
+    const lines = [];
+    for (const [repo, repoItems] of byRepo) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push(`${repo}:`);
+        const numWidth = Math.max(...repoItems.map((item) => `#${item.number}`.length));
+        const statusWidth = Math.max(...repoItems.map((item) => item.status.length));
+        for (const item of repoItems) {
+            const num = `#${item.number}`.padEnd(numWidth);
+            const status = item.status.padEnd(statusWidth);
+            lines.push(`  ${num}  ${status}  ${item.title}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Builds the `compact` command group with its `set` and `list` subcommands.
+ *
+ * @see file://../../docs/compact-format.md
+ */
+function compactCommand() {
+    const compact = new Command("compact").description("Read and write AI-written compact summaries of issues");
+    compact
+        .command("list")
+        .description("List issues with their compaction status; --pending narrows to what needs compacting")
+        .option("--pending", "only issues that need compacting (uncompacted or stale)")
+        .option("--repo <owner/repo>", "restrict to a single watched repo")
+        .option("--limit <n>", "cap the number of issues returned, applied after the pending/repo filter", parseLimit)
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const items = runCompactList(store, options);
+            if (options.json) {
+                console.log(JSON.stringify(items));
+            }
+            else {
+                console.log(formatCompactList(items, { pending: options.pending }));
+            }
+        }
+        catch (error) {
+            if (error instanceof CompactCommandError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+    compact
+        .command("set")
+        .description("Persist a compact for an issue from a file in the canonical format")
+        .argument("<target>", "issue to compact, as owner/repo#number")
+        .requiredOption("--from-file <file>", "path to the compact file to read")
+        .option("--json", "emit machine-readable JSON")
+        .action((target, options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const result = runCompactSet(store, target, options);
+            if (options.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(`Saved compact for ${result.repo}#${result.number}: ${result.tldr}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof CompactCommandError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+    return compact;
+}
+
+/**
+ * Error thrown by the `digest` action for expected, user-facing failures (an
+ * unwatched `--repo` filter, a malformed `--since` value). The CLI prints the
+ * message and exits non-zero.
+ */
+class DigestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DigestError";
+    }
+}
+/** Canonical order and human labels for event types. */
+const TYPE_ORDER = [
+    { type: "opened", label: "new issues" },
+    { type: "closed", label: "closed" },
+    { type: "commented", label: "new comments" },
+    { type: "closed_commented", label: "closed with new comment" },
+    { type: "reopened", label: "reopened" },
+];
+const TYPE_LABELS = new Map(TYPE_ORDER.map((t) => [t.type, t.label]));
+/** Returns the index of a type in {@link TYPE_ORDER}, or a high value if unknown. */
+function typeRank(type) {
+    const index = TYPE_ORDER.findIndex((t) => t.type === type);
+    return index === -1 ? TYPE_ORDER.length : index;
+}
+/**
+ * Resolves a `--since` value to an ISO-8601 timestamp. Accepts a full ISO date
+ * or a simple relative duration: `<n>d` (days) or `<n>h` (hours) before `now`.
+ *
+ * @throws {DigestError} When the value is neither a valid ISO date nor a
+ *   supported relative duration.
+ */
+function resolveSince(value, now = new Date()) {
+    const trimmed = value.trim();
+    const relative = /^(\d+)([dh])$/.exec(trimmed);
+    if (relative) {
+        const amount = Number.parseInt(relative[1], 10);
+        const unitMs = relative[2] === "d" ? 86_400_000 : 3_600_000;
+        return new Date(now.getTime() - amount * unitMs).toISOString();
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new DigestError(`Invalid --since value "${value}". Expected an ISO date or a duration like 7d or 24h.`);
+    }
+    return parsed.toISOString();
+}
+/** Groups context events by repo (ordered by full name), then by canonical type. */
+function groupEvents(events) {
+    const byRepo = new Map();
+    for (const event of events) {
+        const bucket = byRepo.get(event.repoFullName);
+        if (bucket) {
+            bucket.push(event);
+        }
+        else {
+            byRepo.set(event.repoFullName, [event]);
+        }
+    }
+    const repos = [...byRepo.keys()].sort();
+    return repos.map((repo) => {
+        const repoEvents = byRepo.get(repo) ?? [];
+        const byType = new Map();
+        for (const event of repoEvents) {
+            const digestEvent = {
+                id: event.id,
+                type: event.type,
+                detectedAt: event.detectedAt,
+                issueNumber: event.issueNumber,
+                issueTitle: event.issueTitle,
+                issueState: event.issueState,
+            };
+            const bucket = byType.get(event.type);
+            if (bucket) {
+                bucket.push(digestEvent);
+            }
+            else {
+                byType.set(event.type, [digestEvent]);
+            }
+        }
+        const groups = [...byType.entries()]
+            .sort(([a], [b]) => typeRank(a) - typeRank(b))
+            .map(([type, typeEvents]) => ({ type, events: typeEvents }));
+        return { repo, groups };
+    });
+}
+/**
+ * Core action for `issuary digest`: the aggregated inbox across all watched repos.
+ *
+ * - Default (inbox): surfaces unseen events, then marks them seen so each change
+ *   appears once.
+ * - `--since`: a read-only time window (`detected_at >= since`); nothing marked.
+ * - `--all`: every event (seen and unseen); nothing marked.
+ * - `--repo`: narrows any of the above to a single watched repo.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller is responsible for opening/closing the {@link Store}.
+ *
+ * @throws {DigestError} When `--repo` names an unwatched repo or `--since` is
+ *   malformed.
+ */
+function runDigest(store, options = {}) {
+    let repoId;
+    if (options.repo) {
+        const repo = store.getRepoByFullName(options.repo);
+        if (!repo) {
+            throw new DigestError(`Repo "${options.repo}" is not watched. Add it with \`issuary add ${options.repo}\` first.`);
+        }
+        repoId = repo.id;
+    }
+    let mode;
+    let events;
+    if (options.since) {
+        mode = "since";
+        events = store.listEvents({ since: resolveSince(options.since), repoId });
+    }
+    else if (options.all) {
+        mode = "all";
+        events = store.listEvents({ repoId });
+    }
+    else {
+        mode = "inbox";
+        events = store.listEvents({ seen: false, repoId });
+        store.markEventsSeen(events.map((event) => event.id));
+    }
+    return { mode, total: events.length, repos: groupEvents(events) };
+}
+/** Renders a single digest event line. */
+function formatEvent(event) {
+    return `    #${event.issueNumber} [${event.issueState}] ${event.issueTitle}`;
+}
+/** Pure formatter: renders a {@link DigestResult} as human-readable text. */
+function formatDigest(result) {
+    if (result.total === 0) {
+        if (result.mode === "inbox") {
+            return "Inbox empty: no new changes.";
+        }
+        return "No matching events.";
+    }
+    const lines = [];
+    for (const repo of result.repos) {
+        lines.push(repo.repo);
+        for (const group of repo.groups) {
+            const label = TYPE_LABELS.get(group.type) ?? group.type;
+            lines.push(`  ${label} (${group.events.length})`);
+            for (const event of group.events) {
+                lines.push(formatEvent(event));
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * Builds the `digest` command: an aggregated inbox of detected changes across
+ * every watched repo. By default it shows unseen changes and marks them seen so
+ * each appears once; `--since` and `--all` are read-only views that never mark.
+ */
+function digestCommand() {
+    return new Command("digest")
+        .description("Show an aggregated inbox of issue changes across all watched repos")
+        .option("--since <when>", "show events at or after an ISO date or duration (7d, 24h); does not mark them seen")
+        .option("--all", "show all events, seen and unseen, without marking any seen")
+        .option("--repo <owner/repo>", "limit to a single watched repo")
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const result = runDigest(store, options);
+            console.log(options.json ? JSON.stringify(result) : formatDigest(result));
+        }
+        catch (error) {
+            if (error instanceof DigestError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Error thrown by the `issues` action for expected, user-facing failures (an
+ * unwatched `--repo`, a malformed `--since`, mutually exclusive compaction
+ * flags). The CLI prints the message and exits non-zero.
+ */
+class IssuesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IssuesError";
+    }
+}
+/**
+ * Resolves the mutually exclusive `--uncompacted` / `--stale` / `--compacted`
+ * flags into a single compaction filter.
+ *
+ * @throws {IssuesError} When more than one of the three is passed.
+ */
+function resolveCompaction(options) {
+    const selected = [];
+    if (options.uncompacted) {
+        selected.push("uncompacted");
+    }
+    if (options.stale) {
+        selected.push("stale");
+    }
+    if (options.compacted) {
+        selected.push("compacted");
+    }
+    if (selected.length > 1) {
+        throw new IssuesError("Use at most one of --uncompacted, --stale, or --compacted; they are mutually exclusive.");
+    }
+    return selected[0] ?? null;
+}
+/** Parses an issue's stored labels JSON into a string array, tolerating null/garbage. */
+function parseLabels$1(labels) {
+    if (!labels) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(labels);
+        return Array.isArray(parsed) ? parsed.filter((l) => typeof l === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether an issue carries a fresh, trustworthy compact (protocol rule). */
+function isFresh(issue) {
+    return issue.compact != null && !issue.compactStale;
+}
+/**
+ * Core action for `issuary issues`: the filterable, cross-repo, state-based
+ * listing of issues. STRICTLY READ-ONLY: no API calls, no state mutation.
+ *
+ * Resolves `--repo` full names to ids (erroring on an unwatched repo), resolves
+ * `--since`, validates the mutually exclusive compaction flags, queries the
+ * store, and builds the result with per-issue compaction flags and refs.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller is responsible for opening/closing the {@link Store}.
+ *
+ * @throws {IssuesError} For expected, user-facing failures.
+ */
+function runIssues(store, options = {}) {
+    const state = options.state ?? "open";
+    const sort = options.sort ?? "updated";
+    const order = options.order ?? "desc";
+    const compaction = resolveCompaction(options);
+    let repoIds;
+    if (options.repo && options.repo.length > 0) {
+        repoIds = options.repo.map((fullName) => {
+            const repo = store.getRepoByFullName(fullName);
+            if (!repo) {
+                throw new IssuesError(`Repo "${fullName}" is not watched. Add it with \`issuary add ${fullName}\` first.`);
+            }
+            return repo.id;
+        });
+    }
+    let since;
+    if (options.since) {
+        try {
+            since = resolveSince(options.since);
+        }
+        catch (error) {
+            if (error instanceof DigestError) {
+                throw new IssuesError(error.message);
+            }
+            throw error;
+        }
+    }
+    const filter = {
+        state,
+        repoIds,
+        labels: options.label && options.label.length > 0 ? options.label : undefined,
+        author: options.author,
+        stateReason: options.stateReason,
+        since,
+        search: options.search,
+        compaction: compaction ?? undefined,
+        sort,
+        order,
+        limit: options.limit,
+    };
+    const rows = store.queryIssues(filter);
+    let open = 0;
+    const repoSet = new Set();
+    const issues = rows.map((issue) => {
+        if (issue.state === "open") {
+            open += 1;
+        }
+        repoSet.add(issue.repoFullName);
+        const fresh = isFresh(issue);
+        return {
+            repo: issue.repoFullName,
+            number: issue.number,
+            title: issue.title,
+            state: issue.state,
+            stateReason: issue.stateReason,
+            author: issue.author,
+            labels: parseLabels$1(issue.labels),
+            commentCount: issue.commentCount,
+            createdAt: issue.createdAt,
+            updatedAt: issue.updatedAt,
+            compact: issue.compact,
+            compactTldr: issue.compactTldr,
+            compacted: fresh,
+            stale: issue.compact != null && issue.compactStale,
+            refs: store.listIssueRefs(issue.id).map((ref) => ref.target),
+        };
+    });
+    const filters = {
+        state,
+        repos: repoIds ? options.repo : null,
+        labels: filter.labels ?? null,
+        author: options.author ?? null,
+        stateReason: options.stateReason ?? null,
+        since: since ?? null,
+        search: options.search ?? null,
+        compaction,
+        sort,
+        order,
+        limit: options.limit ?? null,
+    };
+    const summary = {
+        total: issues.length,
+        open,
+        closed: issues.length - open,
+        repos: repoSet.size,
+    };
+    return { filters, summary, issues };
+}
+/** Builds the short `(filter: ...)` suffix describing non-default filters. */
+function describeFilters(filters) {
+    const parts = [];
+    if (filters.repos) {
+        parts.push(`repos=${filters.repos.join(",")}`);
+    }
+    if (filters.labels) {
+        parts.push(`labels=${filters.labels.join("|")}`);
+    }
+    if (filters.author) {
+        parts.push(`author=${filters.author}`);
+    }
+    if (filters.stateReason) {
+        parts.push(`state_reason=${filters.stateReason}`);
+    }
+    if (filters.since) {
+        parts.push(`since=${filters.since}`);
+    }
+    if (filters.search) {
+        parts.push(`search="${filters.search}"`);
+    }
+    if (filters.compaction) {
+        parts.push(filters.compaction);
+    }
+    if (filters.sort !== "updated" || filters.order !== "desc") {
+        parts.push(`sort=${filters.sort} ${filters.order}`);
+    }
+    if (filters.limit) {
+        parts.push(`limit=${filters.limit}`);
+    }
+    return parts.length > 0 ? ` (filter: ${parts.join(", ")})` : "";
+}
+/** The discreet compaction marker for a row, or empty when fresh-compacted. */
+function compactionMarker(issue) {
+    if (issue.compacted) {
+        return "";
+    }
+    return issue.stale ? " (stale)" : " (uncompacted)";
+}
+/** Pure formatter: renders an {@link IssuesResult} as human-readable text. */
+function formatIssues(result) {
+    const { summary, filters } = result;
+    if (summary.total === 0) {
+        return `No issues match${describeFilters(filters)}.`;
+    }
+    const stateWord = filters.state === "all" ? "issues" : `${filters.state} issues`;
+    const repoWord = summary.repos === 1 ? "repo" : "repos";
+    const header = `${summary.total} ${stateWord} across ${summary.repos} ${repoWord}${describeFilters(filters)}`;
+    const byRepo = new Map();
+    for (const issue of result.issues) {
+        const bucket = byRepo.get(issue.repo);
+        if (bucket) {
+            bucket.push(issue);
+        }
+        else {
+            byRepo.set(issue.repo, [issue]);
+        }
+    }
+    const lines = [header];
+    for (const [repo, repoIssues] of byRepo) {
+        lines.push("");
+        lines.push(`${repo}:`);
+        const numWidth = Math.max(...repoIssues.map((i) => `#${i.number}`.length));
+        const stateWidth = Math.max(...repoIssues.map((i) => `[${i.state}]`.length));
+        for (const issue of repoIssues) {
+            const num = `#${issue.number}`.padEnd(numWidth);
+            const stateTag = `[${issue.state}]`.padEnd(stateWidth);
+            const labels = issue.labels.length ? ` {${issue.labels.join(", ")}}` : "";
+            const comments = issue.commentCount > 0 ? ` (${issue.commentCount}c)` : "";
+            lines.push(`  ${num}  ${stateTag}  ${issue.title}${labels}${comments}${compactionMarker(issue)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Builds the `issues` command: a read-only, state-based, filterable listing of
+ * issues across watched repos. Distinct from `digest` (what changed) and
+ * `repo-digest` (one repo's full dump). Defaults to open issues across all
+ * watched repos, newest-updated first, grouped by repo.
+ */
+function issuesCommand() {
+    const collect = (value, previous = []) => [...previous, value];
+    return new Command("issues")
+        .description("List issues across watched repos with filters (read-only); defaults to open issues everywhere")
+        .option("--state <state>", "issue state: open, closed, or all", "open")
+        .option("--repo <owner/repo>", "scope to a watched repo (repeatable)", collect)
+        .option("--label <name>", "match issues with any of these labels (repeatable, OR)", collect)
+        .option("--author <login>", "restrict to issues by this author")
+        .option("--state-reason <reason>", "restrict to this state_reason (completed, not_planned)")
+        .option("--since <when>", "only issues updated at or after an ISO date or duration (7d, 24h)")
+        .option("--search <text>", "case-insensitive substring match on the issue title")
+        .option("--uncompacted", "only issues without a compact (exclusive with --stale/--compacted)")
+        .option("--stale", "only issues whose compact is stale (exclusive with --uncompacted/--compacted)")
+        .option("--compacted", "only issues with a fresh compact (exclusive with --uncompacted/--stale)")
+        .option("--sort <key>", "sort by updated, created, or number", "updated")
+        .option("--order <dir>", "sort direction: asc or desc", "desc")
+        .option("--limit <n>", "cap the number of issues returned", (v) => Number.parseInt(v, 10))
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const result = runIssues(store, options);
+            console.log(options.json ? JSON.stringify(result) : formatIssues(result));
+        }
+        catch (error) {
+            if (error instanceof IssuesError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Core action for `issuary list`: returns the watched repos and their state,
+ * ordered by `full_name`. Separated from the Commander wiring for testing.
+ */
+function runList(store) {
+    return store.listRepos().map((repo) => ({
+        repo: repo.fullName,
+        active: repo.active,
+        lastSyncedAt: repo.lastSyncedAt,
+    }));
+}
+/**
+ * Renders the human-readable, aligned listing. Repos are grouped active first,
+ * then inactive; `last_synced_at` shows "never" when null.
+ */
+function formatList(items) {
+    if (items.length === 0) {
+        return "No repos watched yet. Add one with `issuary add owner/repo`.";
+    }
+    const active = items.filter((item) => item.active);
+    const inactive = items.filter((item) => !item.active);
+    const width = Math.max(...items.map((item) => item.repo.length));
+    const lines = [];
+    const render = (item) => `  ${item.repo.padEnd(width)}  last synced: ${item.lastSyncedAt ?? "never"}`;
+    if (active.length > 0) {
+        lines.push("active:");
+        for (const item of active) {
+            lines.push(render(item));
+        }
+    }
+    if (inactive.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("inactive:");
+        for (const item of inactive) {
+            lines.push(render(item));
+        }
+    }
+    return lines.join("\n");
+}
+/** Builds the `list` command. */
+function listCommand() {
+    return new Command("list")
+        .description("List watched repos with their state and last sync time")
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const items = runList(store);
+            if (options.json) {
+                console.log(JSON.stringify(items));
+            }
+            else {
+                console.log(formatList(items));
+            }
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Error thrown by the auth (device flow) module for expected, user-facing
+ * failures: a missing client id, a denied or expired device-flow grant, or an
+ * unexpected OAuth response.
+ *
+ * Callers should catch this to print a friendly, actionable message instead of a
+ * stack trace. Messages never contain the resulting access token.
+ */
+class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+
+/**
+ * Public client id of the registered GitHub app used for the device flow.
+ *
+ * A device-flow client id is not a secret, so it is safe to commit. Users can
+ * override it at runtime with the `ISSUARY_GITHUB_CLIENT_ID` environment
+ * variable (for example to point at their own app or a GitHub Enterprise one).
+ */
+const DEFAULT_GITHUB_CLIENT_ID = "Ov23liOws9jSkjjC2PAL";
+/** Default OAuth scope requested by `issuary login`; `repo` so private repos work. */
+const DEFAULT_SCOPE = "repo";
+/**
+ * Resolves the OAuth client id to use for the device flow.
+ *
+ * `ISSUARY_GITHUB_CLIENT_ID` (trimmed) overrides the baked
+ * {@link DEFAULT_GITHUB_CLIENT_ID}.
+ *
+ * @param env - Environment to read from; defaults to `process.env`.
+ * @param defaultClientId - Baked-in fallback; defaults to {@link DEFAULT_GITHUB_CLIENT_ID}.
+ * @returns The resolved client id.
+ * @throws {AuthError} When no client id is configured.
+ */
+function resolveClientId(env = process.env, defaultClientId = DEFAULT_GITHUB_CLIENT_ID) {
+    const fromEnv = (env.ISSUARY_GITHUB_CLIENT_ID ?? "").trim();
+    const clientId = fromEnv || defaultClientId;
+    if (clientId === "") {
+        throw new AuthError("No GitHub OAuth client id is configured, so `issuary login` cannot run. " +
+            "Set ISSUARY_GITHUB_CLIENT_ID to a GitHub OAuth App client id (device flow enabled), " +
+            "or use `export GITHUB_TOKEN=...` instead.");
+    }
+    return clientId;
+}
+/**
+ * Resolves the OAuth scope to request.
+ *
+ * `ISSUARY_GITHUB_SCOPE` (trimmed) overrides the default {@link DEFAULT_SCOPE}.
+ *
+ * @param env - Environment to read from; defaults to `process.env`.
+ * @returns The resolved scope string.
+ */
+function resolveScope(env = process.env) {
+    return (env.ISSUARY_GITHUB_SCOPE ?? "").trim() || DEFAULT_SCOPE;
+}
+
+/** Default OAuth endpoints host; overridable for tests and GitHub Enterprise. */
+const DEFAULT_OAUTH_HOST = "https://github.com";
+/** Standard extra delay (seconds) applied when GitHub asks us to `slow_down`. */
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+/** Fallback poll interval (seconds) when GitHub omits one. */
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+/** Default sleep backed by a real timer. */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Normalizes an OAuth host: trims trailing slashes, falls back to the default. */
+function normalizeHost(raw) {
+    return ((raw ?? "").trim() || DEFAULT_OAUTH_HOST).replace(/\/+$/, "");
+}
+/**
+ * Requests a device and user code to start the GitHub device flow.
+ *
+ * `POST {oauthHost}/login/device/code` with the client id and scope.
+ *
+ * @param options - Client id, scope, and optional host/`fetch` overrides.
+ * @returns The parsed {@link DeviceCodeResponse}.
+ * @throws {AuthError} When the request fails or the response is malformed.
+ */
+async function requestDeviceCode(options) {
+    const doFetch = options.fetch ?? fetch;
+    const host = normalizeHost(options.oauthHost);
+    let response;
+    try {
+        response = await doFetch(`${host}/login/device/code`, {
+            method: "POST",
+            headers: { Accept: "application/json", "Content-Type": "application/json" },
+            body: JSON.stringify({ client_id: options.clientId, scope: options.scope }),
+        });
+    }
+    catch (error) {
+        throw new AuthError(`Could not reach GitHub to start device login: ${error.message}.`);
+    }
+    if (!response.ok) {
+        throw new AuthError(`GitHub rejected the device-code request with HTTP ${response.status}.`);
+    }
+    const body = (await response.json());
+    if (body.error) {
+        throw new AuthError(`GitHub device-code request failed: ${body.error_description ?? body.error}.`);
+    }
+    if (typeof body.device_code !== "string" ||
+        typeof body.user_code !== "string" ||
+        typeof body.verification_uri !== "string") {
+        throw new AuthError("GitHub returned an unexpected device-code response.");
+    }
+    return {
+        device_code: body.device_code,
+        user_code: body.user_code,
+        verification_uri: body.verification_uri,
+        expires_in: typeof body.expires_in === "number" ? body.expires_in : 900,
+        interval: typeof body.interval === "number" ? body.interval : DEFAULT_POLL_INTERVAL_SECONDS,
+    };
+}
+/**
+ * Polls GitHub for the access token after the user authorizes the device.
+ *
+ * `POST {oauthHost}/login/oauth/access_token` on the given `interval`, handling
+ * the documented device-flow responses: `authorization_pending` (keep polling),
+ * `slow_down` (back off by the standard 5s plus any returned interval),
+ * `expired_token` and `access_denied` (throw), and success (`access_token`).
+ * Stops once the `expiresIn` window elapses. Uses an injectable `sleep` and
+ * `now` so tests never actually wait.
+ *
+ * @param options - Client id, device code, timing, and overrides.
+ * @returns The access token string.
+ * @throws {AuthError} On denial, expiry, timeout, or an unexpected response.
+ */
+async function pollForAccessToken(options) {
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const host = normalizeHost(options.oauthHost);
+    const deadline = now() + options.expiresIn * 1000;
+    let intervalSeconds = options.interval > 0 ? options.interval : DEFAULT_POLL_INTERVAL_SECONDS;
+    for (;;) {
+        if (now() >= deadline) {
+            throw new AuthError("Device login timed out before it was authorized. Run `issuary login` again.");
+        }
+        await sleep(intervalSeconds * 1000);
+        let response;
+        try {
+            response = await doFetch(`${host}/login/oauth/access_token`, {
+                method: "POST",
+                headers: { Accept: "application/json", "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    client_id: options.clientId,
+                    device_code: options.deviceCode,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                }),
+            });
+        }
+        catch (error) {
+            throw new AuthError(`Could not reach GitHub while polling for the token: ${error.message}.`);
+        }
+        if (!response.ok) {
+            throw new AuthError(`GitHub rejected the token poll with HTTP ${response.status}.`);
+        }
+        const body = (await response.json());
+        if (typeof body.access_token === "string" && body.access_token !== "") {
+            return body.access_token;
+        }
+        switch (body.error) {
+            case "authorization_pending":
+                // The user has not finished authorizing yet; keep the same interval.
+                continue;
+            case "slow_down":
+                // GitHub asks us to back off. Always bump by at least the standard 5s,
+                // and honor a larger returned interval if present. Never go below the
+                // current interval, even if GitHub returns a smaller value.
+                intervalSeconds = Math.max(intervalSeconds + SLOW_DOWN_INCREMENT_SECONDS, typeof body.interval === "number" ? body.interval : 0);
+                continue;
+            case "expired_token":
+                throw new AuthError("The device code expired before login was authorized. Run `issuary login` again.");
+            case "access_denied":
+                throw new AuthError("Device login was denied. You cancelled or rejected the authorization.");
+            default:
+                throw new AuthError(`Device login failed: ${body.error_description ?? body.error ?? "unknown error"}.`);
+        }
+    }
+}
+
+/** Default `/user` lookup used to confirm the freshly stored token. */
+async function defaultGetAuthenticatedUser(apiUrl, token) {
+    let response;
+    try {
+        response = await fetch(`${apiUrl}/user`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "merencia-issuary",
+            },
+        });
+    }
+    catch (error) {
+        throw new AuthError(`Logged in, but could not confirm the token with GitHub: ${error.message}.`);
+    }
+    if (!response.ok) {
+        throw new AuthError(`Logged in, but GitHub rejected the token confirmation with HTTP ${response.status}.`);
+    }
+    const body = (await response.json());
+    const scopesHeader = response.headers.get("x-oauth-scopes") ?? "";
+    const scopes = scopesHeader
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+    return {
+        login: typeof body.login === "string" ? body.login : "unknown",
+        scopes,
+    };
+}
+/**
+ * Core action for `issuary login`: runs the GitHub device flow, prints the user
+ * code and verification URL, polls until the user authorizes, stores the token,
+ * and confirms it by fetching the authenticated user. Never prints the token.
+ *
+ * Separated from the Commander wiring so it can be tested with injected fakes.
+ *
+ * @param deps - Injected dependencies; see {@link LoginDeps}.
+ * @returns The {@link LoginResult} on success.
+ * @throws {AuthError} For device-flow and confirmation failures.
+ */
+async function runLogin(deps) {
+    const log = deps.log ?? ((message) => console.log(message));
+    const doRequest = deps.requestDeviceCode ?? requestDeviceCode;
+    const doPoll = deps.pollForAccessToken ?? pollForAccessToken;
+    const store = deps.writeStoredToken ?? writeStoredToken;
+    const getUser = deps.getAuthenticatedUser ?? defaultGetAuthenticatedUser;
+    const device = await doRequest({
+        clientId: deps.clientId,
+        scope: deps.scope,
+        oauthHost: deps.oauthHost,
+    });
+    log(`To authorize issuary, open ${device.verification_uri} and enter the code: ${device.user_code}`);
+    log("Waiting for you to authorize in the browser...");
+    const token = await doPoll({
+        clientId: deps.clientId,
+        deviceCode: device.device_code,
+        interval: device.interval,
+        expiresIn: device.expires_in,
+        oauthHost: deps.oauthHost,
+    });
+    store(deps.home, token);
+    const user = await getUser(deps.apiUrl, token);
+    return { ok: true, login: user.login, scopes: user.scopes };
+}
+/**
+ * Builds the `login` command.
+ *
+ * `issuary login` authenticates via the GitHub OAuth device flow and stores the
+ * resulting token in the credentials file. The action is kept thin: it resolves
+ * config and the client id, then delegates to {@link runLogin}.
+ */
+function loginCommand() {
+    return new Command("login")
+        .description("Authenticate with GitHub via the device flow and store the token")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (options) => {
+        // No token is required to log in; that is the whole point.
+        const config = loadConfig({ requireToken: false });
+        const clientId = resolveClientId();
+        const scope = resolveScope();
+        const result = await runLogin({
+            home: config.home,
+            apiUrl: config.apiUrl,
+            clientId,
+            scope,
+            // Silence the human progress lines in --json mode so stdout stays clean.
+            log: options.json ? () => { } : undefined,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result));
+        }
+        else {
+            console.log(`Logged in as ${result.login}.`);
+        }
+    });
+}
+
+/**
+ * Core action for `issuary logout`: clears the stored token. Local only; it does
+ * not contact GitHub or revoke the token server-side.
+ *
+ * @param deps - Injected dependencies; see {@link LogoutDeps}.
+ * @returns A {@link LogoutResult} reporting whether anything was removed.
+ */
+function runLogout(deps) {
+    const clear = deps.clearStoredToken ?? clearStoredToken;
+    const removed = clear(deps.home);
+    return { ok: true, removed };
+}
+/**
+ * Builds the `logout` command.
+ *
+ * `issuary logout` removes the locally stored token. It never hits the network.
+ */
+function logoutCommand() {
+    return new Command("logout")
+        .description("Remove the stored GitHub token saved by `issuary login`")
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        const config = loadConfig({ requireToken: false });
+        const result = runLogout({ home: config.home });
+        if (options.json) {
+            console.log(JSON.stringify(result));
+        }
+        else {
+            console.log(result.removed ? "Logged out. Stored token removed." : "No stored token to remove.");
+        }
+    });
+}
+
+/**
+ * The canonical AI compaction protocol, exposed as a first-class, machine-readable
+ * contract. Kept consistent with the "Protocolo de compactacao" section of
+ * `CLAUDE.md` and the full spec in `docs/compact-format.md`.
+ *
+ * The full field-by-field specification lives in {@link COMPACT_FORMAT_DOC}.
+ */
+/** Pointer to the full, authoritative compact format specification. */
+const COMPACT_FORMAT_DOC = "docs/compact-format.md";
+/**
+ * The canonical compaction protocol text that AI consumers follow.
+ *
+ * It states what each issue exposes (`compact` and `compact_stale`), the two
+ * rules for using or regenerating a compact, the persistence command, and what
+ * a compact must preserve. It points to {@link COMPACT_FORMAT_DOC} for the full
+ * field spec.
+ *
+ * Asserted on by tests via substrings so the contract cannot silently drift.
+ */
+const COMPACTION_PROTOCOL = `issuary compaction protocol (contract for AI consumers)
+
+Each issue issuary exposes carries two fields:
+  - compact: string | null   the AI-written structured summary, or null if none
+  - compact_stale: boolean    true when the compact no longer reflects the issue
+
+Rule 1 (use when fresh):
+  If compact != null AND compact_stale == false, USE the compact. Do not refetch
+  the raw issue, do not re-read raw_comments, and do not recompact. The compact is
+  trusted and current.
+
+Rule 2 (recompact when missing or stale):
+  If compact == null OR compact_stale == true, read raw_body and raw_comments,
+  write a fresh compact in the canonical format, and persist it:
+
+    issuary compact set <owner/repo>#<n> --from-file <file>
+
+  Persisting a compact clears the stale flag.
+
+What a compact must preserve:
+  - status and state_reason are copied verbatim from the GitHub API, never inferred.
+  - labels are copied from the API; only their selection is a judgment call.
+  - refs are preserved literally, exactly as written (for example "#812", "PR #820").
+  - tldr is one standalone sentence (soft cap about 20 words).
+  - The body fields tldr, problem, status_detail, decisions, open_questions keep a
+    fixed order. An empty textual field is the literal null. Soft cap about 8 lines.
+
+Full field-by-field specification, rules, and worked examples: ${COMPACT_FORMAT_DOC}.`;
+/** Structured, machine-readable description of the canonical compact format. */
+const COMPACT_FORMAT_SPEC = {
+    doc: COMPACT_FORMAT_DOC,
+    frontmatterFields: ["status", "state_reason", "refs", "versions", "labels"],
+    bodyFields: ["tldr", "problem", "status_detail", "decisions", "open_questions"],
+    persistCommand: "issuary compact set <owner/repo>#<n> --from-file <file>",
+};
+
+/**
+ * Core action for `issuary protocol`: returns the canonical compaction protocol.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. Returns the human text, or the structured JSON payload when
+ * `options.json` is set.
+ */
+function runProtocol(options = {}) {
+    if (options.json) {
+        return { protocol: COMPACTION_PROTOCOL, compactFormat: COMPACT_FORMAT_SPEC };
+    }
+    return COMPACTION_PROTOCOL;
+}
+/**
+ * Builds the `protocol` command. It prints the AI compaction contract so an
+ * agent can discover the protocol it must follow.
+ *
+ * @see file://../../docs/compact-format.md
+ */
+function protocolCommand() {
+    return new Command("protocol")
+        .description("Print the AI compaction protocol (the contract AI consumers follow)")
+        .option("--json", "emit machine-readable JSON")
+        .action((options) => {
+        if (options.json) {
+            console.log(JSON.stringify(runProtocol({ json: true })));
+        }
+        else {
+            console.log(runProtocol());
+        }
+    });
+}
+
+/**
+ * Core action for `issuary remove`: deactivates a watched repo (sets `active = 0`).
+ * Never deletes, so issues and compacts are preserved for history.
+ *
+ * Separated from the Commander wiring for testing. The caller owns the
+ * {@link Store} lifecycle.
+ *
+ * @throws {RepoCommandError} When the repo is not watched.
+ */
+function runRemove(store, arg, _options = {}) {
+    const { fullName } = parseRepoArg(arg);
+    const existing = store.getRepoByFullName(fullName);
+    if (!existing) {
+        throw new RepoCommandError(`Repo "${fullName}" is not watched. Nothing to remove.`);
+    }
+    if (!existing.active) {
+        return { ok: true, repo: fullName, status: "already-inactive" };
+    }
+    store.setRepoActive(fullName, false);
+    return { ok: true, repo: fullName, status: "removed" };
+}
+/** Human-readable line for a successful {@link runRemove}. */
+function removeMessage(result) {
+    return result.status === "removed"
+        ? `Stopped watching ${result.repo}. Its history and compacts are kept.`
+        : `${result.repo} was already not being watched.`;
+}
+/** Builds the `remove` command. */
+function removeCommand() {
+    return new Command("remove")
+        .description("Stop watching a repo (deactivates it; history and compacts are kept)")
+        .argument("<owner/repo>", "repository to stop watching, as owner/repo")
+        .option("--json", "emit machine-readable JSON")
+        .action((arg, options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            const result = runRemove(store, arg, options);
+            if (options.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(removeMessage(result));
+            }
+        }
+        catch (error) {
+            if (error instanceof RepoCommandError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Error thrown by the `repo-digest` action for expected, user-facing failures
+ * (an unwatched repo). The CLI prints the message and exits non-zero.
+ */
+class RepoDigestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RepoDigestError";
+    }
+}
+/**
+ * Whether an issue has a fresh, trustworthy compact: it must exist and not be
+ * stale. This is the protocol rule (see docs/compact-format.md section 5).
+ */
+function hasFreshCompact(issue) {
+    return issue.compact != null && !issue.compactStale;
+}
+/**
+ * Orders issues for a project-wide view: open issues first, then closed, each
+ * group ordered by issue number ascending (the order `listIssues` returns).
+ */
+function orderIssues(issues) {
+    const open = issues.filter((issue) => issue.state === "open");
+    const closed = issues.filter((issue) => issue.state !== "open");
+    return [...open, ...closed];
+}
+/** Computes the summary counts over all of a repo's issues. */
+function summarize(issues) {
+    let open = 0;
+    let compacted = 0;
+    for (const issue of issues) {
+        if (issue.state === "open") {
+            open += 1;
+        }
+        if (hasFreshCompact(issue)) {
+            compacted += 1;
+        }
+    }
+    return {
+        total: issues.length,
+        open,
+        closed: issues.length - open,
+        compacted,
+        staleOrUncompacted: issues.length - compacted,
+    };
+}
+/**
+ * Looks up the repo and returns its ordered issues plus the summary counts.
+ *
+ * @throws {RepoDigestError} When the repo is not watched.
+ */
+function loadDigest(store, fullName) {
+    const repo = store.getRepoByFullName(fullName);
+    if (!repo) {
+        throw new RepoDigestError(`Repo "${fullName}" is not watched. Add it with \`issuary add ${fullName}\` first.`);
+    }
+    const issues = store.listIssues(repo.id);
+    return { repo: repo.fullName, ordered: orderIssues(issues), summary: summarize(issues) };
+}
+/**
+ * Core action for `issuary repo-digest`: builds the full project-wide view of one
+ * watched repo. For each issue it prefers a fresh compact and falls back to the
+ * raw body, flagging which issues an AI may want to (re)compact.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller is responsible for opening/closing the {@link Store}.
+ *
+ * @throws {RepoDigestError} When the repo is not watched.
+ */
+function runRepoDigest(store, fullName) {
+    const { repo, ordered, summary } = loadDigest(store, fullName);
+    const issues = ordered.map((issue) => {
+        const fresh = hasFreshCompact(issue);
+        return {
+            number: issue.number,
+            state: issue.state,
+            stateReason: issue.stateReason,
+            title: issue.title,
+            representation: fresh ? issue.compact : issue.rawBody,
+            compacted: fresh,
+            stale: issue.compact != null && issue.compactStale,
+            refs: store.listIssueRefs(issue.id).map((ref) => ref.target),
+        };
+    });
+    return { repo, summary, issues };
+}
+/**
+ * Core action for `issuary repo-digest --headlines`: lists the whole project using
+ * only the cheap `tldr` headline (roughly 20 tokens per issue), falling back to
+ * the title for issues without a tldr.
+ *
+ * @throws {RepoDigestError} When the repo is not watched.
+ */
+function runRepoDigestHeadlines(store, fullName) {
+    const { repo, ordered, summary } = loadDigest(store, fullName);
+    const headlines = ordered.map((issue) => {
+        const tldr = issue.compactTldr?.trim();
+        const fromTldr = tldr != null && tldr !== "";
+        return {
+            number: issue.number,
+            state: issue.state,
+            headline: fromTldr ? tldr : issue.title,
+            fromTldr,
+        };
+    });
+    return { repo, summary, headlines };
+}
+/** Formats the summary header line shared by both human renderings. */
+function formatSummary(repo, summary) {
+    return (`${repo}: ${summary.total} issues (${summary.open} open, ${summary.closed} closed; ` +
+        `${summary.compacted} compacted, ${summary.staleOrUncompacted} stale/uncompacted)`);
+}
+/** Renders the lean headline digest as human-readable text. */
+function renderHeadlines(result) {
+    const lines = [formatSummary(result.repo, result.summary), ""];
+    for (const h of result.headlines) {
+        lines.push(`#${h.number} [${h.state}] ${h.headline}`);
+    }
+    return lines.join("\n");
+}
+/** Renders the full digest as human-readable text. */
+function renderFull(result) {
+    const lines = [formatSummary(result.repo, result.summary), ""];
+    for (const issue of result.issues) {
+        const reason = issue.stateReason ? `/${issue.stateReason}` : "";
+        const flag = issue.compacted ? "compact" : issue.stale ? "stale, raw" : "uncompacted, raw";
+        const refs = issue.refs.length ? ` refs: ${issue.refs.length}` : "";
+        lines.push(`#${issue.number} [${issue.state}${reason}] (${flag})${refs} ${issue.title}`);
+        if (issue.representation) {
+            lines.push(issue.representation);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * Builds the `repo-digest` command: a project-wide, AI-optimized view of all
+ * issues in one watched repo.
+ *
+ * @see file://../../docs/compact-format.md
+ */
+function repoDigestCommand() {
+    return new Command("repo-digest")
+        .description("Consume all issues of one watched repo as a project-wide, AI-optimized view")
+        .argument("<repo>", "watched repo, as owner/name")
+        .option("--headlines", "list every issue using only its cheap tldr headline")
+        .option("--json", "emit machine-readable JSON")
+        .action((repo, options) => {
+        const config = loadConfig({ requireToken: false });
+        const store = openStore(config.dbPath);
+        try {
+            if (options.headlines) {
+                const result = runRepoDigestHeadlines(store, repo);
+                console.log(options.json ? JSON.stringify(result) : renderHeadlines(result));
+            }
+            else {
+                const result = runRepoDigest(store, repo);
+                console.log(options.json ? JSON.stringify(result) : renderFull(result));
+            }
+        }
+        catch (error) {
+            if (error instanceof RepoDigestError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Error thrown by the `show` action for expected, user-facing failures
+ * (malformed target, unwatched repo, missing issue). The CLI prints the message
+ * and exits non-zero.
+ */
+class ShowCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShowCommandError";
+    }
+}
+/** Parses an issue's JSON-encoded labels column into an array. */
+function parseLabels(labels) {
+    if (!labels) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(labels);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Parses an issue's cached `raw_comments` column into an array. */
+function parseComments(rawComments) {
+    if (!rawComments) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(rawComments);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolves the comments for `--raw`: returns the cached `raw_comments` when
+ * present, otherwise fetches them via the client and caches them on the store.
+ */
+async function resolveComments(store, client, fullName, issue) {
+    if (issue.rawComments !== null) {
+        return parseComments(issue.rawComments);
+    }
+    const comments = await client.getComments(fullName, issue.number);
+    store.setIssueRawComments(issue.repoId, issue.number, JSON.stringify(comments), new Date().toISOString());
+    return comments;
+}
+/**
+ * Core action for `issuary show`: validates the target, looks up the repo and
+ * issue, and assembles a {@link ShowResult}. With `--raw`, the full body and
+ * comments are included, fetching and caching comments on demand.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. The caller owns the {@link Store}; `client` is only used (and so only
+ * required) when `--raw` needs to fetch uncached comments.
+ *
+ * @throws {ShowCommandError} For expected, user-facing failures.
+ */
+async function runShow(store, target, options, client) {
+    const { fullName, number } = parseTarget(target);
+    const repo = store.getRepoByFullName(fullName);
+    if (!repo) {
+        throw new ShowCommandError(`Repo "${fullName}" is not watched. Add it with \`issuary add ${fullName}\` first.`);
+    }
+    const issue = store.getIssue(repo.id, number);
+    if (!issue) {
+        throw new ShowCommandError(`Issue ${fullName}#${number} is not in the local store. Run \`issuary sync\` first.`);
+    }
+    const result = {
+        repo: fullName,
+        number: issue.number,
+        title: issue.title,
+        state: issue.state,
+        stateReason: issue.stateReason,
+        author: issue.author,
+        labels: parseLabels(issue.labels),
+        commentCount: issue.commentCount,
+        createdAt: issue.createdAt,
+        updatedAt: issue.updatedAt,
+        closedAt: issue.closedAt,
+        compact: issue.compact,
+        compactStale: issue.compactStale,
+        rawBody: issue.rawBody,
+        refs: store.listIssueRefs(issue.id).map((ref) => ref.target),
+    };
+    if (options.raw) {
+        if (!client) {
+            throw new ShowCommandError("A GitHub client is required to fetch comments for --raw.");
+        }
+        result.comments = await resolveComments(store, client, fullName, issue);
+    }
+    return result;
+}
+/** Renders a {@link ShowResult} as human-readable text. */
+function formatShow(result, options) {
+    const lines = [];
+    const reason = result.stateReason ? ` (${result.stateReason})` : "";
+    lines.push(`${result.repo}#${result.number} ${result.title}`);
+    lines.push(`state: ${result.state}${reason}`);
+    lines.push(`author: ${result.author ?? "unknown"}`);
+    lines.push(`labels: ${result.labels.length ? result.labels.join(", ") : "(none)"}`);
+    lines.push(`comments: ${result.commentCount}`);
+    lines.push(`references: ${result.refs.length ? result.refs.join(", ") : "(none)"}`);
+    lines.push(`created: ${result.createdAt}`);
+    lines.push(`updated: ${result.updatedAt}`);
+    if (result.closedAt) {
+        lines.push(`closed: ${result.closedAt}`);
+    }
+    lines.push("");
+    if (options.raw) {
+        lines.push("--- body ---");
+        lines.push(result.rawBody ?? "(no body)");
+        lines.push("");
+        lines.push("--- comments ---");
+        const comments = result.comments ?? [];
+        if (comments.length === 0) {
+            lines.push("(no comments)");
+        }
+        else {
+            for (const comment of comments) {
+                lines.push(`@${comment.author ?? "unknown"} (${comment.created_at}):`);
+                lines.push(comment.body ?? "(empty)");
+                lines.push("");
+            }
+        }
+    }
+    else if (result.compact) {
+        if (result.compactStale) {
+            lines.push("(compact is stale)");
+        }
+        lines.push(result.compact);
+    }
+    else {
+        lines.push(result.rawBody ?? "(no body)");
+    }
+    return lines.join("\n");
+}
+/**
+ * Builds the `show` command.
+ *
+ * The default view is local-only and needs no token; `--raw` may fetch comments
+ * on demand and therefore requires a token.
+ */
+function showCommand() {
+    return new Command("show")
+        .description("Display a single issue from the local store")
+        .argument("<target>", "issue to show, as owner/repo#number")
+        .option("--raw", "show the full raw body and comments (fetches comments on demand)")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (target, options) => {
+        const config = loadConfig({ requireToken: Boolean(options.raw) });
+        const store = openStore(config.dbPath);
+        try {
+            const client = options.raw ? createGitHubClient({ token: config.token, apiUrl: config.apiUrl }) : undefined;
+            const result = await runShow(store, target, options, client);
+            if (options.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(formatShow(result, options));
+            }
+        }
+        catch (error) {
+            if (error instanceof ShowCommandError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * The installable agent skill for issuary: a `SKILL.md` document an AI coding agent
+ * (for example Claude Code) can discover and follow to operate issuary.
+ *
+ * The skill is intentionally THIN. It states what issuary is and when to reach for
+ * it, then defers to `issuary protocol` and `issuary --help` for the exact contract and
+ * flags so it can never drift from the actual CLI. The compaction contract itself
+ * is reused from {@link COMPACTION_PROTOCOL} rather than restated here.
+ */
+/** The skill name, used as the frontmatter `name` and the install directory. */
+const SKILL_NAME = "issuary";
+/** The skill description, used as the frontmatter `description`. */
+const SKILL_DESCRIPTION = "Monitor GitHub issues across repos and produce or consume AI-written compactions (structured summaries) of them.";
+/**
+ * The full `SKILL.md` document text, including YAML frontmatter and body.
+ *
+ * Asserted on by tests via substrings (the core loop commands) so the skill
+ * cannot silently drift away from the CLI it describes.
+ */
+const SKILL_MD = `---
+name: ${SKILL_NAME}
+description: ${SKILL_DESCRIPTION}
+---
+
+# issuary
+
+\`issuary\` is a CLI (npm \`issuary\`, binary \`issuary\`) that monitors GitHub
+issues across many repositories. It keeps a local mirror, detects what changed,
+and exposes a compaction layer: structured, AI-written summaries of issues that
+save context tokens when you later need to reason over a project's issues.
+
+The tool never calls an LLM. You are the CPU of the compaction: issuary stores raw
+content, tells you what needs compacting, and takes your summary back.
+
+## When to use this
+
+Reach for issuary when you need to understand or triage GitHub issues across one or
+more repos without burning context on raw bodies and long comment threads, or
+when you are asked to keep a project's issue knowledge compacted and
+current. If a compact exists and is fresh, read it instead of refetching the
+issue.
+
+## issuary vs GitHub's MCP
+
+These are complementary, not competing. GitHub's MCP server gives live, raw
+access to issues: use it when you need the current, unfiltered state of an issue
+or its comments. issuary is NOT another raw-issue reader. Its value is the
+persistent, compacted MEMORY of issues plus the cross-repo digest of what changed
+since you last looked. Use issuary for the distilled memory and the "what changed"
+digest, and use GitHub's MCP for live, raw issue access.
+
+## Core loop
+
+1. Read the contract first: run \`issuary protocol\` (add \`--json\` for the machine
+   form). It defines what \`compact\` and \`compact_stale\` mean and exactly when to
+   reuse versus regenerate a compact. Follow it.
+2. Find work: \`issuary compact list --pending --json\` lists issues that have no
+   compact or whose compact went stale. To read the existing memory with filters
+   (state, repo, label, author, since, search, compaction), use \`issuary issues
+   --json\`; it returns the matched issues with their compacts and flags.
+3. Read the raw issue: \`issuary show <owner/repo>#<n> --raw --json\` returns the raw
+   body and comments to summarize.
+4. Write a compact in the canonical format (frontmatter copied from the API, body
+   written by you). The format and field rules come from \`issuary protocol\`.
+5. Persist it: \`issuary compact set <owner/repo>#<n> --from-file <file>\`. Persisting
+   clears the stale flag.
+6. Re-compact when stale: a new comment marks a compact stale, so repeat the loop
+   for anything \`issuary compact list --pending\` reports.
+
+## Flags and exact contract
+
+Do not hardcode flags from memory. Consult \`issuary --help\` (and \`issuary <command>
+--help\`) for the current commands and options, and \`issuary protocol\` for the exact
+compaction contract and canonical compact format. Those are the source of truth;
+this skill only points you at them.
+
+## The compaction contract (for reference)
+
+${COMPACTION_PROTOCOL}
+`;
+
+/** Raised for invalid `skill` command input, such as an unknown `--format`. */
+class SkillCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillCommandError";
+    }
+}
+/** The install formats the `skill` command accepts. */
+const SKILL_FORMATS = ["claude", "agents"];
+/** The default install format, kept as `claude` for back-compat. */
+const DEFAULT_SKILL_FORMAT = "claude";
+/** The marker that opens issuary's managed section inside an `AGENTS.md`. */
+const AGENTS_START_MARKER = "<!-- issuary:start -->";
+/** The marker that closes issuary's managed section inside an `AGENTS.md`. */
+const AGENTS_END_MARKER = "<!-- issuary:end -->";
+/**
+ * Validates and normalizes the requested format.
+ *
+ * @param format - The raw `--format` value, or undefined for the default.
+ * @returns The validated {@link SkillFormat}.
+ * @throws If the value is not one of {@link SKILL_FORMATS}.
+ */
+function resolveFormat(format) {
+    const value = (format ?? "").trim() || DEFAULT_SKILL_FORMAT;
+    if (!SKILL_FORMATS.includes(value)) {
+        throw new SkillCommandError(`Unknown skill format "${value}". Expected one of: ${SKILL_FORMATS.join(", ")}.`);
+    }
+    return value;
+}
+/**
+ * Resolves the skills root directory for the `claude` format.
+ *
+ * Precedence: explicit `--dir`, then the `CLAUDE_SKILLS_DIR` environment
+ * override, then the default `~/.claude/skills`.
+ */
+function resolveSkillsDir(dir) {
+    const fromEnv = (process.env.CLAUDE_SKILLS_DIR ?? "").trim();
+    return (dir ?? "").trim() || fromEnv || join(homedir(), ".claude", "skills");
+}
+/**
+ * Resolves the absolute path the skill is (or would be) written to for a format.
+ *
+ * - `claude`: `<skillsDir>/issuary/SKILL.md` (see {@link resolveSkillsDir}).
+ * - `agents`: `<dir or cwd>/AGENTS.md`.
+ *
+ * @param format - The install format.
+ * @param dir - Optional directory override.
+ * @returns The absolute path for the selected format.
+ */
+function resolveSkillPath(format, dir) {
+    if (format === "agents") {
+        return join((dir ?? "").trim() || process.cwd(), "AGENTS.md");
+    }
+    return join(resolveSkillsDir(dir), SKILL_NAME, "SKILL.md");
+}
+/**
+ * Builds the delimited issuary section written into an `AGENTS.md`.
+ *
+ * The content is the same neutral skill body, wrapped in start/end markers so it
+ * can be replaced in place on a re-install.
+ */
+function buildAgentsSection() {
+    return `${AGENTS_START_MARKER}\n${SKILL_MD}\n${AGENTS_END_MARKER}`;
+}
+/**
+ * Inserts or replaces issuary's delimited section in an existing `AGENTS.md` body.
+ *
+ * If the markers are present, only the content between them is replaced (leaving
+ * the rest untouched). If they are absent, the section is appended. The
+ * operation is idempotent: running it twice yields exactly one issuary section.
+ *
+ * Assumes well-formed markers: a matching start before end. A file that was
+ * hand-corrupted (a start without an end, or end before start) is treated as
+ * having no managed section, so the next run appends a fresh one rather than
+ * trying to repair the damage.
+ *
+ * @param existing - The current `AGENTS.md` content (empty string if new).
+ * @returns The updated file content.
+ */
+function upsertAgentsSection(existing) {
+    const section = buildAgentsSection();
+    const start = existing.indexOf(AGENTS_START_MARKER);
+    const end = existing.indexOf(AGENTS_END_MARKER);
+    if (start !== -1 && end !== -1 && end > start) {
+        const before = existing.slice(0, start);
+        const after = existing.slice(end + AGENTS_END_MARKER.length);
+        return `${before}${section}${after}`;
+    }
+    if (existing.trim().length === 0) {
+        return `${section}\n`;
+    }
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${separator}${section}\n`;
+}
+/**
+ * Core action for `issuary skill`.
+ *
+ * Separated from the Commander wiring so it can be tested without spawning a
+ * process. Behavior by option:
+ *
+ * - default: returns the neutral skill document text.
+ * - `json`: returns the structured {@link SkillJson} payload (includes `format`).
+ * - `install`: writes the skill for the selected format and returns a
+ *   {@link SkillInstallResult}. `claude` writes a `SKILL.md`; `agents` inserts or
+ *   replaces a delimited, idempotent section in an `AGENTS.md`.
+ */
+async function runSkill(options = {}) {
+    const format = resolveFormat(options.format);
+    if (options.install) {
+        const path = resolveSkillPath(format, options.dir);
+        const existed = await fileExists(path);
+        await mkdir(dirname(path), { recursive: true });
+        if (format === "agents") {
+            const existing = existed ? await readFile(path, "utf8") : "";
+            await writeFile(path, upsertAgentsSection(existing), "utf8");
+        }
+        else {
+            await writeFile(path, SKILL_MD, "utf8");
+        }
+        return { format, path, overwrote: existed };
+    }
+    if (options.json) {
+        const json = {
+            name: SKILL_NAME,
+            description: SKILL_DESCRIPTION,
+            path: resolveSkillPath(format, options.dir),
+            content: SKILL_MD,
+            format,
+        };
+        return json;
+    }
+    return SKILL_MD;
+}
+/** Returns whether a file already exists at the given path. */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds the `skill` command. It emits issuary's neutral agent skill, or installs
+ * it for an AI agent: a Claude Code `SKILL.md` (`--format claude`, the default)
+ * or a delimited section in a project `AGENTS.md` (`--format agents`). Printing
+ * with no `--install` is the universal path: any agent can paste it into a system
+ * prompt or rules file.
+ *
+ * @see file://../skill/skill.ts
+ */
+function skillCommand() {
+    return new Command("skill")
+        .description("Print issuary's agent skill, or install it for an AI agent (claude SKILL.md or AGENTS.md)")
+        .option("--install", "write the skill to disk instead of printing it")
+        .option("--format <format>", `install format: ${SKILL_FORMATS.join("|")} (default ${DEFAULT_SKILL_FORMAT})`)
+        .option("--dir <path>", "install directory (claude: skills root ~/.claude/skills; agents: dir holding AGENTS.md)")
+        .option("--json", "emit machine-readable JSON ({ name, description, path, content, format })")
+        .action(async (options) => {
+        const result = await runSkill(options);
+        if (options.install) {
+            const { format, path, overwrote } = result;
+            const verb = overwrote ? "Updated" : "Wrote";
+            console.log(`${verb} issuary skill (${format}) at ${path}`);
+            return;
+        }
+        if (options.json) {
+            console.log(JSON.stringify(result));
+            return;
+        }
+        console.log(result);
+    });
+}
+
+/**
+ * Parser for explicit issue/PR cross-references found in issue bodies and
+ * comments. This is deliberately literal: it recognizes only the textual forms
+ * GitHub itself links (`#123`, `owner/repo#123`, and `GH-123`-style numeric
+ * references), never semantic or similarity-based relationships. Anything beyond
+ * a literal token match is out of scope (see CLAUDE.md, princípio 7 / relacionamento).
+ */
+/**
+ * Matches a cross-repo reference like `owner/repo#123`. Owner and repo follow
+ * GitHub's allowed characters (alphanumerics, `-`, `_`, `.`). The leading `(?<![\w-])`
+ * lookbehind keeps the owner from starting in the middle of another word so a URL
+ * path segment such as `foo/bar/baz#1` does not match the wrong slice.
+ */
+const CROSS_REPO = /(?<![\w./-])([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)/g;
+/**
+ * Matches a same-repo reference like `#123`. The leading lookbehind rejects a
+ * `#` that is glued to a word character (e.g. an anchor in `page#section` or the
+ * `repo#123` already handled by {@link CROSS_REPO}), so only standalone `#123`
+ * tokens are captured.
+ */
+const SAME_REPO = /(?<![\w/#])#(\d+)/g;
+/**
+ * Matches an explicit `PR #123` / `pull request #123` / `pull/123` phrasing. The
+ * issue/PR number is captured; the surrounding wording is normalized away to the
+ * canonical `#123` form.
+ */
+const PR_PHRASE = /\b(?:pull request|pull|pr)\s*(?:#|\/)\s*(\d+)/gi;
+/**
+ * Strips fenced code blocks (```...```) and inline code spans (`...`) from the
+ * text so references that are clearly shown as code (e.g. a literal `#123` in a
+ * snippet) are not harvested. Autolink URLs are left intact: the regexes above
+ * already avoid matching inside `owner/repo/...` URL paths via lookbehinds.
+ */
+function stripCode(text) {
+    return text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+}
+/**
+ * Extracts the explicit issue/PR references from a text blob, returning a deduped
+ * list of normalized literal targets in first-seen order.
+ *
+ * Recognized forms and their normalized output:
+ * - `#123`            -> `"#123"`            (same-repo issue or PR)
+ * - `owner/repo#123`  -> `"owner/repo#123"` (cross-repo)
+ * - `PR #123`, `pull request #123`, `pull/123` -> `"#123"`
+ *
+ * References inside fenced or inline code are ignored. The issue's own number is
+ * ignored when `selfNumber` is provided so an issue never references itself.
+ *
+ * @param text - The raw markdown body (or comment) to scan. `null`/empty yields `[]`.
+ * @param selfNumber - The number of the issue being parsed, to drop self-references.
+ * @returns Deduped, normalized literal targets in first-seen order.
+ */
+function parseRefs(text, selfNumber) {
+    if (!text) {
+        return [];
+    }
+    const cleaned = stripCode(text);
+    const seen = new Set();
+    const targets = [];
+    const add = (target, number) => {
+        if (selfNumber !== undefined && number === selfNumber && !target.includes("/")) {
+            // Self-reference: only drop the bare same-repo form; a cross-repo token
+            // that happens to share the number still refers to a different repo.
+            return;
+        }
+        if (!seen.has(target)) {
+            seen.add(target);
+            targets.push(target);
+        }
+    };
+    for (const match of cleaned.matchAll(CROSS_REPO)) {
+        add(`${match[1]}#${match[2]}`, Number(match[2]));
+    }
+    for (const match of cleaned.matchAll(PR_PHRASE)) {
+        add(`#${match[1]}`, Number(match[1]));
+    }
+    for (const match of cleaned.matchAll(SAME_REPO)) {
+        add(`#${match[1]}`, Number(match[1]));
+    }
+    return targets;
+}
+
+/**
+ * Serializes a normalized issue's labels into the JSON shape the store holds,
+ * or null when there are none.
+ */
+function labelsJson(issue) {
+    return issue.labels.length > 0 ? JSON.stringify(issue.labels) : null;
+}
+/**
+ * Detects the change events for one incoming issue relative to its stored
+ * counterpart. Returns the event types to emit. An empty array means no change
+ * worth recording (including a brand-new issue that arrives already closed).
+ */
+function detectEvents(stored, incoming) {
+    if (!stored) {
+        // Brand-new issue. Only emit `opened` when it is actually open; an issue
+        // that arrives already closed is stored silently (no historical event).
+        return incoming.state === "open" ? ["opened"] : [];
+    }
+    const events = [];
+    if (stored.state === "open" && incoming.state === "closed") {
+        events.push("closed");
+    }
+    else if (stored.state === "closed" && incoming.state === "open") {
+        events.push("reopened");
+    }
+    if (incoming.comment_count > stored.commentCount) {
+        events.push(incoming.state === "closed" ? "closed_commented" : "commented");
+    }
+    return events;
+}
+/**
+ * Returns true when an existing issue's tracked fields changed in a way that
+ * should mark its compact stale (state, comment count, or update timestamp).
+ */
+function hasMeaningfulChange(stored, incoming) {
+    return (stored.state !== incoming.state ||
+        stored.commentCount !== incoming.comment_count ||
+        stored.updatedAt !== incoming.updated_at);
+}
+/**
+ * Syncs a single repo: lists its issues conditionally, diffs each against the
+ * local mirror, upserts metadata and raw bodies, records events, marks compacts
+ * stale on change, and updates the repo's sync bookkeeping. All writes for the
+ * repo run in one transaction. Comments are never fetched here.
+ */
+async function syncRepo(store, client, repo, now) {
+    const result = await client.listIssues(repo.fullName, {
+        since: repo.lastSyncedAt ?? undefined,
+        etag: repo.etag ?? undefined,
+    });
+    const base = {
+        repo: repo.fullName,
+        notModified: false,
+        opened: 0,
+        closed: 0,
+        reopened: 0,
+        commented: 0,
+        processed: 0,
+        error: null,
+    };
+    if (result.status === "notModified") {
+        // 304: nothing changed. Do not touch anything and do not spend further
+        // calls. We intentionally leave last_synced_at as-is.
+        return { ...base, notModified: true };
+    }
+    const detectedAt = now();
+    const apply = store.db.transaction(() => {
+        const summary = { ...base };
+        for (const incoming of result.issues) {
+            const stored = store.getIssue(repo.id, incoming.number);
+            const events = detectEvents(stored, incoming);
+            const upserted = store.upsertIssue({
+                repoId: repo.id,
+                number: incoming.number,
+                title: incoming.title,
+                state: incoming.state,
+                stateReason: incoming.state_reason,
+                author: incoming.author,
+                labels: labelsJson(incoming),
+                createdAt: incoming.created_at,
+                updatedAt: incoming.updated_at,
+                closedAt: incoming.closed_at,
+                commentCount: incoming.comment_count,
+                rawBody: incoming.body,
+                // Preserve raw comments and compact across syncs: upsert overwrites
+                // every column, so carry the stored values forward explicitly.
+                rawComments: stored?.rawComments ?? null,
+                rawFetchedAt: stored?.rawFetchedAt ?? null,
+                compact: stored?.compact ?? null,
+                compactTldr: stored?.compactTldr ?? null,
+                compactStale: stored?.compactStale ?? false,
+                compactedAt: stored?.compactedAt ?? null,
+            });
+            // Extract explicit references from the raw body and persist them. Runs in
+            // the same per-repo transaction; idempotent across syncs (replace clears
+            // first), so a re-synced body never accumulates stale refs.
+            store.replaceIssueRefs(upserted.id, parseRefs(incoming.body, incoming.number));
+            for (const type of events) {
+                store.insertEvent(upserted.id, type, detectedAt);
+                if (type === "opened")
+                    summary.opened += 1;
+                else if (type === "closed")
+                    summary.closed += 1;
+                else if (type === "reopened")
+                    summary.reopened += 1;
+                else
+                    summary.commented += 1;
+            }
+            // Mark an existing, already-compacted issue stale when it changed.
+            if (stored && stored.compact !== null && hasMeaningfulChange(stored, incoming)) {
+                store.setCompactStale(upserted.id, true);
+            }
+            summary.processed += 1;
+        }
+        store.updateRepoSync(repo.id, { lastSyncedAt: detectedAt, etag: result.etag });
+        return summary;
+    });
+    return apply();
+}
+/**
+ * Runs the sync engine over the given repos in sequence, returning a structured
+ * summary. Each repo is synced independently in its own transaction.
+ *
+ * A failure in one repo (network, 404/private, ...) is recorded in that repo's
+ * result and does not abort the run: the remaining repos are still synced. The
+ * per-repo transaction means a failed repo never advances its etag or
+ * `last_synced_at`, so a later run retries it from where it left off.
+ *
+ * @param deps - Injected store, GitHub client, and optional clock.
+ * @param repos - The repos to sync (typically the active set, or a single repo).
+ * @returns The aggregate {@link SyncResult}.
+ */
+async function runSync(deps, repos) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const results = [];
+    for (const repo of repos) {
+        try {
+            results.push(await syncRepo(deps.store, deps.client, repo, now));
+        }
+        catch (error) {
+            // Isolate the failure: record it and keep going with the other repos.
+            // No write happened for this repo (the listing threw before the
+            // transaction, or the transaction rolled back), so its etag and
+            // last_synced_at are untouched and the next run retries it.
+            results.push({
+                repo: repo.fullName,
+                notModified: false,
+                opened: 0,
+                closed: 0,
+                reopened: 0,
+                commented: 0,
+                processed: 0,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { repos: results };
+}
+
+/**
+ * Error thrown by the `sync` action for expected, user-facing failures (no repos
+ * watched, the named repo is not watched). The CLI prints the message and exits
+ * non-zero.
+ */
+class SyncCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SyncCommandError";
+    }
+}
+/**
+ * Resolves which repos to sync: the single named one (when `repo` is given), or
+ * every active repo otherwise.
+ *
+ * @throws {SyncCommandError} When the named repo is not watched, or when no
+ *   active repos exist.
+ */
+function resolveRepos(store, repo) {
+    if (repo) {
+        const found = store.getRepoByFullName(repo);
+        if (!found) {
+            throw new SyncCommandError(`Repo "${repo}" is not watched. Add it with \`issuary add ${repo}\` first.`);
+        }
+        return [found];
+    }
+    const active = store.listRepos({ activeOnly: true });
+    if (active.length === 0) {
+        throw new SyncCommandError("No active repos to sync. Add one with `issuary add <owner/repo>`.");
+    }
+    return active;
+}
+/**
+ * Core action for `issuary sync [repo]`: resolves the target repos and runs the
+ * diff engine over them. Separated from the Commander wiring so it can be tested
+ * without spawning a process. The caller owns the {@link Store} and client.
+ *
+ * @throws {SyncCommandError} For expected, user-facing failures.
+ */
+async function runSyncCommand(store, client, repo) {
+    const repos = resolveRepos(store, repo);
+    return runSync({ store, client }, repos);
+}
+/**
+ * True when a repo result carries noteworthy activity worth reporting even in
+ * quiet mode: a failure, or any recorded event (opened/closed/reopened/new
+ * comments). A 304, a no-op incremental sync, and a silent baseline import all
+ * count as no activity.
+ */
+function hasActivity(r) {
+    return r.error !== null || r.opened > 0 || r.closed > 0 || r.reopened > 0 || r.commented > 0;
+}
+/** Renders a single repo result as one human-readable line. */
+function formatRepoLine(r) {
+    if (r.error) {
+        return `${r.repo}: failed (${r.error})`;
+    }
+    if (r.notModified) {
+        return `${r.repo}: unchanged`;
+    }
+    const parts = [];
+    if (r.opened > 0)
+        parts.push(`${r.opened} new`);
+    if (r.closed > 0)
+        parts.push(`${r.closed} closed`);
+    if (r.reopened > 0)
+        parts.push(`${r.reopened} reopened`);
+    if (r.commented > 0)
+        parts.push(`${r.commented} new comments`);
+    if (parts.length > 0) {
+        return `${r.repo}: ${parts.join(", ")}`;
+    }
+    if (r.processed > 0) {
+        // Issues were fetched and mirrored but produced no noteworthy events. This
+        // is the common case on a first sync of a repo whose issues are all closed
+        // (closed issues are imported as a silent baseline). Saying "no changes"
+        // here would wrongly imply nothing was stored.
+        return `${r.repo}: no new activity (${r.processed} issues synced)`;
+    }
+    return `${r.repo}: no changes`;
+}
+/** Renders a sync result as grouped, human-readable lines. */
+function formatSyncResult(result) {
+    return result.repos.map(formatRepoLine).join("\n");
+}
+/**
+ * Quiet rendering for unattended/cron runs. Returns the empty string when no
+ * repo had any activity (no events and no errors), so a scheduled run is silent
+ * on a quiet cycle. When something happened it returns only the repos that had
+ * activity (their event lines and any failures), never the "unchanged" or
+ * "no changes" noise.
+ */
+function formatSyncResultQuiet(result) {
+    return result.repos.filter(hasActivity).map(formatRepoLine).join("\n");
+}
+/**
+ * Process exit code for a sync result: `1` when any repo failed to sync (a
+ * non-null `error`), `0` otherwise. Lets a scheduler/monitor detect failures
+ * even when output is suppressed. Kept as a pure helper so the exit-code
+ * contract can be tested without spawning a process or calling `process.exit`.
+ */
+function syncExitCode(result) {
+    return result.repos.some((r) => r.error !== null) ? 1 : 0;
+}
+/**
+ * Builds the `sync` command.
+ *
+ * `issuary sync [repo]` hits the GitHub API, so a token is required. The action is
+ * kept thin: it wires config, store, and client, then delegates to
+ * {@link runSyncCommand}.
+ */
+function syncCommand() {
+    return new Command("sync")
+        .description("Fetch issue updates for watched repos and record what changed")
+        .argument("[repo]", "limit the sync to a single watched repo, as owner/repo")
+        .option("--json", "emit machine-readable JSON")
+        .option("--quiet", "print nothing when there was no activity (errors are always printed); for cron")
+        .action(async (repo, options) => {
+        const config = loadConfig();
+        const store = openStore(config.dbPath);
+        const client = createGitHubClient({ token: config.token, apiUrl: config.apiUrl });
+        try {
+            const result = await runSyncCommand(store, client, repo);
+            if (options.json) {
+                // --json always emits the full result; --quiet does not change it.
+                console.log(JSON.stringify(result));
+            }
+            else if (options.quiet) {
+                // Print only when something happened; stay silent on a no-op cycle.
+                const text = formatSyncResultQuiet(result);
+                if (text !== "") {
+                    console.log(text);
+                }
+            }
+            else {
+                console.log(formatSyncResult(result));
+            }
+            // Signal failures to the scheduler/monitor even when output is quiet.
+            const code = syncExitCode(result);
+            if (code !== 0) {
+                process.exitCode = code;
+            }
+        }
+        catch (error) {
+            if (error instanceof SyncCommandError) {
+                console.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        finally {
+            store.close();
+        }
+    });
+}
+
+/**
+ * Wires every subcommand onto the root program.
+ *
+ * Each feature task adds its command module under `src/commands/` and registers
+ * it here. This is the single, intentional merge point for new commands.
+ */
+function registerCommands(program) {
+    // Commands are added by feature tasks (add, remove, list, sync, digest,
+    // repo-digest, show, compact, protocol). See .local/TASKS.md.
+    program.addCommand(addCommand());
+    program.addCommand(removeCommand());
+    program.addCommand(listCommand());
+    program.addCommand(compactCommand());
+    program.addCommand(protocolCommand());
+    program.addCommand(digestCommand());
+    program.addCommand(repoDigestCommand());
+    program.addCommand(issuesCommand());
+    program.addCommand(showCommand());
+    program.addCommand(skillCommand());
+    program.addCommand(syncCommand());
+    program.addCommand(loginCommand());
+    program.addCommand(logoutCommand());
+}
+
+const require$1 = createRequire(import.meta.url);
+const pkg = require$1("../package.json");
+/**
+ * Builds the root `issuary` command with all subcommands registered.
+ * Kept separate from {@link file://./cli.ts} so it can be exercised in tests
+ * without spawning a process.
+ */
+function createProgram() {
+    const program = new Command();
+    program.name("issuary").description(pkg.description).version(pkg.version);
+    registerCommands(program);
+    program.addHelpText("after", "\nAI consumers: run `issuary protocol` for the compaction contract (how to use, when to\nrecompact, and how to persist a compact). Add `--json` for the machine-readable form.\nAI agents: run `issuary skill --install` to install issuary as a discoverable agent skill.");
+    return program;
+}
+
+try {
+    await createProgram().parseAsync(process.argv);
+}
+catch (error) {
+    process.exitCode = handleCliError(error);
+}
+//# sourceMappingURL=cli.js.map